HuggingFaceTEIRanker

Ranks documents based on their semantic similarity to the query.

Basic Information

• Type: haystack_integrations.rankers.hugging_face_tei.HuggingFaceTEIRanker

Inputs

Parameter	Type	Default	Description
query	str		The user query string to guide reranking.
documents	List[Document]		List of Document objects to rerank.
top_k	Optional[int]	None	Optional override for the maximum number of documents to return.
truncation_direction	Optional[TruncationDirection]	None	If set, enables text truncation in the specified direction.

Outputs

Parameter	Type	Default	Description
documents	List[Document]		A dictionary with the following keys: - documents: A list of reranked documents.

Overview

Work in Progress

Bear with us while we're working on adding pipeline examples and most common components connections.

Ranks documents based on their semantic similarity to the query.

It can be used with a Text Embeddings Inference (TEI) API endpoint:

• Self-hosted Text Embeddings Inference
• Hugging Face Inference Endpoints

Usage example:

from haystack import Document
from haystack.components.rankers import HuggingFaceTEIRanker
from haystack.utils import Secret

reranker = HuggingFaceTEIRanker(
    url="http://localhost:8080",
    top_k=5,
    timeout=30,
    token=Secret.from_token("my_api_token")
)

docs = [Document(content="The capital of France is Paris"), Document(content="The capital of Germany is Berlin")]

result = reranker.run(query="What is the capital of France?", documents=docs)

ranked_docs = result["documents"]
print(ranked_docs)
>> {'documents': [Document(id=..., content: 'the capital of France is Paris', score: 0.9979767),
>>                Document(id=..., content: 'the capital of Germany is Berlin', score: 0.13982213)]}

Usage Example

components:
  HuggingFaceTEIRanker:
    type: components.rankers.hugging_face_tei.HuggingFaceTEIRanker
    init_parameters:

Parameters

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
url	str		Base URL of the TEI reranking service (for example, "https://api.example.com").
top_k	int	10	Maximum number of top documents to return.
raw_scores	bool	False	If True, include raw relevance scores in the API payload.
timeout	Optional[int]	30	Request timeout in seconds.
max_retries	int	3	Maximum number of retry attempts for failed requests.
retry_status_codes	Optional[List[int]]	None	List of HTTP status codes that will trigger a retry. When None, HTTP 408, 418, 429 and 503 will be retried (default: None).
token	Optional[Secret]	Secret.from_env_var(['HF_API_TOKEN', 'HF_TOKEN'], strict=False)	The Hugging Face token to use as HTTP bearer authorization. Not always required depending on your TEI server configuration. Check your HF token in your account settings.

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 user query string to guide reranking.
documents	List[Document]		List of Document objects to rerank.
top_k	Optional[int]	None	Optional override for the maximum number of documents to return.
truncation_direction	Optional[TruncationDirection]	None	If set, enables text truncation in the specified direction.