Embedders

Embedders convert text into vector embeddings for semantic search. Embeddings capture the semantic meaning of text, allowing similar concepts to be found even with different wording.

Embedder API

All embedders implement the Embedder abstract base class, which provides four methods:

Method	Signature	Description
`embed`	`(texts: list[str], context: RetrievalContext = RetrievalContext()) -> EmbeddingResult`	Core method: embed a batch of strings.
`embed_chunks`	`(chunks: list[DocumentChunk]) -> list[DocumentChunk]`	Embed chunks and return copies with embeddings set.
`embed_query`	`(text: str, context: RetrievalContext = RetrievalContext()) -> list[float]`	Embed a single string and return the vector.
`process`	`(document: Document, context: IngestContext) -> Document`	Embed the chunks of a document. `Pipeline` calls it.

Only embed is abstract. The other methods are built on top of it.

`EmbeddingResult`

Returned by embed:

from pydantic import BaseModel

class EmbeddingResult(BaseModel):
    embeddings: list[list[float]]  # One embedding per input
    total_tokens: int              # Total tokens consumed

from pydantic import BaseModel

class EmbeddingResult(BaseModel):
    embeddings: list[list[float]]  # One embedding per input
    total_tokens: int              # Total tokens consumed

Mistral Embedder

MistralEmbedder calls the Mistral embeddings API to vectorize text.

Installation: Core library (no extra required)

Example:

from mistralai.client import Mistral
from mistralai.search.toolkit.embedding import MistralEmbedder, MODEL_1024_EMBEDDING

client = Mistral(api_key="your-api-key")
embedder = MistralEmbedder(
    client=client,
    model_name=MODEL_1024_EMBEDDING,
)
embedded_chunks = await embedder.embed_chunks(chunks)

from mistralai.client import Mistral
from mistralai.search.toolkit.embedding import MistralEmbedder, MODEL_1024_EMBEDDING

client = Mistral(api_key="your-api-key")
embedder = MistralEmbedder(
    client=client,
    model_name=MODEL_1024_EMBEDDING,
)
embedded_chunks = await embedder.embed_chunks(chunks)

Configuration:

Option	Type	Default	Purpose
`model_name`	str	`MODEL_128_EMBEDDING`	Embedding model to use (see the model constants in the next table)
`client`	`Mistral \| None`	`None`	Mistral client. When `None`, the embedder builds one from `MISTRAL_API_KEY`
`max_concurrency`	`int \| asyncio.Semaphore \| None`	`10`	Maximum number of concurrent embedding requests

Embedding model constants:

Use these predefined constants when configuring MistralEmbedder. The dimensions must match the embedding_model set on your index schema. Pair each constant with the matching MistralEmbeddingPreset (see Embedding models).

Constant	Model Name	Dimensions	Matching preset	Best for
`MODEL_1024_EMBEDDING`	`"mistral-embed"`	1024	`MistralEmbeddingPreset.MISTRAL_EMBED_DIM_1024`	Full-dimension model; pass it explicitly
`MODEL_256_EMBEDDING`	`"mistral-embed-dim256-2510"`	256	`MistralEmbeddingPreset.MISTRAL_EMBED_DIM_256`	Low-latency, memory-constrained environments
`MODEL_128_EMBEDDING`	`"mistral-embed-dim128-2510"`	128	`MistralEmbeddingPreset.MISTRAL_EMBED_DIM_128`	Minimum dimensions; `MistralEmbedder` default

Import and usage:

from mistralai.search.toolkit.embedding import MistralEmbedder, MODEL_1024_EMBEDDING, MODEL_256_EMBEDDING, MODEL_128_EMBEDDING

# Use the full-dimension model
embedder = MistralEmbedder(client=client, model_name=MODEL_1024_EMBEDDING)

# Or use a different model for specific use cases
embedder_compact = MistralEmbedder(client=client, model_name=MODEL_256_EMBEDDING)

from mistralai.search.toolkit.embedding import MistralEmbedder, MODEL_1024_EMBEDDING, MODEL_256_EMBEDDING, MODEL_128_EMBEDDING

# Use the full-dimension model
embedder = MistralEmbedder(client=client, model_name=MODEL_1024_EMBEDDING)

# Or use a different model for specific use cases
embedder_compact = MistralEmbedder(client=client, model_name=MODEL_256_EMBEDDING)

Batch processing (automatic):

# embed_chunks handles batching internally
chunks_with_embeddings = await embedder.embed_chunks(chunks)

# For custom batching, embed() returns an EmbeddingResult (result.embeddings)
result = await embedder.embed([
    "text 1",
    "text 2",
    "text 3",
])

# embed_chunks handles batching internally
chunks_with_embeddings = await embedder.embed_chunks(chunks)

# For custom batching, embed() returns an EmbeddingResult (result.embeddings)
result = await embedder.embed([
    "text 1",
    "text 2",
    "text 3",
])

Custom embedders

Implement the Embedder base class with a single embed method:

from mistralai.search.toolkit.context import RetrievalContext
from mistralai.search.toolkit.embedding import Embedder, EmbeddingResult


class MyEmbedder(Embedder):
    async def embed(self, texts: list[str], context: RetrievalContext = RetrievalContext()) -> EmbeddingResult:
        embeddings = my_provider.embed(texts)
        return EmbeddingResult(
            embeddings=embeddings,
            total_tokens=sum(len(t.split()) for t in texts),
        )


embedder = MyEmbedder(model_name="my-model")  # Embedder.__init__ requires model_name

from mistralai.search.toolkit.context import RetrievalContext
from mistralai.search.toolkit.embedding import Embedder, EmbeddingResult


class MyEmbedder(Embedder):
    async def embed(self, texts: list[str], context: RetrievalContext = RetrievalContext()) -> EmbeddingResult:
        embeddings = my_provider.embed(texts)
        return EmbeddingResult(
            embeddings=embeddings,
            total_tokens=sum(len(t.split()) for t in texts),
        )


embedder = MyEmbedder(model_name="my-model")  # Embedder.__init__ requires model_name

embed_chunks and embed_query are inherited automatically.

When you use a custom embedder, declare a CustomEmbeddingModel on your index schema with matching dimensions, data type, and distance metric. The schema describes the index, while the embedder produces the vectors. They must agree on the vector shape. See Embedding models for the distinction between MistralEmbeddingModel and CustomEmbeddingModel.