Implementation:Deepset ai Haystack SentenceTransformersTextEmbedder

Metadata

Field	Value
Implementation Name	SentenceTransformersTextEmbedder
Implementing Principle	Deepset_ai_Haystack_Query_Text_Embedding
Class	`SentenceTransformersTextEmbedder`
Module	`haystack.components.embedders.sentence_transformers_text_embedder`
Source Reference	`haystack/components/embedders/sentence_transformers_text_embedder.py:L17-243`
Repository	Deepset_ai_Haystack
Dependencies	sentence-transformers, torch

Overview

SentenceTransformersTextEmbedder is a Haystack component that embeds a single text string using a Sentence Transformers model. It is designed for query-time use in retrieval pipelines, where the user's query must be converted to a dense vector for comparison against pre-embedded documents. The component outputs a single embedding vector as a list[float].

Description

This component serves as the query-side counterpart to SentenceTransformersDocumentEmbedder. While the document embedder processes a list of Document objects and populates their embedding fields, the text embedder takes a single raw string and returns its embedding directly.

Key behaviors:

Single string input: The run() method accepts exactly one string. Passing a list or non-string type raises a TypeError with a message directing the user to use SentenceTransformersDocumentEmbedder instead.
Lazy initialization: The model is loaded on the first call to warm_up() or automatically on the first run() invocation.
Prefix/suffix support: The text is transformed as prefix + text + suffix before embedding, supporting instruction-based models (E5, BGE).
Model consistency: This component must use the same model, normalization, and precision settings as the document embedder to ensure vectors are in the same space.

Code Reference

Import

from haystack.components.embedders import SentenceTransformersTextEmbedder

Constructor Signature

SentenceTransformersTextEmbedder(
    model: str = "sentence-transformers/all-mpnet-base-v2",
    device: ComponentDevice | None = None,
    token: Secret | None = Secret.from_env_var(["HF_API_TOKEN", "HF_TOKEN"], strict=False),
    prefix: str = "",
    suffix: str = "",
    batch_size: int = 32,
    progress_bar: bool = True,
    normalize_embeddings: bool = False,
    trust_remote_code: bool = False,
    local_files_only: bool = False,
    truncate_dim: int | None = None,
    model_kwargs: dict[str, Any] | None = None,
    tokenizer_kwargs: dict[str, Any] | None = None,
    config_kwargs: dict[str, Any] | None = None,
    precision: Literal["float32", "int8", "uint8", "binary", "ubinary"] = "float32",
    encode_kwargs: dict[str, Any] | None = None,
    backend: Literal["torch", "onnx", "openvino"] = "torch",
    revision: str | None = None,
)

Parameter	Type	Default	Description
`model`	`str`	`"sentence-transformers/all-mpnet-base-v2"`	Hugging Face model ID or local path for the embedding model.
`device`	None	`None`	Device to load the model on. If None, uses the default device.
`token`	None	env var	API token for private Hugging Face models.
`prefix`	`str`	`""`	String prepended to the text before embedding.
`suffix`	`str`	`""`	String appended to the text before embedding.
`batch_size`	`int`	`32`	Batch size for encoding (used internally even for single text).
`progress_bar`	`bool`	`True`	Whether to display a progress bar.
`normalize_embeddings`	`bool`	`False`	If True, L2-normalizes the embedding to unit length.
`trust_remote_code`	`bool`	`False`	Whether to allow custom model code from Hugging Face.
`local_files_only`	`bool`	`False`	If True, only use locally cached models.
`truncate_dim`	None	`None`	Truncate embeddings to this dimensionality (Matryoshka support).
`model_kwargs`	None	`None`	Additional kwargs for model loading.
`tokenizer_kwargs`	None	`None`	Additional kwargs for tokenizer loading.
`config_kwargs`	None	`None`	Additional kwargs for config loading.
`precision`	`Literal[...]`	`"float32"`	Embedding precision: float32, int8, uint8, binary, or ubinary.
`encode_kwargs`	None	`None`	Additional kwargs passed to `SentenceTransformer.encode`.
`backend`	`Literal[...]`	`"torch"`	Inference backend: torch, onnx, or openvino.
`revision`	None	`None`	Specific model version (branch, tag, or commit ID).

I/O Contract

Input

Parameter	Type	Required	Description
`text`	`str`	Yes	The query text string to embed.

Output

Key	Type	Description
`embedding`	`list[float]`	The dense vector embedding of the input text.

The output dictionary has the structure:

{"embedding": list[float]}

Usage Examples

Basic Query Embedding

from haystack.components.embedders import SentenceTransformersTextEmbedder

text_embedder = SentenceTransformersTextEmbedder()
text_embedder.warm_up()

result = text_embedder.run("I love pizza!")
print(result["embedding"])
# [-0.07804739475250244, 0.1498992145061493, ...]

Embedding with Instruction Prefix (E5 Model)

from haystack.components.embedders import SentenceTransformersTextEmbedder

text_embedder = SentenceTransformersTextEmbedder(
    model="intfloat/e5-large-v2",
    prefix="query: ",
    normalize_embeddings=True,
)
text_embedder.warm_up()

result = text_embedder.run("What is semantic search?")
print(f"Embedding dimension: {len(result['embedding'])}")

In a Query Pipeline

from haystack import Pipeline
from haystack.components.embedders import SentenceTransformersTextEmbedder
from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
from haystack.document_stores.in_memory import InMemoryDocumentStore

document_store = InMemoryDocumentStore()
# (assume documents have been pre-embedded and written to document_store)

query_pipeline = Pipeline()
query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder(
    model="sentence-transformers/all-mpnet-base-v2",
    normalize_embeddings=True,
))
query_pipeline.add_component("retriever", InMemoryEmbeddingRetriever(document_store=document_store))
query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")

result = query_pipeline.run({"text_embedder": {"text": "What is Haystack?"}})
for doc in result["retriever"]["documents"]:
    print(doc.content, doc.score)

Related Pages

Principle: Deepset_ai_Haystack_Query_Text_Embedding -- The principle that this component implements.
Related Implementation: Deepset_ai_Haystack_SentenceTransformersDocumentEmbedder -- The document-side embedder using the same model family.
Related Implementation: Deepset_ai_Haystack_InMemoryEmbeddingRetriever -- Retriever that consumes the embedding produced by this component.

Implements Principle

Principle:Deepset_ai_Haystack_Query_Text_Embedding

Requires Environment

Uses Heuristic

Heuristic:Deepset_ai_Haystack_Embedding_Batch_Size_And_Prefix

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment