Embeddings

Model Choices

Voyage currently provides the following embedding models.

Model
Context Length (tokens)Embedding DimensionDescription
voyage-large-2-instruct160001024Top of MTEB leaderboard. Instruction-tuned general-purpose embedding model optimized for clustering, classification, and retrieval. For retrieval, please use input_type parameter to specify whether the text is a query or document. For classification and clustering, please use the instructions here. See blog post for details.
voyage-law-2160001024Optimized for legal and long-context retrieval and RAG. Also improved performance across all domains. See blog post for details.
voyage-code-2160001536Optimized for code retrieval (17% better than alternatives). See blog post for details.
voyage-large-2160001536General-purpose embedding model that is optimized for retrieval quality (e.g., better than OpenAI V3 Large).
voyage-240001024General-purpose embedding model optimized for a balance between cost, latency, and retrieval quality.

📘

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

  • voyage-finance-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. Our latest models listed in the above table will be strictly better than the deprecated models in all aspects, such as quality, context length, latency, and throughput.

Model
Context Length (tokens)Embedding DimensionDescription
voyage-lite-02-instruct40001024[Deprecated] Instruction-tuned for classification, clustering, and sentence textual similarity tasks, which are the only recommended use cases. Please transition to voyage-large-2-instruct.
voyage-0240001024[Deprecated] This is our pilot-version v2 embedding model. We kindly ask you to transition to voyage-large-2-instruct as detailed above.
voyage-0140001024[Deprecated] This is our v1 embedding model. Please transition to voyage-large-2-instruct.
voyage-lite-0140001024[Deprecated] This is our v1 embedding model. Please transition to voyage-large-2-instruct.
voyage-lite-01-instruct40001024[Deprecated] Tweaked on top of voyage-lite-01 for classification and clustering tasks. Please transition to voyage-large-2-instruct.

Python API

Voyage embeddings are accessible in Python through the voyageai package. Please first install the voyageai package and setup the API key, and use the embed() function of voyageai.Client to embed your input texts.

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, we have two constraints on the list:
    • The maximum length of the list is 128.
    • The total number of tokens in the list is at most 320K for voyage-2, and 120K for voyage-large-2-instruct, voyage-law-2, voyage-code-2, and voyage-large-2.
  • model (str) - Name of the model. Recommended options: voyage-large-2-instruct, voyage-law-2, voyage-code-2, voyage-large-2, voyage-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 True) - 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.

Returns

  • A 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, and vegetables, believed to reduce chronic diseases.",
    "Photosynthesis in plants converts light energy into glucose and produces essential oxygen.",
    "20th-century innovations, from radios to smartphones, centered on electronic advancements.",
    "Rivers provide water, irrigation, and habitat for aquatic species, vital for ecosystems.",
    "Apple’s conference call to discuss fourth fiscal quarter results and business updates is scheduled for Thursday, November 2, 2023 at 2:00 p.m. PT / 5:00 p.m. ET.",
    "Shakespeare's works, like 'Hamlet' and 'A Midsummer Night's Dream,' endure in literature."
]

# Embed the documents
result = vo.embed(texts, model="voyage-large-2-instruct", 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.

REST 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-large-2-instruct",
    "input_type": "document"
  }'
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-large-2-instruct",
    "input_type": "document"
  }'