Voyage AI Provider

The Voyage AI provider contains embedding and reranking model support for the Voyage AI API.

Setup

The Voyage AI provider is available in the @ai-sdk/voyage module. You can install it with

pnpm add @ai-sdk/voyage

Provider Instance

You can import the default provider instance voyage from @ai-sdk/voyage:

1
import { voyage } from '@ai-sdk/voyage';

If you need a customized setup, you can import createVoyage from @ai-sdk/voyage and create a provider instance with your settings:

1
import { createVoyage } from '@ai-sdk/voyage';
2

3
const voyage = createVoyage({
4
  // custom settings
5
});

You can use the following optional settings to customize the Voyage AI provider instance:

• baseURL string

  Use a different URL prefix for API calls, e.g. to use proxy servers. The default prefix is https://api.voyageai.com/v1.

• apiKey string

  API key that is being sent using the Authorization header. It defaults to the VOYAGE_API_KEY environment variable.

• headers Record<string,string>

  Custom headers to include in the requests.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  Custom fetch implementation. Defaults to the global fetch function. You can use it as a middleware to intercept requests, or to provide a custom fetch implementation for e.g. testing.

Embedding Models

You can create models that call the Voyage AI embeddings API using the .embedding() factory method.

1
const model = voyage.embedding('voyage-3.5');

You can use Voyage AI embedding models to generate embeddings with the embed function:

1
import { voyage } from '@ai-sdk/voyage';
2
import { embed } from 'ai';
3

4
const { embedding } = await embed({
5
  model: voyage.embedding('voyage-3.5'),
6
  value: 'sunny day at the beach',
7
});

Voyage AI embedding models support additional provider options that can be passed via providerOptions.voyage:

1
import { voyage, type VoyageEmbeddingModelOptions } from '@ai-sdk/voyage';
2
import { embed } from 'ai';
3

4
const { embedding } = await embed({
5
  model: voyage.embedding('voyage-4-large'),
6
  value: 'sunny day at the beach',
7
  providerOptions: {
8
    voyage: {
9
      inputType: 'document',
10
      outputDimension: 512,
11
    } satisfies VoyageEmbeddingModelOptions,
12
  },
13
});

The following provider options are available:

• inputType 'query' | 'document' | null

  Specifies the type of input passed to the model. Defaults to null.

  • null: The embedding model directly converts the inputs into numerical vectors.
  • 'query': Used for embeddings of search queries run against a vector DB to find relevant documents.
  • 'document': Used for embeddings stored in a vector database for search use-cases.

• truncation boolean

  Whether to truncate the input texts to fit within the model's context length. Defaults to true.

• outputDimension number

  The number of dimensions for the resulting output embeddings. Supported by models with flexible dimensions (e.g. voyage-4-large, voyage-4, voyage-4-lite, voyage-4-nano, voyage-code-3.5, voyage-code-3, voyage-3-large, voyage-3.5, voyage-3.5-lite). Supported values: 256, 512, 1024, 2048.

• outputDtype 'float' | 'int8' | 'uint8' | 'binary' | 'ubinary'

  The data type for the output embeddings. Defaults to 'float'.

  • 'float': 32-bit floating-point numbers.
  • 'int8', 'uint8': 8-bit integer types.
  • 'binary', 'ubinary': Bit-packed, quantized single-bit embedding values.

Model Capabilities

Reranking Models

You can create models that call the Voyage AI rerank API using the .reranking() factory method.

1
const model = voyage.reranking('rerank-2.5');

You can use Voyage AI reranking models to rerank documents with the rerank function:

1
import { voyage } from '@ai-sdk/voyage';
2
import { rerank } from 'ai';
3

4
const documents = [
5
  'sunny day at the beach',
6
  'rainy afternoon in the city',
7
  'snowy night in the mountains',
8
];
9

10
const { ranking } = await rerank({
11
  model: voyage.reranking('rerank-2.5'),
12
  documents,
13
  query: 'talk about rain',
14
  topN: 2,
15
});
16

17
console.log(ranking);

Voyage AI reranking models support additional provider options that can be passed via providerOptions.voyage:

1
import { voyage, type VoyageRerankingModelOptions } from '@ai-sdk/voyage';
2
import { rerank } from 'ai';
3

4
const { ranking } = await rerank({
5
  model: voyage.reranking('rerank-2.5'),
6
  documents: ['sunny day at the beach', 'rainy afternoon in the city'],
7
  query: 'talk about rain',
8
  providerOptions: {
9
    voyage: {
10
      returnDocuments: true,
11
      truncation: true,
12
    } satisfies VoyageRerankingModelOptions,
13
  },
14
});

The following provider options are available:

• returnDocuments boolean

  Whether to return the documents in the response. Defaults to false.

• truncation boolean

  Whether to truncate the input texts to fit within the model's context length. Defaults to true.

Model Capabilities