Voyage AI Integration Example
Configure Voyage AI embedding, multimodal embedding, and rerank models in a self-hosted FastGPT deployment through AI Proxy.
Voyage AI provides text embedding, multimodal embedding, and rerank models. FastGPT reaches them through the Voyage channel type of AI Proxy, which converts FastGPT's OpenAI-style embedding requests and its /rerank requests to the Voyage API, so no extra service is needed.
Before reading this guide, make sure you've read the Model Configuration Guide.
The
Voyagechannel type and the built-in Voyage model presets require an AI Proxy and a FastGPT Plugin version that include them. The contextualized embedding models (voyage-context-*) are served as ordinary embedding models, one input per document (see the notes below).
1. Get an API Key
- Visit the Voyage AI dashboard and sign in.
- Create an API key on the API Keys page and store it securely.
2. Add a Channel
On the Model providers page, click "Add Channel" and configure the Voyage channel:
- Name: Custom channel name, e.g.,
Voyage AI - Protocol type: Select voyage
- Proxy URL: Leave empty to use the default
https://api.voyageai.com/v1 - API Key: Enter the Voyage API Key obtained in the previous step
- Models: Select the Voyage models you want to use
3. Models
| Model ID | Type | Context | Price (USD / 1M tokens) |
|---|---|---|---|
voyage-4-large, voyage-code-4 | Embedding | 32K | 0.12 |
voyage-4, voyage-3.5 | Embedding | 32K | 0.06 |
voyage-4-lite, voyage-3.5-lite | Embedding | 32K | 0.02 |
voyage-3-large, voyage-code-3 | Embedding | 32K | 0.18 |
voyage-context-4 | Embedding (contextualized) | 32K | 0.12 |
voyage-context-3 | Embedding (contextualized) | 32K | 0.18 |
voyage-finance-2 | Embedding | 32K | 0.12 |
voyage-law-2 | Embedding | 16K | 0.12 |
voyage-multimodal-3.5, voyage-multimodal-3 | Embedding (text and images) | 32K | 0.12 text, 0.60 per 1B image pixels |
rerank-3, rerank-2.5 | Rerank | 32K | 0.05 |
rerank-3-lite, rerank-2.5-lite | Rerank | 32K | 0.02 |
Notes for embedding models:
- FastGPT stores vectors with a fixed size of 1536. Voyage returns 1024 dimensions by default, and FastGPT pads them with zeros, which does not change cosine similarity. Keep the default dimension; other
output_dimensionvalues (256, 512, 2048) are not needed, and 2048 would be cut to 1536. - The built-in presets send
input_type: documentwhen text is indexed andinput_type: querywhen it is searched. When you add a custom model, set the same in the model config:
{
"type": "embedding",
"provider": "Voyage",
"model": "voyage-4",
"name": "voyage-4",
"isActive": true,
"pricing": { "unitPrice": 0 },
"config": {
"defaultToken": 512,
"maxToken": 32000,
"dbConfig": { "input_type": "document" },
"queryConfig": { "input_type": "query" }
}
}voyage-context-4andvoyage-context-3use the contextualized embeddings API. AI Proxy sends every input as its own document withenable_auto_chunking: trueandchunk_size: 32000, and does not auto-chunk queries. FastGPT sends one chunk per input, so the vector of a chunk is not conditioned on the other chunks of its file. A request fails when Voyage splits an input into more than one chunk; the preset limit of 30000 tokens keeps inputs well below that. Voyage rejects these models withoutinput_type, so their presets also setinput_type: documentas the default.- Mark
voyage-multimodal-3.5andvoyage-multimodal-3as accepting images (vision) to use them for image indexing.
4. Test Models
After configuration, click the test button in the channel list to verify channel connectivity and model availability.