Contextualized Chunk Embeddings

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

Contextualized Chunk Embeddings

voyage-context-4 is a contextualized chunk embedding model that produces vectors for chunks that capture the full document context without any manual metadata and context augmentation. This leads to higher retrieval accuracies than with or without augmentation. The model is also simpler, faster, and cheaper. It serves as a drop-in replacement for standard embeddings without downstream workflow changes and reduces chunking strategy sensitivity.

To learn more, see the blog post.

Available Models

Note:

* The total number of tokens across all inputs must not exceed 120K if enable_auto_chunk = true; otherwise they must not exceed 32K.

Older Contextualized Chunk Embedding Models

The following older models are still accessible from the API, but we recommend using the new models for better quality and efficiency.

The latest models perform better than the legacy models in all aspects, such as quality, context length, latency, and throughput.

Tutorial

For a tutorial on using contextualized chunk embeddings, see [Semantic Search with Voyage AI Embeddings.](https://www.mongodb.com/docs/voyageai/tutorials/semantic-search.md#std-label-voyage-semantic-search

Usage

You can access Voyage contextualized chunk embeddings in Python through the voyageai package. Install the voyageai package, set up the API key, and use the voyageai.Client.contextualized_embed() function to vectorize your inputs.

voyageai.Client.contextualized_embed(
    inputs: Union[List[List[str]], List[str]], # see below for specifics on when to pass one or the other.
    model: str,
    input_type: Optional[str] = None,
    output_dimension: Optional[int] = None,
    output_dtype: Optional[str] = "float",
    enable_auto_chunking: Optional[bool] = False,
    chunk_size: Optional[int] = 512,
    chunk_overlap: Optional[int] = 0,
    chunk_fn: Optional[Callable[[str], List[str]]] = None,
)

Parameters

View the parameters for the contextualized_embed method.

Note:

• The listed limits for both chunk_size and chunk_overlap are upper bounds. The actual chunk_size and chunk_overlap can be less than the value passed, but cannot be higher.

• Overlapping tokens are billed in the same way as input tokens.

Response

View the response for the contextualized_embed method.

This method returns a ContextualizedEmbeddingsObject, which contains the following attributes:

A ContextualizedEmbeddingsObject, containing the following attributes:

Example: see the [quickstart.](https://www.mongodb.com/docs/voyageai/quickstart.md#std-label-voyage-quickstart

Quick Reference: Valid Parameter Combinations

Quickstart

Auto Chunking and Embedding

Use this when you want Voyage to split each full document into chunks for you.

import voyageai

vo = voyageai.Client()

documents = [
    "This is the SEC filing on Leafy Inc.'s Q2 2024 performance.\nThe company's revenue increased by 15% compared to the previous quarter.",
    "This is the SEC filing on Elephant Ltd.'s Q2 2024 performance.\nThe company's revenue decreased by 2% compared to the previous quarter.",
]

result = vo.contextualized_embed(
    model="voyage-context-4",
    inputs=documents,
    input_type="document",
    enable_auto_chunking=True,
    chunk_size=512,
    chunk_overlap=0,
)

When auto-chunking is enabled, the backend splits each full document into chunks before embedding.

Embed Pre-Chunked Documents

Use this when you have already split each document into chunks on the client side.

import voyageai

vo = voyageai.Client()

inputs = [
    [
        "This is the SEC filing on Leafy Inc.'s Q2 2024 performance.",
        "The company's revenue increased by 15% compared to the previous quarter.",
    ],
    [
        "This is the SEC filing on Elephant Ltd.'s Q2 2024 performance.",
        "The company's revenue decreased by 2% compared to the previous quarter.",
    ],
]

result = vo.contextualized_embed(
    model="voyage-context-4",
    inputs=inputs,
    input_type="document",
)

Each inner list is embedded as a group, so each chunk is encoded in the context of the other chunks from the same document.

Client-Side Chunking and Embedding

Use this when you have full documents and want to handle chunking locally in the Python SDK rather than in the backend.

import voyageai

vo = voyageai.Client()

inputs = [
    [
        "This is the SEC filing on Leafy Inc.'s Q2 2024 performance.\nThe company's revenue increased by 15% compared to the previous quarter.",
    ],
    [
        "This is the SEC filing on Elephant Ltd.'s Q2 2024 performance.\nThe company's revenue decreased by 2% compared to the previous quarter.",
    ],
]

result = vo.contextualized_embed(
    model="voyage-context-4",
    inputs=inputs,
    input_type="document",
    chunk_fn=voyageai.default_chunk_fn,
)

chunk_fn is applied locally to each input string before the request is sent.

Embedding Queries

Use this when your inputs are search queries.

import voyageai

vo = voyageai.Client()

result = vo.contextualized_embed(
    model="voyage-context-4",
    inputs=[
        "What was the revenue growth for Leafy Inc. in Q2 2024?",
        "What changed in Greenery Corp. between Q1 and Q2 2024?",
    ],
    input_type="query",
)

The following query input shape is also valid and is treated equivalently:

result = vo.contextualized_embed(
    model="voyage-context-4",
    inputs=[
        ["What was the revenue growth for Leafy Inc. in Q2 2024?"],
        ["What changed in Greenery Corp. between Q1 and Q2 2024?"],
    ],
    input_type="query",
)

Returned Chunk Text

The response contains contextualized embedding results for each query or document. For document chunks, embeddings are ordered to match chunk order.

In the Python SDK, returned chunk text is available through chunk_texts on the result object. In the REST API, returned chunk text is available as text on each embedding item.

If you provide a client-side chunking function, the returned chunk text corresponds to the chunks produced by that function. When auto-chunking is enabled, the response also includes the backend-generated chunk text for each returned embedding so you can inspect and store it.

You can access Voyage contextualized chunk embeddings in TypeScript through the voyageai package. Install the voyageai package, set up the API key, and use the VoyageAIClient.contextualizedEmbed() method to vectorize your inputs.

The TypeScript client sends requests to the Voyage platform endpoint (https://api.voyageai.com/v1) by default. To use a [model API key](https://www.mongodb.com/docs/voyageai/management/api-keys.md#std-label-voyage-api-keys, set the environment option to https://ai.mongodb.com/v1 when you create the client, as shown in the following example. To learn more about the client, see [TypeScript Client.](https://www.mongodb.com/docs/voyageai/api-and-clients.md#std-label-voyage-typescript-client

Example

The following example embeds two pre-chunked documents. Each inner array contains one document's chunks, so each chunk is encoded in the context of the other chunks from the same document.

import { VoyageAIClient } from "voyageai";

// To use a model API key created in the Atlas UI, set the
// environment option to https://ai.mongodb.com/v1
const client = new VoyageAIClient({
  apiKey: process.env.VOYAGE_API_KEY,
  environment: "https://ai.mongodb.com/v1",
});

// Each inner array contains the chunks of one document
const inputs = [
  [
    "This is the SEC filing on Leafy Inc.'s Q2 2024 performance.",
    "The company's revenue increased by 15% compared to the previous quarter.",
  ],
  [
    "This is the SEC filing on Elephant Ltd.'s Q2 2024 performance.",
    "The company's revenue decreased by 2% compared to the previous quarter.",
  ],
];

const result = await client.contextualizedEmbed({
  inputs: inputs,
  model: "voyage-context-4",
  inputType: "document",
});

console.log(`Embedding dimension: ${result.results[0].embeddings[0].length}`);
console.log(`Total tokens used: ${result.totalTokens}`);

The contextualizedEmbed() method returns a result object whose results field contains one item per input document. Each item's embeddings field contains one embedding per chunk, ordered to match chunk order. The totalTokens field contains the total number of tokens processed.

You can access Voyage contextualized chunk embeddings in Java by sending HTTP requests using the built-in HttpClient or other HTTP libraries.

Example

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String apiKey = System.getenv("VOYAGE_API_KEY");
String url = "https://api.voyageai.com/v1/contextualizedembeddings";

String jsonBody = """
    {
        "inputs": [
            ["doc_1_chunk_1", "doc_1_chunk_2"],
            ["doc_2_chunk_1", "doc_2_chunk_2"]
        ],
        "input_type": "document",
        "model": "voyage-context-4"
    }
    """;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Authorization", "Bearer " + apiKey)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
    .build();

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

You can access Voyage contextualized chunk embeddings in Go by sending HTTP requests using the standard net/http package.

Example

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    apiKey := os.Getenv("VOYAGE_API_KEY")
    url := "https://api.voyageai.com/v1/contextualizedembeddings"

    // Example input containing chunks from two documents
    inputs := [][]string{
        {"doc_1_chunk_1", "doc_1_chunk_2"},
        {"doc_2_chunk_1", "doc_2_chunk_2"},
    }

    requestBody := map[string]interface{}{
        "inputs":     inputs,
        "input_type": "document",
        "model":      "voyage-context-4",
    }

    jsonData, _ := json.Marshal(requestBody)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

REST API

Voyage contextualized chunk embeddings are available at:

POST https://api.voyageai.com/v1/contextualizedembeddings

See the Contextualized Embeddings API reference.

Response Shape

The REST API returns chunk text as text on each individual embedding item, not as a top-level chunk_texts list.

{
  "data": [
    {
      "data": [
        { "embedding": ["..."], "index": 0, "text": "chunk text here" },
        { "embedding": ["..."], "index": 1, "text": "..." }
      ],
      "index": 0
    }
  ],
  "model": "voyage-context-4",
  "usage": { "total_tokens": 100 },
  "chunker_version": "1.0.0"
}

• data - A list of results, one per input query or document.

• data[].data - A list of embedding items for that input.

• data[].data[].embedding - The embedding vector.

• data[].data[].index - The chunk index within that input.

• data[].data[].text - The returned chunk text for that embedding item.

• model - The model used.

• usage.total_tokens - Total tokens processed.

• chunker_version - The version of the server-side chunker. This is returned when auto-chunking is enabled.

Example

curl -X POST https://api.voyageai.com/v1/contextualizedembeddings \
  -H "Authorization: Bearer $VOYAGE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "inputs": [
      "This is the SEC filing on Leafy Inc.'\''s Q2 2024 performance.\nThe company'\''s revenue increased by 15% compared to the previous quarter.",
      "This is the SEC filing on Elephant Ltd.'\''s Q2 2024 performance.\nThe company'\''s revenue decreased by 2% compared to the previous quarter."
    ],
    "input_type": "document",
    "model": "voyage-context-4",
    "enable_auto_chunking": true,
    "chunk_size": 512,
    "chunk_overlap": 0
  }'