FlagEmbedding 评估参数完全指南AbsEvalArgs 与 AbsEvalModelArgs 逐项解析【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding本篇技术指南围绕 FlagEmbedding 的评估参数体系展开FlagEmbedding.abc.evaluation模块通过AbsEvalArgs数据与评估流程参数和AbsEvalModelArgs嵌入器/重排器模型参数两个 dataclass统一了 BEIR、MIRACL、MSMARCO、MTEB、AirBench 等全部内置评估任务以及自定义数据集的评估入口。读完本文你将掌握每个参数的作用、默认值与生效链路并能基于这些参数写出可复用的评估脚本。评估参数的定位一套参数全任务复用在 FlagEmbedding 中所有评估任务BEIR、MIRACL、MLDR、MSMARCO、MTEB、AirBench、MKQA、BRIGHT、自定义数据等共享同一个抽象的评估骨架定义于 FlagEmbedding/abc/evaluation 目录arguments.py定义AbsEvalArgs与AbsEvalModelArgs即本文核心对象data_loader.py负责加载本地或远程语料、查询、qrelssearcher.py封装稠密检索Faiss与重排逻辑evaluator.py计算指标并输出 JSON/Markdown 结果runner.py编排完整评估流程。两个参数类共同构成 参数即 API 的设计用户只需通过命令行或 Python 对象配置这两组参数即可驱动整条评估流水线。从源码结构看具体任务如 BEIR通过继承这两个基类来扩展专属参数例如 BEIREvalArgs 在基类之上仅新增了一个use_special_instructions字段这说明绝大多数评估配置都由基类承担。AbsEvalArgs评估流程与数据参数AbsEvalArgs是评估数据 检索/重排流程 指标输出的全部配置项定义于 arguments.py。其字段通过 Pythondataclasses的field声明并使用metadata{help: ...}携带说明信息这一点与 Transformers 的HfArgumentParser无缝兼容——每个任务的__main__.py都直接用HfArgumentParser解析该 dataclass例如 beir/main.py。数据来源与数据集选择参数默认值说明eval_nameNone评估任务名称如msmarco、beir、miracl等它同时决定数据加载器和评估器选择并作为结果元数据写入dataset_dirNone自定义数据集目录或远程数据集下载保存目录为None时数据集仅下载到缓存目录force_redownloadFalse是否强制重新下载数据集用于更新已缓存的远程数据dataset_namesNonenargs要评估的数据集名称列表为None时评估全部可用数据集名称粒度因任务而异BEIR 是具体数据集名MIRACL 可以是语言名splitstestnargs要评估的划分如test devcache_pathNone数据集加载时的 HuggingFace 缓存目录token环境变量HF_TOKEN访问受限数据集/模型时使用的 token其中dataset_dir的语义具有双重身份这一点在源码 help 中特别强调评估自定义数据集传入本地目录路径目录下须包含corpus.jsonl、split_queries.jsonl、split_qrels.jsonl或包含多个子目录、每个子目录内含上述三件套。对应 data_loader.py 中的_load_local_corpus/_load_local_queries/_load_local_qrelscorpus.jsonl每行须含id与text可选title有 title 时检索/重排会以title text拼接split_queries.jsonl每行含id与textsplit_qrels.jsonl每行含qid、docid与relevance。保存远程数据集若本地三件套缺失数据加载器会调用_load_remote_*下载到该目录详见 data_loader.py 的 NotImplementedError 占位与各子类实现。检索、重排与结果落盘参数默认值说明corpus_embd_save_dirNone语料嵌入保存目录为None时不保存。设置后语料向量会以doc.npy形式缓存再次评估时若存在且overwriteFalse则直接加载复用见 searcher.pyoutput_dir./search_results搜索结果各 query 的 top-k 文档及分数保存目录search_top_k1000检索阶段每个 query 返回的候选文档数rerank_top_k100重排阶段截断保留的文档数仅传入重排器时生效overwriteFalse是否覆盖已存在的评估结果False且结果已存在时会直接跳过对应计算实现断点续跑ignore_identical_idsFalse检索/重排结果中是否忽略与 query id 相同的 doc id。注意源码 searcher.py 中明确警告MIRACL 这类数据集不应设为True结果目录结构由 evaluator.py 决定output_dir/检索器名/NoReranker/split.json与output_dir/检索器名/重排器名/split.json。每个结果文件不仅保存search_results还写入eval_name、model_name、reranker_name、split、dataset_name元数据见save_search_results并在加载时通过check_data_info做一致性校验防止误用错配的旧结果。评估指标与输出参数默认值说明k_values[1, 3, 5, 10, 100, 1000]nargs计算指标时使用的截断值集合如--k_values 10 100仅计算 k10/100 的指标eval_metrics[ndcg_at_10, recall_at_10]nargs写入最终 Markdown 报告的指标列取值形如ndcg_at_10、recall_at_100、mrr_at_10等eval_output_methodmarkdown结果输出格式可选json或markdowneval_output_path./eval_results.md汇总结果输出路径指标计算在 evaluator.py 的compute_metrics中完成一次性产出 NDCG、MAP、Recall、Precision、MRR、RecallCap 六类指标在全部k_values上的取值。底层实现见 utils.pyNDCG/MAP/Recall/Precision 基于pytrec_eval的RelevanceEvaluatorutils.pyMRR 与 capped recall 则在 utils.py 中自行实现分别改编自 BEIR 与 MTEB 的指标实现。最终eval_metrics指定的指标通过output_eval_results_to_markdown生成 Markdown 表格且对每个指标会以粗体高亮该指标最优的模型见 evaluator.py并计算各 split 的average列。AbsEvalModelArgs模型与推理参数AbsEvalModelArgs负责定义用什么模型、以什么方式推理定义于 arguments.py。它分为模型选择、指令格式与推理配置三大块。嵌入器配置参数默认值说明embedder_name_or_path必填嵌入器模型名称或本地路径如BAAI/bge-large-en-v1.5embedder_model_classNone模型类可选encoder-only-base、encoder-only-m3、decoder-only-base、decoder-only-icl、decoder-only-pseudo_moe。自定义模型必须显式指定normalize_embeddingsTrue是否对嵌入向量做归一化L2 归一化pooling_methodNone嵌入池化方式如cls、mean等按模型需要指定use_fp16True推理是否使用 FP16 半精度devicesNonenargs推理设备如cuda:0 cuda:1支持多卡trust_remote_codeFalse是否信任远程模型代码cache_dirNone模型缓存目录指令Instruction配置参数默认值说明query_instruction_for_retrievalNone检索阶段 query 的前缀指令如 BGE 系列的Represent this sentence for searching relevant passages:query_instruction_format_for_retrieval{}{}query 指令拼接格式前一个{}为指令、后一个为原文__post_init__会把字面量\n替换为真实换行examples_for_taskNone提供给 ICL 类嵌入器decoder-only-icl的任务示例examples_instruction_format{}{}示例指令拼接格式examples_for_task与examples_instruction_format对应 inference/embedder/decoder_only/icl.py 所支持的 ICLIn-Context Learning嵌入方式是decoder-only-icl模型类专属能力。重排器配置参数默认值说明reranker_name_or_pathNone重排器模型名称或本地路径为None则只做检索不做重排reranker_model_classNone重排器模型类可选encoder-only-base、decoder-only-base、decoder-only-layerwise、decoder-only-lightweight自定义模型必须显式指定reranker_peft_pathNone重排器的 PEFTLoRA 等权重路径use_bf16False推理是否使用 BF16与use_fp16共用嵌入器设置重排器部分单独提供该开关query_instruction_for_rerankNone重排阶段 query 指令query_instruction_format_for_rerank{}{}query 指令拼接格式passage_instruction_for_rerankNone重排阶段 passage 指令passage_instruction_format_for_rerank{}{}passage 指令拼接格式normalizeFalse是否对重排分数做归一化promptNone提供给重排器的提示词cutoff_layersNonelayerwise/lightweight重排器输出的层集合listcompress_ratio1lightweight重排器的压缩比compress_layersNonenargslightweight重排器的压缩层重排器是可选组件reranker_name_or_path为None时AbsEvalRunner.get_models只加载嵌入器评估仅执行检索阶段runner.py。推理批处理与长度参数默认值说明embedder_batch_size3000嵌入器推理批大小reranker_batch_size3000重排器推理批大小embedder_query_max_length512query 最大长度tokenembedder_passage_max_length512passage/语料最大长度truncate_dimNone嵌入截断维度适用于 Matryoshka Representation LearningMRL模型为None不截断reranker_query_max_lengthNone重排 query 最大长度覆盖reranker_max_lengthreranker_max_length512重排 query-passage 拼接后的最大长度truncate_dim使得同一 MRL 模型可在不同嵌入维度下分别评估如截断到 128/256/512 维无需重复加载模型。参数如何驱动整条评估流水线AbsEvalArgs与AbsEvalModelArgs在 AbsEvalRunner 中被消费执行链路如下构造 runnerAbsEvalRunner.__init__依次调用load_retriever_and_reranker、load_data_loader、load_evaluatorrunner.py。加载模型get_models把AbsEvalModelArgs的每个字段逐一透传给FlagAutoModel.from_finetuned与FlagAutoReranker.from_finetunedrunner.py并设置model.config._name_or_path供检索器/重排器命名。load_retriever_and_reranker随后用eval_args.search_top_k和eval_args.rerank_top_k包装出EvalDenseRetriever与可选EvalReranker。加载数据load_data_loader把eval_name、dataset_dir、cache_path、token、force_redownload传给AbsEvalDataLoader缓存目录未指定时回退到环境变量HF_HUB_CACHE默认~/.cache/huggingface/hub并追加eval_name子目录data_loader.py。执行评估AbsEvaluator.__call__先check_splits校验划分再执行 Faiss 检索EvalDenseRetriever内部调用index/search见 utils.py若配置了重排器则在检索 top-k 上做rerank_top_k截断后二次排序searcher.py。计算与汇总指标run()末尾调用evaluate_metrics遍历output_dir下所有模型/重排器组合的EVAL/eval_results.json按eval_output_method与eval_metrics汇总输出runner.py。实战基于两组参数编写评估脚本以 BEIR 评估为例仓库提供了可直接运行的脚本 examples/evaluation/beir/eval_beir.sh其参数组织正是上述两类的命令行映射dataset_namesfiqa arguana cqadupstack eval_args\ --eval_name beir \ --dataset_dir ./beir/data \ --dataset_names $dataset_names \ --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 $HF_HUB_CACHE \ --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 \ model_args\ --embedder_name_or_path BAAI/bge-large-en-v1.5 \ --reranker_name_or_path BAAI/bge-reranker-v2-m3 \ --devices cuda:0 cuda:1 \ --cache_dir $HF_MODEL_CACHE \ --reranker_max_length 1024 \ cmdpython -m FlagEmbedding.evaluation.beir \ $eval_args \ $model_args \ eval $cmd要点解读检索器BAAI/bge-large-en-v1.5与重排器BAAI/bge-reranker-v2-m3组合使用体现先检索 top-1000、再重排 top-100的两阶段评估reranker_max_length 1024保证长文档重排时上下文充足--k_values 10 100仅计算 k10/100 的截断指标eval_metrics相应指定ndcg_at_10与recall_at_100与k_values保持一致--corpus_embd_save_dir缓存语料嵌入多轮实验或--splits test dev跨划分复用时避免重复编码三个数据集并行评估run()会遍历dataset_names逐个调用 evaluatorrunner.py。评估完成后./beir/beir_eval_results.md会生成每个指标的 Markdown 表格行为各数据集列行为模型, 重排器组合最优值加粗并附average列evaluator.py。继承与扩展为自定义任务添加专属参数若要在基类之上扩展任务专属参数参考 BEIREvalArgs 的模式继承AbsEvalArgs并声明新字段即可无需改动评估框架本体from dataclasses import dataclass, field from FlagEmbedding.abc.evaluation.arguments import AbsEvalArgs dataclass class MyEvalArgs(AbsEvalArgs): 自定义评估任务的专属参数。 use_special_instructions: bool field( defaultFalse, metadata{help: Whether to use specific instructions for evaluation. Default: False} )同时数据加载器需继承AbsEvalDataLoader并实现available_splits与_load_remote_*等抽象方法评估器继承AbsEvaluator以复用指标计算与结果落盘逻辑。整个 ABC 层在 FlagEmbedding/abc/evaluation 目录中保持参数类 数据加载器 检索器 评估器 运行器的清晰分层任何新任务都只需在此骨架上填充任务特有逻辑。小结AbsEvalArgs与AbsEvalModelArgs是 FlagEmbedding 评估体系的控制面板前者决定评估什么数据、检索多少候选、重排多少结果、输出哪些指标后者决定用什么嵌入器/重排器、如何构造指令、以什么精度与批大小推理。掌握这两张参数表配合 examples/evaluation 下的各任务脚本即可在 BEIR、MIRACL、MSMARCO、MTEB 等基准上快速复现或扩展自己的检索评估实验。【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考