FlagEmbedding 检索模型评测全指南七大 Benchmark 的完整评估流程、参数体系与源码原理【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding本篇技术指南以 FlagEmbedding 的评估文档体系docs/source/API/evaluation.rst为核心系统讲解该仓库内置的七大信息检索评测基准——BEIR、MTEB、AIR-Bench、MS MARCO、MIRACL、MKQA 与 MLDR 的一键评估方案。读者读完本文后将能够独立完成任意主流 Embedding / Reranker 模型在这七个基准上的评估理解每个命令行参数的语义与默认值并掌握底层检索→重排→指标计算流水线的实现原理为论文实验、模型对比与自定义数据评测提供可直接复用的实战方案。评测体系总览FlagEmbedding 在FlagEmbedding/evaluation/目录下为 7 个业界主流的信息检索基准提供了统一的评测入口每个基准均有独立的python -m FlagEmbedding.evaluation.name命令行入口以及配套的一键 Shell 脚本位于 examples/evaluation/基准命令行入口一键脚本评测重点BEIRFlagEmbedding.evaluation.beirexamples/evaluation/beir/eval_beir.sh异构信息检索15 个零样本检索任务MTEBFlagEmbedding.evaluation.mtebexamples/evaluation/mteb/eval_mteb.sh大规模文本嵌入基准8 大类任务AIR-BenchFlagEmbedding.evaluation.air_benchexamples/evaluation/air_bench/eval_air_bench.sh动态生成数据LLM 无人工标注MS MARCOFlagEmbedding.evaluation.msmarcoexamples/evaluation/msmarco/eval_msmarco.sh大规模真实阅读理解/检索MIRACLFlagEmbedding.evaluation.miraclexamples/evaluation/miracl/eval_miracl.sh18 种语言的多语言检索MKQAFlagEmbedding.evaluation.mkqaexamples/evaluation/mkqa/eval_mkqa.sh26 种语言的开放域 QA 评测MLDRFlagEmbedding.evaluation.mldrexamples/evaluation/mldr/eval_mldr.sh13 种语言的长文档检索所有基准共享同一套数据加载DataLoader→ 稠密检索Dense Retriever→ 可选重排Reranker→ 指标计算Evaluator的抽象流水线基类定义在 FlagEmbedding/abc/evaluation/ 下。这意味着你只需掌握一套参数体系就能在所有基准间无缝切换。评测流水线的源码级原理入口解析HfArgumentParser 与参数 Dataclass每个基准的__main__.py都使用 Hugging Face 的HfArgumentParser将两个 Dataclass评估参数 模型参数解析为命令行参数。以 BEIR 为例FlagEmbedding/evaluation/beir/main.py 的核心流程为parser HfArgumentParser((BEIREvalArgs, BEIREvalModelArgs)) eval_args, model_args parser.parse_args_into_dataclasses() runner BEIREvalRunner(eval_argseval_args, model_argsmodel_args) runner.run()BEIREvalArgs继承自AbsEvalArgsFlagEmbedding/evaluation/beir/arguments.py仅新增了一个字段use_special_instructions。这种基类沉淀通用逻辑、子类扩展基准特性的设计贯穿整个评测模块。Runner 调度检索器与重排器的装载AbsEvalRunnerFlagEmbedding/abc/evaluation/runner.py是流水线的调度核心其构造过程分为三步get_models()通过FlagAutoModel.from_finetuned(...)装载 Embedder若提供了reranker_name_or_path则再通过FlagAutoReranker.from_finetuned(...)装载 Reranker。两者均支持model_class显式指定模型架构如encoder-only-base、decoder-only-icl、decoder-only-layerwise等。load_retriever_and_reranker()将 Embedder 包装为EvalDenseRetriever携带search_top_k将 Reranker 包装为EvalReranker携带rerank_top_k二者实现在 FlagEmbedding/abc/evaluation/searcher.py。load_data_loader()与load_evaluator()分别装载对应基准的数据加载器与评估器不同基准通过重写这两个方法注入自身的数据逻辑例如 FlagEmbedding/evaluation/mldr/runner.py 中的MLDREvalRunner只重写了load_data_loader。检索实现Faiss 索引与向量搜索稠密检索基于 Faiss 完成FlagEmbedding/abc/evaluation/utils.pyindex()默认使用index_factory(Flat, ...)创建内积METRIC_INNER_PRODUCT索引并自动尝试将索引搬运到所有可用 GPUfaiss.index_cpu_to_all_gpus启用 shard 与 float16若 GPU 版 faiss 不可用则回退 CPU 并打印提示。search()将查询向量以每批 32 条的粒度送入faiss_index.search()返回 top-k 分数与索引。值得注意的是评测默认对 Embedding 进行归一化normalize_embeddingsTrue配合内积距离即等价于余弦相似度。数据加载远程数据集与本地缓存AbsEvalDataLoaderFlagEmbedding/abc/evaluation/data_loader.py统一封装了数据集管理数据集优先从cache_dir缺省取HF_HUB_CACHE环境变量否则~/.cache/huggingface/hub加载force_redownloadTrue时强制重新下载。它还提供check_dataset_names/check_splits对用户传入的数据集名与分割做合法性校验非法名称直接抛出ValueError。核心参数体系详解所有基准共享的评估参数定义在 FlagEmbedding/abc/evaluation/arguments.py 中分为AbsEvalArgs评测流程参数与AbsEvalModelArgs模型推理参数两大类。评测流程参数AbsEvalArgs参数默认值说明--eval_name无评测任务名如beir、msmarco、miracl等--dataset_dirNone本地数据集目录需包含corpus.jsonl、split_queries.jsonl、split_qrels.jsonl或指定下载数据集的保存路径--force_redownloadFalse强制重新下载远程数据集--dataset_namesNone评估全部数据集名称列表BEIR 的数据集名 / MIRACL 的语言名等支持多个值--splitstest要评估的划分如test dev--corpus_embd_save_dirNone语料 Embedding 的保存目录为None则不落盘--output_dir./search_results检索结果保存目录--search_top_k1000稠密检索阶段返回的 top-k 文档数--rerank_top_k100重排阶段保留的 top-k 文档数--cache_pathNone数据集缓存目录--token环境变量HF_TOKEN访问受限数据集的令牌--overwriteFalse是否覆盖已有评测结果--ignore_identical_idsFalse是否忽略检索结果中与查询同 ID 的文档--k_values1 3 5 10 100 1000指标计算的截断值列表--eval_output_methodmarkdown结果输出格式可选json/markdown--eval_output_path./eval_results.md结果文件输出路径--eval_metricsndcg_at_10 recall_at_10要计算的指标如ndcg_at_10 recall_at_100模型推理参数AbsEvalModelArgsEmbedder 相关参数默认值说明--embedder_name_or_path必填Embedder 模型名Hugging Face Hub或本地路径--embedder_model_classNone模型架构可选encoder-only-base/encoder-only-m3/decoder-only-base/decoder-only-icl/decoder-only-pseudo_moe自定义模型必须显式指定--normalize_embeddingsTrue是否归一化 Embedding--pooling_methodNoneEmbedder 的池化方式--use_fp16True推理是否使用 fp16--devicesNone推理设备列表如cuda:0 cuda:1--query_instruction_for_retrievalNone查询侧指令模板--query_instruction_format_for_retrieval{}{}指令拼接格式--examples_for_task/--examples_instruction_formatNone/{}{}ICL 类模型的示例与拼接格式--trust_remote_codeFalse是否信任远端自定义代码--cache_dirNone模型缓存目录--domain_for_pseudo_moeNonedecoder-only-pseudo_moe模型使用的领域如 general/coding/reasoning--embedder_batch_size3000编码批大小--embedder_query_max_length512查询最大长度--embedder_passage_max_length512段落最大长度长文档评测中常调大如 MLDR 用 8192--truncate_dimNoneEmbedding 截断维度适用于 Matryoshka 表示学习模型Reranker 相关参数默认值说明--reranker_name_or_pathNoneReranker 模型名或路径不填则跳过重排阶段--reranker_model_classNone可选encoder-only-base/decoder-only-base/decoder-only-layerwise/decoder-only-lightweight--reranker_peft_pathNoneReranker 的 PEFTLoRA权重路径--use_bf16False推理是否使用 bf16--query_instruction_for_rerank/--passage_instruction_for_rerankNone重排时查询/段落的指令--reranker_batch_size3000重排批大小--reranker_query_max_lengthNone重排查询最大长度--reranker_max_length512重排最大长度长文档任务常调为 8192--normalizeFalse是否归一化重排分数--promptNoneReranker 的提示词--cutoff_layersNonelayerwise / lightweight Reranker 的输出层--compress_ratio/--compress_layers1/Nonelightweight Reranker 的压缩配置细节AbsEvalModelArgs的__post_init__会将指令格式参数中的字面量\n自动替换为真实换行符因此可在命令行中以\\n形式传递多行指令模板。七大基准逐一评测BEIR异构零样本检索基准BEIRBenchmarking-IR是一个异构信息检索评测基准覆盖论证检索、事实核查、金融问答、科学论文等多个领域是衡量现代 Embedding 模型零样本泛化能力的业界标准。chmod x examples/evaluation/beir/eval_beir.sh ./examples/evaluation/beir/eval_beir.sh或直接运行python -m FlagEmbedding.evaluation.beir \ --eval_name beir \ --dataset_dir ./beir/data \ --dataset_names fiqa arguana cqadupstack \ --splits test dev \ --corpus_embd_save_dir ./beir/corpus_embd \ --output_dir ./beir/search_results \ --search_top_k 1000 \ --rerank_top_k 100 \ --cache_path /root/.cache/huggingface/hub \ --overwrite False \ --k_values 10 100 \ --eval_output_method markdown \ --eval_output_path ./beir/beir_eval_results.md \ --eval_metrics ndcg_at_10 recall_at_100 \ --ignore_identical_ids True \ --embedder_name_or_path BAAI/bge-large-en-v1.5 \ --reranker_name_or_path BAAI/bge-reranker-v2-m3 \ --devices cuda:0 cuda:1 \ --reranker_max_length 1024BEIR 的独有特性——数据集专属指令BEIREvalArgs新增的use_special_instructions参数FlagEmbedding/evaluation/beir/arguments.py开启后BEIREvalRunner 会在每个数据集评测前把检索指令切换为该数据集的专属指令定义于 FlagEmbedding/evaluation/beir/prompts.py。仓库内置的指令覆盖 15 个数据集例如数据集指令fiqaGiven a financial question, retrieve user replies that best answer the question.arguanaGiven a claim, find documents that refute the claim.hotpotqaGiven a multi-hop question, retrieve documents that can help answer the question.trec-covidGiven a query on COVID-19, retrieve documents that answer the query.nqGiven a question, retrieve Wikipedia passages that answer the question.quoraGiven a question, retrieve questions that are semantically equivalent to the given question.完整指令表见 prompts.py涵盖 dbpedia-entity、climate-fever、cqadupstack、fever、msmarco、nfcorpus、scidocs、scifact、webis-touche2020 等。MTEB大规模文本嵌入基准MTEBMassive Text Embedding Benchmark是面向文本嵌入模型的大规模评测框架覆盖检索、聚类、重排、STS 等 8 大类 NLP 任务与多种语言并维护着业界知名的公开排行榜。chmod x examples/evaluation/mteb/eval_mteb.sh ./examples/evaluation/mteb/eval_mteb.sh或直接运行python -m FlagEmbedding.evaluation.mteb \ --eval_name mteb \ --output_dir ./mteb/search_results \ --languages eng \ --tasks NFCorpus BiorxivClusteringS2S SciDocsRR \ --eval_output_path ./mteb/mteb_eval_results.json \ --embedder_name_or_path BAAI/bge-large-en-v1.5 \ --devices cuda:7 \ --cache_dir /root/.cache/huggingface/hubMTEBEvalArgsFlagEmbedding/evaluation/mteb/arguments.py在基类之上扩展了四个基准专属参数--languages要评测的语言默认eng如eng、zho等--tasks要评测的具体任务列表如NFCorpus、BiorxivClusteringS2S不填则评测全部--task_types按任务类型筛选如 Retrieval、Clustering、STS 等--use_special_instructions与--examples_path是否使用提示文件中的专属指令以及是否使用指定路径的示例。AIR-BenchLLM 自动生成的动态基准AIR-BenchAutomated heterogeneous Information Retrieval Benchmark是一个持续更新的动态检索基准其测试数据完全由 LLM 生成、无人工干预。这带来两个关键特性新领域评测可以快速扩展同时保证任何模型都无法在训练阶段看过测试数据。chmod x examples/evaluation/air_bench/eval_air_bench.sh ./examples/evaluation/air_bench/eval_air_bench.sh或直接运行python -m FlagEmbedding.evaluation.air_bench \ --benchmark_version AIR-Bench_24.05 \ --task_types qa long-doc \ --domains arxiv \ --languages en \ --splits dev test \ --output_dir ./air_bench/search_results \ --search_top_k 1000 \ --rerank_top_k 100 \ --cache_dir /root/.cache/huggingface/hub \ --overwrite False \ --embedder_name_or_path BAAI/bge-m3 \ --reranker_name_or_path BAAI/bge-reranker-v2-m3 \ --devices cuda:0 cuda:1 \ --model_cache_dir /root/.cache/huggingface/hub \ --reranker_max_length 1024AIR-Bench 的入口在生成检索结果后会打印提示指标计算需参考 AIR-Bench 官方提交规范FlagEmbedding/evaluation/air_bench/main.py 末尾的日志说明即本仓库负责产出检索结果评分环节对接官方评测流程。MS MARCO大规模真实检索数据集MS MARCOMicrosoft MAchine Reading Comprehension是大规模真实世界阅读理解数据集广泛用于信息检索、问答与 NLP 研究。chmod x examples/evaluation/msmarco/eval_msmarco.sh ./examples/evaluation/msmarco/eval_msmarco.sh或直接运行python -m FlagEmbedding.evaluation.msmarco \ --eval_name msmarco \ --dataset_dir ./msmarco/data \ --dataset_names passage \ --splits dev \ --corpus_embd_save_dir ./msmarco/corpus_embd \ --output_dir ./msmarco/search_results \ --search_top_k 1000 \ --rerank_top_k 100 \ --cache_path /root/.cache/huggingface/hub \ --overwrite True \ --k_values 10 100 \ --eval_output_method markdown \ --eval_output_path ./msmarco/msmarco_eval_results.md \ --eval_metrics ndcg_at_10 recall_at_100 \ --embedder_name_or_path BAAI/bge-large-en-v1.5 \ --reranker_name_or_path BAAI/bge-reranker-v2-m3 \ --devices cuda:0 cuda:1 cuda:2 cuda:3 cuda:4 cuda:5 cuda:6 cuda:7 \ --cache_dir /root/.cache/huggingface/hub \ --reranker_max_length 1024MS MARCO 的语料规模较大示例脚本配置了全部 8 张 GPU 进行 Embedding 编码——这也是--devices支持多设备列表的意义所在大规模语料编码会被自动切分到多个 GPU 上并行处理。MIRACL18 语言的多语言检索挑战MIRACLMultilingual Information Retrieval Across a Continuum of Languages源自 WSDM 2023 Cup 挑战赛聚焦 18 种语言的跨语言检索。其中 16 种已知语言提供训练集与开发集2 种惊喜语言德语de、约鲁巴语yo仅有开发集查询由各语言母语者撰写并标注相关性。从源码可见其支持的全部语言FlagEmbedding/evaluation/miracl/data_loader.py# ar bn en es fa fi fr hi id ja ko ru sw te th zh de yo且de与yo两种语言只提供dev划分其余语言提供train与dev。chmod x examples/evaluation/miracl/eval_miracl.sh ./examples/evaluation/miracl/eval_miracl.sh或直接运行python -m FlagEmbedding.evaluation.miracl \ --eval_name miracl \ --dataset_dir ./miracl/data \ --dataset_names bn hi sw te th yo \ --splits dev \ --corpus_embd_save_dir ./miracl/corpus_embd \ --output_dir ./miracl/search_results \ --search_top_k 1000 \ --rerank_top_k 100 \ --cache_path /root/.cache/huggingface/hub \ --overwrite False \ --k_values 10 100 \ --eval_output_method markdown \ --eval_output_path ./miracl/miracl_eval_results.md \ --eval_metrics ndcg_at_10 recall_at_100 \ --embedder_name_or_path BAAI/bge-m3 \ --reranker_name_or_path BAAI/bge-reranker-v2-m3 \ --devices cuda:0 cuda:1 \ --cache_dir /root/.cache/huggingface/hub \ --reranker_max_length 1024MKQA26 语言开放域问答评测MKQA 是包含 1 万条问答对的开放域问答评测集问题对齐到 26 种类型学上差异显著的语言查询源自 Google Natural Questions 数据集。每条样本包含多语言查询与多语言答案其数据结构如下见 docs/source/API/evaluation/mkqa.rst{ example_id: 563260143484355911, queries: { en: who sings i hear you knocking but you cant come in, ru: кто поет i hear you knocking but you cant come in, ja: 「 I hear you knocking」は誰が歌っていますか, zh_cn: 《i hear you knocking but you cant come in》是谁演唱的, ... }, query: who sings i hear you knocking but you cant come in, answers: { en: [{ type: entity, entity: Q545186, text: Dave Edmunds, aliases: [], }], ru: [{ type: entity, entity: Q545186, text: Эдмундс, Дэйв, aliases: [Эдмундс, Дэйв Эдмундс, Эдмундс Дэйв, Dave Edmunds], }], ja: [{ type: entity, entity: Q545186, text: デイヴ・エドモンズ, aliases: [デーブ・エドモンズ, デイブ・エドモンズ], }], zh_cn: [{ type: entity, text: 戴维·埃德蒙兹 , entity: Q545186, }], ... }, }chmod x examples/evaluation/mkqa/eval_mkqa.sh ./examples/evaluation/mkqa/eval_mkqa.sh或直接运行python -m FlagEmbedding.evaluation.mkqa \ --eval_name mkqa \ --dataset_dir ./mkqa/data \ --dataset_names en zh_cn \ --splits test \ --corpus_embd_save_dir ./mkqa/corpus_embd \ --output_dir ./mkqa/search_results \ --search_top_k 1000 \ --rerank_top_k 100 \ --cache_path /root/.cache/huggingface/hub \ --overwrite False \ --k_values 20 \ --eval_output_method markdown \ --eval_output_path ./mkqa/mkqa_eval_results.md \ --eval_metrics qa_recall_at_20 \ --embedder_name_or_path BAAI/bge-m3 \ --reranker_name_or_path BAAI/bge-reranker-v2-m3 \ --devices cuda:0 cuda:1 \ --cache_dir /root/.cache/huggingface/hub \ --reranker_max_length 1024注意 MKQA 的指标与其他基准不同使用qa_recall_at_20top-20 检索结果中回答正确率。其实现位于 FlagEmbedding/evaluation/mkqa/evaluator.py通过evaluate_qa_recallFlagEmbedding/evaluation/mkqa/utils/compute_metrics.py结合答案归一化逻辑计算同时复用教程 Tutorials/4_Evaluation/utils/compute_metrics.py 中的工具函数。MLDR13 语言长文档检索MLDRMultilingual Long-Document Retrieval基于 Wikipedia、Wudao 与 mC4 构建覆盖 13 种语言。其构造方式为从上述语料中抽取长文章随机选取段落再用 GPT-3.5 基于段落生成问题构成新的问题-文章文本对。各划分的数据结构如下train划分示例{ query_id: q-zh-..., query: ..., positive_passages: [ { docid: doc-zh-..., text: ... } ], negative_passages: [ { docid: doc-zh-..., text: ... }, ... ] }dev与test划分示例负例为空{ query_id: q-zh-..., query: ..., positive_passages: [ { docid: doc-zh-..., text: ... } ], negative_passages: [] }corpus语料示例{ docid: doc-zh-..., text: ... }chmod x examples/evaluation/mldr/eval_mldr.sh ./examples/evaluation/mldr/eval_mldr.sh或直接运行python -m FlagEmbedding.evaluation.mldr \ --eval_name mldr \ --dataset_dir ./mldr/data \ --dataset_names hi \ --splits test \ --corpus_embd_save_dir ./mldr/corpus_embd \ --output_dir ./mldr/search_results \ --search_top_k 1000 \ --rerank_top_k 100 \ --cache_path /root/.cache/huggingface/hub \ --overwrite False \ --k_values 10 100 \ --eval_output_method markdown \ --eval_output_path ./mldr/mldr_eval_results.md \ --eval_metrics ndcg_at_10 \ --embedder_name_or_path BAAI/bge-m3 \ --reranker_name_or_path BAAI/bge-reranker-v2-m3 \ --devices cuda:0 cuda:1 \ --cache_dir /root/.cache/huggingface/hub \ --embedder_passage_max_length 8192 \ --reranker_max_length 8192长文档评测的关键MLDR 必须把--embedder_passage_max_length与--reranker_max_length调大到 8192这正是 BGE-M3 这类支持长文本模型的用武之地——标准 512 截断会丢失长文档的关键信息这也是该基准区别于其他短文本基准的核心差异。指标计算与结果输出统一指标计算所有检索类基准BEIR / MS MARCO / MIRACL / MLDR / MTEB 检索子任务共享 FlagEmbedding/abc/evaluation/utils.py 中的指标实现evaluate_metrics()基于pytrec_eval.RelevanceEvaluator一次性计算NDCGk、MAPk、Recallk、Pk四类指标evaluate_mrr()计算平均倒数排名MRRkevaluate_recall_cap()计算带上限的召回率R_capk分母取min(相关文档数, k)。这些实现注明改编自 BEIR 与 MTEB 官方仓库的自定义指标函数保证了跨仓库结果的可比性。输出格式AbsEvalRunner.evaluate_metrics()FlagEmbedding/abc/evaluation/runner.py会扫描output_dir下模型名 → 重排器名两级目录中的EVAL/eval_results.json聚合后按指定格式输出--eval_output_method json输出 JSON 文件--eval_output_method markdown按指标列表输出 Markdown 表格便于直接写入论文或排行榜。结果缓存与断点续跑检索结果与语料 Embedding 都支持落盘缓存--corpus_embd_save_dir保存语料向量后续评测可直接加载避免重复编码--output_dir保存检索结果。配合--overwrite False重复运行同一评测时会跳过已完成的检索实现先检索、后统一算指标的两阶段工作流方便快速迭代实验。扩展自定义数据集评测除内置基准外评测框架也支持自有数据。根据AbsEvalArgs.dataset_dir的说明FlagEmbedding/abc/evaluation/arguments.py本地数据集目录需按以下约定组织dataset_dir/ ├── corpus.jsonl # 语料{docid, text, title?} ├── split_queries.jsonl # 查询{qid, text} └── split_qrels.jsonl # 相关性标注{qid, docid, score}或按数据集分子目录每个子目录内部同样包含上述三个文件。指定--dataset_dir后即可复用整套检索 → 重排 → 指标计算流水线将自定义数据的评测结果与内置基准对齐这正是该抽象架构AbsEvalDataLoader/AbsEvaluator/AbsEvalRunner的核心价值。总结FlagEmbedding 的评测体系以 FlagEmbedding/abc/evaluation/ 的抽象基类为骨架为 BEIR、MTEB、AIR-Bench、MS MARCO、MIRACL、MKQA、MLDR 七大基准提供了统一的参数体系与执行流水线。实际使用时只需把握三条主线一是理解AbsEvalArgs/AbsEvalModelArgs的通用参数检索深度、重排深度、截断值、输出格式等二是按基准特性调整专属参数BEIR 的专属指令、MTEB 的语言与任务筛选、MKQA 的 QA 指标、MLDR 的 8192 长文本长度三是善用 Embedding 与检索结果的缓存机制实现高效迭代。各基准的完整参数定义可查阅 docs/source/API/evaluation/ 下的 arguments 文档或直接阅读对应源码的 Dataclass 定义。【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考