CrossEncoder 評估器完全指南從重排序到 NanoBEIR 的信息檢索評測體系【免費下載鏈接】sentence-transformersState-of-the-Art Embeddings, Retrieval, and Reranking項目地址: https://gitcode.com/gh_mirrors/se/sentence-transformers導(dǎo)讀CrossEncoder交叉編碼器在 sentence-transformers 中承擔(dān)著精排re-ranking與配對打分任務(wù)與之配套的是一套獨立的評估體系。本文以 docs/package_reference/cross_encoder/evaluation.md 為核心系統(tǒng)講解sentence_transformers.cross_encoder.evaluation包下的四大評估器——CrossEncoderRerankingEvaluator、CrossEncoderNanoBEIREvaluator、CrossEncoderClassificationEvaluator與CrossEncoderCorrelationEvaluator。讀完本文你將掌握每種評估器適用的任務(wù)場景、樣本數(shù)據(jù)格式、全部核心參數(shù)與默認(rèn)值以及如何將評估指標(biāo)接入訓(xùn)練流程實現(xiàn)按指標(biāo)自動選最優(yōu)模型。一、CrossEncoder 評估體系總覽CrossEncoder 擁有自己獨立的評估類統(tǒng)一位于sentence_transformers.cross_encoder.evaluation命名空間下見 包入口。與 SentenceTransformer 的稠密向量評估不同CrossEncoder 評估的核心是句子對打分模型同時接收兩個文本并輸出一個相關(guān)性分?jǐn)?shù)因此其評估器天然圍繞打分質(zhì)量展開。當(dāng)前包內(nèi)共導(dǎo)出四類正式評估器外加一組歷史遺留的 Deprecated 別名評估器適用任務(wù)核心指標(biāo)CrossEncoderRerankingEvaluator重排序精排MRRk、NDCGk、MAPCrossEncoderNanoBEIREvaluatorNanoBEIR 檢索基準(zhǔn)快速評測MRRk、NDCGk、MAP逐數(shù)據(jù)集 均值CrossEncoderClassificationEvaluator二分類 / 多分類Accuracy、F1、Precision、Recall、Average PrecisionCrossEncoderCorrelationEvaluator語義相似度回歸STSPearson、Spearman 相關(guān)系數(shù)所有評估器都繼承自 BaseEvaluator該基類統(tǒng)一約定了評估器的兩個關(guān)鍵契約greater_is_better布爾值默認(rèn)True表示分?jǐn)?shù)越高模型越好。當(dāng)訓(xùn)練參數(shù)開啟load_best_model_at_end時訓(xùn)練器據(jù)此選擇最優(yōu) checkpointprimary_metric字符串指代評估器返回指標(biāo)字典中的主指標(biāo)用于模型選擇與日志記錄。調(diào)用evaluator(model)后會得到一個指標(biāo)字典配合evaluator.primary_metric即可取出主指標(biāo)數(shù)值。此外基類還提供prefix_name_to_metrics將評估器name作為指標(biāo)前綴、store_metrics_in_model_card_data把評估結(jié)果寫入模型的 Model Card與description生成人類可讀的評估器描述等方法這些機制讓每個評估器都能無縫接入訓(xùn)練循環(huán)與模型卡生成流程。二、CrossEncoderRerankingEvaluator重排序質(zhì)量評測重排序是 CrossEncoder 最典型的應(yīng)用場景先由召回階段如 BM25 或 SentenceTransformer 稠密檢索返回一批候選文檔再由 CrossEncoder 逐一對(query, doc)打分并重新排序。CrossEncoderRerankingEvaluator正是對這一過程的質(zhì)量度量器源碼位于 reranking.py。2.1 評測原理與指標(biāo)給定一個 query 和一組文檔評估器對每個(query, doc_i)計算分?jǐn)?shù)并按降序排列然后計算三項經(jīng)典排序指標(biāo)MRRkMean Reciprocal Rank第一個相關(guān)文檔在 Top-k 中位置倒數(shù)的均值NDCGkNormalized Discounted Cumulative Gain考慮相關(guān)文檔位置與相關(guān)級別的折損累計增益MAPMean Average Precision每個查詢的平均精確率再取均值。默認(rèn)at_k10即只考察 Top-10 的排序質(zhì)量。2.2 樣本數(shù)據(jù)格式兩種互斥模式評估器接收一個samples列表每個樣本是一個字典必須包含query與positive兩個鍵且negative與documents必須二選一源碼第 168-173 行會嚴(yán)格校驗并拋出明確的ValueError模式 Anegative模式——提供正例與負(fù)例列表評估器只報告重排后的分?jǐn)?shù)模式 Bdocuments模式——提供包含正例在內(nèi)的全部文檔列表假定該列表已按相似度降序排列即模擬第一輪召回結(jié)果。此模式下評估器會同時報告召回基線Base→ 重排后Reranked兩組分?jǐn)?shù)直觀展示精排帶來的提升。用 MS MARCO 數(shù)據(jù)構(gòu)建樣本的完整示例來自源碼 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、正例、負(fù)例的數(shù)據(jù)集 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 完整參數(shù)表參數(shù)類型默認(rèn)值說明sampleslist[dict]必填每個字典含query必填、positive必填、negative或documents二選一at_kint10僅考察每個 query 相似度最高的前 k 個文檔always_rerank_positivesboolTrue為True時總是把所有正例納入排序為False時僅保留documents列表中已有的正例。使用negative模式時必須設(shè)為True使用documents模式時True得到更實用的評測信號False更貼近真實場景namestr評估器名稱用于日志、CSV 文件名與模型卡prompt_namestr \| NoneNone調(diào)用model.predict()時使用的提示詞名必須是模型prompts字典中的鍵batch_sizeint64計算分?jǐn)?shù)時的批大小show_progress_barboolFalse是否顯示進度條write_csvboolTrue是否將結(jié)果寫入 CSV 文件mrr_at_kint \| NoneNone已棄用參數(shù)請改用at_k關(guān)于分?jǐn)?shù)上限有一個易被忽視的細(xì)節(jié)由于默認(rèn)always_rerank_positivesTrue且所有正例都包含在排序中最高分天然是 1.0。若想得到更嚴(yán)格的分?jǐn)?shù)應(yīng)使用documents模式并設(shè)置always_rerank_positivesFalse此時正例可能未被召回進候選集分?jǐn)?shù)上限取決于召回質(zhì)量。2.4 輸出與日志解讀評估完成后日志會輸出類似下面的對比結(jié)果數(shù)值取自源碼示例實際結(jié)果因模型而異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主指標(biāo)可通過reranking_evaluator.primary_metric獲取格式為{name}_ndcg{at_k}指標(biāo)數(shù)值通過results[...]取出print(reranking_evaluator.primary_metric) # ms-marco-dev_ndcg10 print(results[reranking_evaluator.primary_metric]) # 0.71046568571841842.5 源碼級實現(xiàn)細(xì)節(jié)從源碼實現(xiàn)看該評估器做了兩項值得注意的工程優(yōu)化reranking.py兩遍處理 單次批量預(yù)測第一遍把所有樣本的(query, doc)對拍平成單一列表all_pairs只調(diào)用一次model.predict()完成全部打分避免逐樣本調(diào)用帶來的開銷第二遍再按sample_metadata記錄的偏移量切分預(yù)測結(jié)果逐樣本計算指標(biāo)。指標(biāo)計算依賴 scikit-learncompute_metrics中 MRR 通過np.argsort手工實現(xiàn)NDCG 使用ndcg_scoreMAP 使用average_precision_scorereranking.py。評測時若提供了output_path且write_csvTrue結(jié)果會以追加方式寫入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同時出現(xiàn)或同時缺失都會拋出含明確信息的ValueErrorpositive傳入單個字符串而非列表會被自動包裹為列表單樣本、documents中不含正例等邊界場景均能正常返回指標(biāo)。三、CrossEncoderNanoBEIREvaluator輕量級檢索基準(zhǔn)評測NanoBEIR 是基于 BEIR 集合裁剪出的小規(guī)模信息檢索評測集專為完整跑 BEIR 之前先快速驗證模型檢索性能而設(shè)計。CrossEncoderNanoBEIREvaluator將這一基準(zhǔn)與 CrossEncoder 重排評測無縫銜接源碼位于 nano_beir.py。3.1 評測機制與CrossEncoderRerankingEvaluator直接對全部候選文檔重排不同本評估器只對 BM25 排名的前rerank_k個文檔進行重排默認(rèn)rerank_k100大幅降低評測成本。內(nèi)部機制是從 Hugging Face 的 NanoBEIR 數(shù)據(jù)集中加載corpus、queries、qrels、bm25四個子集按Nano{數(shù)據(jù)集名}的 split 存放組裝成CrossEncoderRerankingEvaluator所需的{query, positive, documents}樣本格式再逐一評測見 nano_beir.py。它返回與重排評估器相同的指標(biāo)MRRk、nDCGk、MAP既有每個數(shù)據(jù)集的單獨結(jié)果也有全部數(shù)據(jù)集上的均值aggregate結(jié)果。當(dāng)日志級別設(shè)為 INFO 時會自動打印逐數(shù)據(jù)集與總平均的 Base → Reranked 對比。3.2 支持的數(shù)據(jù)集與參數(shù)內(nèi)置 13 個 NanoBEIR 數(shù)據(jù)集climatefever、dbpedia、fever、fiqa2018、hotpotqa、msmarco、nfcorpus、nq、quoraretrieval、scidocs、arguana、scifact、touche2020。重要行為差異默認(rèn)情況下不手動指定dataset_names評估器會排除arguana與touche2020因為其 Argument Retrieval 任務(wù)與其他數(shù)據(jù)集存在明顯差異。這與sentence_transformer.evaluation.NanoBEIREvaluator和sparse_encoder.evaluation.SparseNanoBEIREvaluator默認(rèn)包含全部數(shù)據(jù)集有所不同。完整參數(shù)如下參數(shù)類型默認(rèn)值說明dataset_nameslist[str]全部除 arguana、touche2020要評測的數(shù)據(jù)集短名列表dataset_idstrsentence-transformers/NanoBEIR-enHuggingFace 數(shù)據(jù)集 ID可替換為其他語言的 NanoBEIR 數(shù)據(jù)集要求含corpus/queries/qrels/bm25子集rerank_kint100從 BM25 排名中取前多少個文檔進行重排at_kint10排序指標(biāo)只考察 Top-kalways_rerank_positivesboolTrue語義同CrossEncoderRerankingEvaluatorprompt_namestr \| NoneNone提示詞名batch_sizeint32預(yù)測批大小show_progress_barboolFalse是否顯示進度條write_csvboolTrue是否寫 CSVaggregate_fnCallablenp.mean聚合各數(shù)據(jù)集分?jǐn)?shù)的函數(shù)aggregate_keystrmean聚合結(jié)果的鍵名3.3 結(jié)果鍵命名與訓(xùn)練集成本評估器的輸出鍵遵循固定格式源碼 Docstring 明確說明聚合結(jié)果NanoBEIR_R{rerank_k}_{aggregate_key}_{metric}其中metric為map、mrr{at_k}或ndcg{at_k}。默認(rèn)主指標(biāo)名為NanoBEIR_R100_mean_ndcg10單數(shù)據(jù)集結(jié)果Nano{數(shù)據(jù)集名}_R{rerank_k}_{metric}例如NanoMSMARCO_R100_mrr10。這些鍵可直接用作訓(xùn)練時的metric_for_best_model配合CrossEncoderTrainingArguments中的load_best_model_at_endTruetraining_args.py實現(xiàn)訓(xùn)練過程中自動加載指定指標(biāo)最優(yōu)的模型?；居梅ㄊ纠齠rom 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) # 只評測三個數(shù)據(jù)集快速驗證 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評測自定義如翻譯后的數(shù)據(jù)集時只需替換dataset_id例如傳入Serbian-AI-Society/NanoBEIR-sr即可用非英文模型評測對應(yīng)語言的數(shù)據(jù)集。注意使用本評估器需要安裝datasets庫pip install datasets否則會在加載數(shù)據(jù)集時拋出明確錯誤見 nano_beir.py 中的is_datasets_available檢查。四、CrossEncoderClassificationEvaluator分類任務(wù)評測當(dāng) CrossEncoder 被用于判斷兩個文本是否屬于同一類如 NLI 蘊含判斷、重復(fù)問題檢測、相關(guān)性二分類時使用CrossEncoderClassificationEvaluator評估分類質(zhì)量源碼位于 classification.py。4.1 單輸出二分類與多輸出模式評估器根據(jù)模型的輸出維度自動切換評測邏輯model.num_labels決定num_labels 1單輸出即二分類模型使用BinaryClassificationEvaluator.find_best_acc_and_threshold與find_best_f1_and_threshold搜索最優(yōu)決策閾值報告Accuracy、F1、Precision、Recall、Average Precision平均精確率并給出對應(yīng)的最優(yōu)閾值。此時主指標(biāo)為average_precisionnum_labels 1多輸出多分類模型取argmax得到預(yù)測類別報告Macro F1、Micro F1、Weighted F1。此時主指標(biāo)為f1_macro。4.2 構(gòu)造參數(shù)與 NLI 示例參數(shù)說明參數(shù)類型默認(rèn)值說明sentence_pairslist[list[str]]必填句子對列表每元素為兩個字符串labelslist[int]必填每對句子對應(yīng)的金標(biāo)標(biāo)簽與sentence_pairs長度必須一致否則拋ValueErrornamestr評估器名稱prompt_namestr \| NoneNone提示詞名batch_sizeint32預(yù)測批大小show_progress_barbool \| NoneNone為None時僅當(dāng)日志級別為 INFO/DEBUG 時顯示進度條write_csvboolTrue是否寫 CSV用 NLI 數(shù)據(jù)集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) # 加載包含兩列文本和一列標(biāo)簽的數(shù)據(jù)集 eval_dataset load_dataset(sentence-transformers/all-nli, pair-class, splitdev[-1000:]) # 構(gòu)造句子對并將標(biāo)簽映射為模型認(rèn)識的標(biāo)簽 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二分類模式下日志輸出格式略有不同會附帶最優(yōu)閾值A(chǔ)ccuracy: 85.32 (Threshold: 0.4371) F1: 78.94 (Threshold: 0.5123) Precision: 81.23 Recall: 76.84 Average Precision: 88.174.3 歷史遺留類Deprecated在舊版 API 中分類與相關(guān)度評估由多個以CE前綴命名的類承擔(dān)。當(dāng)前倉庫將它們統(tǒng)一收斂為上述四個正式類并在 deprecated.py 中以deprecated裝飾器標(biāo)記CEBinaryAccuracyEvaluator、CEBinaryClassificationEvaluator、CEF1Evaluator、CESoftmaxAccuracyEvaluator→ 全部建議改用CrossEncoderClassificationEvaluator其同時支持二分類與多分類輸入基本兼容CECorrelationEvaluator→ 改名為CrossEncoderCorrelationEvaluatorCERerankingEvaluator→ 改名為CrossEncoderRerankingEvaluator。新代碼請直接使用正式類這些別名仍在__init__.py中導(dǎo)出以保持向后兼容但會在使用時報出棄用警告。五、CrossEncoderCorrelationEvaluator語義相似度回歸評測在 STSSemantic Textual Similarity等任務(wù)中模型需要為句子對輸出一個連續(xù)相似度分?jǐn)?shù)評估時通常用預(yù)測分?jǐn)?shù)與金標(biāo)分?jǐn)?shù)的相關(guān)性來衡量質(zhì)量。CrossEncoderCorrelationEvaluator正是為此設(shè)計源碼位于 correlation.py。5.1 原理與參數(shù)它接收句子對列表與連續(xù)型金標(biāo)分?jǐn)?shù)計算預(yù)測分?jǐn)?shù)與金標(biāo)分?jǐn)?shù)之間的Pearson 相關(guān)系數(shù)線性相關(guān)Spearman 相關(guān)系數(shù)秩相關(guān)對單調(diào)關(guān)系更穩(wěn)健。主指標(biāo)為spearman。參數(shù)與CrossEncoderClassificationEvaluator幾乎一致sentence_pairs、labels/scores、name、prompt_name、batch_size32、show_progress_barNone、write_csvTrue唯一的區(qū)別是第二參數(shù)名為scores連續(xù)值而非類別標(biāo)簽。用 STSB 數(shù)據(jù)集評測的完整示例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 數(shù)據(jù)集 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列表直接構(gòu)造評估器correlation.py將每個example.texts作為句子對、example.label作為分?jǐn)?shù)。這一入口讓評估器可以很方便地接入既有訓(xùn)練管線中基于InputExample組織的數(shù)據(jù)。5.3 相關(guān)系數(shù)的計算實現(xiàn)從源碼看correlation.py評估流程是先調(diào)用model.predict(self.sentence_pairs, ...)得到所有預(yù)測分?jǐn)?shù)再分別用scipy.stats.pearsonr與scipy.stats.spearmanr計算兩類相關(guān)系數(shù)。與重排評估器一致結(jié)果會通過store_metrics_in_model_card_data寫入模型卡并在提供output_path時追加寫入CrossEncoderCorrelationEvaluator_{name}_results.csv表頭含Pearson_Correlation、Spearman_Correlation。六、評估器與訓(xùn)練流程的協(xié)同6.1 統(tǒng)一的調(diào)用約定四個正式評估器都遵循BaseEvaluator約定的調(diào)用簽名evaluator(model, output_pathNone, epoch-1, steps-1) - dict[str, float]。訓(xùn)練過程中CrossEncoder 的 trainer 會在每個 epoch 結(jié)束或指定 steps時調(diào)用評估器將返回的指標(biāo)字典用于 checkpoint 選擇與日志記錄epoch/steps參數(shù)同時決定了 CSV 中的記錄與日志文案如 after epoch 1。6.2 指標(biāo)前綴與主指標(biāo)當(dāng)給評估器指定了name例如ms-marco-dev時返回字典的所有鍵都會帶上{name}_前綴prefix_name_to_metricsprimary_metric也會同步更新為{name}_{原始主指標(biāo)}。這保證了多評估器并行評測時指標(biāo)互不沖突也能直接對應(yīng)CrossEncoderTrainingArguments中的metric_for_best_model。6.3 選型建議訓(xùn)練/評測任務(wù)推薦評估器精排模型MS MARCO、NQ 等檢索語料CrossEncoderRerankingEvaluator自有數(shù)據(jù)或CrossEncoderNanoBEIREvaluator快速對標(biāo)基準(zhǔn)NLI、重復(fù)檢測等二分類/多分類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訓(xùn)練參數(shù)中的指標(biāo)選擇CrossEncoderTrainingArgumentssentence_transformers/cross_encoder/training_args.py評估器搭配訓(xùn)練腳本的實戰(zhàn)示例examples/cross_encoder/training/ 目錄下各訓(xùn)練腳本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創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 CrossEncoder 評估器完全指南：從重排序到 NanoBEIR 的信息檢索評測體系
CrossEncoder 評估器完全指南從重排序到 NanoBEIR 的信息檢索評測體系【免費下載鏈接】sentence-transformersState-of-the-Art Embeddings, Retrieval, and Reranking項目地址: https://gitcode.com/gh_mirrors/se/sentence-transformers導(dǎo)讀CrossEncoder交叉編碼器在 sentence-transformers 中承擔(dān)著精排re-ranking與配對打分任務(wù)與之配套的是一套獨立的評估體系。本文以 docs/package_reference/cross_encoder/evaluation.md 為核心系統(tǒng)講解sentence_transformers.cross_encoder.evaluation包下的四大評估器——CrossEncoderRerankingEvaluator、CrossEncoderNanoBEIREvaluator、CrossEncoderClassificationEvaluator與CrossEncoderCorrelationEvaluator。讀完本文你將掌握每種評估器適用的任務(wù)場景、樣本數(shù)據(jù)格式、全部核心參數(shù)與默認(rèn)值以及如何將評估指標(biāo)接入訓(xùn)練流程實現(xiàn)按指標(biāo)自動選最優(yōu)模型。一、CrossEncoder 評估體系總覽CrossEncoder 擁有自己獨立的評估類統(tǒng)一位于sentence_transformers.cross_encoder.evaluation命名空間下見 包入口。與 SentenceTransformer 的稠密向量評估不同CrossEncoder 評估的核心是句子對打分模型同時接收兩個文本并輸出一個相關(guān)性分?jǐn)?shù)因此其評估器天然圍繞打分質(zhì)量展開。當(dāng)前包內(nèi)共導(dǎo)出四類正式評估器外加一組歷史遺留的 Deprecated 別名評估器適用任務(wù)核心指標(biāo)CrossEncoderRerankingEvaluator重排序精排MRRk、NDCGk、MAPCrossEncoderNanoBEIREvaluatorNanoBEIR 檢索基準(zhǔn)快速評測MRRk、NDCGk、MAP逐數(shù)據(jù)集 均值CrossEncoderClassificationEvaluator二分類 / 多分類Accuracy、F1、Precision、Recall、Average PrecisionCrossEncoderCorrelationEvaluator語義相似度回歸STSPearson、Spearman 相關(guān)系數(shù)所有評估器都繼承自 BaseEvaluator該基類統(tǒng)一約定了評估器的兩個關(guān)鍵契約greater_is_better布爾值默認(rèn)True表示分?jǐn)?shù)越高模型越好。當(dāng)訓(xùn)練參數(shù)開啟load_best_model_at_end時訓(xùn)練器據(jù)此選擇最優(yōu) checkpointprimary_metric字符串指代評估器返回指標(biāo)字典中的主指標(biāo)用于模型選擇與日志記錄。調(diào)用evaluator(model)后會得到一個指標(biāo)字典配合evaluator.primary_metric即可取出主指標(biāo)數(shù)值。此外基類還提供prefix_name_to_metrics將評估器name作為指標(biāo)前綴、store_metrics_in_model_card_data把評估結(jié)果寫入模型的 Model Card與description生成人類可讀的評估器描述等方法這些機制讓每個評估器都能無縫接入訓(xùn)練循環(huán)與模型卡生成流程。二、CrossEncoderRerankingEvaluator重排序質(zhì)量評測重排序是 CrossEncoder 最典型的應(yīng)用場景先由召回階段如 BM25 或 SentenceTransformer 稠密檢索返回一批候選文檔再由 CrossEncoder 逐一對(query, doc)打分并重新排序。CrossEncoderRerankingEvaluator正是對這一過程的質(zhì)量度量器源碼位于 reranking.py。2.1 評測原理與指標(biāo)給定一個 query 和一組文檔評估器對每個(query, doc_i)計算分?jǐn)?shù)并按降序排列然后計算三項經(jīng)典排序指標(biāo)MRRkMean Reciprocal Rank第一個相關(guān)文檔在 Top-k 中位置倒數(shù)的均值NDCGkNormalized Discounted Cumulative Gain考慮相關(guān)文檔位置與相關(guān)級別的折損累計增益MAPMean Average Precision每個查詢的平均精確率再取均值。默認(rèn)at_k10即只考察 Top-10 的排序質(zhì)量。2.2 樣本數(shù)據(jù)格式兩種互斥模式評估器接收一個samples列表每個樣本是一個字典必須包含query與positive兩個鍵且negative與documents必須二選一源碼第 168-173 行會嚴(yán)格校驗并拋出明確的ValueError模式 Anegative模式——提供正例與負(fù)例列表評估器只報告重排后的分?jǐn)?shù)模式 Bdocuments模式——提供包含正例在內(nèi)的全部文檔列表假定該列表已按相似度降序排列即模擬第一輪召回結(jié)果。此模式下評估器會同時報告召回基線Base→ 重排后Reranked兩組分?jǐn)?shù)直觀展示精排帶來的提升。用 MS MARCO 數(shù)據(jù)構(gòu)建樣本的完整示例來自源碼 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、正例、負(fù)例的數(shù)據(jù)集 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 完整參數(shù)表參數(shù)類型默認(rèn)值說明sampleslist[dict]必填每個字典含query必填、positive必填、negative或documents二選一at_kint10僅考察每個 query 相似度最高的前 k 個文檔always_rerank_positivesboolTrue為True時總是把所有正例納入排序為False時僅保留documents列表中已有的正例。使用negative模式時必須設(shè)為True使用documents模式時True得到更實用的評測信號False更貼近真實場景namestr評估器名稱用于日志、CSV 文件名與模型卡prompt_namestr \| NoneNone調(diào)用model.predict()時使用的提示詞名必須是模型prompts字典中的鍵batch_sizeint64計算分?jǐn)?shù)時的批大小show_progress_barboolFalse是否顯示進度條write_csvboolTrue是否將結(jié)果寫入 CSV 文件mrr_at_kint \| NoneNone已棄用參數(shù)請改用at_k關(guān)于分?jǐn)?shù)上限有一個易被忽視的細(xì)節(jié)由于默認(rèn)always_rerank_positivesTrue且所有正例都包含在排序中最高分天然是 1.0。若想得到更嚴(yán)格的分?jǐn)?shù)應(yīng)使用documents模式并設(shè)置always_rerank_positivesFalse此時正例可能未被召回進候選集分?jǐn)?shù)上限取決于召回質(zhì)量。2.4 輸出與日志解讀評估完成后日志會輸出類似下面的對比結(jié)果數(shù)值取自源碼示例實際結(jié)果因模型而異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主指標(biāo)可通過reranking_evaluator.primary_metric獲取格式為{name}_ndcg{at_k}指標(biāo)數(shù)值通過results[...]取出print(reranking_evaluator.primary_metric) # ms-marco-dev_ndcg10 print(results[reranking_evaluator.primary_metric]) # 0.71046568571841842.5 源碼級實現(xiàn)細(xì)節(jié)從源碼實現(xiàn)看該評估器做了兩項值得注意的工程優(yōu)化reranking.py兩遍處理 單次批量預(yù)測第一遍把所有樣本的(query, doc)對拍平成單一列表all_pairs只調(diào)用一次model.predict()完成全部打分避免逐樣本調(diào)用帶來的開銷第二遍再按sample_metadata記錄的偏移量切分預(yù)測結(jié)果逐樣本計算指標(biāo)。指標(biāo)計算依賴 scikit-learncompute_metrics中 MRR 通過np.argsort手工實現(xiàn)NDCG 使用ndcg_scoreMAP 使用average_precision_scorereranking.py。評測時若提供了output_path且write_csvTrue結(jié)果會以追加方式寫入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同時出現(xiàn)或同時缺失都會拋出含明確信息的ValueErrorpositive傳入單個字符串而非列表會被自動包裹為列表單樣本、documents中不含正例等邊界場景均能正常返回指標(biāo)。三、CrossEncoderNanoBEIREvaluator輕量級檢索基準(zhǔn)評測NanoBEIR 是基于 BEIR 集合裁剪出的小規(guī)模信息檢索評測集專為完整跑 BEIR 之前先快速驗證模型檢索性能而設(shè)計。CrossEncoderNanoBEIREvaluator將這一基準(zhǔn)與 CrossEncoder 重排評測無縫銜接源碼位于 nano_beir.py。3.1 評測機制與CrossEncoderRerankingEvaluator直接對全部候選文檔重排不同本評估器只對 BM25 排名的前rerank_k個文檔進行重排默認(rèn)rerank_k100大幅降低評測成本。內(nèi)部機制是從 Hugging Face 的 NanoBEIR 數(shù)據(jù)集中加載corpus、queries、qrels、bm25四個子集按Nano{數(shù)據(jù)集名}的 split 存放組裝成CrossEncoderRerankingEvaluator所需的{query, positive, documents}樣本格式再逐一評測見 nano_beir.py。它返回與重排評估器相同的指標(biāo)MRRk、nDCGk、MAP既有每個數(shù)據(jù)集的單獨結(jié)果也有全部數(shù)據(jù)集上的均值aggregate結(jié)果。當(dāng)日志級別設(shè)為 INFO 時會自動打印逐數(shù)據(jù)集與總平均的 Base → Reranked 對比。3.2 支持的數(shù)據(jù)集與參數(shù)內(nèi)置 13 個 NanoBEIR 數(shù)據(jù)集climatefever、dbpedia、fever、fiqa2018、hotpotqa、msmarco、nfcorpus、nq、quoraretrieval、scidocs、arguana、scifact、touche2020。重要行為差異默認(rèn)情況下不手動指定dataset_names評估器會排除arguana與touche2020因為其 Argument Retrieval 任務(wù)與其他數(shù)據(jù)集存在明顯差異。這與sentence_transformer.evaluation.NanoBEIREvaluator和sparse_encoder.evaluation.SparseNanoBEIREvaluator默認(rèn)包含全部數(shù)據(jù)集有所不同。完整參數(shù)如下參數(shù)類型默認(rèn)值說明dataset_nameslist[str]全部除 arguana、touche2020要評測的數(shù)據(jù)集短名列表dataset_idstrsentence-transformers/NanoBEIR-enHuggingFace 數(shù)據(jù)集 ID可替換為其他語言的 NanoBEIR 數(shù)據(jù)集要求含corpus/queries/qrels/bm25子集rerank_kint100從 BM25 排名中取前多少個文檔進行重排at_kint10排序指標(biāo)只考察 Top-kalways_rerank_positivesboolTrue語義同CrossEncoderRerankingEvaluatorprompt_namestr \| NoneNone提示詞名batch_sizeint32預(yù)測批大小show_progress_barboolFalse是否顯示進度條write_csvboolTrue是否寫 CSVaggregate_fnCallablenp.mean聚合各數(shù)據(jù)集分?jǐn)?shù)的函數(shù)aggregate_keystrmean聚合結(jié)果的鍵名3.3 結(jié)果鍵命名與訓(xùn)練集成本評估器的輸出鍵遵循固定格式源碼 Docstring 明確說明聚合結(jié)果NanoBEIR_R{rerank_k}_{aggregate_key}_{metric}其中metric為map、mrr{at_k}或ndcg{at_k}。默認(rèn)主指標(biāo)名為NanoBEIR_R100_mean_ndcg10單數(shù)據(jù)集結(jié)果Nano{數(shù)據(jù)集名}_R{rerank_k}_{metric}例如NanoMSMARCO_R100_mrr10。這些鍵可直接用作訓(xùn)練時的metric_for_best_model配合CrossEncoderTrainingArguments中的load_best_model_at_endTruetraining_args.py實現(xiàn)訓(xùn)練過程中自動加載指定指標(biāo)最優(yōu)的模型?；居梅ㄊ纠齠rom 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) # 只評測三個數(shù)據(jù)集快速驗證 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評測自定義如翻譯后的數(shù)據(jù)集時只需替換dataset_id例如傳入Serbian-AI-Society/NanoBEIR-sr即可用非英文模型評測對應(yīng)語言的數(shù)據(jù)集。注意使用本評估器需要安裝datasets庫pip install datasets否則會在加載數(shù)據(jù)集時拋出明確錯誤見 nano_beir.py 中的is_datasets_available檢查。四、CrossEncoderClassificationEvaluator分類任務(wù)評測當(dāng) CrossEncoder 被用于判斷兩個文本是否屬于同一類如 NLI 蘊含判斷、重復(fù)問題檢測、相關(guān)性二分類時使用CrossEncoderClassificationEvaluator評估分類質(zhì)量源碼位于 classification.py。4.1 單輸出二分類與多輸出模式評估器根據(jù)模型的輸出維度自動切換評測邏輯model.num_labels決定num_labels 1單輸出即二分類模型使用BinaryClassificationEvaluator.find_best_acc_and_threshold與find_best_f1_and_threshold搜索最優(yōu)決策閾值報告Accuracy、F1、Precision、Recall、Average Precision平均精確率并給出對應(yīng)的最優(yōu)閾值。此時主指標(biāo)為average_precisionnum_labels 1多輸出多分類模型取argmax得到預(yù)測類別報告Macro F1、Micro F1、Weighted F1。此時主指標(biāo)為f1_macro。4.2 構(gòu)造參數(shù)與 NLI 示例參數(shù)說明參數(shù)類型默認(rèn)值說明sentence_pairslist[list[str]]必填句子對列表每元素為兩個字符串labelslist[int]必填每對句子對應(yīng)的金標(biāo)標(biāo)簽與sentence_pairs長度必須一致否則拋ValueErrornamestr評估器名稱prompt_namestr \| NoneNone提示詞名batch_sizeint32預(yù)測批大小show_progress_barbool \| NoneNone為None時僅當(dāng)日志級別為 INFO/DEBUG 時顯示進度條write_csvboolTrue是否寫 CSV用 NLI 數(shù)據(jù)集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) # 加載包含兩列文本和一列標(biāo)簽的數(shù)據(jù)集 eval_dataset load_dataset(sentence-transformers/all-nli, pair-class, splitdev[-1000:]) # 構(gòu)造句子對并將標(biāo)簽映射為模型認(rèn)識的標(biāo)簽 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二分類模式下日志輸出格式略有不同會附帶最優(yōu)閾值A(chǔ)ccuracy: 85.32 (Threshold: 0.4371) F1: 78.94 (Threshold: 0.5123) Precision: 81.23 Recall: 76.84 Average Precision: 88.174.3 歷史遺留類Deprecated在舊版 API 中分類與相關(guān)度評估由多個以CE前綴命名的類承擔(dān)。當(dāng)前倉庫將它們統(tǒng)一收斂為上述四個正式類并在 deprecated.py 中以deprecated裝飾器標(biāo)記CEBinaryAccuracyEvaluator、CEBinaryClassificationEvaluator、CEF1Evaluator、CESoftmaxAccuracyEvaluator→ 全部建議改用CrossEncoderClassificationEvaluator其同時支持二分類與多分類輸入基本兼容CECorrelationEvaluator→ 改名為CrossEncoderCorrelationEvaluatorCERerankingEvaluator→ 改名為CrossEncoderRerankingEvaluator。新代碼請直接使用正式類這些別名仍在__init__.py中導(dǎo)出以保持向后兼容但會在使用時報出棄用警告。五、CrossEncoderCorrelationEvaluator語義相似度回歸評測在 STSSemantic Textual Similarity等任務(wù)中模型需要為句子對輸出一個連續(xù)相似度分?jǐn)?shù)評估時通常用預(yù)測分?jǐn)?shù)與金標(biāo)分?jǐn)?shù)的相關(guān)性來衡量質(zhì)量。CrossEncoderCorrelationEvaluator正是為此設(shè)計源碼位于 correlation.py。5.1 原理與參數(shù)它接收句子對列表與連續(xù)型金標(biāo)分?jǐn)?shù)計算預(yù)測分?jǐn)?shù)與金標(biāo)分?jǐn)?shù)之間的Pearson 相關(guān)系數(shù)線性相關(guān)Spearman 相關(guān)系數(shù)秩相關(guān)對單調(diào)關(guān)系更穩(wěn)健。主指標(biāo)為spearman。參數(shù)與CrossEncoderClassificationEvaluator幾乎一致sentence_pairs、labels/scores、name、prompt_name、batch_size32、show_progress_barNone、write_csvTrue唯一的區(qū)別是第二參數(shù)名為scores連續(xù)值而非類別標(biāo)簽。用 STSB 數(shù)據(jù)集評測的完整示例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 數(shù)據(jù)集 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列表直接構(gòu)造評估器correlation.py將每個example.texts作為句子對、example.label作為分?jǐn)?shù)。這一入口讓評估器可以很方便地接入既有訓(xùn)練管線中基于InputExample組織的數(shù)據(jù)。5.3 相關(guān)系數(shù)的計算實現(xiàn)從源碼看correlation.py評估流程是先調(diào)用model.predict(self.sentence_pairs, ...)得到所有預(yù)測分?jǐn)?shù)再分別用scipy.stats.pearsonr與scipy.stats.spearmanr計算兩類相關(guān)系數(shù)。與重排評估器一致結(jié)果會通過store_metrics_in_model_card_data寫入模型卡并在提供output_path時追加寫入CrossEncoderCorrelationEvaluator_{name}_results.csv表頭含Pearson_Correlation、Spearman_Correlation。六、評估器與訓(xùn)練流程的協(xié)同6.1 統(tǒng)一的調(diào)用約定四個正式評估器都遵循BaseEvaluator約定的調(diào)用簽名evaluator(model, output_pathNone, epoch-1, steps-1) - dict[str, float]。訓(xùn)練過程中CrossEncoder 的 trainer 會在每個 epoch 結(jié)束或指定 steps時調(diào)用評估器將返回的指標(biāo)字典用于 checkpoint 選擇與日志記錄epoch/steps參數(shù)同時決定了 CSV 中的記錄與日志文案如 after epoch 1。6.2 指標(biāo)前綴與主指標(biāo)當(dāng)給評估器指定了name例如ms-marco-dev時返回字典的所有鍵都會帶上{name}_前綴prefix_name_to_metricsprimary_metric也會同步更新為{name}_{原始主指標(biāo)}。這保證了多評估器并行評測時指標(biāo)互不沖突也能直接對應(yīng)CrossEncoderTrainingArguments中的metric_for_best_model。6.3 選型建議訓(xùn)練/評測任務(wù)推薦評估器精排模型MS MARCO、NQ 等檢索語料CrossEncoderRerankingEvaluator自有數(shù)據(jù)或CrossEncoderNanoBEIREvaluator快速對標(biāo)基準(zhǔn)NLI、重復(fù)檢測等二分類/多分類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訓(xùn)練參數(shù)中的指標(biāo)選擇CrossEncoderTrainingArgumentssentence_transformers/cross_encoder/training_args.py評估器搭配訓(xùn)練腳本的實戰(zhàn)示例examples/cross_encoder/training/ 目錄下各訓(xùn)練腳本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創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考