Embeddings

Model Choices

Voyage currently provides the following embedding models.

Model
Context Length (tokens)Embedding DimensionDescription
voyage-large-2160001536Our most powerful generalist embedding model (e.g., better than OpenAI V3 Large).
voyage-code-2160001536Optimized for code retrieval (17% better than alternatives), and also SoTA on general-purpose corpora (see blog post for details).
voyage-240001024Base generalist embedding model optimized for both latency and quality, while still offering better retrieval performance than OpenAI V3 Large.
voyage-lite-02-instruct40001024Instruction-tuned for classification, clustering, and sentence textual similarity tasks, which are the only recommended use cases.

voyage-2 and voyage-large-2 are generalist embedding models, which achieve state-of-the-art performance across domains and retain high efficiency. voyage-code-2 is optimized for the code field, offering 4x the context length for more flexible usage, albeit at a relatively higher latency.

📘

More advanced and specialized models are coming soon and please email [email protected] for free trial access.

  • voyage-finance-2: coming soon
  • voyage-law-2: coming soon
  • voyage-multilingual-2: coming soon
  • voyage-healthcare-2: coming soon

Deprecated Models

The following are our earlier models, which are still accessible from our API. We recommend to use the new models above for better quality and efficiency. voyage-2, voyage-large-2 and voyage-code-2 will be strictly better than all these models in all aspects, such as quality, context length, latency, and throughput.

ModelContext Length (tokens)Embedding DimensionDescription
voyage-0240001024[Deprecated] This is our pilot-version v2 embedding model. We kindly ask you to transition to the final version, voyage-2, as detailed above.
voyage-0140001024[Deprecated] This is our v1 embedding model. Please transition to voyage-2, which offers higher quality and efficiency.
voyage-lite-0140001024[Deprecated] This is our v1 embedding model. Please transition to voyage-2, which offers higher quality and efficiency.
voyage-lite-01-instruct40001024[Deprecated] Tweaked on top of voyage-lite-01 for classification and clustering tasks. Please transition to voyage-lite-02-instruct.

Python API

Voyage embeddings are accessible in Python through the voyageai package. Please first install the voyageai package and setup the API key.

The Python package offers the voyageai.Client class as the interface to invoke Voyage's API.

class voyageai.Client

Parameters

  • api_key (str, optional, defaults to None) - Voyage API key. If None, the client will search for the API key in the following order:
    • voyageai.api_key_path, path to the file containing the key;
    • voyageai.api_key, an attribute of the voyageai module, which can be used to store the key;
    • environment variable VOYAGE_API_KEY.

voyageai.Client.embed (texts : List[str], model : str, input_type : Optional[str] = None, truncation : Optional[bool] = None)

Parameters

  • texts (List[str]) - A list of texts as a list of strings, such as ["I like cats", "I also like dogs"].
    • Currently, the maximum length of the list is 128, and total number of tokens in the list is at most 320K for voyage-2 and 120K for voyage-large-2 and voyage-code-2.
  • model (str) - Name of the model. Recommended options: voyage-2, voyage-large-2, voyage-code-2.
  • input_type (str, optional, defaults to None) - Type of the input text. Default to None. Other options: query, document.
    • When the input_type is set to None, and the input text will be directly encoded by our embedding model. Alternatively, when the inputs are documents or queries, the users can specify input_type to be query or document, respectively. In such cases, Voyage will prepend a special prompt to input text and send the extended inputs to the embedding model.
    • For retrieval/search use cases, we recommend specifying this argument when encoding queries or documents to enhance retrieval quality. Embeddings generated with and without the input_type argument are compatible.
    • For transparency, the prompts the backend will prepend to your texts are below.
      • For query, the prompt is "Represent the query for retrieving supporting documents: ".
      • For document, the prompt is "Represent the document for retrieval: ".
  • truncation (bool, optional, defaults to None) - Whether to truncate the input texts to fit within the context length.
    • If True, over-length input texts will be truncated to fit within the context length, before vectorized by the embedding model.
    • If False, an error will be raised if any given text exceeds the context length.
    • If not specified (defaults to None), we will truncate the input text before sending it to the embedding model if it slightly exceeds the context window length. If it significantly exceeds the context window length, an error will be raised.

Returns

  • A voyageai.EmbeddingsObject, containing the following attributes:
    • embeddings (List[List[float]]) - A list of embeddings for the corresponding list of input texts, where each embedding is a vector represented as a list of floats.
    • total_tokens (int) - The total number of tokens in the input texts.

Example

import voyageai

vo = voyageai.Client()
# This will automatically use the environment variable VOYAGE_API_KEY.
# Alternatively, you can use vo = voyageai.Client(api_key="<your secret key>")

texts = [
    "The Mediterranean diet emphasizes fish, olive oil, ...",
    "Photosynthesis in plants converts light energy into ...",
    "20th-century innovations, from radios to smartphones ...",
    "Rivers provide water, irrigation, and habitat for ...",
    "Apple’s conference call to discuss fourth fiscal ...",
    "Shakespeare's works, like 'Hamlet' and ...",
]

# Embed the documents
result = vo.embed(texts, model="voyage-2", input_type="document")
print(result.embeddings)
[
    [0.00526228, -0.000373015, -0.02525081, ...],
    [-0.00811059, 0.012202565, -0.05196673, ...],
    [-0.00748063, 0.014599844, -0.02266245, ...],
    [0.00425616, 0.024158479, -0.03241389, ...],
    [0.00873539, 0.003794617, -0.02606661, ...],
    [0.01898119, 0.025468252, -0.05191393, ...]
]

Deprecated Functions

The following functions are deprecated and will be removed in the future.

get_embedding(text, model="voyage-01", input_type=None)

Parameters

  • text - A single document/query as a string, such as "I like cats" .
  • model - Name of the model. Options: voyage-01 (default), voyage-lite-01.
  • input_type - Type of the input text. Defalut to None, meaning the type is unspecified. Other options: query, document.

Returns

  • An embedding vector (a list of floating-point numbers) for the document.

get_embeddings(list_of_text, model="voyage-01", input_type=None)

Parameters

  • list_of_text - A list of documents as a list of strings, such as ["I like cats", "I also like dogs"]. The maximum length of the list is 64.
  • model - Name of the model. Options: voyage-01 (default), voyage-lite-01.
  • input_type - Type of the input text. Defalut to None, meaning the type is unspecified. Other options: query, document.

Returns

  • A list of embedding vectors.

HTTP API

Voyage embeddings can be accessed by calling the endpoint POST https://api.voyageai.com/v1/embeddings. Please refer to the Embeddings API Reference for the specification.

Example

curl https://api.voyageai.com/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $VOYAGE_API_KEY" \
  -d '{
    "input": "Sample text",
    "model": "voyage-2"
  }'
curl https://api.voyageai.com/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $VOYAGE_API_KEY" \
  -d '{
    "input": ["Sample text 1", "Sample text 2"],
    "model": "voyage-2"
  }'