使用 sentence-transformers 微调 CrossEncoder 重排序模型:从数据准备、损失函数到 Trainer 的完整训练指南
使用 sentence-transformers 微调 CrossEncoder 重排序模型:从数据准备、损失函数到 Trainer 的完整训练指南
本篇技术指南围绕 sentence-transformers 仓库中 CrossEncoder 模型的微调全流程展开,覆盖训练所需的六大组件——模型初始化、数据集与硬负例挖掘、损失函数、训练参数、评估器与 Trainer,并给出可直接复制的完整训练脚本。读完本文,你将掌握如何在 Retrieve-and-Rerank 检索链路中微调属于自己的重排序模型(Reranker),也能独立完成 NLI 对文本分类等 Pair Classification 任务的训练与评估。
为什么需要微调 CrossEncoder
CrossEncoder 模型最常见的落地场景,是作为 Retrieve and Rerank(检索-重排) 搜索链路中的第二阶段重排序器,参见 examples/sentence_transformer/applications/retrieve_rerank/README.md。该链路通常包含两个阶段:
- 第一阶段检索(Retriever):使用一个 Sentence Transformer 模型(如双编码器)对海量文档做粗粒度召回,得到候选文档(例如 Top 100~1000);
- 第二阶段重排(Reranker):CrossEncoder 将查询与每个候选文档拼接成「查询-文档」对送入同一个 Transformer,输出一个相关性分数,从而对 Top-X 候选做精排。
由于第一阶段的召回列表受限于检索器质量,如果重排序模型在自己的业务场景上表现不佳,会直接拉低整条链路的精度,因此微调至关重要。需要特别注意的是:重排序器(Reranker)永远只输出 1 个标签——即一个连续的相关性分数。
除了重排序,CrossEncoder 还可以作为 Pair Classifier(对文本分类器) 使用。例如,在自然语言推理(NLI)数据上训练的模型,可以判断一对文本之间的关系属于 "contradiction"(矛盾)、"entailment"(蕴含)还是 "neutral"(中立)。与 Reranker 不同,Pair Classifier 通常有多个输出标签(每个类别一个 logit)。
仓库中提供了大量面向真实场景、可直接改用的训练脚本,详见 docs/cross_encoder/training/examples.rst,涵盖 MS MARCO 重排、NLI、STS、Quora 重复问题检测、多模态重排、知识蒸馏等任务。
训练组件总览
与 训练 Sentence Transformer 模型 类似,训练 CrossEncoder 模型通常涉及 4~6 个组件:
| 组件 | 是否必需 | 作用 |
|---|---|---|
| Model | 必需 | 初始化用于训练的 CrossEncoder 模型 |
| Dataset | 必需 | 准备训练数据(datasets.Dataset 或 DatasetDict) |
| Loss Function | 必需 | 选择并初始化损失函数 |
| Training Arguments | 可选 | 配置训练性能与日志/调试参数 |
| Evaluator | 可选 | 训练前、训练中、训练后评估模型指标 |
| Trainer | 必需 | 汇聚以上组件,启动训练流程 |
下面按组件逐一展开。
Model:初始化 CrossEncoder 模型
CrossEncoder 将预训练的 transformers 模型包装起来,并使用或新增一个小的输出头(head)来为输入对产生分数或标签。直接实例化一个已经训练好的 CrossEncoder 模型非常简单:
from sentence_transformers import CrossEncoder
model = CrossEncoder("cross-encoder/ms-marco-MiniLM-L6-v2")
如果你打算从其他 checkpoint 或从零训练,仓库支持两类主流的底层架构,CrossEncoder.__init__ 会根据模型的 config.architectures 自动选择加载路径(见 sentence_transformers/cross_encoder/model.py)。
方案一:Encoder / sequence-classification checkpoint
可以从编码器类模型(如 BERT、RoBERTa、ModernBERT)或已有的序列分类(sequence-classification)checkpoint 初始化 CrossEncoder。如果 checkpoint 已经带有序列分类头,CrossEncoder 会直接复用;否则会自动新增一个输出头,输出标签数取自模型配置或 num_labels 参数。
from sentence_transformers import CrossEncoder
# 单标签回归 / 重排序模型
reranker = CrossEncoder(
"google-bert/bert-base-uncased", num_labels=1, model_kwargs={"torch_dtype": "float32"}
)
# 多类对文本分类模型(例如 NLI)
classifier = CrossEncoder(
"FacebookAI/xlm-roberta-base", num_labels=3, model_kwargs={"torch_dtype": "float32"}
)
参数说明:
num_labels=1:适用于重排序等回归类任务,模型对每对输入输出单一分数,与BinaryCrossEntropyLoss等损失配合良好(源码校验见 sentence_transformers/cross_encoder/losses/binary_cross_entropy.py);num_labels=N:多分类/多标签对文本分类任务,标签数需与类别数一致,配合分类损失使用。num_labels会被写入config_kwargs并最终传给AutoConfig(见 sentence_transformers/cross_encoder/model.py);model_kwargs={"torch_dtype": "float32"}:如果显存允许,训练时推荐以 fp32 精度加载模型,即使后续打算使用混合精度或 fp16。否则训练后期常见的小幅参数更新会被舍入为零。除torch_dtype外,model_kwargs还支持attn_implementation(如"eager"/"sdpa"/"flash_attention_2",默认在可用时使用"sdpa")与device_map(如"auto"或"cuda:1")等选项,详见 model.py。
关于基础模型选择的建议:最强的底座模型往往是「编码器模型」,即训练目标是为输入产生有意义的 token embedding 的模型,例如:
- fill-mask 模型(为 token embedding 训练);
- sentence-similarity 模型(为文本 embedding 训练);
- feature-extraction 模型(为文本 embedding 训练)。
优先寻找针对你所用语言和/或领域设计的底座模型。例如对韩语任务,klue/bert-base 通常会远好于 google-bert/bert-base-uncased。
方案二:Decoder / text-generation checkpoint
CrossEncoder 也可以包装文本生成 / 因果语言模型(配置名以 ForCausalLM 结尾)。此时它使用文本生成骨干,并附加一个 LogitScore 模块:该模块查看特定的 "true"/"false" token(例如 "yes"/"no" 或 "1"/"0")的 logit,并把因果 logits 转换为每对输入的单一标量分数。
from sentence_transformers import CrossEncoder
# 使用文本生成 checkpoint 作为重排序器
model = CrossEncoder("google/gemma-2-2b-it")
从源码看,加载 causal-LM 时(见 model.py),仓库会:
- 读取
AutoConfig判断config.architectures[0]是否以ForCausalLM结尾; - 若是,则以
transformer_task="text-generation"加载Transformer模块; - 从 tokenizer 中取
"yes"与"no"的 token id,构建LogitScore(true_token_id, false_token_id)作为后处理模块。
LogitScore 的计分逻辑(见 logit_score.py):取最后一个 token 位置(左填充保证最后位置是真实 token)的 logits,若只提供 true_token_id 则分数为该 token 的 logit;若同时提供 false_token_id,则分数为对数几率 logit[true_token_id] - logit[false_token_id]。
需要注意:causal-LM 配置始终表现为单标签打分器(等价于 num_labels=1),它专为打分与重排设计(如查询-文档相关性),不适用于需要每个类别一个 logit 的多分类问题。多分类任务请优先选择 encoder / sequence-classification checkpoint。
Dataset:准备训练数据
CrossEncoderTrainer 使用 datasets.Dataset(单数据集)或 datasets.DatasetDict(多数据集,见下文「多数据集训练」)进行训练与评估。根据数据来源,有三种加载方式。
从 Hugging Face Hub 加载
使用 datasets.load_dataset 加载公开数据集:
from datasets import load_dataset
train_dataset = load_dataset("sentence-transformers/all-nli", "pair-class", split="train")
eval_dataset = load_dataset("sentence-transformers/all-nli", "pair-class", split="dev")
print(train_dataset)
"""
Dataset({
features: ['premise', 'hypothesis', 'label'],
num_rows: 942069
})
"""
部分数据集(包括 sentence-transformers/all-nli)要求同时提供 subset(子集)。all-nli 共有 4 个子集,数据格式各不相同:pair、pair-class、pair-score、triplet。
提示:许多开箱即用且兼容 Sentence Transformers 的 Hugging Face 数据集都带有
sentence-transformers标签,可以在 HF Datasets 上按other=sentence-transformers浏览筛选,寻找适合自己任务的训练数据。
加载本地数据(CSV、JSON、Parquet、Arrow、SQL)
本地常见格式的数据同样可用 datasets.load_dataset 加载:
from datasets import load_dataset
dataset = load_dataset("csv", data_files="my_file.csv")
from datasets import load_dataset
dataset = load_dataset("json", data_files="my_file.json")
需要预处理的本地数据
如果本地数据需要额外的预处理(打开文件、过滤、清洗等),推荐用字典初始化数据集——Dataset.from_dict 中每个键都会成为结果数据集的一列:
from datasets import Dataset
anchors = []
positives = []
# 打开文件,做预处理、过滤、清洗等,
# 然后追加到上面的列表中
dataset = Dataset.from_dict({
"anchor": anchors,
"positive": positives,
})
数据集格式规则(重要)
数据集的格式必须与损失函数匹配(反之亦然:选择与数据集格式、模型匹配的损失函数)。校验「数据集格式 + 模型」能否与某个损失函数配合,遵循三个步骤:
- 判定输入列:所有列名不是
"label"、"labels"、"score"、"scores"的列都被视为 Inputs(参见 Loss Overview 表格)。剩余列数必须等于所选损失函数要求的有效输入个数;列名无关紧要,只有列的顺序重要。 - 判定标签列:如果损失函数需要 Label(见 Loss Overview),数据集必须有一列名为
"label"、"labels"、"score"或"scores",该列会被自动当作标签。 - 匹配输出标签数:模型输出标签数必须满足损失函数的要求。
举例:一个列结构为 ["text1", "text2", "label"] 的数据集,其中 label 列是 0~1 的浮点相似度分数,模型输出 1 个标签。它可以配合 BinaryCrossEntropyLoss 使用,因为:① 数据集有该损失要求的 label 列;② 非标签列恰好 2 个,正是该损失要求的输入数;③ 模型输出 1 个标签,恰好符合。
若列顺序不对,请用 Dataset.select_columns 重排。例如数据集列为 ["good_answer", "bad_answer", "question"],技术上可被要求 (anchor, positive, negative) 三元组的损失使用,但 good_answer 会被当作 anchor、bad_answer 会被当作 positive、question 会被当作 negative——这通常不是你想要的结果。
另外,如果数据集有多余的列(如 sample_id、metadata、source、type),必须用 Dataset.remove_columns 移除,否则它们会被当作输入列;也可以用 Dataset.select_columns 只保留目标列。
多模态数据集
多模态模型需要额外依赖,图片支持可执行 pip install -U "sentence-transformers<a href="https://link.gitcode.com/i/e9a14d8ef5dc67f87726a83f178f5be1" target="_blank">image]" 安装(全部选项见 [docs/installation.md)。
CrossEncoder 的数据集不限于文本列。使用多模态骨干(如视觉-语言模型)时,输入列还可以包含图片(PIL 图像、文件路径或 URL)、音频、视频或多模态字典。上述「数据集格式」规则依然适用:非标签列视为输入,"label" 列提供目标分数或类别。
例如,一个用于「图像到文本」重排序的数据集可能包含 "image" 列(PIL 图像)、"text" 列(候选描述)和 "label" 列(二值相关性分数):
from datasets import Dataset
from PIL import Image
dataset = Dataset.from_dict({
"image": [Image.open("cat.jpg"), Image.open("cat.jpg"), Image.open("dog.jpg")],
"text": ["a photo of a cat", "a photo of a dog", "a photo of a dog"],
"label": [1, 0, 1],
})
你也可以做双向训练(例如同时支持 image-to-text 与 text-to-image):分别构造子数据集,并以字典形式传入做多数据集训练:
train_image_to_text = full_dataset.select_columns(["image", "text", "label"])
train_text_to_image = full_dataset.select_columns(["text", "image", "label"])
trainer = CrossEncoderTrainer(
model=model,
args=args,
train_dataset={
"image_to_text": train_image_to_text,
"text_to_image": train_text_to_image,
},
loss=loss,
)
数据整理器(data collator)会通过模型的 preprocess 方法自动完成多模态预处理,无需手动分词或图像处理。无论底层是 encoder 还是 causal LM,数据集格式都相同,只有模型架构不同。完整的多模态训练脚本参见 examples/cross_encoder/training/multimodal/README.md。
硬负例挖掘(Hard Negatives Mining)
CrossEncoder 训练的成功往往取决于负例的质量——即查询-负例对的分数应当很低的那部分语料。负例分为两类:
- 软负例(Soft negatives):与查询完全无关的段落;
- 硬负例(Hard negatives):看起来可能与查询相关、但实际上不相关的段落。
一个直观的例子:
- 查询:Where was Apple founded?
- 软负例:The Cache River Bridge is a Parker pony truss that spans the Cache River between Walnut Ridge and Paragould, Arkansas.
- 硬负例:The Fuji apple is an apple cultivar developed in the late 1930s, and brought to market in 1962.
最强的 CrossEncoder 模型通常都经过硬负例训练,因此「挖掘」硬负例非常有价值。Sentence Transformers 提供了强大的 mine_hard_negatives 函数(位于 sentence_transformers.util),给定查询-答案对数据集即可自动挖掘:
from datasets import load_dataset
from sentence_transformers import SentenceTransformer
from sentence_transformers.util import mine_hard_negatives
# 加载 GooAQ 数据集:https://huggingface.co/datasets/sentence-transformers/gooaq
train_dataset = load_dataset("sentence-transformers/gooaq", split=f"train").select(range(100_000))
print(train_dataset)
# 使用一个非常高效的 embedding 模型挖掘硬负例
embedding_model = SentenceTransformer("sentence-transformers/static-retrieval-mrl-en-v1", device="cpu")
hard_train_dataset = mine_hard_negatives(
train_dataset,
embedding_model,
num_negatives=5, # 每个问答对挖掘的负例数量
range_min=10, # 跳过最相似的 x 个样本
range_max=100, # 只考虑最相似的 x 个样本
max_score=0.8, # 只考虑相似度分数不超过 x 的样本
absolute_margin=0.1, # anchor-负例相似度至少比 anchor-正例相似度低 x
relative_margin=0.1, # anchor-负例相似度比 anchor-正例相似度低至少其量值的 x(如 10%)
sampling_strategy="top", # 从候选区间采样 top 负例
batch_size=4096, # embedding 模型的批大小
output_format="labeled-pair", # 输出格式为 (query, passage, label),适配 BinaryCrossEntropyLoss
use_faiss=True, # 推荐使用 FAISS 以降低内存占用(pip install faiss-gpu 或 pip install faiss-cpu)
)
print(hard_train_dataset)
print(hard_train_dataset[1])
该脚本的输出(节选):
Dataset({
features: ['question', 'answer'],
num_rows: 100000
})
Batches: 100%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 22/22 [00:01<00:00, 12.74it/s]
Batches: 100%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 25/25 [00:00<00:00, 37.50it/s]
Querying FAISS index: 100%|███████████████████████████████████████████████████████████████████████████████████████████████████████| 7/7 [00:18<00:00, 2.66s/it]
Metric Positive Negative Difference
Count 100,000 436,925
Mean 0.5882 0.4040 0.2157
Median 0.5989 0.4024 0.1836
Std 0.1425 0.0905 0.1013
Min -0.0514 0.1405 0.1014
25% 0.4993 0.3377 0.1352
50% 0.5989 0.4024 0.1836
75% 0.6888 0.4681 0.2699
Max 0.9748 0.7486 0.7545
Skipped 2,420,871 potential negatives (23.97%) due to the absolute_margin of 0.1.
Skipped 43 potential negatives (0.00%) due to the max_score of 0.8.
Could not find enough negatives for 63075 samples (12.62%). Consider adjusting the range_max, range_min, absolute_margin, relative_margin and max_score parameters if you'd like to find more valid negatives.
Dataset({
features: ['question', 'answer', 'label'],
num_rows: 536925
})
{
'question': 'how to transfer bookmarks from one laptop to another?',
'answer': 'Using an External Drive Just about any external drive, including a USB thumb drive, or an SD card can be used to transfer your files from one laptop to another. Connect the drive to your old laptop; drag your files to the drive, then disconnect it and transfer the drive contents onto your new laptop.',
'label': 0
}
从源码看(hard_negatives.py),mine_hard_negatives 的可调参数还包括:min_score(跳过与 anchor 过于不相似的候选)、margin(兼容旧接口的绝对间隔参数)、anchor_column_name / positive_column_name(自定义列名)、corpus(额外语料)、cross_encoder(用 CrossEncoder 对候选重新打分)、query_prompt_name / corpus_prompt_name(指令式模型的 prompt)、include_positives(把正例也包含进负例候选列表,供评估器使用)、output_scores(输出相似度分数)、use_multi_process(多进程加速)等。output_format 支持 "triplet"、"n-tuple"、"labeled-pair"、"labeled-list" 四种格式。
挖掘技巧(源自 NV-Retriever 论文实践,见 hard_negatives.py):
relative_margin=0.05(负例分数至少比正例低 5%)、num_negatives不超过 10、sampling_strategy="top"、use_faiss=True,对应TopK-PercPos (95%)挖掘方法。
Loss Function:损失函数
损失函数用于量化模型在给定批次数据上的表现,使优化器据此更新模型权重以降低损失值,是训练过程的核心。
遗憾的是,不存在对所有场景都最优的单一损失函数——选择哪个损失函数,主要取决于你拥有的数据格式与目标任务。可用的损失函数概览请以 Loss Overview 为准,其中列出了每个损失要求的输入数量、是否需要标签以及要求的模型输出标签数。
绝大多数损失函数只需用正在训练的 CrossEncoder 模型(加上少量可选参数)即可初始化,例如:
from datasets import load_dataset
from sentence_transformers import CrossEncoder
from sentence_transformers.cross_encoder.losses import MultipleNegativesRankingLoss
# 加载一个待训练/微调的模型(num_labels=1 用于重排序器)
model = CrossEncoder("FacebookAI/xlm-roberta-base", num_labels=1, model_kwargs={"torch_dtype": "float32"})
# 初始化 MultipleNegativesRankingLoss
# 该损失要求相关文本对或三元组
loss = MultipleNegativesRankingLoss(model)
# 加载一个与该损失函数匹配的训练数据集
train_dataset = load_dataset("sentence-transformers/gooaq", split="train")
MultipleNegativesRankingLoss 的核心思想(见 sentence_transformers/cross_encoder/losses/multiple_negatives_ranking.py):给定 (anchor, positive) 对或 (anchor, positive, negative) 三元组,该损失在批次内为每个 anchor 构造「一个正例 + n-1 个批内负例」的候选集,要求模型为正例分配最高分。因此批大小越大,批内负例越多,训练效果通常越强;配合 BatchSamplers.NO_DUPLICATES 可确保批内负例不与 anchor/正例重复。它也被称为 InfoNCE、SimCSE、批内负例交叉熵等。当显存受限时,可使用其缓存版本 CachedMultipleNegativesRankingLoss,后者通过缓存中间结果在同等显存下支持更大的批大小。
BinaryCrossEntropyLoss 的实现(见 binary_cross_entropy.py)基于 torch.nn.BCEWithLogitsLoss:训练模型对正例输出高 logit、对负例输出低 logit,模型需以 num_labels=1 初始化。它接受 (anchor, positive/negative) 对(标签为 1/0)或 (input_A, input_B) 对(标签为 0~1 的相似度分数)。其 pos_weight 参数(正例权重)推荐设为正负样本比(即 num_hard_negatives),例如 BinaryCrossEntropyLoss(model=model, pos_weight=torch.tensor(num_hard_negatives))。许多强力的 MS MARCO Reranker 模型都是用该损失训练的。
Training Arguments:训练参数
CrossEncoderTrainingArguments 继承自 BaseTrainingArguments 与 transformers.TrainingArguments,用于配置影响训练性能的参数以及跟踪/调试参数。虽然它是可选的,但强烈建议尝试各种有用的参数组合。
提升训练性能的关键参数:
| 参数 | 说明 |
|---|---|
learning_rate |
学习率 |
lr_scheduler_type |
学习率调度器类型 |
warmup_steps |
预热步数 |
num_train_epochs |
训练轮数 |
max_steps |
最大步数(与 epoch 二选一) |
per_device_train_batch_size |
每设备训练批大小 |
per_device_eval_batch_size |
每设备评估批大小 |
auto_find_batch_size |
自动寻找最大可用批大小 |
fp16 / bf16 |
混合精度(fp16 或 bf16) |
load_best_model_at_end |
训练结束时加载评估指标最优的 checkpoint |
metric_for_best_model |
决定「最优」的指标名 |
gradient_accumulation_steps |
梯度累积步数 |
gradient_checkpointing |
梯度检查点(省显存换速度) |
eval_accumulation_steps |
评估时累积预测的步数 |
optim |
优化器选择 |
dataloader_num_workers / dataloader_persistent_workers / dataloader_prefetch_factor |
数据加载 worker 数、常驻 worker、预取因子 |
batch_sampler |
批采样器(如 BatchSamplers.NO_DUPLICATES,对使用批内负例的损失有好处) |
multi_dataset_batch_sampler |
多数据集批采样策略(见「多数据集训练」) |
learning_rate_mapping |
按参数名正则表达式为模型不同部分设置不同学习率,例如 {'SparseStaticEmbedding\.*': 1e-3} |
观察训练性能的关键参数:
| 参数 | 说明 |
|---|---|
eval_strategy / eval_steps |
评估策略(如 "steps")与评估步数 |
save_strategy / save_steps / save_total_limit |
保存策略、保存步数与最多保留的 checkpoint 数 |
report_to |
指标上报目标(如 wandb、tensorboard) |
run_name |
运行名称(安装 wandb 时会用于 W&B) |
log_level / logging_steps |
日志级别与日志步数 |
push_to_hub / hub_model_id / hub_strategy / hub_private_repo |
推送到 Hugging Face Hub 的开关与配置 |
CrossEncoderTrainingArguments 的初始化示例:
from sentence_transformers.cross_encoder import CrossEncoderTrainingArguments
args = CrossEncoderTrainingArguments(
# 必填参数:
output_dir="models/reranker-MiniLM-msmarco-v1",
# 可选训练参数:
num_train_epochs=1,
per_device_train_batch_size=16,
per_device_eval_batch_size=16,
learning_rate=2e-5,
warmup_steps=0.1,
fp16=True, # 若 GPU 无法运行 FP16 会报错,请设为 False
bf16=False, # 若 GPU 支持 BF16 可设为 True
batch_sampler=BatchSamplers.NO_DUPLICATES, # 使用"批内负例"的损失受益于无重复采样
# 可选跟踪/调试参数:
eval_strategy="steps",
eval_steps=0.1,
save_strategy="steps",
save_steps=0.1,
save_total_limit=2,
logging_steps=0.01,
run_name="reranker-MiniLM-msmarco-v1", # 安装 wandb 后将用于 W&B
)
Evaluator:评估器
你可以给 CrossEncoderTrainer 传入 eval_dataset 来获取训练期间的评估损失,但获取更具体的指标同样很有用。为此可以使用评估器在训练前、训练中或训练后评估模型性能。eval_dataset 与评估器可以同时使用、二选一,或都不用——它们都基于 eval_strategy 与 eval_steps 训练参数触发。
仓库为 CrossEncoder 提供了以下内置评估器:
| 评估器 | 所需数据 |
|---|---|
| CrossEncoderClassificationEvaluator | 带类别标签(二分类或多分类)的文本对 |
| CrossEncoderCorrelationEvaluator | 带相似度分数的文本对 |
| CrossEncoderNanoBEIREvaluator | 无需数据(自动从 HF 加载) |
| CrossEncoderRerankingEvaluator | {'query': '...', 'positive': [...], 'negative': [...]} 字典列表;负例可用 mine_hard_negatives 挖掘 |
此外,SequentialEvaluator(位于 sentence_transformers.base.evaluation)可用于把多个评估器组合成一个评估器再传给 Trainer。
当你手头没有评估数据、但仍想在常见基准上跟踪模型表现时,可以结合 Hugging Face 数据使用以下评估器。
CrossEncoderNanoBEIREvaluator(免数据评估)
与其他评估器不同,该评估器直接从 Hugging Face 加载相关数据集,因此没有必填参数:
from sentence_transformers import CrossEncoder
from sentence_transformers.cross_encoder.evaluation import CrossEncoderNanoBEIREvaluator
# 加载模型
model = CrossEncoder("cross-encoder/ms-marco-MiniLM-L6-v2")
# 初始化评估器
dev_evaluator = CrossEncoderNanoBEIREvaluator()
# 可这样运行评估:
# results = dev_evaluator(model)
从源码看(nano_beir.py),该评估器默认使用 sentence-transformers/NanoBEIR-en 数据集,支持 dataset_names(如 ["msmarco", "nfcorpus", "nq"])、rerank_k(默认 100)、at_k(默认 10)、always_rerank_positives(默认 True)、batch_size 等参数,内部会把每个数据集封装成 CrossEncoderRerankingEvaluator 并聚合各数据集分数。
CrossEncoderRerankingEvaluator + GooAQ 挖掘负例
为 CrossEncoderRerankingEvaluator 准备数据通常比较麻烦,因为你除了查询-正例数据外还需要负例。mine_hard_negatives 提供了方便的 include_positives 参数:设为 True 时会连同正例文本一起挖掘。当这些结果作为 documents(要求 1. 已按相似度排序;2. 包含正例)提供给评估器时,评估器不仅评估 CrossEncoder 的重排性能,还会报告挖掘所用 embedding 模型的原始排序性能作为基线。
from datasets import load_dataset
from sentence_transformers import SentenceTransformer
from sentence_transformers.cross_encoder import CrossEncoder
from sentence_transformers.cross_encoder.evaluation import CrossEncoderRerankingEvaluator
from sentence_transformers.util import mine_hard_negatives
# 加载模型
model = CrossEncoder("cross-encoder/ms-marco-MiniLM-L6-v2")
# 加载 GooAQ 数据集:https://huggingface.co/datasets/sentence-transformers/gooaq
full_dataset = load_dataset("sentence-transformers/gooaq", split=f"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"]
print(eval_dataset)
"""
Dataset({
features: ['question', 'answer'],
num_rows: 1000
})
"""
# 使用一个非常高效的 embedding 模型挖掘硬负例
embedding_model = SentenceTransformer("sentence-transformers/static-retrieval-mrl-en-v1", device="cpu")
hard_eval_dataset = mine_hard_negatives(
eval_dataset,
embedding_model,
corpus=full_dataset["answer"], # 使用完整数据集作为语料库
num_negatives=50, # 每个问答对的负例数量
batch_size=4096, # embedding 模型的批大小
output_format="n-tuple", # 输出格式为 (query, positive, negative1, negative2, ...),供评估器使用
include_positives=True, # 关键:把正例答案也包含进负例列表
use_faiss=True, # 推荐使用 FAISS 以降低内存占用(pip install faiss-gpu 或 pip install faiss-cpu)
)
print(hard_eval_dataset)
"""
Dataset({
features: ['question', 'answer', 'negative_1', 'negative_2', ..., 'negative_50'],
num_rows: 1000
})
"""
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=32,
name="gooaq-dev",
)
# 可这样运行评估:
results = reranking_evaluator(model)
"""
CrossEncoderRerankingEvaluator: Evaluating the model on the gooaq-dev dataset:
Queries: 1000 Positives: Min 1.0, Mean 1.0, Max 1.0 Negatives: Min 49.0, Mean 49.1, Max 50.0
Base -> Reranked
MAP: 53.28 -> 67.28
MRR@10: 52.40 -> 66.65
NDCG@10: 59.12 -> 71.35
"""
# {'gooaq-dev_map': 0.6728370126462222, 'gooaq-dev_mrr@10': 0.6665190476190477, 'gooaq-dev_ndcg@10': 0.7135068904582963, 'gooaq-dev_base_map': 0.5327714512001362, 'gooaq-dev_base_mrr@10': 0.5239674603174603, 'gooaq-dev_base_ndcg@10': 0.5912299141913905}
注意:默认情况下,如果使用 documents 模式,评估器会重排所有正例(即使它们不在 documents 中)。这有助于获得更强的评估信号,但性能数字会略微「不真实」——因为理论上限变成了 100,而实际两阶段链路的上限受制于第一阶段检索器是否真正召回了正例。
如需真实行为,可在初始化时设置 always_rerank_positives=False(该参数说明见 reranking.py)。用真实的两阶段设置重复同一脚本,结果如下:
CrossEncoderRerankingEvaluator: Evaluating the model on the gooaq-dev dataset:
Queries: 1000 Positives: Min 1.0, Mean 1.0, Max 1.0 Negatives: Min 49.0, Mean 49.1, Max 50.0
Base -> Reranked
MAP: 53.28 -> 66.12
MRR@10: 52.40 -> 65.61
NDCG@10: 59.12 -> 70.10
CrossEncoderCorrelationEvaluator + STSb
from datasets import load_dataset
from sentence_transformers import CrossEncoder
from sentence_transformers.cross_encoder.evaluation import CrossEncoderCorrelationEvaluator
# 加载模型
model = CrossEncoder("cross-encoder/stsb-TinyBERT-L4")
# 加载 STSB 数据集(https://huggingface.co/datasets/sentence-transformers/stsb)
eval_dataset = load_dataset("sentence-transformers/stsb", split="validation")
pairs = list(zip(eval_dataset["sentence1"], eval_dataset["sentence2"]))
# 初始化评估器
dev_evaluator = CrossEncoderCorrelationEvaluator(
sentence_pairs=pairs,
scores=eval_dataset["score"],
name="sts_dev",
)
# 可这样运行评估:
# results = dev_evaluator(model)
CrossEncoderClassificationEvaluator + AllNLI
from datasets import load_dataset
from sentence_transformers import CrossEncoder
from sentence_transformers.cross_encoder.evaluation import CrossEncoderClassificationEvaluator
# 加载模型
model = CrossEncoder("cross-encoder/nli-deberta-v3-base")
# 从 AllNLI 数据集加载三元组(https://huggingface.co/datasets/sentence-transformers/all-nli)
max_samples = 1000
eval_dataset = load_dataset("sentence-transformers/all-nli", "pair-class", split=f"dev[:{max_samples}]")
# 构建文本对列表,并把标签映射到模型认识的标签
pairs = list(zip(eval_dataset["premise"], eval_dataset["hypothesis"]))
label_mapping = {0: 1, 1: 2, 2: 0}
labels = [label_mapping[label] for label in eval_dataset["label"]]
# 初始化评估器
cls_evaluator = CrossEncoderClassificationEvaluator(
sentence_pairs=pairs,
labels=labels,
name="all-nli-dev",
)
# 可这样运行评估:
# results = cls_evaluator(model)
警告:使用 分布式训练 时,评估器只在第一个设备上运行;训练集与评估集则在所有设备间共享。
Trainer:汇聚所有组件开始训练
CrossEncoderTrainer 是汇聚所有组件的核心:只需指定模型、训练参数(可选)、训练集、评估集(可选)、损失函数、评估器(可选),即可开始训练。
简单示例:GooAQ 重排器(CachedMultipleNegativesRankingLoss)
import logging
import traceback
from datasets import load_dataset
from sentence_transformers.cross_encoder import (
CrossEncoder,
CrossEncoderModelCardData,
CrossEncoderTrainer,
CrossEncoderTrainingArguments,
)
from sentence_transformers.cross_encoder.evaluation import CrossEncoderNanoBEIREvaluator
from sentence_transformers.cross_encoder.losses import CachedMultipleNegativesRankingLoss
# 将日志级别设为 INFO 以获得更多信息
logging.basicConfig(format="%(asctime)s - %(message)s", datefmt="%Y-%m-%d %H:%M:%S", level=logging.INFO)
model_name = "microsoft/MiniLM-L12-H384-uncased"
train_batch_size = 64
num_epochs = 1
num_rand_negatives = 5 # 每个问答对使用的随机负例数量
# 1a. 加载待微调的模型;1b.(可选)模型卡数据
model = CrossEncoder(
model_name,
model_card_data=CrossEncoderModelCardData(
language="en",
license="apache-2.0",
model_name="MiniLM-L12-H384 trained on GooAQ",
),
model_kwargs={"torch_dtype": "float32"},
)
print("Model max length:", model.max_length)
print("Model num labels:", model.num_labels)
# 2. 加载 GooAQ 数据集:https://huggingface.co/datasets/sentence-transformers/gooaq
logging.info("Read the gooaq training dataset")
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"]
logging.info(train_dataset)
logging.info(eval_dataset)
# 3. 定义训练损失
loss = CachedMultipleNegativesRankingLoss(
model=model,
num_negatives=num_rand_negatives,
mini_batch_size=32, # 告知内存占用情况
)
# 4. 使用 CrossEncoderNanoBEIREvaluator,一个轻量级英文重排评估器
evaluator = CrossEncoderNanoBEIREvaluator(
dataset_names=["msmarco", "nfcorpus", "nq"],
batch_size=train_batch_size,
)
evaluator(model)
# 5. 定义训练参数
short_model_name = model_name if "/" not in model_name else model_name.split("/")[-1]
run_name = f"reranker-{short_model_name}-gooaq-cmnrl"
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, # 若 GPU 支持 BF16 可设为 True
# 可选跟踪/调试参数:
eval_strategy="steps",
eval_steps=0.1,
save_strategy="steps",
save_steps=0.1,
save_total_limit=2,
logging_steps=0.01,
logging_first_step=True,
run_name=run_name, # 安装 wandb 后将用于 W&B
seed=12,
)
# 6. 创建 trainer 并开始训练
trainer = CrossEncoderTrainer(
model=model,
args=args,
train_dataset=train_dataset,
eval_dataset=eval_dataset,
loss=loss,
evaluator=evaluator,
)
trainer.train()
# 7. 评估最终模型,便于将结果写入模型卡
evaluator(model)
# 8. 保存最终模型
final_output_dir = f"models/{run_name}/final"
model.save_pretrained(final_output_dir)
# 9.(可选)保存模型到 Hugging Face Hub!
# 建议先运行 `huggingface-cli login` 登录 Hugging Face 账号
try:
model.push_to_hub(run_name)
except Exception:
logging.error(
f"Error uploading model to the Hugging Face Hub:\n{traceback.format_exc()}To upload it manually, you can run "
f"`huggingface-cli login`, followed by loading the model using `model = CrossEncoder({final_output_dir!r})` "
f"and saving it using `model.push_to_hub('{run_name}')`."
)
关于 CachedMultipleNegativesRankingLoss:它是 MultipleNegativesRankingLoss 的缓存版本(源码见 sentence_transformers/cross_encoder/losses/cached_multiple_negatives_ranking.py),通过 mini_batch_size 控制缓存子批次大小、以轻微速度代价换取显著的内存节省,从而支持更大的有效批大小(更多批内负例,通常带来更好性能)。
详尽示例:硬负例 + 双评估器(BinaryCrossEntropyLoss)
import logging
import traceback
import torch
from datasets import load_dataset
from sentence_transformers import SentenceTransformer
from sentence_transformers.cross_encoder import (
CrossEncoder,
CrossEncoderModelCardData,
CrossEncoderTrainer,
CrossEncoderTrainingArguments,
)
from sentence_transformers.cross_encoder.evaluation import (
CrossEncoderNanoBEIREvaluator,
CrossEncoderRerankingEvaluator,
)
from sentence_transformers.cross_encoder.losses import BinaryCrossEntropyLoss
from sentence_transformers.base.evaluation import SequentialEvaluator
from sentence_transformers.util import mine_hard_negatives
# 将日志级别设为 INFO 以获得更多信息
logging.basicConfig(format="%(asctime)s - %(message)s", datefmt="%Y-%m-%d %H:%M:%S", level=logging.INFO)
def main():
model_name = "answerdotai/ModernBERT-base"
train_batch_size = 64
num_epochs = 1
num_hard_negatives = 5 # 每个问答对挖掘的硬负例数量
# 1a. 加载待微调的模型;1b.(可选)模型卡数据
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)
# 2a. 加载 GooAQ 数据集:https://huggingface.co/datasets/sentence-transformers/gooaq
logging.info("Read the gooaq training dataset")
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"]
logging.info(train_dataset)
logging.info(eval_dataset)
# 2b. 使用一个非常高效的 embedding 模型,为训练集添加硬负例
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, # 每个问答对的负例数量
margin=0, # 查询与负例的相似度应比查询-正例相似度低 x
range_min=0, # 跳过最相似的 x 个样本
range_max=100, # 只考虑最相似的 x 个样本
sampling_strategy="top", # 从候选区间采样 top 负例
batch_size=4096, # embedding 模型的批大小
output_format="labeled-pair", # 输出格式为 (query, passage, label),适配 BinaryCrossEntropyLoss
use_faiss=True,
)
logging.info(hard_train_dataset)
# 2c.(可选)把硬负例训练集保存到磁盘
# hard_train_dataset.save_to_disk("gooaq-hard-train")
# 再次加载:
# hard_train_dataset = load_from_disk("gooaq-hard-train")
# 3. 定义训练损失。
# pos_weight 推荐设置为正负样本比,即 `num_hard_negatives`
loss = BinaryCrossEntropyLoss(model=model, pos_weight=torch.tensor(num_hard_negatives))
# 4a. 定义评估器。我们使用 CrossEncoderNanoBEIREvaluator,一个轻量级英文重排评估器
nano_beir_evaluator = CrossEncoderNanoBEIREvaluator(
dataset_names=["msmarco", "nfcorpus", "nq"],
batch_size=train_batch_size,
)
# 4b. 通过挖掘硬负例定义重排评估器
# 我们把正例答案也包含进负例列表,这样评估器可以用 embedding 模型的性能作为基线
hard_eval_dataset = mine_hard_negatives(
eval_dataset,
embedding_model,
corpus=full_dataset["answer"], # 使用完整数据集作为语料库
num_negatives=30, # 要重排的文档数量
batch_size=4096,
include_positives=True,
output_format="n-tuple",
use_faiss=True,
)
logging.info(hard_eval_dataset)
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",
# 真实设置:只重排检索器找到的正例
# 设为 True 则重排所有正例
always_rerank_positives=False,
)
# 4c. 组合评估器,并让基础模型在其上跑一遍
evaluator = SequentialEvaluator([reranking_evaluator, nano_beir_evaluator])
evaluator(model)
# 5. 定义训练参数
short_model_name = model_name if "/" not in model_name else 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, # 若 GPU 支持 BF16 可设为 True
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",
# 可选跟踪/调试参数:
eval_strategy="steps",
eval_steps=0.1,
save_strategy="steps",
save_steps=0.1,
save_total_limit=2,
logging_steps=0.01,
logging_first_step=True,
run_name=run_name, # 安装 wandb 后将用于 W&B
seed=12,
)
# 6. 创建 trainer 并开始训练
trainer = CrossEncoderTrainer(
model=model,
args=args,
train_dataset=hard_train_dataset,
loss=loss,
evaluator=evaluator,
)
trainer.train()
# 7. 评估最终模型,便于将结果写入模型卡
evaluator(model)
# 8. 保存最终模型
final_output_dir = f"models/{run_name}/final"
model.save_pretrained(final_output_dir)
# 9.(可选)保存模型到 Hugging Face Hub!
# 建议先运行 `huggingface-cli login` 登录 Hugging Face 账号
try:
model.push_to_hub(run_name)
except Exception:
logging.error(
f"Error uploading model to the Hugging Face Hub:\n{traceback.format_exc()}To upload it manually, you can run "
f"`huggingface-cli login`, followed by loading the model using `model = CrossEncoder({final_output_dir!r})` "
f"and saving it using `model.push_to_hub('{run_name}')`."
)
if __name__ == "__main__":
main()
关于默认损失函数:如果创建 Trainer 时不传 loss,CrossEncoderTrainer.get_default_loss(见 trainer.py)会根据模型输出标签数自动选择——num_labels == 1 时使用 BinaryCrossEntropyLoss,否则使用 CrossEntropyLoss。显式传入损失函数仍然更可控。
Callbacks:训练回调
CrossEncoder Trainer 集成了多种 transformers.TrainerCallback 子类支持,例如:
WandbCallback:若安装了wandb,自动将训练指标记录到 W&B;TensorBoardCallback:若可访问tensorboard,将训练指标记录到 TensorBoard;CodeCarbonCallback:若安装了codecarbon,跟踪训练期间的碳排放(这些碳排放信息会被包含进自动生成的模型卡中)。
更多关于内置回调与自定义回调的写法,参见 Transformers 的 Callbacks 文档。
多数据集训练
顶级模型通常使用许多数据集同时训练。通常这很棘手,因为每个数据集格式不同。但 CrossEncoderTrainer 可以在不把各数据集转换成相同格式的情况下同时训练多个数据集,甚至可以对每个数据集应用不同的损失函数。多数据集训练的步骤:
- 用
datasets.Dataset实例的字典(或DatasetDict)作为train_dataset(可选地也是eval_dataset); - (可选)用「数据集名 → 损失函数」的字典传入
loss,仅当你想对不同数据集使用不同损失时才需要。
每个训练/评估批次只包含其中一个数据集的样本。批次从多个数据集中采样的顺序由 MultiDatasetBatchSamplers 枚举决定,通过 multi_dataset_batch_sampler 参数传给 CrossEncoderTrainingArguments。可选值:
MultiDatasetBatchSamplers.ROUND_ROBIN:从每个数据集轮询采样直到其中一个耗尽。该策略下很可能不会用完每个数据集的所有样本,但对每个数据集的采样是均匀的;MultiDatasetBatchSamplers.PROPORTIONAL(默认):按各数据集大小比例采样。该策略下每个数据集的所有样本都会被用到,更大的数据集被采样更频繁。
训练技巧
CrossEncoder 模型有一些独特的「怪癖」,以下技巧值得留意:
-
CrossEncoder 模型过拟合很快。建议搭配
CrossEncoderNanoBEIREvaluator或CrossEncoderRerankingEvaluator等评估器,并使用load_best_model_at_end与metric_for_best_model训练参数,在训练结束后加载评估表现最优的模型。 -
CrossEncoder 对强硬负例(
mine_hard_negatives)特别敏感。硬负例教会模型变得非常严格,例如用于区分「能回答问题」的段落与「只是与问题相关」的段落。- 注意:如果只用硬负例,模型在较简单任务上可能意外变差(相关论文:2411.11767)。这意味着对第一阶段检索系统(如 SentenceTransformer 模型)召回的前 200 个结果重排,得到的 Top-10 可能反而比只重排前 100 个更差。在硬负例之外混合随机负例可以缓解这个问题。
-
不要低估
BinaryCrossEntropyLoss。尽管它比学习排序损失(LambdaLoss、ListNetLoss)或批内负例损失(CachedMultipleNegativesRankingLoss、MultipleNegativesRankingLoss)更简单,它依然是非常强的选项,而且数据易于准备——尤其配合mine_hard_negatives使用时。
已弃用的训练方式
在 Sentence Transformers v4.0 之前,模型使用 CrossEncoder.fit() 方法与 torch.utils.data.DataLoader(由 InputExample 组成)训练,大致如下:
from sentence_transformers import CrossEncoder, InputExample
from torch.utils.data import DataLoader
# 定义模型。从零初始化或加载预训练模型
model = CrossEncoder("distilbert/distilbert-base-uncased")
# 定义训练样本。实际使用中你需要远多于两个样本……
train_examples = [
InputExample(texts=["What are pandas?", "The giant panda ..."], label=1),
InputExample(texts=["What's a panda?", "Mount Vesuvius is a ..."], label=0),
]
# 定义训练数据集、dataloader 与训练损失
train_dataloader = DataLoader(train_examples, shuffle=True, batch_size=16)
# 微调模型
model.fit(train_dataloader=train_dataloader, epochs=1, warmup_steps=100)
自 v4.0 起,CrossEncoder.fit() 仍然可用,但它会在后台初始化一个 CrossEncoderTrainer。推荐直接使用 Trainer,因为你能通过 CrossEncoderTrainingArguments 获得更多控制;不过依赖 fit() 的旧脚本应该仍然能工作。若新版 fit() 有问题,也可以通过调用 CrossEncoder.old_fit() 获得完全一致的旧行为,但该方法计划在未来完全弃用(两个方法的签名见 sentence_transformers/cross_encoder/fit_mixin.py)。
与 SentenceTransformer 训练的对比
训练 CrossEncoder 模型与训练 SentenceTransformer 模型非常相似,关键区别如下:
- 在 SentenceTransformer 训练中,训练/评估数据集的列中不能使用输入列表(如文本列表);而 CrossEncoder 训练中,可以在一列中使用(可变长度的)文本列表——例如
ListNetLoss类就要求这种格式。
Sentence Transformer 的训练细节参见 Sentence Transformer > Training Overview。
端到端示例
以上组件已经覆盖了完整的训练流程。对于更完整的端到端训练示例,可参考仓库中的现成脚本:简单示例对应 examples/cross_encoder/training/rerankers/training_gooaq_cmnrl.py,详尽示例对应 training_gooaq_bce.py,此外还有 training_gooaq_lambda.py(LambdaLoss)与 training_nq_bce.py(Natural Questions + BCE)等变体。它们把本文描述的各组件应用到真实训练任务上,并在训练后把重排器与其基础 checkpoint 进行基准对比。多模态重排器训练的细节可参考 examples/cross_encoder/training/multimodal/README.md。损失函数的完整清单与「输入-标签-输出标签数」对照表见 docs/cross_encoder/loss_overview.md,各评估器与 Trainer 的 API 细节见 docs/package_reference/cross_encoder/index.rst。