Embeddings

Generate embedding batches with OpenAI, Google Gemini, and Mistral through Batchwork's normalized embedding result types.

Embeddings are supported through OpenAI, Google Gemini, and Mistral.

Submit embeddings

from batchwork import BatchEmbeddingRequest, Batchwork

requests = [
    BatchEmbeddingRequest(custom_id="doc-1", value="First document"),
    BatchEmbeddingRequest(custom_id="doc-2", value="Second document"),
]

async with Batchwork() as client:
    job = await client.batch_embeddings(
        model="openai/text-embedding-3-small",
        requests=requests,
    )
    await job.wait(timeout=3600)
    vectors = {
        result.custom_id: result.embedding
        for result in await job.collect()
        if result.status == "succeeded"
    }

Each request contains one value. Results expose the vector through result.embedding. Use dimensions on a request or BatchEmbeddingDefaults for providers that support a reduced width:

from batchwork import BatchEmbeddingDefaults

job = await client.batch_embeddings(
    model="openai/text-embedding-3-small",
    requests=[
        BatchEmbeddingRequest(value="Uses the batch default"),
        BatchEmbeddingRequest(value="Overrides the default", dimensions=512),
    ],
    defaults=BatchEmbeddingDefaults(dimensions=256),
)

Record values override defaults. OpenAI and Google support canonical dimensions; Mistral rejects it before submission.

CLI

batchwork submit embeddings requests.jsonl \
  --model openai/text-embedding-3-small \
  --dimensions 256

batchwork run embeddings values.txt \
  --format text \
  --model google/gemini-embedding-001

JSON and JSONL map directly to BatchEmbeddingRequest. CSV accepts value, custom_id, and dimensions; text maps each non-whitespace line to one value. Missing IDs are generated as request-0, request-1, and so on. Human results show vector dimensions without printing vectors; JSON and JSONL preserve the complete vectors.

Provider coverage

Provider	Submission	Results	Notes
OpenAI	JSONL file through `/v1/embeddings`	Output/error JSONL files	Supports canonical dimensions and the `user` provider option.
Google	Inline `:asyncBatchEmbedContent` operation	Inline response	Supports output dimensionality, task type, and title.
Mistral	JSONL file and Batch Job	Output/error JSONL files	Canonical dimensions and CLI provider options are unsupported.

Anthropic, Groq, Together AI, and xAI raise UnsupportedProviderError before network I/O.

OpenAI options

request = BatchEmbeddingRequest(
    custom_id="doc-1",
    value="Document text",
    dimensions=256,
    provider_options={"openai": {"user": "tenant-1"}},
)

Google embedding configuration

request = BatchEmbeddingRequest(
    custom_id="search-document",
    value="Document text",
    dimensions=256,
    provider_options={
        "google": {
            "taskType": "RETRIEVAL_DOCUMENT",
            "title": "Document title",
        }
    },
)

Batchwork moves these values into Google’s batch-level embedContentConfig where required.

Correlation and failures

Output order is not stable. Join vectors through custom_id and handle item-level errors before storing embeddings.

async for result in job.results():
    if result.status == "succeeded" and result.embedding is not None:
        await vector_store.put(result.custom_id, result.embedding)
    elif result.status == "errored":
        await record_failure(result.custom_id, result.error)

Model IDs in examples are illustrative. Select a current batch-compatible embedding model from the provider’s documentation.