Cross-Encoder 损失函数完全指南:sentence-transformers 排序模型微调实战

原创2026-09-20 10:06:541,937 阅读
文章标签:人工智能NLP深度学习微调RAG

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()

支持两种标签语义:

  1. 二值标签:(anchor, positive/negative) 对,1 正 0 负;
  2. 连续相似度:(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 中有明确说明:

  1. 无梯度/计算图的快速预测,得到全部 logits;
  2. 计算 loss 并反向传播到 logits 层,缓存 logits 的梯度;
  3. 带计算图做第二次预测,把缓存梯度接入反向链。

参数在基类之上新增:

  • 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),可作为自定义实现的最佳参考模板。

登录后查看全文
sentence-transformers