Model Choices

Voyage currently provides the following embedding models.

📘

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

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, ...]
]

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"
  }'