Haystack Rankers 组件完全指南：从语义重排到 LLM 上下文编排（v2.20 API 参考与源码解析）-平芜编程栈

Haystack Rankers 组件完全指南：从语义重排到 LLM 上下文编排（v2.20 API 参考与源码解析）

【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack

本指南以 Haystack 官方 v2.20 版本化 API 参考 rankers_api.md 为核心骨架，系统讲解 Haystack 中 7 个 Ranker 组件的功能定位、完整参数签名、代码示例与运行机制。读者将掌握：如何用 TEI 端点或 cross-encoder 模型做语义级重排、如何用 MetaFieldRanker 按元数据二次排序、如何用 MetaFieldGroupingRanker 为 LLM 组织上下文，以及如何用 LostInTheMiddleRanker 与多样性排序优化长上下文输入。文中同时结合当前仓库源码（如 meta_field.py、lost_in_the_middle.py）解析底层实现原理，帮助你在真实 RAG 与 Agent 管线中做出正确的组件选型。

Ranker 组件在 Haystack 中的定位

Ranker（重排序器）是 Haystack 检索增强生成（RAG）管线中负责"二次排序"的一类组件。检索器（Retriever）通常先从文档库中召回数量较多的候选文档，而 Ranker 在此基础上按查询相关度或业务规则对候选文档重新排序，并把最相关的top_k个结果交给后续的 PromptBuilder 与 LLM。在 Haystack 中，每个 Ranker 都是一个@component装饰的组件，统一暴露documents（list[Document]）输出，因此可以无缝插入任何 Pipeline 或 Agent 工作流。

v2.20 版 Rankers API 共包含 7 个组件，按用途可分为三类：

类别	组件	输入特性
语义相似度重排	HuggingFaceTEIRanker、SentenceTransformersSimilarityRanker、TransformersSimilarityRanker	需要`query`+`documents`
元数据驱动排序/分组	MetaFieldRanker、MetaFieldGroupingRanker	仅需要`documents`（利用`meta`字段）
上下文布局优化	LostInTheMiddleRanker、SentenceTransformersDiversityRanker	前者仅需`documents`，后者需要`query`+`documents`

需要说明的是：当前仓库主分支（VERSION.txt 标记为3.2.0-rc0）的 rankers 组件目录已精简为LLMRanker、LostInTheMiddleRanker、MetaFieldRanker、MetaFieldGroupingRanker四个类；而 HuggingFaceTEIRanker 与三个 SentenceTransformers/Transformers 系列组件属于 v2.20 版本化 API 文档所定义的内容。本文以该版本化文档为准逐一展开，并用仍然存在于主分支中的源码佐证底层实现。

HuggingFaceTEIRanker：基于 TEI 端点的语义重排

HuggingFaceTEIRanker根据文档与查询之间的语义相似度对文档重新排序。它通过调用 Text Embeddings Inference（TEI）API 端点完成推理，既可用于自托管 TEI 服务，也可对接 Hugging Face Inference Endpoints 托管的 reranking 模型。

初始化签名

def __init__( *, url: str, top_k: int = 10, raw_scores: bool = False, timeout: Optional[int] = 30, max_retries: int = 3, retry_status_codes: Optional[list[int]] = None, token: Optional[Secret] = Secret.from_env_var(["HF_API_TOKEN", "HF_TOKEN"], strict=False) ) -> None

各参数含义如下：

url（必填）：TEI 重排服务的 Base URL，例如"https://api.example.com"或自托管地址"http://localhost:8080"。
top_k：返回的 Top 文档数量上限，默认 10。
raw_scores：设为True时，请求载荷中会携带原始相关性分数（不做归一化）。
timeout：请求超时时间（秒），默认 30。
max_retries：请求失败时的最大重试次数，默认 3。
retry_status_codes：触发重试的 HTTP 状态码列表。为None时默认对 HTTP 408、418、429 和 503 进行重试。
token：用于 HTTP Bearer 授权的 Hugging Face Token，通过Secret管理，默认从环境变量HF_API_TOKEN或HF_TOKEN读取（strict=False表示未设置时不报错）。是否必需取决于你的 TEI 服务端配置。

完整用法示例

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)]}

run 与 run_async

run方法签名如下：

@component.output_types(documents=list[Document]) def run( query: str, documents: list[Document], top_k: Optional[int] = None, truncation_direction: Optional[TruncationDirection] = None ) -> dict[str, list[Document]]

query：用于引导重排的用户查询字符串。
documents：待重排的Document对象列表。
top_k：可选，运行时覆盖初始化时的返回数量上限。
truncation_direction：可选，设置后按指定方向启用文本截断（当输入长度超过模型上限时）。方向由TruncationDirection枚举定义：LEFT表示从文本左侧（开头）截断，RIGHT表示从文本右侧（结尾）截断。

异常行为：API 请求失败时抛出requests.exceptions.RequestException；API 返回错误响应时抛出RuntimeError。返回值字典的documents键给出重排后的文档列表。

run_async提供异步版本，签名与run一致（query、documents、top_k、truncation_direction），区别在于请求失败时抛出httpx.RequestError。在 Pipeline 以异步模式运行时，可以优先使用它，避免阻塞事件循环。

LostInTheMiddleRanker：为 LLM 长上下文布局文档

LostInTheMiddleRanker基于论文《Lost in the Middle: How Language Models Use Long Contexts》提出的现象设计：当关键信息位于长上下文的中间位置时，LLM 往往更难利用它；而位于开头或结尾的信息更容易被模型关注。该组件据此把最相关的文档放在上下文开头和结尾，最不相关的放在中间，从而提升 LLM 对检索结果的利用率。

它的使用前提是：管线中已有前置组件（如 Retriever）按相关性完成了初步排序，因此它不需要query输入，只接收documents。它通常被用作构建 Prompt 之前的最后一个组件，专门负责把文档内容排布进 LLM 输入上下文。

初始化签名

def __init__(word_count_threshold: Optional[int] = None, top_k: Optional[int] = None)

word_count_threshold：所有被选中文档的总词数上限。指定后，该组件会依次纳入文档，直到再加入一篇文档会超过阈值为止；导致阈值被突破的那篇文档仍会被保留，但其后的所有文档都会被丢弃。
top_k：返回文档数量上限。

用法示例

from haystack.components.rankers import LostInTheMiddleRanker from haystack import Document ranker = LostInTheMiddleRanker() docs = [Document(content="Paris"), Document(content="Berlin"), Document(content="Madrid")] result = ranker.run(documents=docs) for doc in result["documents"]: print(doc.content)

运行机制与源码解析

run的签名支持在运行时覆盖初始化参数：

@component.output_types(documents=list[Document]) def run(documents: list[Document], top_k: Optional[int] = None, word_count_threshold: Optional[int] = None ) -> dict[str, list[Document]]

从 lost_in_the_middle.py 的源码可以看到具体的重排算法（对应第 106-136 行）：

先按文档 id 去重（保留分数最高的副本），再按top_k截取待排序文档；
若只剩 1 篇文档则直接返回；若存在content为None的非文本文档，抛出ValueError；
用索引插入法构建"lost in the middle"顺序：第一个文档放在开头，之后每篇文档插入到当前序列的中间偏后位置（insertion_index = len(lost_in_the_middle_indices) // 2 + len(lost_in_the_middle_indices) % 2）；
若设置了word_count_threshold，在插入的同时累计词数，一旦累计词数达到阈值即停止处理后续文档。

例如对按相关性从高到低排列的[A, B, C, D, E]，最终输出顺序会接近[A, E, D, B, C]——相关性最高的 A 留在开头，次相关的文档被推向中间，保证 LLM 最先和最后看到的内容质量最高。相关的单元测试位于 test_lost_in_the_middle.py，可用于观察各边界场景（单文档、词数阈值、非文本文档报错等）的预期行为。

MetaFieldRanker：按元数据字段二次排序

MetaFieldRanker根据文档meta字典中某个特定字段的值对文档排序，支持降序或升序。典型应用场景包括：按价格、评分、热度、日期等业务字段对检索结果二次排序，并将排序结果与检索器给出的相关性分数按权重融合。

初始化签名

def __init__(meta_field: str, weight: float = 1.0, top_k: Optional[int] = None, ranking_mode: Literal["reciprocal_rank_fusion", "linear_score"] = "reciprocal_rank_fusion", sort_order: Literal["ascending", "descending"] = "descending", missing_meta: Literal["drop", "top", "bottom"] = "bottom", meta_value_type: Optional[Literal["float", "int", "date"]] = None)

参数详解：

meta_field（必填）：用于排序的元数据字段名，例如"rating"。
weight：取值范围 [0, 1]，控制"前序组件（Retriever/Ranker）的相关性排序"与"元字段排序"的权重：
- 0：完全禁用元字段排序，直接返回前序排序结果；
- 0.5：两种排序各占一半权重；
- 1：仅按元字段排序。
top_k：每次查询返回的文档数量上限；不提供时返回全部文档（按新排序顺序）。
ranking_mode：合并 Retriever 分数与 Ranker 分数的方式，取值reciprocal_rank_fusion（默认，即倒数排名融合 RRF）或linear_score（线性分数）。linear_score模式仅适用于分数落在 [0,1] 区间的 Retriever 或 Ranker。
sort_order：元字段排序方向，descending（默认，降序）或ascending（升序）。
missing_meta：对缺少该元字段的文档的处理策略：
- drop：直接丢弃这些文档；
- top：无论升降序，都把它们放在元字段排序结果的最前面；
- bottom（默认）：放在最后面。
meta_value_type：排序前把字符串形式的元数据值解析为指定类型，仅当meta_field下的所有值都是字符串时有效。可选值：
- float：解析为浮点数；
- int：解析为整数；
- date：解析为 datetime 对象（例如"2015-02-01"会被解析后按日期排序）；
- None（默认）：不解析。

用法示例

from haystack import Document from haystack.components.rankers import MetaFieldRanker ranker = MetaFieldRanker(meta_field="rating") docs = [ Document(content="Paris", meta={"rating": 1.3}), Document(content="Berlin", meta={"rating": 0.7}), Document(content="Barcelona", meta={"rating": 2.1}), ] output = ranker.run(documents=docs) docs = output["documents"] assert docs[0].content == "Barcelona"

run 参数与排序流程

run支持对初始化参数做运行时覆盖（top_k、weight、ranking_mode、sort_order、missing_meta、meta_value_type，均为可选，未提供时回退到初始化值）。排序过程分三步（见 meta_field.py 第 162-327 行）：

按元字段排序：先把文档按meta_field的值升序或降序排序；
融合两路排序：按照ranking_mode与weight，把前序组件给出的相关性排序与基于元字段的排序合并；
截取 top-k：返回前top_k篇文档。

实现细节值得注意：

排序前会先调用_deduplicate_documents按文档 id 去重（保留分数最高的副本）；当weight == 0时直接返回去重后的前top_k篇原始文档（第 253-255 行）。
若所有文档都缺少meta_field键，组件会打印警告并直接返回去重后的前top_k篇文档（第 260-270 行）；若只有部分文档缺失，则按missing_meta策略处理并给出相应警告（第 272-295 行）。
类型解析失败（如meta_value_type="date"但值无法解析）或混入不可比较的异构类型（如 int 与 list）导致TypeError时，组件会打印警告并退回按原始顺序返回（第 297-313 行），不会让管线崩溃。
RRF 实现：_calculate_rrf使用1 / (k + rank)，其中常数K取 61（论文建议 60，因 Python 列表从 0 开始编号而原文使用 1-based 排名，故 +1，见 meta_field.py）。
linear_score 实现：_calc_linear_score按(amount - rank) / amount线性缩放，把元字段排名映射到 [0,1] 区间，从而压制离群值、与 Retriever 分数量纲对齐（见 meta_field.py）；同时会校验 Document 自带 score 是否在 [0,1] 内，越界或缺省时按 0 处理并告警（第 387-402 行）。

参数校验在初始化和每次run时都会执行（_validate_params）：top_k必须 > 0，weight必须在 [0,1]，ranking_mode只能是reciprocal_rank_fusion或linear_score，sort_order只能是ascending或descending，meta_value_type只能是float、int、date或None，否则抛出ValueError。对应测试位于 test_metafield.py。

MetaFieldGroupingRanker：按元数据分组编排文档

MetaFieldGroupingRanker通过元数据键对文档进行分组而非排序：用主键group_by分组，用可选次键subgroup_by分组内再分小组，还可以用sort_docs_by键对组/小组内的文档排序。输出是一个按group_by、subgroup_by值排序的扁平文档列表，没有分组的文档会被放在列表末尾。恰当的文档组织有助于提升 LLM 后续处理的效率与效果。

初始化签名

def __init__(group_by: str, subgroup_by: Optional[str] = None, sort_docs_by: Optional[str] = None)

group_by（必填）：用于聚合文档的元数据键。
subgroup_by：可选，在group_by形成的组内再按此键聚合。
sort_docs_by：可选，决定组/小组内文档按哪个元数据键排序；不提供时保持文档在组内的原始插入顺序。

完整用法示例

from haystack.components.rankers import MetaFieldGroupingRanker from haystack.dataclasses import Document docs = [ Document(content="Javascript is a popular programming language", meta={"group": "42", "split_id": 7, "subgroup": "subB"}), Document(content="Python is a popular programming language",meta={"group": "42", "split_id": 4, "subgroup": "subB"}), Document(content="A chromosome is a package of DNA", meta={"group": "314", "split_id": 2, "subgroup": "subC"}), Document(content="An octopus has three hearts", meta={"group": "11", "split_id": 2, "subgroup": "subD"}), Document(content="Java is a popular programming language", meta={"group": "42", "split_id": 3, "subgroup": "subB"}) ] ranker = MetaFieldGroupingRanker(group_by="group",subgroup_by="subgroup", sort_docs_by="split_id") result = ranker.run(documents=docs) print(result["documents"]) # [ # Document(id=d665bbc83e52c08c3d8275bccf4f22bf2bfee21c6e77d78794627637355b8ebc, # content: 'Java is a popular programming language', meta: {'group': '42', 'split_id': 3, 'subgroup': 'subB'}), # Document(id=a20b326f07382b3cbf2ce156092f7c93e8788df5d48f2986957dce2adb5fe3c2, # content: 'Python is a popular programming language', meta: {'group': '42', 'split_id': 4, 'subgroup': 'subB'}), # Document(id=ce12919795d22f6ca214d0f161cf870993889dcb146f3bb1b3e1ffdc95be960f, # content: 'Javascript is a popular programming language', meta: {'group': '42', 'split_id': 7, 'subgroup': 'subB'}), # Document(id=d9fc857046c904e5cf790b3969b971b1bbdb1b3037d50a20728fdbf82991aa94, # content: 'A chromosome is a package of DNA', meta: {'group': '314', 'split_id': 2, 'subgroup': 'subC'}), # Document(id=6d3b7bdc13d09aa01216471eb5fb0bfdc53c5f2f3e98ad125ff6b85d3106c9a3, # content: 'An octopus has three hearts', meta: {'group': '11', 'split_id': 2, 'subgroup': 'subD'}) # ]

从示例可见：三篇group="42"的文档被聚到一起，组内按split_id升序排列（3 → 4 → 7），随后依次是group="314"与group="11"的文档——输出顺序与group_by、subgroup_by元数据值首次出现的顺序一致。

运行机制与源码解析

run只接收一个参数documents（list[Document]），输出{"documents": ...}。从 meta_field_grouping_ranker.py 源码可见其核心逻辑（第 92-141 行）：

输入为空时直接返回空列表；随后按文档 id 去重；
用嵌套defaultdict构造group → subgroup → docs的两级映射；缺失group_by键的文档进入no_group_docs；未设置subgroup_by或缺失该键时，使用默认子组键"no_subgroup"；
若设置了sort_docs_by，则组内按(d.meta.get(sort_field) is None, d.meta.get(sort_field))排序，缺失该键的文档排在组内最后；若组内出现不可比较的异构类型引发TypeError，则打印警告并保持原插入顺序（与 MetaFieldRanker 的行为保持一致）；
最后把各组文档按组序拼接，并把no_group_docs追加到末尾。

对应测试位于 test_meta_field_grouping_ranker.py。这一组件非常适合多文档分块检索后需要"按来源文档聚拢片段"再交给 LLM 的场景——比如按group（来源文档 id）聚合、按split_id（分块序号）恢复片段先后顺序，从而避免上下文碎片化。

SentenceTransformersDiversityRanker：多样性重排

SentenceTransformersDiversityRanker是一个基于 Sentence Transformers 的多样性排序器，支持两种策略：

Greedy Diversity Order（贪心多样性序）：使用预训练的 Sentence Transformers 模型对查询与文档做嵌入，然后按与查询的相似度对文档排序，同时最大化已选文档集合的整体多样性。
Maximum Margin Relevance（MMR，最大边际相关）：对每篇文档按"与查询的相关性"和"与已选文档的多样性"计算 MMR 分数，迭代选取 MMR 分数最高的文档，从而在相关性与多样性之间取得平衡；lambda_threshold控制二者的权衡。

初始化签名

def __init__( model: str = "sentence-transformers/all-MiniLM-L6-v2", top_k: int = 10, device: Optional[ComponentDevice] = None, token: Optional[Secret] = Secret.from_env_var( ["HF_API_TOKEN", "HF_TOKEN"], strict=False), similarity: Union[str, DiversityRankingSimilarity] = "cosine", query_prefix: str = "", query_suffix: str = "", document_prefix: str = "", document_suffix: str = "", meta_fields_to_embed: Optional[list[str]] = None, embedding_separator: str = "\n", strategy: Union[str, DiversityRankingStrategy] = "greedy_diversity_order", lambda_threshold: float = 0.5, model_kwargs: Optional[dict[str, Any]] = None, tokenizer_kwargs: Optional[dict[str, Any]] = None, config_kwargs: Optional[dict[str, Any]] = None, backend: Literal["torch", "onnx", "openvino"] = "torch")

参数详解：

model：模型在 Hugging Face Hub 上的名称或本地路径，默认'sentence-transformers/all-MiniLM-L6-v2'。
top_k：每次查询返回的文档数量上限，默认 10。
device：模型加载设备；None时自动选择默认设备。
token：下载私有模型时使用的 Hugging Face API Token，默认从HF_API_TOKEN/HF_TOKEN环境变量读取。
similarity：嵌入相似度度量，可选"dot_product"（默认）或"cosine"（组件默认值为"cosine"，见上方签名）。
query_prefix/query_suffix：排序前追加到查询文本开头/结尾的字符串；一些嵌入模型（如 E5、BGE）要求按指令前缀输入，可借此注入。
document_prefix/document_suffix：排序前追加到每篇文档文本开头/结尾的字符串，用途同上。
meta_fields_to_embed：需要与文档内容一起参与嵌入的元数据字段列表。
embedding_separator：把元数据字段拼接到文档内容时使用的分隔符，默认"\n"。
strategy：多样性排序策略，"greedy_diversity_order"（默认）或"maximum_margin_relevance"。
lambda_threshold：相关性与多样性之间的权衡参数，仅maximum_margin_relevance策略使用，默认 0.5。
model_kwargs/tokenizer_kwargs/config_kwargs：分别透传给AutoModelForSequenceClassification.from_pretrained、AutoTokenizer.from_pretrained、AutoConfig.from_pretrained的额外关键字参数。
backend：Sentence Transformers 模型的后端，可选"torch"、"onnx"或"openvino"，用于加速与量化场景。

生命周期与运行

warm_up()：初始化组件（加载模型），首次run前必须调用。
run(query, documents, top_k=None, lambda_threshold=None)：top_k与lambda_threshold可在运行时覆盖初始化值。若top_k<= 0 抛出ValueError；若组件未warm_up则抛出RuntimeError。
to_dict()/from_dict()：支持组件序列化与反序列化，便于存入 YAML/JSON 格式的管线定义。
配套的两个枚举DiversityRankingStrategy与DiversityRankingSimilarity都提供__str__()与from_str()静态方法，用于枚举与字符串之间的互转。

用法示例

from haystack import Document from haystack.components.rankers import SentenceTransformersDiversityRanker ranker = SentenceTransformersDiversityRanker(model="sentence-transformers/all-MiniLM-L6-v2", similarity="cosine", strategy="greedy_diversity_order") ranker.warm_up() docs = [Document(content="Paris"), Document(content="Berlin")] query = "What is the capital of germany?" output = ranker.run(query=query, documents=docs) docs = output["documents"]

该组件适合"候选文档高度相似"的召回场景——例如大量重复或雷同的搜索结果——用多样性排序避免把几乎一样的内容全部塞进 LLM 上下文，从而扩大信息覆盖面。

SentenceTransformersSimilarityRanker：cross-encoder 语义重排

SentenceTransformersSimilarityRanker使用 Hugging Face 的预训练cross-encoder模型计算查询与文档的语义相似度并据此排序。cross-encoder 把查询与文档拼接后整体过编码器，精度通常高于 bi-encoder 式的检索嵌入，因此适合作为检索后的精排环节。

初始化签名

def __init__(*, model: Union[str, Path] = "cross-encoder/ms-marco-MiniLM-L-6-v2", device: Optional[ComponentDevice] = None, token: Optional[Secret] = Secret.from_env_var( ["HF_API_TOKEN", "HF_TOKEN"], strict=False), top_k: int = 10, query_prefix: str = "", document_prefix: str = "", meta_fields_to_embed: Optional[list[str]] = None, embedding_separator: str = "\n", scale_score: bool = True, score_threshold: Optional[float] = None, trust_remote_code: bool = False, model_kwargs: Optional[dict[str, Any]] = None, tokenizer_kwargs: Optional[dict[str, Any]] = None, config_kwargs: Optional[dict[str, Any]] = None, backend: Literal["torch", "onnx", "openvino"] = "torch", batch_size: int = 16)

参数详解：

model：cross-encoder 模型的本地路径或 Hugging Face 模型名，默认"cross-encoder/ms-marco-MiniLM-L-6-v2"。
device：模型加载设备，None时自动选择。
token：下载私有模型用的 HF Token。
top_k：每次查询返回的文档数量上限，默认 10。
query_prefix/document_prefix：追加在查询/文档文本开头的指令前缀，供bge等需要指令前缀的模型使用。
meta_fields_to_embed：与文档一起嵌入的元数据字段列表。
embedding_separator：拼接元数据字段与文档内容的分隔符，默认"\n"。
scale_score：True时用 Sigmoid 激活函数对原始 logit 预测做缩放（使其落在 0~1 区间）；False时禁用缩放。
score_threshold：只返回分数高于该阈值的文档。
trust_remote_code：False时仅允许 Hugging Face 官方验证的模型架构；True时允许自定义模型与脚本。
model_kwargs/tokenizer_kwargs/config_kwargs：透传给模型、分词器、配置加载的额外参数。
backend："torch"、"onnx"或"openvino"，用于加速与量化。
batch_size：推理批大小，默认 16。批越大占用内存越多，遇到内存不足时应调小。

参数校验：若top_k不是 > 0，初始化即抛出ValueError。

生命周期与运行

warm_up()：加载模型，首次run前必须调用。
run(*, query, documents, top_k=None, scale_score=None, score_threshold=None)：三个可选参数均可覆盖初始化值。若top_k<= 0 抛出ValueError；若未warm_up则抛出RuntimeError。返回{"documents": [...]}，文档按与查询的相似度从高到低排列。
to_dict()/from_dict()：支持序列化与反序列化。

用法示例

from haystack import Document from haystack.components.rankers import SentenceTransformersSimilarityRanker ranker = SentenceTransformersSimilarityRanker() docs = [Document(content="Paris"), Document(content="Berlin")] query = "City in Germany" ranker.warm_up() result = ranker.run(query=query, documents=docs) docs = result["documents"] print(docs[0].content)

TransformersSimilarityRanker：兼容旧版（Legacy）

TransformersSimilarityRanker与SentenceTransformersSimilarityRanker功能相同——同样使用 Hugging Face 的预训练 cross-encoder 模型按语义相似度排序。但该组件在 v2.20 文档中已被明确标注为legacy（旧版）：不再接收更新，未来版本可能先进入弃用期、随后被移除；官方建议改用功能相同且特性更多的SentenceTransformersSimilarityRanker。

初始化签名

def __init__(model: Union[str, Path] = "cross-encoder/ms-marco-MiniLM-L-6-v2", device: Optional[ComponentDevice] = None, token: Optional[Secret] = Secret.from_env_var( ["HF_API_TOKEN", "HF_TOKEN"], strict=False), top_k: int = 10, query_prefix: str = "", document_prefix: str = "", meta_fields_to_embed: Optional[list[str]] = None, embedding_separator: str = "\n", scale_score: bool = True, calibration_factor: Optional[float] = 1.0, score_threshold: Optional[float] = None, model_kwargs: Optional[dict[str, Any]] = None, tokenizer_kwargs: Optional[dict[str, Any]] = None, batch_size: int = 16)

多数参数含义与SentenceTransformersSimilarityRanker一致，两个关键差异是：

calibration_factor：概率校准因子，仅在scale_score=True时生效，计算公式为sigmoid(logits * calibration_factor)，默认 1.0。
参数集合更精简：没有trust_remote_code、config_kwargs与backend选项。

run(query, documents, top_k=None, scale_score=None, calibration_factor=None, score_threshold=None)同样支持运行时覆盖。异常行为：top_k<= 0 或scale_score=True且未提供calibration_factor时抛出ValueError；未warm_up时抛出RuntimeError。

用法示例

from haystack import Document from haystack.components.rankers import TransformersSimilarityRanker ranker = TransformersSimilarityRanker() docs = [Document(content="Paris"), Document(content="Berlin")] query = "City in Germany" ranker.warm_up() result = ranker.run(query=query, documents=docs) docs = result["documents"] print(docs[0].content)

组件选型建议与综合运用

把上述组件放入真实的 RAG 管线时，可以按以下思路组合：

召回 + 语义精排：Retriever 召回的候选文档先经过HuggingFaceTEIRanker（有 TEI 服务）或SentenceTransformersSimilarityRanker（本地 cross-encoder）做语义精排，得到相关性最高的 top-k；
业务规则干预：若排序还需叠加价格、日期等业务字段，用MetaFieldRanker通过weight与ranking_mode控制相关性与业务字段的融合比例；需要把碎片文档按来源聚拢时，用MetaFieldGroupingRanker按group_by/subgroup_by/sort_docs_by重组上下文；
上下文布局优化：在构建 Prompt 前，用LostInTheMiddleRanker把最相关内容排布到上下文首尾，或用SentenceTransformersDiversityRanker去除冗余、扩大覆盖面；
维护与迁移：新代码优先选用SentenceTransformersSimilarityRanker而非 legacy 的TransformersSimilarityRanker；所有组件都实现了to_dict/from_dict，可被完整序列化进 YAML 管线定义，便于版本管理与 CI 测试。

需要留意的是：本文中 TEI 与 SentenceTransformers 系列组件依据 v2.20 版本化 API 文档撰写；而当前仓库主分支的 rankers 组件目录仅保留了LLMRanker、LostInTheMiddleRanker、MetaFieldRanker、MetaFieldGroupingRanker。在使用前，请根据你实际安装的 Haystack 版本确认可用的组件清单，并以对应版本的 API 文档与 pydoc/rankers_api.yml 配置为准。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Haystack Rankers 组件完全指南：从语义重排到 LLM 上下文编排（v2.20 API 参考与源码解析）