Skip to main content

agrag.embedding.sentence_transformers.SentenceTransformerEmbedder

SentenceTransformerEmbedder(*, settings:EmbeddingSettings | None = None, cache:EmbeddingCache | None = None, model:object | None = None, tracer:Tracer | None = None) -> None

Bases: Embedder

An embedder backed by sentence-transformers.

The model loads lazily on first embed, so constructing the embedder does not touch the GPU or download weights. Every blocking call into the model runs in a worker thread (asyncio.to_thread), so the event loop stays free for other work while a large batch encodes.

Functions:

  • dimensions – Return the dimension the loaded model produces.
  • embed – Embed a batch of texts, using the cache where possible.
  • embed_one – Embed a single text.

Attributes:

  • distance (Distance) – Return the distance metric for vector indexes created for this embedder.
  • model (str) – The configured model name.

Parameters:

  • settings (EmbeddingSettings | None) – Embedder configuration. Defaults to EmbeddingSettings().
  • cache (EmbeddingCache | None) – An optional content-addressed cache. Defaults to a no-op cache.
  • model (object | None) – A pre-built sentence-transformers model, for tests. When set, __init__ imports nothing and embed calls this object directly instead of building one.
  • tracer (Tracer | None) – Opens every span this embedder's methods produce.

dimensions​

dimensions() -> int

Return the dimension the loaded model produces.

Calling this loads the model the first time, the same lock-protected, worker-thread path embed uses, so it is safe to call concurrently with embed without stalling the event loop or loading a second copy of the model.

Raises:

distance​

distance: Distance

Return the distance metric for vector indexes created for this embedder.

Defaults to cosine, which matches normalized sentence-transformer models. Concrete embedders can override when their vectors use a different metric.

embed​

embed(texts:Sequence[str]) -> list[list[float]]

Embed a batch of texts, using the cache where possible.

Parameters:

  • texts (Sequence[str]) – The texts to embed, in order.

Returns:

  • list[list[float]] – One vector per input text, in the same order.

embed_one​

embed_one(text:str) -> list[float]

Embed a single text.

Parameters:

  • text (str) – The text to embed.

Returns:

  • list[float] – The text's embedding vector.

model​

model: str

The configured model name.