SentenceTransformersDocumentEmbedder

Compute embeddings for a list of documents using Sentence Transformers models. Use this component in indexing pipelines to prepare documents for embedding-based retrieval.

Key Features

• Works with any model available on Hugging Face that is compatible with Sentence Transformers.
• Stores the computed embedding in each document's embedding field.
• Supports embedding metadata fields alongside document content.
• Supports multiple embedding precisions including float32, int8, uint8, binary, and ubinary.
• Supports model quantization and custom backends (PyTorch, ONNX, OpenVINO).

Embedding Models in Query Pipelines and Indexes

The embedding model you use to embed documents in your indexing pipeline must be the same as the embedding model you use to embed the query in your query pipeline.

This means the embedders for your indexing and query pipelines must match. For example, if you use CohereDocumentEmbedder to embed your documents, you should use CohereTextEmbedder with the same model to embed your queries.

Configuration

1. Drag the SentenceTransformersDocumentEmbedder component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the General tab:
   1. Set the model to the Sentence Transformers model you want to use (for example, sentence-transformers/all-mpnet-base-v2).
   2. Optionally set a Hugging Face token if using private or gated models.
4. Go to the Advanced tab to configure meta_fields_to_embed, embedding_separator, normalize_embeddings, batch_size, and precision.

Connections

SentenceTransformersDocumentEmbedder receives a list of documents, typically from a document splitter or converter. It outputs the same documents with embeddings added to their embedding field, ready to be sent to a DocumentWriter.

Source Code

To check this component's source code, open sentence_transformers_document_embedder.py in the Haystack Core Integrations repository.

Usage Examples

Basic Configuration

  SentenceTransformersDocumentEmbedder:
    type: haystack_integrations.components.embedders.sentence_transformers.SentenceTransformersDocumentEmbedder
    init_parameters:
      model: sentence-transformers/all-mpnet-base-v2
      batch_size: 32
      normalize_embeddings: false

Using the Component in a Pipeline

# haystack-pipeline
components:
  SentenceTransformersDocumentEmbedder:
    type: haystack_integrations.components.embedders.sentence_transformers.SentenceTransformersDocumentEmbedder
    init_parameters:
      model: sentence-transformers/all-mpnet-base-v2
      batch_size: 32
      normalize_embeddings: false
      token:
        type: env_var
        env_vars:
        - HF_API_TOKEN
        - HF_TOKEN
        strict: false
      meta_fields_to_embed:
      embedding_separator: "\n"

  document_writer:
    type: haystack.components.writers.document_writer.DocumentWriter
    init_parameters:
      document_store:
        type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
        init_parameters:
          hosts:
          index: my-index
          embedding_dim: 768

connections:
- sender: SentenceTransformersDocumentEmbedder.documents
  receiver: document_writer.documents

max_runs_per_component: 100

metadata: {}

Parameters

Inputs

Parameter	Type	Description
documents	List[Document]	A list of documents to embed.

Outputs

Parameter	Type	Description
documents	List[Document]	The documents with their embedding field populated.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
model	str	sentence-transformers/all-mpnet-base-v2	The name of the Sentence Transformers model from Hugging Face.
device	Optional[ComponentDevice]	None	The device to run the model on. If not set, automatically detected.
token	Optional[Secret]	Secret.from_env_var(["HF_API_TOKEN", "HF_TOKEN"])	A Hugging Face token for accessing private or gated models.
prefix	str	""	A string to add at the beginning of each document's text before embedding.
suffix	str	""	A string to add at the end of each document's text before embedding.
batch_size	int	32	The number of documents to process in each batch.
progress_bar	bool	True	Whether to show a progress bar during embedding.
normalize_embeddings	bool	False	Whether to normalize embedding vectors to unit length.
meta_fields_to_embed	Optional[List[str]]	None	A list of document metadata field names to include in the text before embedding.
embedding_separator	str	"\n"	The separator used to join the document text and metadata fields.
trust_remote_code	bool	False	Whether to trust remote code when loading models with custom code.
local_files_only	bool	False	Whether to use only local files, without downloading from Hugging Face.
truncate_dim	Optional[int]	None	The dimension to truncate the embedding to.
model_kwargs	Optional[Dict[str, Any]]	None	Additional keyword arguments passed to the model constructor.
tokenizer_kwargs	Optional[Dict[str, Any]]	None	Additional keyword arguments for the tokenizer.
config_kwargs	Optional[Dict[str, Any]]	None	Additional keyword arguments for the model configuration.
precision	Literal["float32", "int8", "uint8", "binary", "ubinary"]	"float32"	The precision of the output embeddings.
encode_kwargs	Optional[Dict[str, Any]]	None	Additional keyword arguments for the encode() method.
backend	Literal["torch", "onnx", "openvino"]	"torch"	The backend to use for inference.
revision	Optional[str]	None	The model revision to use.

Run Method Parameters

These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see Modify Pipeline Parameters at Query Time.

Parameter	Type	Default	Description
documents	List[Document]		A list of documents to embed.

Related Information

• Pipeline Components