sentence-transformers 多向量编码器评估指南MultiVectorEncoder 的 MaxSim 评测体系与 NanoBEIR 实战【免费下载链接】sentence-transformersState-of-the-Art Embeddings, Retrieval, and Reranking项目地址: https://gitcode.com/gh_mirrors/se/sentence-transformers导读本指南围绕 sentence-transformers 仓库中多向量编码器MultiVectorEncoder即 ColBERT 风格 late-interaction 模型的评估体系展开核心场景是检索质量IR、重排序Reranking、三元组排序与知识蒸馏跟踪等任务的离线评测。读完本文你将掌握评估器基于 MaxSim 打分端到端运行的原理能用 nano_beir.py 在 13 个 NanoBEIR 子集上快速评估预训练模型并熟练配置dataset_names、corpus_chunk_size、chunk_elements等关键参数同时了解全套评估器的数据格式与指标含义。一、多向量编码器为什么需要专门的评估器与 SentenceTransformer 将每个输入编码为单个向量不同多向量编码器把每个输入编码为一串 token 向量每个 token 一个向量查询与文档的比较采用 ColBERT 风格的 MaxSimlate-interaction打分对每个查询 token取其与文档所有 token 的最大相似度再对所有查询 token 求和即sum_i max_j (a_i · b_j)。该公式的权威实现见 sentence_transformers/util/similarity.py 中的maxsim函数它在sentence_transformers/multi_vector_encoder之外同样被多处复用。正是这种查询一组 token 向量 vs 文档一组 token 向量的形态决定了普通的余弦/点积评估器无法直接套用——它们定义在单向量之上对非齐次ragged的 per-token 嵌入无法正确计算。sentence_transformers/multi_vector_encoder/evaluation/下的评估器把打分链路端到端封装好了编码阶段使用encode_query与encode_document而非统一的encode因此模型的[Q]/[D]前缀、查询扩展query expansion以及文档 skiplist 都会在评估时生效打分阶段使用模型自身的similarity_fn_namemaxsim或meanmaxsim指标阶段在分数之上计算标准的检索/排序指标。MultiVectorEncoder只支持这两种相似度函数见 sentence_transformers/multi_vector_encoder/model.py 中的SUPPORTED_SIMILARITY_FN_NAMES (maxsim, meanmaxsim)。两者的区别在于maxsim会随查询长度累积分数归一化嵌入下约每个查询 token 贡献 1 分而meanmaxsim将总分除以真实查询 token 数把分数拉回余弦的[-1, 1]区间——后者用于以长度归一化打分训练的模型。一个必须注意的约束这些评估器不支持truncate_dim。原因在源码 docstring 中写得很清楚——多向量 token 嵌入没有 Matryoshka 式截断任何非None的truncate_dim都会直接抛出ValueError见 nano_beir.py 与 information_retrieval.py 的构造函数校验。二、运行评估脚本的通用流程目录下的每个评估脚本都遵循统一的五步流程加载预训练的多向量模型MultiVectorEncoder(...)准备评估数据集配置合适的评估器运行评估报告结果。评估器与示例脚本的对应关系如下评估器示例脚本MultiVectorNanoBEIREvaluatorexamples/multi_vector_encoder/evaluation/nano_beir.py运行方式很简单直接执行 Python 脚本即可无需任何额外的前置数据处理步骤NanoBEIR 子集由评估器自行加载。三、NanoBEIR 快速评测实战3.1 什么是 NanoBEIRNanoBEIR 是 BEIR。3.2 完整示例代码以下是 nano_beir.py 的完整内容评估lightonai/LateOn模型在全部 13 个 Nano-* 检索数据集上的 MaxSim 表现Evaluate a pretrained multi-vector model on NanoBEIR. NanoBEIR is a fast benchmarking suite of 13 small BEIR subsets, useful for quickly comparing models without running the full BEIR evaluation. This script loads a model from the Hub and runs all 13 Nano-* IR datasets with MaxSim scoring. from __future__ import annotations from pprint import pprint from sentence_transformers import MultiVectorEncoder from sentence_transformers.multi_vector_encoder.evaluation import MultiVectorNanoBEIREvaluator def main() - None: model MultiVectorEncoder(lightonai/LateOn) evaluator MultiVectorNanoBEIREvaluator(batch_size16) results evaluator(model) print(fPrimary metric: {evaluator.primary_metric} {results[evaluator.primary_metric]:.4f}) pprint({k: v for k, v in results.items() if ndcg10 in k}) if __name__ __main__: main()要点拆解MultiVectorEncoder(lightonai/LateOn)从 Hub 加载预训练模型等价于用任意多向量模型如lightonai/GTE-ModernColBERT-v1见评估器 docstring 中的示例替换MultiVectorNanoBEIREvaluator(batch_size16)配置评估器batch_size控制编码时每次处理的文本数evaluator(model)触发端到端评估返回一个dict[str, float]默认配置下evaluator.primary_metric对应各子集主指标的均值聚合aggregate_fn默认np.mean、aggregate_key默认mean示例中的过滤条件ndcg10 in k会打印每个子集的 NDCG10 以及聚合均值。3.3 报告哪些指标对每个子集评估器报告MRRk、NDCGk、Recallk、Precisionk、Accuracyk、MAPk并在最后跨子集聚合这些指标。各 k 值的默认配置可覆盖为MRRk [10]、NDCGk [10]、Accuracyk [1, 3, 5, 10]、Precision/Recallk [1, 3, 5, 10]、MAPk [100]。四、MultiVectorNanoBEIREvaluator 关键参数详解结合 sentence_transformers/multi_vector_encoder/evaluation/nano_beir.py 的 docstring以下参数最值得掌握参数默认值说明dataset_names全部 13 个子集限制评测范围如[msmarco, nq, fiqa2018]。13 个子集为climatefever、dbpedia、fever、fiqa2018、hotpotqa、msmarco、nfcorpus、nq、quoraretrieval、scidocs、arguana、scifact、touche2020dataset_idsentence-transformers/NanoBEIR-en指向具备相同布局corpus / queries / qrels的其他数据集例如 NanoBEIR 集合中的翻译变体用于非英语评估corpus_chunk_size5000每轮往返round-trip编码并打分的文档数量。越大则同时驻留内存的文档嵌入越多但编码轮次越少chunk_elementsNoneMaxSim 打分中间结果的元素预算上限。调低可降低打分阶段内存占用batch_size32编码时的每批输入数量mrr_at_k/ndcg_at_k[10]MRR 与 NDCG 的 k 值accuracy_at_k[1, 3, 5, 10]Accuracy 的 k 值precision_recall_at_k[1, 3, 5, 10]Precision 与 Recall 的 k 值map_at_k[100]MAP 的 k 值show_progress_barFalse评估时是否显示进度条write_csvTrue是否把每次调用按 epoch/steps 一行追加写入 CSVwrite_predictionsFalse是否将每查询 top-k 预测写入 JSONL可直接作为ReciprocalRankFusionEvaluator的输入典型使用建议训练过程中常用dataset_names[msmarco, nq, fiqa2018]这类子集做快速迭代评估完整 13 子集留到训练收尾再跑。4.1chunk_elements背后的内存原理chunk_elements直接透传给 similarity.py 中的maxsim函数它约束的是补零后的(chunk, d_tokens, dim)文档张量与 4D 打分中间张量(batch_q, chunk, q_tokens, d_tokens)的总元素数。文档按预算贪心打包进块逐块补零因此单个超长文档只会撑大自己所在块默认None时采用maxsim内置的1 亿元素预算最多约 400 MBbf16/fp16 下减半。在非常大的查询批量下单文档兜底下限仍然可能很大此时需要在外部对查询分片。另外注意MultiVectorNanoBEIREvaluator构造时会把corpus_chunk_size与chunk_elements注入到每个子集内部构造的 IR 评估器见源码_ir_extra_kwargs与_load_dataset的合并逻辑因此这两个参数对全部子集统一生效。五、其他 MaxSim 评估器数据格式与指标NanoBEIR 是本目录唯一带示例脚本的任务但包内还内置了其他任务的 MaxSim 评估器全部导出自 sentence_transformers/multi_vector_encoder/evaluation/init.py每个类的 docstring 都附有可运行示例评估器必需数据MultiVectorInformationRetrievalEvaluator查询qid 问题文本、语料cid 文档文本、相关文档qid set[cid]MultiVectorRerankingEvaluator形如{query: ..., positive: [...], negative: [...]}的字典列表MultiVectorTripletEvaluator(anchor, positive, negative) 三元组MultiVectorDistillationEvaluator查询 候选文档 teacher 分数5.1 MultiVectorInformationRetrievalEvaluator自建语料的检索评估MultiVectorNanoBEIREvaluator内部就是逐子集运行MultiVectorInformationRetrievalEvaluator因此它接受与上面相同的指标与内存选项corpus_chunk_size、chunk_elements、各*_at_k、write_predictions等用于你自己的语料。实现细节见 information_retrieval.py未显式传入score_functions时打分函数在每次调用时根据model.similarity_fn_name动态解析_model_score_functions因此模型换用meanmaxsim时评估自动跟随若显式传入chunk_elements则会以functools.partial把它绑定到默认打分函数上查询嵌入会被预补零并跨语料块复用embed_inputs中pad_sequence每个块只重新编码文档降低重复开销自定义score_functions时若其中混入 XTR 打分xtr_scores/XTRScores会直接抛ValueError——XTR 做的是跨整个候选集的全局 top-k与评估器逐块打分语料的机制不兼容逐块取 top-k 会静默出错因此源码主动拒绝显式 prompt 与模型注册 prompt 不匹配时会发出warning_once提示避免显式 prompt 悄悄替换掉模型训练时的 marker prompt。5.2 MultiVectorRerankingEvaluator二阶重排MultiVectorRerankingEvaluator对每个查询的固定候选列表打分报告MAP、MRRk、NDCGkat_k默认 10。这正是把多向量模型用作**二阶重排器second-stage reranker**的评测形态一阶段检索器返回每个查询的候选正例与干扰项混合多向量模型再对其重打分排序。实现上见 reranking.py查询与文档分别经encode_query/encode_document非对称编码打分默认回退到model.similarity会把单查询归一化为 one-query batch。5.3 MultiVectorTripletEvaluator三元组排序准确率MultiVectorTripletEvaluator检查 anchor 对 positive 的分数高于对 negative 的次数比例判定条件为MaxSim(anchor, positive) MaxSim(anchor, negative) margin。anchor 经encode_query编码带查询前缀与长度positive / negative 经encode_document编码。margin 有一个容易踩坑的细节margin字典必须按相似度类型maxsim或meanmaxsim分别指定传入 float 则对两者同时生效因为两种打分的量纲不同——maxsim分数随查询长度累积归一化嵌入下约每查询 token 一分而meanmaxsim除以 token 数后落在余弦的[-1, 1]区间两者需要不同的 margin 值。源码通过MultiVectorEncoder.SUPPORTED_SIMILARITY_FN_NAMES枚举生成全部受支持的成对打分函数默认选用模型当前的similarity_fn_name。5.4 MultiVectorDistillationEvaluator蒸馏过程跟踪MultiVectorDistillationEvaluator用KL 散度越低越好与Spearman 秩相关越高越好主指标比较学生分数与 teacher 分数用于跟踪知识蒸馏训练。它支持两种数据形态见 distillation.py逐查询候选集KD 训练格式documents为每查询一个 N 路候选列表scores为对应的 2 维 teacher 分数。两个指标都按查询计算直接对齐训练损失KL 使用与MultiVectorDistillKLDivLoss相同的温度处理temperature、student_temperature、teacher_temperature三个参数KL 还会乘上学生温度平方Spearman 为各查询秩相关的均值若训练使用了非默认的similarity_fct如 MeanMaxSim 打分评估器也支持传入similarity_fct镜像训练设置否则逐查询 KL 无法与训练损失对齐扁平配对每查询一个文档、1 维分数。此时逐查询分布无定义KL 把整个数据集 softmax 成单个分布报告总散度不做配对数量归一因此不可与逐查询 KL 或 PyLate 直接比较Spearman 则是全体配对的单一全局相关。细节上teacher 或学生分数为常量时秩相关无定义对应查询会被跳过全部跳过则报 0.0因为 MaxSim 分数跨查询不可比随查询长度累积逐查询相关才是能跟踪损失的那个信号——这也是 Spearman 被设为主指标的原因。六、评估实践要点小结训练中快速迭代用dataset_names挑 3 个子集如[msmarco, nq, fiqa2018]完整 13 子集留到训练结束内存控制打分内存优先调chunk_elements默认 1 亿元素预算、约 400 MBbf16/fp16 减半编码内存用corpus_chunk_size控制同时驻留的文档嵌入数保持一致打分若模型以meanmaxsim长度归一化训练评估器会自动按model.similarity_fn_name解析打分无需额外配置蒸馏评估则务必把temperature与训练损失对齐非英语评测把dataset_id换成 NanoBEIR 集合中的翻译变体即可无需改动其余代码结果落盘默认write_csvTrue会把每次调用epoch/steps 一行追加到 CSVwrite_predictionsTrue输出的 JSONL 可作为稀疏检索融合评估器ReciprocalRankFusionEvaluator的输入做下游分析。如需深入实现可继续阅读 nano_beir.py子集加载与truncate_dim校验、information_retrieval.py动态打分解析与逐块打分、similarity.pymaxsim/meanmaxsim的底层实现与内存预算逻辑以及配套测试 tests/multi_vector_encoder/test_evaluators.py 验证各评估器的行为。【免费下载链接】sentence-transformersState-of-the-Art Embeddings, Retrieval, and Reranking项目地址: https://gitcode.com/gh_mirrors/se/sentence-transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考