sentence-transformers 交叉编码器 Reranker 训练实战：从 GooAQ/NQ 数据到可部署的排序模型

• 人工智能
• NLP
• Embedding
• 微调

本文围绕 sentence-transformers 仓库中 examples/cross_encoder/training/rerankers/README.md 展开，系统讲解如何基于 CrossEncoder 架构训练自己的重排序（Reranker）模型。文章覆盖四种可直接套用的训练脚本、两种核心损失函数的原理与调参、NanoBEIR 评估方法，以及完整的模型推理与部署流程。读完本文，你将掌握从数据挖掘硬负样本、选择损失函数、配置训练器，到评估与发布一个专属 Reranker 的完整技术路径。

什么是 Reranker：基于 CrossEncoder 的排序模型

Reranker 模型通常是具有1 个输出类的 CrossEncoder 模型：给定一对文本(query, answer)，模型输出一个分数，用于衡量"该答案能在多大程度上回答该查询"。这个分数可以是大约落在-10.0 ~ 10.0区间的浮点数，也可以是绑定在0...1区间内的概率值。

与先对 query 和 document 分别编码、再计算相似度的双塔（Bi-Encoder/SentenceTransformer）方案相比，CrossEncoder 将查询与文档拼接后一次性送入模型，能够建模两者之间的深度交互，因此排序精度更高，但代价是无法预先缓存文档向量，推理成本更高。这正是"两阶段检索"的经典分工：先用高效的嵌入模型召回 Top-K 候选，再用 CrossEncoder Reranker 精排。关于两类架构的直观对比，可参考仓库中的示意图：

从 CrossEncoder 模型源码 可以看到，它默认以num_labels = 1初始化，即只输出一个 logit；predict()方法对一批(query, doc)对批量打分，而rank()方法则直接对"一个查询 + 一组候选文档"给出排序结果（按分数降序返回corpus_id与score），本文后续的推理示例会用到这两个 API。

许多公开的强 Reranker 都基于 MS MARCO 训练，相关预训练模型清单与训练示例可参考：

• docs/cross_encoder/pretrained_models.md（MS MARCO 预训练 Cross Encoder 部分）
• examples/cross_encoder/training/ms_marco/README.md（MS MARCO 训练示例）

但更常见的做法是：在你的自有数据上训练 Reranker 往往效果最佳。这正是本页提供四个可改编训练脚本的原因。

四个开箱即用的训练脚本总览

仓库在examples/cross_encoder/training/rerankers/下提供了四个示例脚本，覆盖三种不同的损失函数与两种数据集：

其中training_gooaq_bce.py与training_nq_bce.py的训练逻辑几乎完全一致，唯一差别在于数据源：GooAQ（Google 问答数据集）规模更大，NQ（Natural Questions）相对更小，便于在小数据集上快速验证流程。以下逐一深入解析各脚本的实现细节。

公共骨架：数据准备、模型加载与硬负样本挖掘

四个脚本共享同一套"加载模型 → 读取数据 → 挖负样本 → 定义损失 → 定义评估器 → 配置训练参数 → 训练 → 评估 → 保存/发布"的流程。以training_gooaq_bce.py为例：

from datasets import load_dataset from sentence_transformers import SentenceTransformer from sentence_transformers.base.evaluation import SequentialEvaluator from sentence_transformers.cross_encoder import CrossEncoder, CrossEncoderModelCardData from sentence_transformers.cross_encoder.evaluation import ( CrossEncoderNanoBEIREvaluator, CrossEncoderRerankingEvaluator, ) from sentence_transformers.cross_encoder.losses import BinaryCrossEntropyLoss from sentence_transformers.cross_encoder.trainer import CrossEncoderTrainer from sentence_transformers.cross_encoder.training_args import CrossEncoderTrainingArguments from sentence_transformers.util import mine_hard_negatives model_name = "answerdotai/ModernBERT-base" train_batch_size = 64 num_epochs = 1 num_hard_negatives = 5 # 每个 (question, answer) 对要挖掘的硬负样本数量 # 1. 加载模型：训练时优先用 fp32（内存足够的前提下） model = CrossEncoder( model_name, model_card_data=CrossEncoderModelCardData( language="en", license="apache-2.0", model_name="ModernBERT-base trained on GooAQ", ), model_kwargs={"torch_dtype": "float32"}, ) print("Model max length:", model.max_length) print("Model num labels:", model.num_labels) # 2. 加载 GooAQ 数据集，取前 100k 条，切分出 1000 条作为开发集 full_dataset = load_dataset("sentence-transformers/gooaq", split="train").select(range(100_000)) dataset_dict = full_dataset.train_test_split(test_size=1_000, seed=12) train_dataset = dataset_dict["train"] eval_dataset = dataset_dict["test"]

硬负样本挖掘是训练高质量 Reranker 的关键一步。脚本使用sentence-transformers/static-retrieval-mrl-en-v1这个高效的嵌入模型（放在 CPU 上即可）作为负样本挖掘器：

embedding_model = SentenceTransformer("sentence-transformers/static-retrieval-mrl-en-v1", device="cpu") hard_train_dataset = mine_hard_negatives( train_dataset, embedding_model, num_negatives=num_hard_negatives, # 每个 query-answer 对挖掘几个负样本 absolute_margin=0, # query 与负样本的相似度应比 query-正样本低 x（0 表示不施加该约束） range_min=0, # 跳过最相似的 x 个样本 range_max=100, # 只考虑最相似的 100 个候选 sampling_strategy="top", # 从候选区间中采样最难的 top 负样本 batch_size=4096, # 嵌入模型的批大小 output_format="labeled-pair", # 输出 (query, passage, label) 格式，BinaryCrossEntropyLoss 需要 use_faiss=True, # 使用 FAISS 加速向量检索 )

mine_hard_negatives定义在 sentence_transformers/util/hard_negatives.py，其关键参数语义如下（与源码 docstring 一致）：

• range_min：负样本候选的最低相似度排名，用于跳过与查询最相似的若干文本；
• range_max：候选的最大排名，用于限制候选规模、控制挖掘成本；
• absolute_margin：硬负样本挖掘的绝对间隔，即 query-负样本 与 query-正样本 之间至少应差多少相似度；
• sampling_strategy："top"总是采样最难的 top n 个候选，"random"则在候选区间内随机采样；
• include_positives：是否把正样本也纳入候选列表（评估用）；
• output_format：可选"triplet"、"n-tuple"、"labeled-pair"、"labeled-list"四种，分别对应不同损失函数的输入需求。

挖掘好的数据集可以用hard_train_dataset.save_to_disk("gooaq-hard-train")落盘，下次用load_from_disk直接加载，省去重复挖掘的时间。

注意：使用include_positives=True时，源码会强制将output_format设为"n-tuple"，以保证排序顺序被保留（见 hard_negatives.py）；同时它会警告你：改动range_min/range_max/margin/sampling_strategy等默认值可能把正样本也过滤掉，评估场景请谨慎。

评估器：NanoBEIR + 开发集重排增益

脚本同时配置了两类评估器，并用SequentialEvaluator串行执行：

# 4a. NanoBEIR：轻量级英文重排序评估器 nano_beir_evaluator = CrossEncoderNanoBEIREvaluator( dataset_names=["msmarco", "nfcorpus", "nq"], batch_size=train_batch_size, ) # 4b. 在 GooAQ 开发集上评估"重排增益"： # 把正样本一并放入候选列表，这样评估器能同时报出"嵌入模型基线"与"重排后"两套指标 hard_eval_dataset = mine_hard_negatives( eval_dataset, embedding_model, corpus=full_dataset["answer"], # 用完整数据集作为语料库 num_negatives=30, # 每个查询重排 30 篇文档 batch_size=4096, include_positives=True, output_format="n-tuple", use_faiss=True, ) reranking_evaluator = CrossEncoderRerankingEvaluator( samples=[ { "query": sample["question"], "positive": [sample["answer"]], "documents": [sample[column_name] for column_name in hard_eval_dataset.column_names[2:]], } for sample in hard_eval_dataset ], batch_size=train_batch_size, name="gooaq-dev", always_rerank_positives=False, # 更贴近真实场景：只重排 BM25/嵌入模型已召回的文档 ) evaluator = SequentialEvaluator([reranking_evaluator, nano_beir_evaluator]) evaluator(model) # 先跑一遍基线模型，便于对比训练前后的提升

NanoBEIR是基于 BEIR 集合裁剪出的轻量版信息检索评估集，规模小、跑得快，适合在完整评估前快速验证模型检索性能。从 nano_beir.py 的源码可以看到：

• 每个数据集只会重排 BM25 排名中的前rerank_k（默认 100）篇文档；
• 返回指标与CrossEncoderRerankingEvaluator一致，即MAP、MRR@k、nDCG@k，并按数据集聚合出均值；
• 主指标键名格式为NanoBEIR_R{rerank_k}_{aggregate_key}_{metric}，默认主指标是NanoBEIR_R100_mean_ndcg@10，可配合训练参数里的load_best_model_at_end=True与metric_for_best_model使用；
• 未指定dataset_names时，默认排除arguana与touche2020（其 Argument Retrieval 任务与其他数据集差异较大），可用数据集包括climatefever、dbpedia、fever、fiqa2018、hotpotqa、msmarco、nfcorpus、nq、quoraretrieval、scidocs、scifact等。

而CrossEncoderRerankingEvaluator（见 reranking.py）的核心逻辑是：对每个 sample 计算[query, doc_i]的分数并按降序排序，然后计算MRR@10、NDCG@10、MAP。每个 sample 必须包含query与positive键，并二选一提供negative（不相关文档列表）或documents（包含正样本在内的完整候选列表，假定已按相似度排序）。当使用documents时，评估器会同时报告"重排前（Base）→ 重排后（Reranked）"两套指标——这正是衡量 Reranker 在首阶段检索之上增益的方式。

训练参数：基于 Hugging Face Trainer 的配置

short_model_name = model_name.split("/")[-1] run_name = f"reranker-{short_model_name}-gooaq-bce" args = CrossEncoderTrainingArguments( # 必填： output_dir=f"models/{run_name}", # 训练超参数： num_train_epochs=num_epochs, per_device_train_batch_size=train_batch_size, per_device_eval_batch_size=train_batch_size, learning_rate=2e-5, warmup_steps=0.1, fp16=False, # 若 GPU 不支持 FP16，保持 False bf16=True, # 支持 BF16 的 GPU 可开启 dataloader_num_workers=2, dataloader_persistent_workers=True, # Windows/macOS 推荐，Linux 可设 False load_best_model_at_end=True, metric_for_best_model="eval_gooaq-dev_ndcg@10", # 以开发集重排 NDCG@10 为选优指标 # 日志与保存： eval_strategy="steps", eval_steps=1000, save_strategy="steps", save_steps=1000, save_total_limit=2, logging_steps=200, logging_first_step=True, run_name=run_name, # 安装 wandb 后会同步到 W&B seed=12, )

然后组装CrossEncoderTrainer并启动训练：

trainer = CrossEncoderTrainer( model=model, args=args, train_dataset=hard_train_dataset, loss=loss, evaluator=evaluator, ) trainer.train() # 训练结束后再评估一次（结果可用于模型卡片） evaluator(model) # 保存最终模型 final_output_dir = f"models/{run_name}/final" model.save_pretrained(final_output_dir) # （可选）发布到 Hugging Face Hub：先运行 huggingface-cli login try: model.push_to_hub(run_name) except Exception: logging.error( f"Error uploading model to the Hugging Face Hub:\n{traceback.format_exc()}" f"To upload it manually, you can run `huggingface-cli login`, followed by loading the model " f"using `model = CrossEncoder({final_output_dir!r})` and saving it using " f"`model.push_to_hub('{run_name}')`." )

损失函数一：BinaryCrossEntropyLoss（简单而强大的点式排序损失）

BinaryCrossEntropyLoss是一种非常强大却又足够简单的损失。给定成对文本（如(query, answer)），它让 CrossEncoder 输出预测分数，与金标（gold）或银标（silver，即用某个模型自动判定的标签）对比，模型表现越好损失越低。

核心实现见 sentence_transformers/cross_encoder/losses/binary_cross_entropy.py，其构造参数与输入要求如下：

• model：要训练的 CrossEncoder，必须初始化 1 个输出标签（num_labels = 1，即默认值），否则会抛出ValueError；
• activation_fn：对 logits 应用激活函数后再算损失，默认为nn.Identity()；
• pos_weight：正样本的权重，必须是torch.Tensor，如torch.tensor(4)表示权重 4；脚本注释明确建议将pos_weight设为正负样本比例，即num_hard_negatives；
• 其余**kwargs透传给torch.nn.BCEWithLogitsLoss。

forward中，输入的两个文本列会被配对为pairs，经model.preprocess与batch_to_device后前向得到 logits，取view(-1)展开、过activation_fn，再交给BCEWithLogitsLoss与标签对比。由于训练数据是mine_hard_negatives(..., output_format="labeled-pair")产出的带 0/1 标签对，天然契合该损失的输入形态：

# 来自 training_gooaq_bce.py # pos_weight 建议设为正负比例，即 num_hard_negatives loss = BinaryCrossEntropyLoss(model=model, pos_weight=torch.tensor(num_hard_negatives))

损失函数二：CachedMultipleNegativesRankingLoss（GradCache 版 InfoNCE）

CachedMultipleNegativesRankingLoss（即InfoNCE with GradCache）比常见的BinaryCrossEntropyLoss更复杂：它接受正样本对(query, answer)或三元组(query, right_answer, wrong_answer)，然后为每个查询随机选取num_negatives个批内负样本（in-batch negatives）——即从 batch 中其他问题的答案中抽取错误答案。

随后，损失会对所有(query, answer)组合（包括刚选出的错误答案）计算分数，并用 Cross Entropy 损失确保(query, correct_answer)的分数高于所有(query, wrong_answer)。换句话说，模型必须在"1 个正确答案 + 若干批内负样本（以及可选硬负样本）"中把正确答案挑出来。

该损失采用GradCache方法（详见其实现的注释与 cached_multiple_negatives_ranking.py），分三步走：

1. 先用无梯度计算图（torch.no_grad）快速预测出所有 logits；
2. 计算损失并只反传到 logits，缓存"损失关于 logits 的梯度"；
3. 再做一次带梯度的前向，通过 backward hook 把缓存的梯度接入反向链。

这三步都以mini_batch_size为粒度分批执行，从而在不显著增加显存的前提下支持超大 batch（batch 越大，批内负样本越多，性能通常越好）。源码 docstring 也明确指出：这是对普通MultipleNegativesRankingLoss（multiple_negatives_ranking.py）的"增强版"，后者没有这种聪明的 mini-batch 机制、显存开销大；代价是 GradCache 版训练略慢（原论文估算约牺牲 20% 计算时间）。源码中的get_in_batch_negatives展示了批内负样本的具体选取逻辑：先构造 mask 屏蔽每个 anchor 自身的正样本与硬负样本，再用torch.multinomial从剩余候选中随机抽取num_negatives个。

脚本中的典型用法：

# 来自 training_gooaq_cmnrl.py loss = CachedMultipleNegativesRankingLoss( model=model, num_negatives=num_rand_negatives, # 每个 query-answer 对使用多少个随机负样本 mini_batch_size=16, # 前向的 mini-batch 大小，直接影响显存占用 )

该损失不需要标注数据，只需正样本对，因此training_gooaq_cmnrl.py直接使用原始 GooAQ 训练集而不做硬负样本挖掘。训练时推荐配合BatchSamplers.NO_DUPLICATES采样器，确保批内负样本不会与 anchor 或正样本重复（源码 docstring 的 Recommendations 部分有说明）。

关于activation_fn与scale的调参（源码默认值为nn.Sigmoid()与scale=10.0）：

• torch.nn.Sigmoid+scale=10.0：效果尚可；
• torch.nn.Identity+scale=1.0：同样可行；
• mGTE 论文作者建议使用torch.nn.Tanh+scale=10.0。

该损失的当前默认值在源码注释中被明确标注为"未来可能变动"，鼓励读者自行实验。

损失函数三：LambdaLoss（面向排序指标的 Listwise 损失）

LambdaLoss实现的是《The LambdaLoss Framework for Ranking Metric Optimization》（Wang et al., CIKM 2018）中的 LambdaLoss 框架，用于直接优化排序指标。它的输入是list 形态：每个查询对应一组文档及其相关性标签（二值或连续均可），实现见 sentence_transformers/cross_encoder/losses/lambda_loss.py。

关键参数：

• weighting_scheme：权重方案，默认NDCGLoss2PPScheme。可选NoWeightingScheme（权重恒为 1）、NDCGLoss1Scheme（NDCG Loss1，论文中表现不如后两者）、NDCGLoss2Scheme（NDCG Loss2）、LambdaRankScheme（LambdaRank，优化 NDCG 的粗略上界）、NDCGLoss2PPScheme（NDCG Loss2++，NDCG Loss2 与 LambdaRank 的混合，论文中表现最强）；
• k：NDCG@K 考虑的文档数，默认None表示使用全部文档；
• sigma：sigmoid 中的分数差权重，默认 1.0；
• reduction_log："natural"（自然对数）或"binary"（以 2 为底的对数），默认"binary"；
• mini_batch_size：每次前向处理的样本数，对显存和速度影响显著——None时等于 batch 大小；大于 0 时按该值切分 mini-batch；小于等于 0 时整批一次前向。

脚本中的典型用法：

# 来自 training_gooaq_lambda.py loss = LambdaLoss(model=model, mini_batch_size=mini_batch_size)

该损失的输入需用mine_hard_negatives(..., output_format="labeled-list")生成——每个查询对应一个带标签的文档列表，这也是training_gooaq_lambda.py与training_gooaq_bce.py在数据准备上的唯一区别（output_format从"labeled-pair"换成"labeled-list"）。从源码forward可以看到，LambdaLoss 会先按(query, doc)配对打分，再把 logits 与标签重排成矩阵，计算 gains、discounts（对数位置折扣）与 maxDCGs，最终按加权概率的对数取负均值作为损失，并利用 padding mask 与 NDCG@K 截断 mask 只对有效文档对计算。源码 docstring 指出，该损失在相同输入格式下，经验上通常优于其他损失。

推理：加载预训练 Reranker 并排序

仓库作者用第一个脚本（training_gooaq_bce.py）训练出了tomaarsen/reranker-ModernBERT-base-gooaq-bce模型。如果你不想自己训练，可以直接下载该模型体验推理：

from sentence_transformers import CrossEncoder # 从 Hugging Face Hub 下载 model = CrossEncoder("tomaarsen/reranker-ModernBERT-base-gooaq-bce") # 为文本对打分 pairs = [ ["how to obtain a teacher's certificate in texas?", 'Some aspiring educators may be confused about the difference between teaching certification and teaching certificates. Teacher certification is another term for the licensure required to teach in public schools, while a teaching certificate is awarded upon completion of an academic program.'], ["how to obtain a teacher's certificate in texas?", '["Step 1: Obtain a Bachelor\'s Degree. One of the most important Texas teacher qualifications is a bachelor\'s degree. ... ", \'Step 2: Complete an Educator Preparation Program (EPP) ... \', \'Step 3: Pass Texas Teacher Certification Exams. ... \', \'Step 4: Complete a Final Application and Background Check.\']'], ["how to obtain a teacher's certificate in texas?", "Washington Teachers Licensing Application Process Official transcripts showing proof of bachelor's degree. Proof of teacher program completion at an approved teacher preparation school. Passing scores on the required examinations. Completed application for teacher certification in Washington."], ["how to obtain a teacher's certificate in texas?", 'Teacher education programs may take 4 years to complete after which certification plans are prepared for a three year period. During this plan period, the teacher must obtain a Standard Certification within 1-2 years. Learn how to get certified to teach in Texas.'], ["how to obtain a teacher's certificate in texas?", 'In Texas, the minimum age to work is 14. Unlike some states, Texas does not require juvenile workers to obtain a child employment certificate or an age certificate to work. A prospective employer that wants one can request a certificate of age for any minors it employs, obtainable from the Texas Workforce Commission.'], ] scores = model.predict(pairs) print(scores) # [0.00121048 0.97105724 0.00536712 0.8632406 0.00168043]

可以看出，模型对包含"Step 1/2/3/4 得克萨斯教师资格认证步骤"的答案给出了接近 0.97 的高分，对"得州最低工作年龄"这类跑题答案给出了接近 0 的低分。

更常见的场景是对单一查询的一组候选文档排序，此时使用rank()方法：

# 对与单个文本最相似的若干文本进行排序 ranks = model.rank( "how to obtain a teacher's certificate in texas?", [ "[\"Step 1: Obtain a Bachelor's Degree. One of the most important Texas teacher qualifications is a bachelor's degree. ... \", 'Step 2: Complete an Educator Preparation Program (EPP) ... ', 'Step 3: Pass Texas Teacher Certification Exams. ... ', 'Step 4: Complete a Final Application and Background Check.']", "Teacher education programs may take 4 years to complete after which certification plans are prepared for a three year period. During this plan period, the teacher must obtain a Standard Certification within 1-2 years. Learn how to get certified to teach in Texas.", "Washington Teachers Licensing Application Process Official transcripts showing proof of bachelor's degree. Proof of teacher program completion at an approved teacher preparation school. Passing scores on the required examinations. Completed application for teacher certification in Washington.", "Some aspiring educators may be confused about the difference between teaching certification and teaching certificates. Teacher certification is another term for the licensure required to teach in public schools, while a teaching certificate is awarded upon completion of an academic program.", "In Texas, the minimum age to work is 14. Unlike some states, Texas does not require juvenile workers to obtain a child employment certificate or an age certificate to work. A prospective employer that wants one can request a certificate of age for any minors it employs, obtainable from the Texas Workforce Commission.", ], ) print(ranks) # [ # {'corpus_id': 0, 'score': 0.97105724}, # {'corpus_id': 1, 'score': 0.8632406}, # {'corpus_id': 2, 'score': 0.0053671156}, # {'corpus_id': 4, 'score': 0.0016804343}, # {'corpus_id': 3, 'score': 0.0012104829}, # ]

rank()返回按分数降序排列的{corpus_id, score}列表，可直接与首阶段检索（如 SentenceTransformer 嵌入检索）串联成两阶段 pipeline。predict()与rank()的完整签名均可参考 sentence_transformers/cross_encoder/model.py 与 model.py#L641。

小结与选型建议

综合以上内容，为自有数据选择 Reranker 训练方案时可参考如下路线：

1. 数据形态决定损失：只有正样本对 → 首选CachedMultipleNegativesRankingLoss（配合mini_batch_size控制显存，实验activation_fn与scale）；有标注的成对数据 →BinaryCrossEntropyLoss（记得用mine_hard_negatives挖硬负样本，并把pos_weight设为正负比例）；有"查询 + 文档列表 + 标签"的 list 数据 →LambdaLoss（直接优化 NDCG 类指标）；
2. 评估先行：用CrossEncoderNanoBEIREvaluator在msmarco/nfcorpus/nq等 NanoBEIR 子集上快速验证，并用CrossEncoderRerankingEvaluator在自有开发集上对比"重排前 → 重排后"的指标增益；
3. 训练参数：建议bf16=True（GPU 支持时）、load_best_model_at_end=True配合metric_for_best_model="eval_<dev-name>_ndcg@10"自动选优，检查点通过save_total_limit控制数量；
4. 发布与部署：save_pretrained保存本地，push_to_hub发布到 Hub；推理时用predict()批量打分、rank()直接排序，衔接首阶段检索构成完整的两阶段检索系统。

所有脚本均可直接运行：python examples/cross_encoder/training/rerankers/training_gooaq_bce.py（依次类推其他三个），并可按需替换model_name、数据集与超参数。

• 人工智能
• NLP
• Embedding
• 微调