Embeddings

Embedding models rely on powerful neural networks to capture and compress semantic context, similar to generative models. Voyage AI's team of experienced AI researchers optimizes every component of the embedding process, including:

• Model architecture
• Data collection
• Loss functions
• Optimizer selection

Learn more about Voyage AI's technical approach on the Voyage AI blog.

For general-purpose embedding, the recommended models are:

• voyage-4-large: Best quality
• voyage-4-lite: Lowest latency and cost
• voyage-4: Balanced performance

For retrieval, use the input_type parameter to specify whether the text is a query or document type.

Domain-specific models:

• Legal tasks: voyage-law-2
• Code retrieval and agentic coding: voyage-code-4
• Finance-related tasks: voyage-finance-2

For chunk-level and document-level retrieval: voyage-context-4

For text, images, and video: voyage-multimodal-3.5

You can use Voyage AI embeddings with dot-product similarity, cosine similarity, or Euclidean distance. For an explanation of embedding similarity, see this vector similarity guide.

Voyage AI embeddings are normalized to length 1, which means that:

• Cosine similarity is equivalent to dot-product similarity, while the latter can be computed more quickly.
• Cosine similarity and Euclidean distance result in identical rankings.

See Tokenization in the MongoDB documentation.

For all retrieval tasks and use cases (for example, RAG), use the input_type parameter to specify whether the input text is a query or document. Do not omit input_type or set input_type=None. Specifying whether input text is a query or document can create better dense vector representations for retrieval, which can lead to better retrieval quality.

When using the input_type parameter, special prompts are prepended to the input text prior to embedding. Specifically:

📘 Prompts associated with input_type

• For a query, the prompt is "Represent the query for retrieving supporting documents: ".
• For a document, the prompt is "Represent the document for retrieval: ".
• Example
  • When input_type="query", a query such as "When is Apple's conference call scheduled?" will become "Represent the query for retrieving supporting documents: When is Apple's conference call scheduled?"
  • When input_type="document", a document such as "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." will become "Represent the document for retrieval: 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."

Quantization in embeddings converts high-precision values, such as 32-bit single-precision floating-point numbers, to lower-precision formats such as 8-bit integers or 1-bit binary values, reducing storage, memory, and costs by 4x and 32x, respectively. Supported Voyage AI models enable quantization by specifying the output data type with the output_dtype parameter:

• float: Each returned embedding is a list of 32-bit (4-byte) single-precision floating-point numbers. This is the default and provides the highest precision / retrieval accuracy.
• int8 and uint8: Each returned embedding is a list of 8-bit (1-byte) integers ranging from -128 to 127 and 0 to 255, respectively.
• binary and ubinary: Each returned embedding is a list of 8-bit integers that represent bit-packed, quantized single-bit embedding values: int8 for binary and uint8 for ubinary. The length of the returned list of integers is 1/8 of the actual dimension of the embedding. The binary type uses the offset binary method, as the following example shows.

Binary quantization example

Consider the following eight embedding values: -0.03955078, 0.006214142, -0.07446289, -0.039001465, 0.0046463013, 0.00030612946, -0.08496094, and 0.03994751. With binary quantization, values less than or equal to zero will be quantized to a binary zero, and positive values to a binary one, resulting in the following binary sequence: 0, 1, 0, 0, 1, 1, 0, 1. These eight bits are then packed into a single 8-bit integer, 01001101 (with the leftmost bit as the most significant bit).

• ubinary: The binary sequence is directly converted and represented as the unsigned integer (uint8) 77.
• binary: The binary sequence is represented as the signed integer (int8) -51, calculated using the offset binary method (77 - 128 = -51).

For the models that support each data type, see Create text embeddings in the Atlas Embedding and Reranking API documentation.

Matryoshka learning creates embeddings with coarse-to-fine representations within a single vector. Voyage AI models that support multiple output dimensions, such as voyage-code-4, generate such Matryoshka embeddings. To get shorter vectors from the API, pass output_dimension (for example, output_dimension=256). To shorten vectors you already stored, truncate them by keeping the leading subset of dimensions, then normalize them again. For example, the following Python code demonstrates how to truncate 1024-dimensional vectors to 256 dimensions:

import voyageai
import numpy as np


def embd_normalize(v: np.ndarray) -> np.ndarray:
    """
    Normalize the rows of a 2D numpy array to unit vectors by dividing each row by its Euclidean
    norm. Raises a ValueError if any row has a norm of zero to prevent division by zero.
    """
    row_norms = np.linalg.norm(v, axis=1, keepdims=True)
    if np.any(row_norms == 0):
        raise ValueError("Cannot normalize rows with a norm of zero.")
    return v / row_norms


vo = voyageai.Client()

# Generate voyage-code-4 vectors, which by default are 1024-dimensional floating-point numbers
embd = vo.embed(["Sample text 1", "Sample text 2"], model="voyage-code-4").embeddings

# Set shorter dimension
short_dim = 256

# Resize and normalize vectors to shorter dimension
resized_embd = embd_normalize(np.array(embd)[:, :short_dim]).tolist()