Cross-Encoder 损失函数完全指南:sentence-transformers 排序模型微调实战
Cross-Encoder 损失函数完全指南:sentence-transformers 排序模型微调实战
losses 是 sentence-transformers 中专门用于微调 Cross-Encoder 重排序模型的损失函数集合,覆盖分类、对比学习、蒸馏与列表式排序四大类任务。选择正确的损失函数直接决定模型在具体下游任务上的表现。本文以 sentence_transformers.cross_encoder.losses 模块为主线,逐一拆解 14 个损失函数的数学动机、参数语义、输入数据格式与完整训练示例,并结合仓库源码验证其底层实现,帮助你快速为手头的数据格式选型并落地训练。
losses 模块为 Cross-Encoder 模型提供了 14 种开箱即用的损失函数,统一注册于 losses/init.py:
| 类别 | 损失函数 |
|---|---|
| 分类/点式 | CrossEntropyLoss、BinaryCrossEntropyLoss |
| 对比(in-batch negatives) | MultipleNegativesRankingLoss、CachedMultipleNegativesRankingLoss |
| 蒸馏(回归) | MSELoss、MarginMSELoss |
| 列表式排序(listwise) | LambdaLoss、ListMLELoss、PListMLELoss、ListNetLoss、RankNetLoss、ADRMSELoss |
没有一个损失函数是"放之四海而皆准"的,选型主要取决于两点:你手头训练数据的格式,以及目标任务。动手前建议先阅读 Loss Overview 中的数据格式—损失函数匹配表。
一、选型核心:先认清你的训练数据格式
所有 Cross-Encoder 损失函数的差异,本质上源于它们消费的训练数据格式不同。下表是 docs/cross_encoder/loss_overview.md 中给出的完整对应关系:
| 输入格式 | 标签 | 模型输出数 | 适用损失函数 |
|---|---|---|---|
(input_A, input_B) pairs |
class |
num_classes |
CrossEntropyLoss |
(anchor, positive) pairs |
无 | 1 | MultipleNegativesRankingLoss、CachedMultipleNegativesRankingLoss |
(anchor, positive/negative) pairs |
1 if positive, 0 if negative |
1 | BinaryCrossEntropyLoss |
(input_A, input_B) pairs |
[0, 1] 浮点相似度 |
1 | BinaryCrossEntropyLoss |
(anchor, positive, negative) triplets |
无 | 1 | MultipleNegativesRankingLoss、CachedMultipleNegativesRankingLoss |
(anchor, positive, negative_1, …, negative_n) |
无 | 1 | MultipleNegativesRankingLoss、CachedMultipleNegativesRankingLoss |
(query, [doc1, doc2, …, docN]) |
[score1, …, scoreN] |
1 | LambdaLoss、PListMLELoss、ListNetLoss、RankNetLoss、ListMLELoss、ADRMSELoss |
蒸馏场景(用小模型模仿强模型)单独成表:
| 输入格式 | 标签 | 适用损失函数 |
|---|---|---|
(input_A, input_B) pairs |
similarity score |
MSELoss |
(query, document_one, document_two) triplets |
gold_sim(q,d1) - gold_sim(q,d2) |
MarginMSELoss |
(query, positive, negative_1, …, negative_n) |
差值列表或分数列表 | MarginMSELoss |
数据格式之间往往可以互相转换。例如带 class 标签的 (input_A, input_B) pairs,可以通过采样同类/异类样本转换为 (anchor, positive, negative) triplets。更通用的是借助 sentence_transformers.util.hard_negatives.mine_hard_negatives 将 (anchor, positive) 一键转换为:
"triplet":(anchor, positive, negative)三元组;"n-tuple":(anchor, positive, negative_1, …, negative_n)多元组;"labeled-pair":(anchor, document, label),label 为 0(负)/ 1(正);"labeled-list":(anchor, [doc1, …, docN], [label1, …, labelN]),labels 为 0/1。
设置 output_scores=True 时还会输出相似度分数而非二值标签,从而适配蒸馏类损失。详细参数见 hard_negatives.py。
二、分类式损失:多分类与二分类
2.1 CrossEntropyLoss:多分类对判断
用于训练模型对给定输入对预测正确类别,类别数必须等于模型输出标签数(num_labels > 1)。源码位于 losses/cross_entropy.py。
from sentence_transformers.cross_encoder import CrossEncoder, CrossEncoderTrainer, losses
from datasets import Dataset
model = CrossEncoder("microsoft/mpnet-base", num_labels=2)
train_dataset = Dataset.from_dict({
"sentence1": ["How can I be a good geologist?", "What is the capital of France?"],
"sentence2": ["What should I do to be a great geologist?", "What is the capital of Germany?"],
"label": [1, 0], # 1: duplicate, 0: not duplicate
})
loss = losses.CrossEntropyLoss(model)
trainer = CrossEncoderTrainer(model=model, train_dataset=train_dataset, loss=loss)
trainer.train()
关键参数:
activation_fn(默认nn.Identity):在计算损失前作用于 logits 的激活函数;**kwargs:透传给底层torch.nn.CrossEntropyLoss。
从 forward 实现看,它要求数据集恰好有两个非标签列(len(inputs) != 2 时抛 ValueError),将两列 zip 成 pairs 后经 model.preprocess 编码并取 scores,再计算交叉熵。适合文本蕴含(NLI)等多分类任务,参考 训练示例。
2.2 BinaryCrossEntropyLoss:正负对 / 相似度回归
用于让模型对正样本对给出高 logit、负样本对给出低 logit,模型需初始化为 num_labels = 1(默认值)。历史上 MS MARCO 重排序榜单上的多个强模型都基于它训练,源码位于 losses/binary_cross_entropy.py。
model = CrossEncoder("microsoft/mpnet-base")
train_dataset = Dataset.from_dict({
"query": ["What are pandas?", "What are pandas?"],
"response": ["Pandas are a kind of bear.", "Pandas are a kind of fish."],
"label": [1, 0],
})
loss = losses.BinaryCrossEntropyLoss(model)
trainer = CrossEncoderTrainer(model=model, train_dataset=train_dataset, loss=loss)
trainer.train()
支持两种标签语义:
- 二值标签:
(anchor, positive/negative)对,1 正 0 负; - 连续相似度:
(input_A, input_B)对 +[0, 1]浮点分数。
参数说明:
pos_weight(默认None):正样本加权,用于处理类别不平衡,传torch.tensor(4)表示正类权重为 4;activation_fn(默认nn.Identity);**kwargs透传给torch.nn.BCEWithLogitsLoss。
实现上,forward 将 logits view(-1) 后与 labels.float() 计算 BCE。构造时会校验 model.num_labels == 1。推荐配合 mine_hard_negatives(output_format="labeled-pair") 将问答对转换为带硬负样本的标注对,参考 STS 示例、Quora 示例 与 MS MARCO 示例。
三、对比式损失:in-batch negatives
3.1 MultipleNegativesRankingLoss
给定 (anchor, positive) 对或 (anchor, positive, negative) 三元组,该损失让模型从 batch 内所有正负候选中给对应 positive 最高分。batch 越大,in-batch negatives 越多,模型通常越强。该损失也称为 InfoNCE loss、SimCSE loss、in-batch negatives loss,源码位于 losses/multiple_negatives_ranking.py。
model = CrossEncoder("microsoft/mpnet-base")
train_dataset = Dataset.from_dict({
"query": ["What are pandas?", "What is the capital of France?"],
"answer": ["Pandas are a kind of bear.", "The capital of France is Paris."],
})
loss = losses.MultipleNegativesRankingLoss(model)
trainer = CrossEncoderTrainer(model=model, train_dataset=train_dataset, loss=loss)
trainer.train()
参数:
num_negatives(默认4):每个 anchor 采样的 in-batch negatives 数量;None时使用全部;scale(默认10.0):logits 放大系数,即温度缩放;activation_fn(默认nn.Sigmoid):作用于 logits 的激活函数。
实现上 get_in_batch_negatives 先用掩码排除每个 anchor 自身的 positive 与硬负样本,再通过 torch.multinomial 随机采样 num_negatives 个负例;calculate_loss 将 scores reshape 为 (batch_size, 1 + 随机负例数 + 硬负例数) 后以第 0 列为正类计算交叉熵。官方提示当前默认值未来可能调整,鼓励自行实验。
3.2 CachedMultipleNegativesRankingLoss:GradCache 加速版
与 MultipleNegativesRankingLoss 数学上等价,但通过梯度缓存(GradCache)在几乎不增加显存的前提下支持超大 batch,从而获得更好性能,代价是训练稍慢(论文称约牺牲 20% 计算时间)。源码位于 losses/cached_multiple_negatives_ranking.py,继承自 MultipleNegativesRankingLoss 并复用其采样逻辑。
loss = losses.CachedMultipleNegativesRankingLoss(model, mini_batch_size=32)
其三步流程在 docstring 中有明确说明:
- 无梯度/计算图的快速预测,得到全部 logits;
- 计算 loss 并反向传播到 logits 层,缓存 logits 的梯度;
- 带计算图做第二次预测,把缓存梯度接入反向链。
参数在基类之上新增:
mini_batch_size(默认32):单次前向的 mini-batch 大小,直接决定显存占用;show_progress_bar(默认False)。
使用建议:采用大的 per_device_train_batch_size + 小的 mini_batch_size 以获得最佳性能。两种对比损失都建议配合 BatchSamplers.NO_DUPLICATES 防止 in-batch negatives 与 anchor/positive 重复,参考 MS MARCO 示例 与 rerankers 示例。
四、蒸馏式损失:向强教师模型对齐
4.1 MSELoss:分数级回归蒸馏
直接回归「模型预测的 query-document 分数」与「目标分数」之间的 MSE,常用于从教师 Cross-Encoder 或标注分数蒸馏知识,源码位于 losses/mse.py。
student_model = CrossEncoder("microsoft/mpnet-base")
teacher_model = CrossEncoder("cross-encoder/ms-marco-MiniLM-L12-v2")
train_dataset = Dataset.from_dict({
"query": ["What are pandas?", "What is the capital of France?"],
"answer": ["Pandas are a kind of bear.", "The capital of France is Paris."],
})
def compute_labels(batch):
return {"label": teacher_model.predict(list(zip(batch["query"], batch["answer"])))}
train_dataset = train_dataset.map(compute_labels, batched=True)
loss = losses.MSELoss(student_model)
trainer = CrossEncoderTrainer(model=student_model, train_dataset=train_dataset, loss=loss)
trainer.train()
注意:要留意标签与模型输出的量纲匹配。若教师模型用 Sigmoid 将 logits 限制在 <a href="https://link.gitcode.com/i/69caf4a5daf4464f93bb30bea7f7a81c" target="_blank">0, 1],则损失中也应传入 Sigmoid 作为 activation_fn。参数为 activation_fn 与透传 torch.nn.MSELoss 的 **kwargs,参考 [蒸馏训练示例。
4.2 MarginMSELoss:带边际的蒸馏
回归目标为 sim(Query, Pos) - sim(Query, Neg) 与金标准边际 gold_sim(Q, Pos) - gold_sim(Q, Neg) 之间的 MSE。相比 MultipleNegativesRankingLoss,它不要求两篇文档严格一正一负——两者都可以相关或不相关,因此约束更灵活,源码位于 losses/margin_mse.py。
student_model = CrossEncoder("microsoft/mpnet-base")
teacher_model = CrossEncoder("cross-encoder/ms-marco-MiniLM-L12-v2")
train_dataset = Dataset.from_dict({
"query": ["What are pandas?", "What is the capital of France?"],
"positive": ["Pandas are a kind of bear.", "The capital of France is Paris."],
"negative": ["Pandas are a kind of fish.", "The capital of France is Berlin."],
})
def compute_labels(batch):
positive_scores = teacher_model.predict(list(zip(batch["query"], batch["positive"])))
negative_scores = teacher_model.predict(list(zip(batch["query"], batch["negative"])))
return {"label": positive_scores - negative_scores}
train_dataset = train_dataset.map(compute_labels, batched=True)
loss = losses.MarginMSELoss(student_model)
trainer = CrossEncoderTrainer(model=student_model, train_dataset=train_dataset, loss=loss)
trainer.train()
forward 支持四种标签形态(源码中以 labels.shape 分支处理):单个边际分数、正负分数列表(自动相减)、多个负例的边际列表、正例加多个负例的分数列表。内部先分别计算 positive 与每个 negative 的 logits,再求差得到 margin_logits 与目标做 MSE。参数为 activation_fn 与透传 torch.nn.MSELoss 的 **kwargs,参考 margin-MSE 蒸馏示例。
五、列表式排序损失:query 下多文档直接排序
列表式(listwise)损失以「一个 query 及其全部候选文档」为基本训练单元,直接面向重排序/学习排序指标优化。这类损失允许每个 query 的文档数不同(batch 内按最长列表 padding)。以下损失函数的输入格式均为:
(query, [doc1, doc2, ..., docN]) + [score1, score2, ..., scoreN]
模型统一要求 num_labels = 1。推荐配合 mine_hard_negatives(output_format="labeled-list") 构造数据。
5.1 LambdaLoss:排序指标优化框架
实现 LambdaLoss 框架(论文。经验上它是同输入格式下表现最好的损失。
model = CrossEncoder("microsoft/mpnet-base")
train_dataset = Dataset.from_dict({
"query": ["What are pandas?", "What is the capital of France?"],
"docs": [
["Pandas are a kind of bear.", "Pandas are kind of like fish."],
["The capital of France is Paris.", "Paris is the capital of France.", "Paris is quite large."],
],
"labels": [[1, 0], [1, 1, 0]],
})
loss = losses.LambdaLoss(model)
trainer = CrossEncoderTrainer(model=model, train_dataset=train_dataset, loss=loss)
trainer.train()
五种加权方案(weighting_scheme 参数,默认 NDCGLoss2PPScheme):
| 方案类 | 语义 | 备注 |
|---|---|---|
NoWeightingScheme |
权重恒为 1.0 | 退化为普通 pairwise |
NDCGLoss1Scheme |
NDCG Loss1 | 原论文中不如以下两种 |
NDCGLoss2Scheme |
NDCG Loss2,更紧的上界 | 性能紧随 Loss2++ |
LambdaRankScheme |
LambdaRank 加权,优化 NDCG 的粗略上界 | — |
NDCGLoss2PPScheme |
NDCG Loss2++,Loss2 与 LambdaRank 的混合(mu * ndcg_weights + lambda_weights,mu 默认 10.0) |
原论文中效果最强,为默认值 |
其他参数:
k(默认None):NDCG@K 考虑的文档数,None表示全部;sigma(默认1.0):sigmoid 内分数差的权重;eps(默认1e-10):数值稳定性常数;reduction_log:"binary"(log2,默认)或"natural"(log);activation_fn、mini_batch_size。
实现上 forward 对 logits 与 labels 按分数降序排序,计算 gain 与 discount,再按加权方案生成 pairwise 权重,最终对 sigmoid 概率取负对数平均。参考 MS MARCO 训练示例。
5.2 RankNetLoss:无加权的 pairwise 基座
RankNet 通过对文档两两比较来学习排序函数,数学上是 LambdaLoss 使用 NoWeightingScheme 的特例(源码中直接继承 LambdaLoss 并固定 weighting_scheme=NoWeightingScheme()),见 losses/rank_net.py。参数与 LambdaLoss 一致(不含 weighting_scheme),参考 训练示例。
5.3 ListMLELoss:排列最大似然
基于排列的最大似然估计:最大化 ground truth 标签诱导出的排列概率(Plackett-Luce 模型),源码位于 losses/list_mle.py。它直接继承 PListMLELoss 且不传入 lambda_weight。
loss = losses.ListMLELoss(model) # 默认 respect_input_order=True
关键参数:
respect_input_order(默认True):为 True 时假定输入文档已按相关性降序排列;为 False 时按标签值排序后再计算。
5.4 PListMLELoss:位置感知的 ListMLE
即 Position-Aware ListMLE(p-ListMLE),在 ListMLE 基础上对不同排序位置施加不同权重,通常优于 ListMLELoss,源码位于 losses/plist_mle.py。
# 方式一:默认位置权重 2^(num_docs - rank) - 1
lambda_weight = losses.PListMLELambdaWeight()
loss = losses.PListMLELoss(model, lambda_weight=lambda_weight)
# 方式二:自定义位置折扣函数
import torch
def custom_discount(ranks): # e.g. ranks: [1, 2, 3, 4, 5]
return 1.0 / torch.log1p(ranks)
lambda_weight = losses.PListMLELambdaWeight(rank_discount_fn=custom_discount)
loss = losses.PListMLELoss(model, lambda_weight=lambda_weight)
PListMLELambdaWeight 的 rank_discount_fn 为 None 时使用默认折扣 2^(num_docs - rank) - 1;实现中权重会归一化为每行和为 1。位置权重乘到 Plackett-Luce 对数似然的每一项上,参考 MS MARCO 示例。
5.5 ListNetLoss:分布交叉熵排序
最小化预测排序分布与 ground truth 排序分布之间的交叉熵(top-one 概率),源码位于 losses/list_net.py。实现中用 labels_matrix.softmax(dim=1) 作为目标分布,与 logits 矩阵计算 torch.nn.CrossEntropyLoss。参数仅 activation_fn 与 mini_batch_size,参考 训练示例。
5.6 ADRMSELoss:可微近似排序的回归
ADR-MSE(Approx Discounted Rank Mean Squared Error)列表式排序损失,直接最小化真实排序位置与可微近似预测排序位置之间的误差,并使用受 nDCG 启发的 log 折扣加权,源自 Rank-DistiLLM 论文,源码位于 losses/adr_mse.py。
近似排序公式:approx_rank(i) = 1 + sum_{j != i} sigmoid(alpha * (s_j - s_i))。对标签并列的文档取平均排名,使模型对并列文档给出相同分数时近似排名可达,避免任意打破平局带来的非零最小损失。ADRMSELoss 支持连续分数标签(不限于 0/1)。
model = CrossEncoder("microsoft/mpnet-base")
train_dataset = Dataset.from_dict({
"query": ["What are pandas?", "What is the capital of France?"],
"docs": [
["Pandas are a kind of bear.", "Pandas are kind of like fish."],
["The capital of France is Paris.", "Paris is the capital of France.", "Paris is quite large."],
],
"scores": [[0.95, 0.1], [0.98, 0.92, 0.2]],
})
loss = losses.ADRMSELoss(model)
trainer = CrossEncoderTrainer(model=model, train_dataset=train_dataset, loss=loss)
trainer.train()
参数:
alpha(默认1.0):ApproxRank sigmoid 的温度。越大近似越紧(越不平滑),但已充分分离的 pair 梯度越弱;activation_fn、mini_batch_size(语义同前)。
实现上 approximate_ranks 通过 scores.unsqueeze(1) - scores.unsqueeze(2) 计算 pairwise 差,用 mask 剔除 padding;forward 中 loss = discount * squared_error 再按 mask 取平均。原论文直接对比对象是 RankNetLoss(LLM 蒸馏设定下两者 nDCG@10 差距约 0.002),参考 训练示例。
六、共同参数:mini_batch_size 与 activation_fn
列表式损失普遍提供两个控制训练行为的关键参数,源码 docstring 中均有统一说明:
mini_batch_size(默认 None)——控制每次前向处理的样本数,显著影响显存与速度,三种取值行为:
None:等于整个 batch 大小;> 0:batch 按该大小拆分多个 mini-batch 依次前向;<= 0:整个 batch 一次前向。
activation_fn(默认 nn.Identity)——在计算损失前作用于 logits 的激活函数,在蒸馏场景中用于对齐教师分数的量纲(如教师输出经 Sigmoid 则学生损失也传 Sigmoid)。
七、实战:从数据准备到完整训练
7.1 用 mine_hard_negatives 构造训练数据
绝大多数排序场景的起点是 (anchor, positive) 问答对。通过 hard_negatives.py 中的 mine_hard_negatives 可一步产出适合各损失的数据:
output_format="labeled-list"→ 配LambdaLoss等列表式损失(学习排序常用);output_format="labeled-pair"→ 配BinaryCrossEntropyLoss(同样表现强劲);output_format="triplet"/"n-tuple"→ 配MultipleNegativesRankingLoss/CachedMultipleNegativesRankingLoss;output_scores=True→ 输出连续分数以适配MSELoss/MarginMSELoss蒸馏。
7.2 端到端训练骨架
所有损失均与 CrossEncoderTrainer 配合使用,统一训练流程为:
from sentence_transformers.cross_encoder import CrossEncoder, CrossEncoderTrainer, losses
from datasets import Dataset
model = CrossEncoder("microsoft/mpnet-base")
train_dataset = Dataset.from_dict({...}) # 列名需匹配所选损失的输入格式
loss = losses.<选型>(model)
trainer = CrossEncoderTrainer(model=model, train_dataset=train_dataset, loss=loss)
trainer.train()
每个损失的 forward 方法签名均为 forward(inputs, labels, prompt=None, task=None):inputs 是 batch 内文本的嵌套列表(外层每个元素对应数据集一列),labels 来自数据集的 label/labels/score/scores 列。仓库中 examples/cross_encoder/training/ms_marco 下提供了 training_ms_marco_bce.py、training_ms_marco_lambda.py、training_ms_marco_cmnrl.py、training_ms_marco_listmle.py、training_ms_marco_listnet.py、training_ms_marco_adrmse.py、training_ms_marco_ranknet.py、training_ms_marco_plistmle.py 等可直接运行的脚本,覆盖本文全部排序类损失。
7.3 选型速查
- 数据是二值标注对 / 0-1 相似度:优先
BinaryCrossEntropyLoss,传统且难以被超越; - 只有正样本对,无标签:
MultipleNegativesRankingLoss,显存受限则换CachedMultipleNegativesRankingLoss; - 有 query 下多文档与相关性分数,目标是重排序指标:
LambdaLoss(默认 NDCGLoss2++ 加权)优先,其次PListMLELoss; - 多分类(如 NLI):
CrossEntropyLoss; - 知识蒸馏:分数级用
MSELoss,边际级用MarginMSELoss。
八、自定义损失函数
当内置 14 种损失无法满足需求时,可以自定义损失并接入 CrossEncoderTrainer。根据 loss_overview.md 的要求,自定义损失需满足:
- 必须是
torch.nn.Module子类; - 构造器第一个参数必须是
model; - 实现
forward(inputs, labels):inputs为 batch 内文本的嵌套列表,需自行组合成可 tokenize 的 pairs 并喂给模型;labels为可选的(列表的)张量;返回单个损失值,或返回「组件名 → 损失值」的字典(字典会被求和得到最终损失,各组件还会单独记录日志,便于监控)。
若希望获得自动模型卡生成支持,可额外实现:
get_config_dict():返回损失参数的字典;citation属性:引用字符串会写入所有使用该损失的训练模型卡片。
仓库中各损失类均已实现这两个接口(例如 LambdaLoss.get_config_dict 返回 weighting_scheme、k、sigma、eps、reduction_log 等,citation 返回论文 BibTeX),可作为自定义实现的最佳参考模板。