CrossEncoder 评估器完全指南从重排序到 NanoBEIR 的信息检索评测体系【免费下载链接】sentence-transformersState-of-the-Art Embeddings, Retrieval, and Reranking项目地址: https://gitcode.com/gh_mirrors/se/sentence-transformers导读CrossEncoder交叉编码器在 sentence-transformers 中承担着精排re-ranking与配对打分任务与之配套的是一套独立的评估体系。本文以 docs/package_reference/cross_encoder/evaluation.md 为核心系统讲解sentence_transformers.cross_encoder.evaluation包下的四大评估器——CrossEncoderRerankingEvaluator、CrossEncoderNanoBEIREvaluator、CrossEncoderClassificationEvaluator与CrossEncoderCorrelationEvaluator。读完本文你将掌握每种评估器适用的任务场景、样本数据格式、全部核心参数与默认值以及如何将评估指标接入训练流程实现按指标自动选最优模型。一、CrossEncoder 评估体系总览CrossEncoder 拥有自己独立的评估类统一位于sentence_transformers.cross_encoder.evaluation命名空间下见 包入口。与 SentenceTransformer 的稠密向量评估不同CrossEncoder 评估的核心是句子对打分模型同时接收两个文本并输出一个相关性分数因此其评估器天然围绕打分质量展开。当前包内共导出四类正式评估器外加一组历史遗留的 Deprecated 别名评估器适用任务核心指标CrossEncoderRerankingEvaluator重排序精排MRRk、NDCGk、MAPCrossEncoderNanoBEIREvaluatorNanoBEIR 检索基准快速评测MRRk、NDCGk、MAP逐数据集 均值CrossEncoderClassificationEvaluator二分类 / 多分类Accuracy、F1、Precision、Recall、Average PrecisionCrossEncoderCorrelationEvaluator语义相似度回归STSPearson、Spearman 相关系数所有评估器都继承自 BaseEvaluator该基类统一约定了评估器的两个关键契约greater_is_better布尔值默认True表示分数越高模型越好。当训练参数开启load_best_model_at_end时训练器据此选择最优 checkpointprimary_metric字符串指代评估器返回指标字典中的主指标用于模型选择与日志记录。调用evaluator(model)后会得到一个指标字典配合evaluator.primary_metric即可取出主指标数值。此外基类还提供prefix_name_to_metrics将评估器name作为指标前缀、store_metrics_in_model_card_data把评估结果写入模型的 Model Card与description生成人类可读的评估器描述等方法这些机制让每个评估器都能无缝接入训练循环与模型卡生成流程。二、CrossEncoderRerankingEvaluator重排序质量评测重排序是 CrossEncoder 最典型的应用场景先由召回阶段如 BM25 或 SentenceTransformer 稠密检索返回一批候选文档再由 CrossEncoder 逐一对(query, doc)打分并重新排序。CrossEncoderRerankingEvaluator正是对这一过程的质量度量器源码位于 reranking.py。2.1 评测原理与指标给定一个 query 和一组文档评估器对每个(query, doc_i)计算分数并按降序排列然后计算三项经典排序指标MRRkMean Reciprocal Rank第一个相关文档在 Top-k 中位置倒数的均值NDCGkNormalized Discounted Cumulative Gain考虑相关文档位置与相关级别的折损累计增益MAPMean Average Precision每个查询的平均精确率再取均值。默认at_k10即只考察 Top-10 的排序质量。2.2 样本数据格式两种互斥模式评估器接收一个samples列表每个样本是一个字典必须包含query与positive两个键且negative与documents必须二选一源码第 168-173 行会严格校验并抛出明确的ValueError模式 Anegative模式——提供正例与负例列表评估器只报告重排后的分数模式 Bdocuments模式——提供包含正例在内的全部文档列表假定该列表已按相似度降序排列即模拟第一轮召回结果。此模式下评估器会同时报告召回基线Base→ 重排后Reranked两组分数直观展示精排带来的提升。用 MS MARCO 数据构建样本的完整示例来自源码 Docstringfrom sentence_transformers import CrossEncoder from sentence_transformers.cross_encoder.evaluation import CrossEncoderRerankingEvaluator from datasets import load_dataset # 加载模型 model CrossEncoder(cross-encoder/ms-marco-MiniLM-L6-v2) # 加载包含 query、正例、负例的数据集 eval_dataset load_dataset(microsoft/ms_marco, v1.1, splitvalidation) samples [ { query: sample[query], positive: [text for is_selected, text in zip(sample[passages][is_selected], sample[passages][passage_text]) if is_selected], documents: sample[passages][passage_text], # 或者使用 negative 模式 # negative: [text for is_selected, text in zip(sample[passages][is_selected], sample[passages][passage_text]) if not is_selected], } for sample in eval_dataset ] # 初始化评估器 reranking_evaluator CrossEncoderRerankingEvaluator( samplessamples, namems-marco-dev, show_progress_barTrue, ) results reranking_evaluator(model)2.3 完整参数表参数类型默认值说明sampleslist[dict]必填每个字典含query必填、positive必填、negative或documents二选一at_kint10仅考察每个 query 相似度最高的前 k 个文档always_rerank_positivesboolTrue为True时总是把所有正例纳入排序为False时仅保留documents列表中已有的正例。使用negative模式时必须设为True使用documents模式时True得到更实用的评测信号False更贴近真实场景namestr评估器名称用于日志、CSV 文件名与模型卡prompt_namestr \| NoneNone调用model.predict()时使用的提示词名必须是模型prompts字典中的键batch_sizeint64计算分数时的批大小show_progress_barboolFalse是否显示进度条write_csvboolTrue是否将结果写入 CSV 文件mrr_at_kint \| NoneNone已弃用参数请改用at_k关于分数上限有一个易被忽视的细节由于默认always_rerank_positivesTrue且所有正例都包含在排序中最高分天然是 1.0。若想得到更严格的分数应使用documents模式并设置always_rerank_positivesFalse此时正例可能未被召回进候选集分数上限取决于召回质量。2.4 输出与日志解读评估完成后日志会输出类似下面的对比结果数值取自源码示例实际结果因模型而异CrossEncoderRerankingEvaluator: Evaluating the model on the ms-marco-dev dataset: Queries: 10047 Positives: Min 0.0, Mean 1.1, Max 5.0 Negatives: Min 1.0, Mean 7.1, Max 10.0 Base - Reranked MAP: 34.03 - 62.36 MRR10: 34.67 - 62.96 NDCG10: 49.05 - 71.05主指标可通过reranking_evaluator.primary_metric获取格式为{name}_ndcg{at_k}指标数值通过results[...]取出print(reranking_evaluator.primary_metric) # ms-marco-dev_ndcg10 print(results[reranking_evaluator.primary_metric]) # 0.71046568571841842.5 源码级实现细节从源码实现看该评估器做了两项值得注意的工程优化reranking.py两遍处理 单次批量预测第一遍把所有样本的(query, doc)对拍平成单一列表all_pairs只调用一次model.predict()完成全部打分避免逐样本调用带来的开销第二遍再按sample_metadata记录的偏移量切分预测结果逐样本计算指标。指标计算依赖 scikit-learncompute_metrics中 MRR 通过np.argsort手工实现NDCG 使用ndcg_scoreMAP 使用average_precision_scorereranking.py。评测时若提供了output_path且write_csvTrue结果会以追加方式写入CrossEncoderRerankingEvaluator_{name}_results_{at_k}.csv表头为[epoch, steps, MAP, MRR{at_k}, NDCG{at_k}]。边界行为与校验逻辑在 tests/cross_encoder/evaluation/test_reranking.py 中有完整覆盖positive缺省、negative与documents同时出现或同时缺失都会抛出含明确信息的ValueErrorpositive传入单个字符串而非列表会被自动包裹为列表单样本、documents中不含正例等边界场景均能正常返回指标。三、CrossEncoderNanoBEIREvaluator轻量级检索基准评测NanoBEIR 是基于 BEIR 集合裁剪出的小规模信息检索评测集专为完整跑 BEIR 之前先快速验证模型检索性能而设计。CrossEncoderNanoBEIREvaluator将这一基准与 CrossEncoder 重排评测无缝衔接源码位于 nano_beir.py。3.1 评测机制与CrossEncoderRerankingEvaluator直接对全部候选文档重排不同本评估器只对 BM25 排名的前rerank_k个文档进行重排默认rerank_k100大幅降低评测成本。内部机制是从 Hugging Face 的 NanoBEIR 数据集中加载corpus、queries、qrels、bm25四个子集按Nano{数据集名}的 split 存放组装成CrossEncoderRerankingEvaluator所需的{query, positive, documents}样本格式再逐一评测见 nano_beir.py。它返回与重排评估器相同的指标MRRk、nDCGk、MAP既有每个数据集的单独结果也有全部数据集上的均值aggregate结果。当日志级别设为 INFO 时会自动打印逐数据集与总平均的 Base → Reranked 对比。3.2 支持的数据集与参数内置 13 个 NanoBEIR 数据集climatefever、dbpedia、fever、fiqa2018、hotpotqa、msmarco、nfcorpus、nq、quoraretrieval、scidocs、arguana、scifact、touche2020。重要行为差异默认情况下不手动指定dataset_names评估器会排除arguana与touche2020因为其 Argument Retrieval 任务与其他数据集存在明显差异。这与sentence_transformer.evaluation.NanoBEIREvaluator和sparse_encoder.evaluation.SparseNanoBEIREvaluator默认包含全部数据集有所不同。完整参数如下参数类型默认值说明dataset_nameslist[str]全部除 arguana、touche2020要评测的数据集短名列表dataset_idstrsentence-transformers/NanoBEIR-enHuggingFace 数据集 ID可替换为其他语言的 NanoBEIR 数据集要求含corpus/queries/qrels/bm25子集rerank_kint100从 BM25 排名中取前多少个文档进行重排at_kint10排序指标只考察 Top-kalways_rerank_positivesboolTrue语义同CrossEncoderRerankingEvaluatorprompt_namestr \| NoneNone提示词名batch_sizeint32预测批大小show_progress_barboolFalse是否显示进度条write_csvboolTrue是否写 CSVaggregate_fnCallablenp.mean聚合各数据集分数的函数aggregate_keystrmean聚合结果的键名3.3 结果键命名与训练集成本评估器的输出键遵循固定格式源码 Docstring 明确说明聚合结果NanoBEIR_R{rerank_k}_{aggregate_key}_{metric}其中metric为map、mrr{at_k}或ndcg{at_k}。默认主指标名为NanoBEIR_R100_mean_ndcg10单数据集结果Nano{数据集名}_R{rerank_k}_{metric}例如NanoMSMARCO_R100_mrr10。这些键可直接用作训练时的metric_for_best_model配合CrossEncoderTrainingArguments中的load_best_model_at_endTruetraining_args.py实现训练过程中自动加载指定指标最优的模型。基本用法示例from sentence_transformers.cross_encoder import CrossEncoder from sentence_transformers.cross_encoder.evaluation import CrossEncoderNanoBEIREvaluator import logging logging.basicConfig(levellogging.INFO, format%(asctime)s - %(message)s) model CrossEncoder(cross-encoder/ms-marco-MiniLM-L6-v2) # 只评测三个数据集快速验证 dataset_names [msmarco, nfcorpus, nq] evaluator CrossEncoderNanoBEIREvaluator(dataset_names) results evaluator(model) print(evaluator.primary_metric) # NanoBEIR_R100_mean_ndcg10 print(results[evaluator.primary_metric]) # 0.60716840988382评测自定义如翻译后的数据集时只需替换dataset_id例如传入Serbian-AI-Society/NanoBEIR-sr即可用非英文模型评测对应语言的数据集。注意使用本评估器需要安装datasets库pip install datasets否则会在加载数据集时抛出明确错误见 nano_beir.py 中的is_datasets_available检查。四、CrossEncoderClassificationEvaluator分类任务评测当 CrossEncoder 被用于判断两个文本是否属于同一类如 NLI 蕴含判断、重复问题检测、相关性二分类时使用CrossEncoderClassificationEvaluator评估分类质量源码位于 classification.py。4.1 单输出二分类与多输出模式评估器根据模型的输出维度自动切换评测逻辑model.num_labels决定num_labels 1单输出即二分类模型使用BinaryClassificationEvaluator.find_best_acc_and_threshold与find_best_f1_and_threshold搜索最优决策阈值报告Accuracy、F1、Precision、Recall、Average Precision平均精确率并给出对应的最优阈值。此时主指标为average_precisionnum_labels 1多输出多分类模型取argmax得到预测类别报告Macro F1、Micro F1、Weighted F1。此时主指标为f1_macro。4.2 构造参数与 NLI 示例参数说明参数类型默认值说明sentence_pairslist[list[str]]必填句子对列表每元素为两个字符串labelslist[int]必填每对句子对应的金标标签与sentence_pairs长度必须一致否则抛ValueErrornamestr评估器名称prompt_namestr \| NoneNone提示词名batch_sizeint32预测批大小show_progress_barbool \| NoneNone为None时仅当日志级别为 INFO/DEBUG 时显示进度条write_csvboolTrue是否写 CSV用 NLI 数据集sentence-transformers/all-nli 的pair-class子集做多分类评测的完整示例from sentence_transformers import CrossEncoder from sentence_transformers.cross_encoder.evaluation import CrossEncoderClassificationEvaluator from datasets import load_dataset # 加载模型 model CrossEncoder(cross-encoder/nli-deberta-v3-base) # 加载包含两列文本和一列标签的数据集 eval_dataset load_dataset(sentence-transformers/all-nli, pair-class, splitdev[-1000:]) # 构造句子对并将标签映射为模型认识的标签 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_pairspairs, labelslabels, nameall-nli-dev, ) results cls_evaluator(model) CrossEncoderClassificationEvaluator: Evaluating the model on all-nli-dev dataset: Macro F1: 89.43 Micro F1: 89.30 Weighted F1: 89.33 print(cls_evaluator.primary_metric) # all-nli-dev_f1_macro print(results[cls_evaluator.primary_metric]) # 0.8942858180262628二分类模式下日志输出格式略有不同会附带最优阈值Accuracy: 85.32 (Threshold: 0.4371) F1: 78.94 (Threshold: 0.5123) Precision: 81.23 Recall: 76.84 Average Precision: 88.174.3 历史遗留类Deprecated在旧版 API 中分类与相关度评估由多个以CE前缀命名的类承担。当前仓库将它们统一收敛为上述四个正式类并在 deprecated.py 中以deprecated装饰器标记CEBinaryAccuracyEvaluator、CEBinaryClassificationEvaluator、CEF1Evaluator、CESoftmaxAccuracyEvaluator→ 全部建议改用CrossEncoderClassificationEvaluator其同时支持二分类与多分类输入基本兼容CECorrelationEvaluator→ 改名为CrossEncoderCorrelationEvaluatorCERerankingEvaluator→ 改名为CrossEncoderRerankingEvaluator。新代码请直接使用正式类这些别名仍在__init__.py中导出以保持向后兼容但会在使用时报出弃用警告。五、CrossEncoderCorrelationEvaluator语义相似度回归评测在 STSSemantic Textual Similarity等任务中模型需要为句子对输出一个连续相似度分数评估时通常用预测分数与金标分数的相关性来衡量质量。CrossEncoderCorrelationEvaluator正是为此设计源码位于 correlation.py。5.1 原理与参数它接收句子对列表与连续型金标分数计算预测分数与金标分数之间的Pearson 相关系数线性相关Spearman 相关系数秩相关对单调关系更稳健。主指标为spearman。参数与CrossEncoderClassificationEvaluator几乎一致sentence_pairs、labels/scores、name、prompt_name、batch_size32、show_progress_barNone、write_csvTrue唯一的区别是第二参数名为scores连续值而非类别标签。用 STSB 数据集评测的完整示例from datasets import load_dataset from sentence_transformers import CrossEncoder from sentence_transformers.cross_encoder.evaluation import CrossEncoderCorrelationEvaluator # 加载模型 model CrossEncoder(cross-encoder/ms-marco-MiniLM-L6-v2) # 加载 STSB 数据集 eval_dataset load_dataset(sentence-transformers/stsb, splitvalidation) pairs list(zip(eval_dataset[sentence1], eval_dataset[sentence2])) # 初始化评估器 dev_evaluator CrossEncoderCorrelationEvaluator( sentence_pairspairs, scoreseval_dataset[score], namests_dev, ) results dev_evaluator(model) CrossEncoderCorrelationEvaluator: Evaluating the model on sts_dev dataset: Correlation: Pearson: 0.8503 Spearman: 0.8486 print(dev_evaluator.primary_metric) # sts_dev_spearman print(results[dev_evaluator.primary_metric]) # 0.84864678978720385.2 便捷工厂方法该类额外提供类方法from_input_examples可从InputExample列表直接构造评估器correlation.py将每个example.texts作为句子对、example.label作为分数。这一入口让评估器可以很方便地接入既有训练管线中基于InputExample组织的数据。5.3 相关系数的计算实现从源码看correlation.py评估流程是先调用model.predict(self.sentence_pairs, ...)得到所有预测分数再分别用scipy.stats.pearsonr与scipy.stats.spearmanr计算两类相关系数。与重排评估器一致结果会通过store_metrics_in_model_card_data写入模型卡并在提供output_path时追加写入CrossEncoderCorrelationEvaluator_{name}_results.csv表头含Pearson_Correlation、Spearman_Correlation。六、评估器与训练流程的协同6.1 统一的调用约定四个正式评估器都遵循BaseEvaluator约定的调用签名evaluator(model, output_pathNone, epoch-1, steps-1) - dict[str, float]。训练过程中CrossEncoder 的 trainer 会在每个 epoch 结束或指定 steps时调用评估器将返回的指标字典用于 checkpoint 选择与日志记录epoch/steps参数同时决定了 CSV 中的记录与日志文案如 after epoch 1。6.2 指标前缀与主指标当给评估器指定了name例如ms-marco-dev时返回字典的所有键都会带上{name}_前缀prefix_name_to_metricsprimary_metric也会同步更新为{name}_{原始主指标}。这保证了多评估器并行评测时指标互不冲突也能直接对应CrossEncoderTrainingArguments中的metric_for_best_model。6.3 选型建议训练/评测任务推荐评估器精排模型MS MARCO、NQ 等检索语料CrossEncoderRerankingEvaluator自有数据或CrossEncoderNanoBEIREvaluator快速对标基准NLI、重复检测等二分类/多分类CrossEncoderClassificationEvaluatorSTS 相似度回归CrossEncoderCorrelationEvaluator七、进一步阅读评估器的完整源码sentence_transformers/cross_encoder/evaluation/含reranking.py、nano_beir.py、classification.py、correlation.py、deprecated.py评估器基类契约sentence_transformers/base/evaluation/evaluator.py行为验证测试tests/cross_encoder/evaluation/test_reranking.py训练参数中的指标选择CrossEncoderTrainingArgumentssentence_transformers/cross_encoder/training_args.py评估器搭配训练脚本的实战示例examples/cross_encoder/training/ 目录下各训练脚本CrossEncoder 模型本身的 API 参考docs/package_reference/cross_encoder/model.md【免费下载链接】sentence-transformersState-of-the-Art Embeddings, Retrieval, and Reranking项目地址: https://gitcode.com/gh_mirrors/se/sentence-transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CrossEncoder 评估器完全指南：从重排序到 NanoBEIR 的信息检索评测体系
CrossEncoder 评估器完全指南从重排序到 NanoBEIR 的信息检索评测体系【免费下载链接】sentence-transformersState-of-the-Art Embeddings, Retrieval, and Reranking项目地址: https://gitcode.com/gh_mirrors/se/sentence-transformers导读CrossEncoder交叉编码器在 sentence-transformers 中承担着精排re-ranking与配对打分任务与之配套的是一套独立的评估体系。本文以 docs/package_reference/cross_encoder/evaluation.md 为核心系统讲解sentence_transformers.cross_encoder.evaluation包下的四大评估器——CrossEncoderRerankingEvaluator、CrossEncoderNanoBEIREvaluator、CrossEncoderClassificationEvaluator与CrossEncoderCorrelationEvaluator。读完本文你将掌握每种评估器适用的任务场景、样本数据格式、全部核心参数与默认值以及如何将评估指标接入训练流程实现按指标自动选最优模型。一、CrossEncoder 评估体系总览CrossEncoder 拥有自己独立的评估类统一位于sentence_transformers.cross_encoder.evaluation命名空间下见 包入口。与 SentenceTransformer 的稠密向量评估不同CrossEncoder 评估的核心是句子对打分模型同时接收两个文本并输出一个相关性分数因此其评估器天然围绕打分质量展开。当前包内共导出四类正式评估器外加一组历史遗留的 Deprecated 别名评估器适用任务核心指标CrossEncoderRerankingEvaluator重排序精排MRRk、NDCGk、MAPCrossEncoderNanoBEIREvaluatorNanoBEIR 检索基准快速评测MRRk、NDCGk、MAP逐数据集 均值CrossEncoderClassificationEvaluator二分类 / 多分类Accuracy、F1、Precision、Recall、Average PrecisionCrossEncoderCorrelationEvaluator语义相似度回归STSPearson、Spearman 相关系数所有评估器都继承自 BaseEvaluator该基类统一约定了评估器的两个关键契约greater_is_better布尔值默认True表示分数越高模型越好。当训练参数开启load_best_model_at_end时训练器据此选择最优 checkpointprimary_metric字符串指代评估器返回指标字典中的主指标用于模型选择与日志记录。调用evaluator(model)后会得到一个指标字典配合evaluator.primary_metric即可取出主指标数值。此外基类还提供prefix_name_to_metrics将评估器name作为指标前缀、store_metrics_in_model_card_data把评估结果写入模型的 Model Card与description生成人类可读的评估器描述等方法这些机制让每个评估器都能无缝接入训练循环与模型卡生成流程。二、CrossEncoderRerankingEvaluator重排序质量评测重排序是 CrossEncoder 最典型的应用场景先由召回阶段如 BM25 或 SentenceTransformer 稠密检索返回一批候选文档再由 CrossEncoder 逐一对(query, doc)打分并重新排序。CrossEncoderRerankingEvaluator正是对这一过程的质量度量器源码位于 reranking.py。2.1 评测原理与指标给定一个 query 和一组文档评估器对每个(query, doc_i)计算分数并按降序排列然后计算三项经典排序指标MRRkMean Reciprocal Rank第一个相关文档在 Top-k 中位置倒数的均值NDCGkNormalized Discounted Cumulative Gain考虑相关文档位置与相关级别的折损累计增益MAPMean Average Precision每个查询的平均精确率再取均值。默认at_k10即只考察 Top-10 的排序质量。2.2 样本数据格式两种互斥模式评估器接收一个samples列表每个样本是一个字典必须包含query与positive两个键且negative与documents必须二选一源码第 168-173 行会严格校验并抛出明确的ValueError模式 Anegative模式——提供正例与负例列表评估器只报告重排后的分数模式 Bdocuments模式——提供包含正例在内的全部文档列表假定该列表已按相似度降序排列即模拟第一轮召回结果。此模式下评估器会同时报告召回基线Base→ 重排后Reranked两组分数直观展示精排带来的提升。用 MS MARCO 数据构建样本的完整示例来自源码 Docstringfrom sentence_transformers import CrossEncoder from sentence_transformers.cross_encoder.evaluation import CrossEncoderRerankingEvaluator from datasets import load_dataset # 加载模型 model CrossEncoder(cross-encoder/ms-marco-MiniLM-L6-v2) # 加载包含 query、正例、负例的数据集 eval_dataset load_dataset(microsoft/ms_marco, v1.1, splitvalidation) samples [ { query: sample[query], positive: [text for is_selected, text in zip(sample[passages][is_selected], sample[passages][passage_text]) if is_selected], documents: sample[passages][passage_text], # 或者使用 negative 模式 # negative: [text for is_selected, text in zip(sample[passages][is_selected], sample[passages][passage_text]) if not is_selected], } for sample in eval_dataset ] # 初始化评估器 reranking_evaluator CrossEncoderRerankingEvaluator( samplessamples, namems-marco-dev, show_progress_barTrue, ) results reranking_evaluator(model)2.3 完整参数表参数类型默认值说明sampleslist[dict]必填每个字典含query必填、positive必填、negative或documents二选一at_kint10仅考察每个 query 相似度最高的前 k 个文档always_rerank_positivesboolTrue为True时总是把所有正例纳入排序为False时仅保留documents列表中已有的正例。使用negative模式时必须设为True使用documents模式时True得到更实用的评测信号False更贴近真实场景namestr评估器名称用于日志、CSV 文件名与模型卡prompt_namestr \| NoneNone调用model.predict()时使用的提示词名必须是模型prompts字典中的键batch_sizeint64计算分数时的批大小show_progress_barboolFalse是否显示进度条write_csvboolTrue是否将结果写入 CSV 文件mrr_at_kint \| NoneNone已弃用参数请改用at_k关于分数上限有一个易被忽视的细节由于默认always_rerank_positivesTrue且所有正例都包含在排序中最高分天然是 1.0。若想得到更严格的分数应使用documents模式并设置always_rerank_positivesFalse此时正例可能未被召回进候选集分数上限取决于召回质量。2.4 输出与日志解读评估完成后日志会输出类似下面的对比结果数值取自源码示例实际结果因模型而异CrossEncoderRerankingEvaluator: Evaluating the model on the ms-marco-dev dataset: Queries: 10047 Positives: Min 0.0, Mean 1.1, Max 5.0 Negatives: Min 1.0, Mean 7.1, Max 10.0 Base - Reranked MAP: 34.03 - 62.36 MRR10: 34.67 - 62.96 NDCG10: 49.05 - 71.05主指标可通过reranking_evaluator.primary_metric获取格式为{name}_ndcg{at_k}指标数值通过results[...]取出print(reranking_evaluator.primary_metric) # ms-marco-dev_ndcg10 print(results[reranking_evaluator.primary_metric]) # 0.71046568571841842.5 源码级实现细节从源码实现看该评估器做了两项值得注意的工程优化reranking.py两遍处理 单次批量预测第一遍把所有样本的(query, doc)对拍平成单一列表all_pairs只调用一次model.predict()完成全部打分避免逐样本调用带来的开销第二遍再按sample_metadata记录的偏移量切分预测结果逐样本计算指标。指标计算依赖 scikit-learncompute_metrics中 MRR 通过np.argsort手工实现NDCG 使用ndcg_scoreMAP 使用average_precision_scorereranking.py。评测时若提供了output_path且write_csvTrue结果会以追加方式写入CrossEncoderRerankingEvaluator_{name}_results_{at_k}.csv表头为[epoch, steps, MAP, MRR{at_k}, NDCG{at_k}]。边界行为与校验逻辑在 tests/cross_encoder/evaluation/test_reranking.py 中有完整覆盖positive缺省、negative与documents同时出现或同时缺失都会抛出含明确信息的ValueErrorpositive传入单个字符串而非列表会被自动包裹为列表单样本、documents中不含正例等边界场景均能正常返回指标。三、CrossEncoderNanoBEIREvaluator轻量级检索基准评测NanoBEIR 是基于 BEIR 集合裁剪出的小规模信息检索评测集专为完整跑 BEIR 之前先快速验证模型检索性能而设计。CrossEncoderNanoBEIREvaluator将这一基准与 CrossEncoder 重排评测无缝衔接源码位于 nano_beir.py。3.1 评测机制与CrossEncoderRerankingEvaluator直接对全部候选文档重排不同本评估器只对 BM25 排名的前rerank_k个文档进行重排默认rerank_k100大幅降低评测成本。内部机制是从 Hugging Face 的 NanoBEIR 数据集中加载corpus、queries、qrels、bm25四个子集按Nano{数据集名}的 split 存放组装成CrossEncoderRerankingEvaluator所需的{query, positive, documents}样本格式再逐一评测见 nano_beir.py。它返回与重排评估器相同的指标MRRk、nDCGk、MAP既有每个数据集的单独结果也有全部数据集上的均值aggregate结果。当日志级别设为 INFO 时会自动打印逐数据集与总平均的 Base → Reranked 对比。3.2 支持的数据集与参数内置 13 个 NanoBEIR 数据集climatefever、dbpedia、fever、fiqa2018、hotpotqa、msmarco、nfcorpus、nq、quoraretrieval、scidocs、arguana、scifact、touche2020。重要行为差异默认情况下不手动指定dataset_names评估器会排除arguana与touche2020因为其 Argument Retrieval 任务与其他数据集存在明显差异。这与sentence_transformer.evaluation.NanoBEIREvaluator和sparse_encoder.evaluation.SparseNanoBEIREvaluator默认包含全部数据集有所不同。完整参数如下参数类型默认值说明dataset_nameslist[str]全部除 arguana、touche2020要评测的数据集短名列表dataset_idstrsentence-transformers/NanoBEIR-enHuggingFace 数据集 ID可替换为其他语言的 NanoBEIR 数据集要求含corpus/queries/qrels/bm25子集rerank_kint100从 BM25 排名中取前多少个文档进行重排at_kint10排序指标只考察 Top-kalways_rerank_positivesboolTrue语义同CrossEncoderRerankingEvaluatorprompt_namestr \| NoneNone提示词名batch_sizeint32预测批大小show_progress_barboolFalse是否显示进度条write_csvboolTrue是否写 CSVaggregate_fnCallablenp.mean聚合各数据集分数的函数aggregate_keystrmean聚合结果的键名3.3 结果键命名与训练集成本评估器的输出键遵循固定格式源码 Docstring 明确说明聚合结果NanoBEIR_R{rerank_k}_{aggregate_key}_{metric}其中metric为map、mrr{at_k}或ndcg{at_k}。默认主指标名为NanoBEIR_R100_mean_ndcg10单数据集结果Nano{数据集名}_R{rerank_k}_{metric}例如NanoMSMARCO_R100_mrr10。这些键可直接用作训练时的metric_for_best_model配合CrossEncoderTrainingArguments中的load_best_model_at_endTruetraining_args.py实现训练过程中自动加载指定指标最优的模型。基本用法示例from sentence_transformers.cross_encoder import CrossEncoder from sentence_transformers.cross_encoder.evaluation import CrossEncoderNanoBEIREvaluator import logging logging.basicConfig(levellogging.INFO, format%(asctime)s - %(message)s) model CrossEncoder(cross-encoder/ms-marco-MiniLM-L6-v2) # 只评测三个数据集快速验证 dataset_names [msmarco, nfcorpus, nq] evaluator CrossEncoderNanoBEIREvaluator(dataset_names) results evaluator(model) print(evaluator.primary_metric) # NanoBEIR_R100_mean_ndcg10 print(results[evaluator.primary_metric]) # 0.60716840988382评测自定义如翻译后的数据集时只需替换dataset_id例如传入Serbian-AI-Society/NanoBEIR-sr即可用非英文模型评测对应语言的数据集。注意使用本评估器需要安装datasets库pip install datasets否则会在加载数据集时抛出明确错误见 nano_beir.py 中的is_datasets_available检查。四、CrossEncoderClassificationEvaluator分类任务评测当 CrossEncoder 被用于判断两个文本是否属于同一类如 NLI 蕴含判断、重复问题检测、相关性二分类时使用CrossEncoderClassificationEvaluator评估分类质量源码位于 classification.py。4.1 单输出二分类与多输出模式评估器根据模型的输出维度自动切换评测逻辑model.num_labels决定num_labels 1单输出即二分类模型使用BinaryClassificationEvaluator.find_best_acc_and_threshold与find_best_f1_and_threshold搜索最优决策阈值报告Accuracy、F1、Precision、Recall、Average Precision平均精确率并给出对应的最优阈值。此时主指标为average_precisionnum_labels 1多输出多分类模型取argmax得到预测类别报告Macro F1、Micro F1、Weighted F1。此时主指标为f1_macro。4.2 构造参数与 NLI 示例参数说明参数类型默认值说明sentence_pairslist[list[str]]必填句子对列表每元素为两个字符串labelslist[int]必填每对句子对应的金标标签与sentence_pairs长度必须一致否则抛ValueErrornamestr评估器名称prompt_namestr \| NoneNone提示词名batch_sizeint32预测批大小show_progress_barbool \| NoneNone为None时仅当日志级别为 INFO/DEBUG 时显示进度条write_csvboolTrue是否写 CSV用 NLI 数据集sentence-transformers/all-nli 的pair-class子集做多分类评测的完整示例from sentence_transformers import CrossEncoder from sentence_transformers.cross_encoder.evaluation import CrossEncoderClassificationEvaluator from datasets import load_dataset # 加载模型 model CrossEncoder(cross-encoder/nli-deberta-v3-base) # 加载包含两列文本和一列标签的数据集 eval_dataset load_dataset(sentence-transformers/all-nli, pair-class, splitdev[-1000:]) # 构造句子对并将标签映射为模型认识的标签 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_pairspairs, labelslabels, nameall-nli-dev, ) results cls_evaluator(model) CrossEncoderClassificationEvaluator: Evaluating the model on all-nli-dev dataset: Macro F1: 89.43 Micro F1: 89.30 Weighted F1: 89.33 print(cls_evaluator.primary_metric) # all-nli-dev_f1_macro print(results[cls_evaluator.primary_metric]) # 0.8942858180262628二分类模式下日志输出格式略有不同会附带最优阈值Accuracy: 85.32 (Threshold: 0.4371) F1: 78.94 (Threshold: 0.5123) Precision: 81.23 Recall: 76.84 Average Precision: 88.174.3 历史遗留类Deprecated在旧版 API 中分类与相关度评估由多个以CE前缀命名的类承担。当前仓库将它们统一收敛为上述四个正式类并在 deprecated.py 中以deprecated装饰器标记CEBinaryAccuracyEvaluator、CEBinaryClassificationEvaluator、CEF1Evaluator、CESoftmaxAccuracyEvaluator→ 全部建议改用CrossEncoderClassificationEvaluator其同时支持二分类与多分类输入基本兼容CECorrelationEvaluator→ 改名为CrossEncoderCorrelationEvaluatorCERerankingEvaluator→ 改名为CrossEncoderRerankingEvaluator。新代码请直接使用正式类这些别名仍在__init__.py中导出以保持向后兼容但会在使用时报出弃用警告。五、CrossEncoderCorrelationEvaluator语义相似度回归评测在 STSSemantic Textual Similarity等任务中模型需要为句子对输出一个连续相似度分数评估时通常用预测分数与金标分数的相关性来衡量质量。CrossEncoderCorrelationEvaluator正是为此设计源码位于 correlation.py。5.1 原理与参数它接收句子对列表与连续型金标分数计算预测分数与金标分数之间的Pearson 相关系数线性相关Spearman 相关系数秩相关对单调关系更稳健。主指标为spearman。参数与CrossEncoderClassificationEvaluator几乎一致sentence_pairs、labels/scores、name、prompt_name、batch_size32、show_progress_barNone、write_csvTrue唯一的区别是第二参数名为scores连续值而非类别标签。用 STSB 数据集评测的完整示例from datasets import load_dataset from sentence_transformers import CrossEncoder from sentence_transformers.cross_encoder.evaluation import CrossEncoderCorrelationEvaluator # 加载模型 model CrossEncoder(cross-encoder/ms-marco-MiniLM-L6-v2) # 加载 STSB 数据集 eval_dataset load_dataset(sentence-transformers/stsb, splitvalidation) pairs list(zip(eval_dataset[sentence1], eval_dataset[sentence2])) # 初始化评估器 dev_evaluator CrossEncoderCorrelationEvaluator( sentence_pairspairs, scoreseval_dataset[score], namests_dev, ) results dev_evaluator(model) CrossEncoderCorrelationEvaluator: Evaluating the model on sts_dev dataset: Correlation: Pearson: 0.8503 Spearman: 0.8486 print(dev_evaluator.primary_metric) # sts_dev_spearman print(results[dev_evaluator.primary_metric]) # 0.84864678978720385.2 便捷工厂方法该类额外提供类方法from_input_examples可从InputExample列表直接构造评估器correlation.py将每个example.texts作为句子对、example.label作为分数。这一入口让评估器可以很方便地接入既有训练管线中基于InputExample组织的数据。5.3 相关系数的计算实现从源码看correlation.py评估流程是先调用model.predict(self.sentence_pairs, ...)得到所有预测分数再分别用scipy.stats.pearsonr与scipy.stats.spearmanr计算两类相关系数。与重排评估器一致结果会通过store_metrics_in_model_card_data写入模型卡并在提供output_path时追加写入CrossEncoderCorrelationEvaluator_{name}_results.csv表头含Pearson_Correlation、Spearman_Correlation。六、评估器与训练流程的协同6.1 统一的调用约定四个正式评估器都遵循BaseEvaluator约定的调用签名evaluator(model, output_pathNone, epoch-1, steps-1) - dict[str, float]。训练过程中CrossEncoder 的 trainer 会在每个 epoch 结束或指定 steps时调用评估器将返回的指标字典用于 checkpoint 选择与日志记录epoch/steps参数同时决定了 CSV 中的记录与日志文案如 after epoch 1。6.2 指标前缀与主指标当给评估器指定了name例如ms-marco-dev时返回字典的所有键都会带上{name}_前缀prefix_name_to_metricsprimary_metric也会同步更新为{name}_{原始主指标}。这保证了多评估器并行评测时指标互不冲突也能直接对应CrossEncoderTrainingArguments中的metric_for_best_model。6.3 选型建议训练/评测任务推荐评估器精排模型MS MARCO、NQ 等检索语料CrossEncoderRerankingEvaluator自有数据或CrossEncoderNanoBEIREvaluator快速对标基准NLI、重复检测等二分类/多分类CrossEncoderClassificationEvaluatorSTS 相似度回归CrossEncoderCorrelationEvaluator七、进一步阅读评估器的完整源码sentence_transformers/cross_encoder/evaluation/含reranking.py、nano_beir.py、classification.py、correlation.py、deprecated.py评估器基类契约sentence_transformers/base/evaluation/evaluator.py行为验证测试tests/cross_encoder/evaluation/test_reranking.py训练参数中的指标选择CrossEncoderTrainingArgumentssentence_transformers/cross_encoder/training_args.py评估器搭配训练脚本的实战示例examples/cross_encoder/training/ 目录下各训练脚本CrossEncoder 模型本身的 API 参考docs/package_reference/cross_encoder/model.md【免费下载链接】sentence-transformersState-of-the-Art Embeddings, Retrieval, and Reranking项目地址: https://gitcode.com/gh_mirrors/se/sentence-transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考