SentenceTransformersSimilarityRanker

Rank documents based on their semantic similarity to the query using a Sentence Transformers cross-encoder model. Use this component as a reranker after retrieval to improve answer quality.

Key Features

• Uses a pre-trained cross-encoder model to score query-document pairs.
• Configurable number of results returned via top_k.
• Supports score scaling via Sigmoid activation for normalized similarity scores.
• Supports filtering by score threshold.
• Deduplicates documents by ID before ranking.
• Supports multiple backends: PyTorch, ONNX, and OpenVINO.

Configuration

1. Drag the SentenceTransformersSimilarityRanker 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 ranking model. Pass a local path or the Hugging Face model name of a cross-encoder model. The default is cross-encoder/ms-marco-MiniLM-L-6-v2.
   2. Set top_k to control how many documents to return.
4. Go to the Advanced tab to configure scale_score, score_threshold, batch_size, backend, and meta_fields_to_embed.

Connections

SentenceTransformersSimilarityRanker accepts a query string and a list of documents as inputs. Connect it after a retriever or DocumentJoiner in a query pipeline.

It outputs a ranked list of documents sorted from most to least relevant to the query. Connect its documents output to ChatPromptBuilder, AnswerBuilder, or another downstream component.

Source Code

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

Usage Examples

Basic Configuration

  SentenceTransformersSimilarityRanker:
    type: haystack_integrations.components.rankers.sentence_transformers.SentenceTransformersSimilarityRanker
    init_parameters:
      model: cross-encoder/ms-marco-MiniLM-L-6-v2
      top_k: 5
      scale_score: true

Using the Component in a Pipeline

# haystack-pipeline
components:
  retriever:
    type: haystack.components.retrievers.in_memory.embedding_retriever.InMemoryEmbeddingRetriever
    init_parameters:
      document_store:
        type: haystack.document_stores.in_memory.document_store.InMemoryDocumentStore
        init_parameters: {}
      top_k: 20

  ranker:
    type: haystack_integrations.components.rankers.sentence_transformers.SentenceTransformersSimilarityRanker
    init_parameters:
      model: cross-encoder/ms-marco-MiniLM-L-6-v2
      top_k: 5

connections:
- sender: retriever.documents
  receiver: ranker.documents

max_runs_per_component: 100

metadata: {}

inputs:
  query:
  - ranker.query

outputs:
  documents: ranker.documents

Parameters

Inputs

Parameter	Type	Description
query	str	The input query to compare the documents to.
documents	List[Document]	A list of documents to be ranked.
top_k	Optional[int]	The maximum number of documents to return. Overrides the init-time value.
scale_score	Optional[bool]	If True, scales raw logit predictions using a Sigmoid activation function. Overrides the init-time value.
score_threshold	Optional[float]	Return documents only with a score above this threshold. Overrides the init-time value.

Outputs

Parameter	Type	Description
documents	List[Document]	Documents closest to the query, sorted from most similar to least similar.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
model	Union[str, Path]	cross-encoder/ms-marco-MiniLM-L-6-v2	The ranking model. Pass a local path or the Hugging Face model name of a cross-encoder model.
device	Optional[ComponentDevice]	None	The device on which the model is loaded.
token	Optional[Secret]	Secret.from_env_var(["HF_API_TOKEN", "HF_TOKEN"], strict=False)	The API token to download private models from Hugging Face.
top_k	int	10	The maximum number of documents to return per query.
query_prefix	str	""	A string to add at the beginning of the query text before ranking.
query_suffix	str	""	A string to add at the end of the query text before ranking.
document_prefix	str	""	A string to add at the beginning of each document before ranking.
document_suffix	str	""	A string to add at the end of each document before ranking.
meta_fields_to_embed	Optional[List[str]]	None	List of metadata fields to include when ranking each document.
embedding_separator	str	\n	Separator to concatenate metadata fields to the document.
scale_score	bool	True	If True, scales raw logit predictions using a Sigmoid activation function.
score_threshold	Optional[float]	None	Return documents with a score above this threshold only.
trust_remote_code	bool	False	Whether to allow custom models and scripts from Hugging Face.
model_kwargs	Optional[Dict[str, Any]]	None	Additional keyword arguments for 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.
backend	Literal["torch", "onnx", "openvino"]	torch	The backend to use for the Sentence Transformers model.
batch_size	int	16	The batch size to use for inference.

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
query	str		The input query to compare the documents to.
documents	List[Document]		A list of documents to be ranked.
top_k	Optional[int]	None	The maximum number of documents to return.
scale_score	Optional[bool]	None	Whether to scale scores with a Sigmoid function.
score_threshold	Optional[float]	None	Minimum score threshold for returned documents.

Related Information

• SentenceTransformersDiversityRanker
• Pipeline Components