FastembedRanker

Rank documents by their similarity to a query using Fastembed cross-encoder models.

Key Features

• Reranks documents based on semantic similarity to the query using cross-encoder models.
• Uses CPU-optimized models from the Fastembed library.
• Returns documents sorted from most to least relevant.
• Configurable number of results with top_k.
• Supports optional score threshold to filter out low-quality results.
• Can include metadata fields in the document text for ranking.

Configuration

1. Drag the FastembedRanker 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_name to the Fastembed cross-encoder model to use (for example, Xenova/ms-marco-MiniLM-L-6-v2). For supported models, see the Fastembed documentation.
   2. Set top_k to limit the number of documents returned.
4. Go to the Advanced tab to configure score_threshold, meta_fields_to_embed, and batch_size.

Connections

FastembedRanker receives a query string and a list of documents from a retriever. It outputs a reranked list of documents, sorted by relevance to the query.

Source Code

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

Usage Examples

Basic Configuration

  FastembedRanker:
    type: haystack_integrations.components.rankers.fastembed.FastembedRanker
    init_parameters:
      model_name: Xenova/ms-marco-MiniLM-L-6-v2
      top_k: 5
      batch_size: 64

Using the Component in a Pipeline

# haystack-pipeline
components:
  retriever:
    type: haystack_integrations.components.retrievers.qdrant.retriever.QdrantEmbeddingRetriever
    init_parameters:
      top_k: 20
      document_store:
        type: haystack_integrations.document_stores.qdrant.document_store.QdrantDocumentStore
        init_parameters:
          url: http://localhost:6333
          index: documents

  FastembedRanker:
    type: haystack_integrations.components.rankers.fastembed.FastembedRanker
    init_parameters:
      model_name: Xenova/ms-marco-MiniLM-L-6-v2
      top_k: 5

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

max_runs_per_component: 100

metadata: {}

inputs:
  query:
  - FastembedRanker.query

Parameters

Inputs

Parameter	Type	Description
query	str	The query to rank documents against.
documents	List[Document]	A list of documents to rerank.
top_k	Optional[int]	The maximum number of documents to return. Overrides the init-time top_k.

Outputs

Parameter	Type	Description
documents	List[Document]	The reranked documents, sorted from most to least relevant.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
model_name	str	Xenova/ms-marco-MiniLM-L-6-v2	The name of the Fastembed cross-encoder model to use.
top_k	int	10	The maximum number of documents to return.
cache_dir	Optional[str]	None	The directory to cache downloaded models.
threads	Optional[int]	None	The number of threads for model inference.
batch_size	int	64	The number of document pairs to score in each batch.
parallel	Optional[int]	None	The number of parallel processes for batch processing.
local_files_only	bool	False	Whether to use only locally cached models.
meta_fields_to_embed	Optional[List[str]]	None	A list of document metadata field names to include in the text when scoring.
meta_data_separator	str	"\n"	The separator used to join the document text and metadata fields.
score_threshold	Optional[float]	None	A minimum score threshold. Documents below this score are filtered out.

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 query to rank documents against.
documents	List[Document]		A list of documents to rerank.
top_k	Optional[int]	None	The maximum number of documents to return. Overrides the init-time top_k.

Related Information

• Pipeline Components