评估器（双编码器）

所有双编码器评估器都位于sentence_transformers.sentence_transformer.evaluation中。

选择合适的评估器

将多个评估器包装在SequentialEvaluator中，以便一起跟踪：

fromsentence_transformers.sentence_transformer.evaluationimportSequentialEvaluator evaluator=SequentialEvaluator([evaluator1,evaluator2,evaluator3])

三大评估器

NanoBEIREvaluator（检索）

BEIR 的小型快速子集。在中端 GPU 上典型运行时间 <1 分钟。检索训练的默认选择。

fromsentence_transformers.sentence_transformer.evaluationimportNanoBEIREvaluator evaluator=NanoBEIREvaluator(dataset_names=["msmarco","nfcorpus","nq"],# 默认：全部 13 个 NanoBEIR 数据集batch_size=128,show_progress_bar=False,)

• 默认数据集列表覆盖 13 个任务；训练期间选择子集以加快速度。
• metric_for_best_model的输出键：eval_NanoBEIR_mean_cosine_ndcg@10（双编码器默认 = 余弦相似度）。

EmbeddingSimilarityEvaluator（STS 风格）

计算模型余弦相似度与金标准标签之间的 Pearson/Spearman 相关性。

fromsentence_transformers.sentence_transformer.evaluationimportEmbeddingSimilarityEvaluatorfromsentence_transformers.util.similarityimportSimilarityFunction evaluator=EmbeddingSimilarityEvaluator(sentences1=stsb["sentence1"],sentences2=stsb["sentence2"],scores=stsb["score"],main_similarity=SimilarityFunction.COSINE,name="sts-dev",)

• main_similarity可以是COSINE、DOT_PRODUCT、EUCLIDEAN、MANHATTAN。
• name用于输出键：eval_sts-dev_spearman_cosine、eval_sts-dev_pearson_cosine等。

InformationRetrievalEvaluator（完整检索）

当你拥有自己的语料库 + 查询 + qrels（不是 NanoBEIR 任务之一）时使用。

fromsentence_transformers.sentence_transformer.evaluationimportInformationRetrievalEvaluator evaluator=InformationRetrievalEvaluator(queries={qid:query_textforqid,query_textin...},corpus={doc_id:doc_textfordoc_id,doc_textin...},relevant_docs={qid:{doc_id,...}forqidin...},# qid -> 相关 doc_id 的集合name="my-retrieval",mrr_at_k=[10],ndcg_at_k=[10],accuracy_at_k=[1,5,10],precision_recall_at_k=[1,5,10],map_at_k=[100],show_progress_bar=False,batch_size=64,)

输出键：eval_{name}_cosine_ndcg@10、eval_{name}_cosine_mrr@10等。

对大型语料库很重——每次评估都会编码整个语料库。不要每 100 步就运行它。训练期间使用NanoBEIREvaluator进行频繁评估，将完整的 IR 评估保留给里程碑 / 训练后。

其他双编码器评估器

BinaryClassificationEvaluator

用于带标签的成对分类（例如重复检测、二分类蕴含）。报告准确率、F1、精确率/召回率、AP。支持所有距离度量——为每个度量找到最佳阈值。

TripletEvaluator

用于(anchor, positive, negative)三元组。报告正例比负例更接近锚点的三元组比例。

RerankingEvaluator

用于自定义重排数据集：你为每个查询提供候选，评估器计算 MAP 和 MRR。适合衡量留出集上的检索质量。

MSEEvaluator/MSEEvaluatorFromDataFrame

用于蒸馏设置。比较学生嵌入与教师嵌入（或教师分数），报告 MSE。

ParaphraseMiningEvaluator

用于释义挖掘任务。给定带标签的释义对语料库，计算挖掘质量（各阈值下的 F1）。

TranslationEvaluator

用于跨语言 /make_multilingual风格对齐检查。衡量学生是否跨语言对齐句子。

LabelAccuracyEvaluator

用于SoftmaxLoss训练的分类头。报告留出数据上的准确率。

编写metric_for_best_model

模式：f"eval_{evaluator.primary_metric}"。构造后检查：print(evaluator.primary_metric)。常见值：

• eval_NanoBEIR_mean_cosine_ndcg@10—NanoBEIREvaluator
• eval_sts-dev_spearman_cosine—EmbeddingSimilarityEvaluator(name="sts-dev")
• eval_{name}_cosine_ndcg@10—InformationRetrievalEvaluator(name=...)

多维评估（Matryoshka）

对于 Matryoshka 训练的模型，在每个目标维度上评估：

per_dim_evaluators=[EmbeddingSimilarityEvaluator(sentences1=...,sentences2=...,scores=...,main_similarity=SimilarityFunction.COSINE,name=f"sts-dev-{dim}",truncate_dim=dim,)fordimin[768,512,256,128,64]]evaluator=SequentialEvaluator(per_dim_evaluators,main_score_function=lambdascores:scores[0])

第一个评估器的分数驱动load_best_model_at_end。

陷阱

• 训练前务必先运行一次evaluator(model)—— 预训练基线。如果训练后增量很小，说明损失/数据/基座有问题。
• 不要使用大型语料库（>10 万文档）的InformationRetrievalEvaluator以频繁的eval_steps运行——训练期间使用NanoBEIREvaluator，将完整的 IR 评估留到训练结束时。
• greater_is_better=True是默认值；适合 nDCG / MRR / 准确率。