Creates contextualized vector embeddings for document chunks. These embeddings capture both local details within each chunk and global context from the entire document.
This endpoint accepts queries, full documents, or document chunks and returns embeddings that are context-aware across the entire document.
Body
Required
-
A list of lists, where each inner list contains a query, a document, or document chunks to be vectorized.
Each inner list in
inputsrepresents a set of text elements that are embedded together. Each element in the list is encoded not just independently, but also encodes context from the other elements in the same list.inputs = [["text_1_1", "text_1_2", ..., "text_1_n"], ["text_2_1", "text_2_2", ..., "text_2_m"]]Document Chunks. Most commonly, each inner list contains chunks from a single document, ordered by their position in the document. In this case:
inputs = [["doc_1_chunk_1", "doc_1_chunk_2", ..., "doc_1_chunk_n"], ["doc_2_chunk_1", "doc_2_chunk_2", ..., "doc_2_chunk_m"]]Each chunk is encoded in context with the others from the same document, resulting in more context-aware embeddings. Supplied chunks should not have any overlap.
Context-Agnostic Behavior for Queries and Documents. If there is one element per inner list, each text is embedded independently—similar to standard (context-agnostic) embeddings:
inputs = [["query_1"], ["query_2"], ..., ["query_k"]] inputs = [["doc_1"], ["doc_2"], ..., ["doc_k"]]Therefore, if the inputs are queries, each inner list should contain a single query (a length of one), as shown above, and the
input_typeshould be set toquery.The following constraints apply to the
inputslist:- The list must not contain more than 1,000 inputs.
- The total number of tokens across all inputs must not exceed 120K.
- The total number of chunks across all inputs must not exceed 16K.
For queries, the list contains only a single query. For documents or document chunks, the list should include all chunks from a single document, ordered by their position in the document, or the entire document may be provided as a single chunk. The total number of tokens in the list must not exceed 32,000 tokens.
At least
1but not more than1000elements.For queries, the list contains only a single query. For documents or document chunks, the list should include all chunks from a single document, ordered by their position in the document, or the entire document may be provided as a single chunk. The total number of tokens in the list must not exceed 32,000 tokens.
At least
1element. Minimum length of each is1. -
The contextualized embedding model to use. Recommended model:
voyage-context-3.Value is
voyage-context-3. -
Type of the input text. Defaults to
null. Other options:query,document.- When
input_typeisnull, the embedding model directly converts the inputs into numerical vectors. For retrieval or search purposes, where a "query" searches for relevant information among a collection of data referred to as "documents," specify whether your inputs are queries or documents by settinginput_typetoqueryordocument, respectively. In these cases, Voyage automatically prepends a prompt to yourinputsbefore vectorizing them, creating vectors more tailored for retrieval or search tasks. Embeddings generated with and without theinput_typeargument are compatible. - For transparency, the following prompts are prepended to your input:
- For
query, the prompt is "Represent the query for retrieving supporting documents: ". - For
document, the prompt is "Represent the document for retrieval: ".
- For
Values are
query,document, or null. - When
-
The number of dimensions for resulting output embeddings. Defaults to
null.voyage-context-3supports the followingoutput_dimensionvalues: 2048, 1024 (default), 512, and 256. If set tonull, the model uses the default value of 1024.Values are
256,512,1024,2048, or null. -
The data type for the embeddings to be returned. Defaults to
float. Other options:int8,uint8,binary,ubinary.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.int8anduint8: Each returned embedding is a list of 8-bit (1-byte) integers ranging from -128 to 127 and 0 to 255, respectively.binaryandubinary: Each returned embedding is a list of 8-bit integers that represent bit-packed, quantized single-bit embedding values:int8forbinaryanduint8forubinary. The length of the returned list of integers is 1/8 ofoutput_dimension(which is the actual dimension of the embedding). Thebinarytype uses the offset binary method.
Default value is
float. -
Format in which the embeddings are encoded. Defaults to
null. Other options:base64.- If
null, each embedding is an array of float numbers whenoutput_dtypeis set tofloatand an array of integers for all other values ofoutput_dtype(int8,uint8,binary, andubinary). Seeoutput_dtypefor more details. - If
base64, the embeddings are represented as a Base64-encoded NumPy array of:- Floating-point numbers (numpy.float32) for
output_dtypeset tofloat. - Signed integers (numpy.int8) for
output_dtypeset toint8orbinary. - Unsigned integers (numpy.uint8) for
output_dtypeset touint8orubinary.
- Floating-point numbers (numpy.float32) for
Values are
base64or null. - If
curl \
--request POST 'https://ai.mongodb.com/v1/contextualizedembeddings' \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data '{"inputs":[["string"]],"model":"voyage-context-3","input_type":"query","output_dimension":256,"output_dtype":"float","encoding_format":"base64"}'{
"inputs": [
[
"string"
]
],
"model": "voyage-context-3",
"input_type": "query",
"output_dimension": 256,
"output_dtype": "float",
"encoding_format": "base64"
}{
"object": "list",
"data": [
{
"object": "list",
"data": [
{
"object": "embedding",
"embedding": [
42.0
],
"index": 42
}
],
"index": 42
}
],
"model": "string",
"usage": {
"total_tokens": 42
}
}{
"detail": "string"
}{
"detail": "string"
}{
"detail": "string"
}{
"detail": "string"
}{
"detail": "string"
}{
"detail": "string"
}{
"detail": "string"
}{
"detail": "string"
}