LlamaIndex 检索评估实战指南：使用 RetrieverEvaluator 与合成数据集量化检索质量

LlamaIndex 检索评估实战指南使用 RetrieverEvaluator 与合成数据集量化检索质量【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index导读检索Retrieval是 RAG 系统的第一道关卡检索质量直接决定最终生成答案的上限。本文基于 LlamaIndex 框架的检索评估模块系统讲解如何用RetrieverEvaluator在单条查询 标准答案文档集上运行评估指标如 MRR、Hit Rate如何通过generate_question_context_pairs从现有语料合成问题-节点评估数据集以及如何用批量模式快速跑完整套评估。读完本文你将掌握一套可落地的检索质量度量与回归测试方案。一、认识检索评估的整体思路检索评估的目标很简单给定一条查询query和一组应该被检索到的文档节点 IDground-truth 节点让待评估的 retriever 去检索然后比较期望命中与实际召回之间的重合程度用标准化指标打分。LlamaIndex 将这一过程封装为RetrieverEvaluator。从其源码定义可以看到它接收三类核心组件evaluator.pyretriever待评估的检索器BaseRetriever例如index.as_retriever(...)的产物metrics一组BaseRetrievalMetric指标node_postprocessors可选的节点后处理器如 reranker在检索完成后、打分之前对结果做二次过滤。评估流程在_aget_retrieved_ids_and_texts中清晰可见先调用retriever.aretrieve(query)拿到检索结果再依次应用每个node_postprocessor.postprocess_nodes(...)最后把结果拆成节点 ID 列表和文本列表交给指标计算。这意味着你评估的可以是检索器 后处理管道的完整链路而不仅是裸检索器本身。二、用 RetrieverEvaluator 评估单条查询2.1 最小可用示例官方文档给出的标准用法是先用from_metric_names声明要使用的指标集合然后调用evaluatefrom llama_index.core.evaluation import RetrieverEvaluator # 先在别处定义 retriever例如从 index 获取 # retriever index.as_retriever(similarity_top_k2) retriever ... retriever_evaluator RetrieverEvaluator.from_metric_names( [mrr, hit_rate], retrieverretriever ) retriever_evaluator.evaluate( queryquery, expected_ids[node_id1, node_id2] )from_metric_names是工厂方法定义在 base.py它调用resolve_metrics把字符串名字解析为对应的指标类再实例化并挂到 evaluator 上。因此你只需记住指标的名字字符串即可。2.2 评估返回什么evaluate及其异步版本aevaluate返回一个RetrievalEvalResult对象它包含以下字段字段含义query本次评估的查询字符串expected_ids期望被检索到的节点 ID 列表expected_texts与expected_ids对应的节点文本可选retrieved_ids检索器实际召回的节点 ID 列表retrieved_texts实际召回的节点文本mode评估模态text或image默认textmetric_dict每个指标的计算结果RetrievalMetricResult含score其中metric_vals_dict属性会把metric_dict压缩成{指标名: 分数}的纯数值字典方便直接打印或落表。RetrievalEvalResult还实现了__str__直接打印即可看到查询与各项指标分数。从源码可以看到evaluate是同步封装它内部通过asyncio_run调用了异步实现aevaluate所以你也可以在异步环境里直接使用await retriever_evaluator.aevaluate(...)。2.3 支持的指标一览所有内置检索指标定义在 metrics.py并通过METRIC_REGISTRY注册。合法指标名如下指标名字符串类计算方式说明hit_rateHitRate命中率。默认判断实际召回中是否存在至少一个期望节点设置use_granular_hit_rateTrue后改为命中数 / 期望节点数mrrMRR平均倒数排名。默认取第一个相关文档排名的倒数use_granular_mrrTrue时对所有相关文档的倒数排名求平均precisionPrecision精确率 召回 ∩ 期望 / 召回总数对应 PrecisionKK 通常等于 retriever 的 top_krecallRecall召回率 召回 ∩ 期望 / 期望总数apAveragePrecision平均精确率按检索结果排序位置累计计算ndcgNDCG归一化折损累计增益目前仅支持二元相关性在期望集合中 rel1否则 rel0mode可选linear或exponentialcohere_rerank_relevancyCohereRerankRelevancyMetric调用 Cohere rerank 服务对召回文本打分后聚合需安装cohere包并配置COHERE_API_KEY传入未注册的指标名会抛出ValueError: Invalid metric name。需要强调的一点是hit_rate与mrr是实践中最常用的两个基础指标官方文档示例也正是以它们开场——前者衡量是否找得到后者额外惩罚相关文档排得太靠后。2.4 让 reranker 参与评估RetrieverEvaluator的构造参数还支持node_postprocessors。例如from llama_index.core.postprocessor import SentenceTransformerRerank reranker SentenceTransformerRerank(top_n3, modelBAAI/bge-reranker-base) retriever_evaluator RetrieverEvaluator( metrics[HitRate(), MRR()], retrieverretriever, node_postprocessors[reranker], )这样评估的就是检索 重排后的最终候选质量更贴近真实生产链路。三、构建评估数据集评估不能只靠一两条查询。标准的做法是准备一组问题 → 期望节点 ID的配对集合。有两种途径3.1 人工标注手动从你的知识库中挑选若干代表性查询并记录每条查询对应的 ground-truth 节点 ID。这种方式质量最高但成本也高适合评估集规模不大或需要精确控制的场景。3.2 合成数据集generate_question_context_pairsLlamaIndex 提供了generate_question_context_pairs函数可以直接基于已有文本语料合成评估数据集from llama_index.core.evaluation import generate_question_context_pairs qa_dataset generate_question_context_pairs( nodes, llmllm, num_questions_per_chunk2 )参数含义nodes已切分好的节点列表例如SimpleNodeParser或SentenceSplitter的输出llm用于生成问题的语言模型num_questions_per_chunk每个节点生成的问问题数量上例中每个 chunk 生成 2 个问题。函数返回EmbeddingQAFinetuneDataset对象内部包含三个字段queries{query_id: query_text}生成的查询集合relevant_docs{query_id: [node_id, ...]}每条查询对应的期望节点映射corpus{node_id: node_text}原始语料字典。这正是RetrieverEvaluator批量评估所需的全部信息查询、期望节点、以及用于对照的语料。注在该函数对应的底层实现中LLM 驱动的数据集生成还以DatasetGenerator形式存在见 dataset_generation.py。它会把每个节点包进SummaryIndex用默认问题生成模板DEFAULT_QUESTION_GENERATION_PROMPT根据给定上下文、不依赖先验知识生成问题批量产问题并支持用required_keywords/exclude_keywords过滤节点。从源码注释看该路径已被标注为弃用deprecated官方推荐改用LabelledRagDataset但generate_question_context_pairs仍是文档记载的检索评估数据集入口。四、批量评估aevaluate_dataset手动对每条查询调用.evaluate既慢又繁琐。RetrieverEvaluator提供了便捷的批量接口eval_results await retriever_evaluator.aevaluate_dataset(qa_dataset)相比逐条调用.evaluate这种方式会显著更快因为它把查询并行化提交给底层检索链路内部对每个查询发起aretrieve并并发聚合结果避免了同步循环中反复等待。eval_results是RetrievalEvalResult的列表长度与数据集中的查询数一致。随后你可以对结果做进一步分析for result in eval_results: print(result)RetrievalEvalResult.__str__会输出Query: ...和Metrics: {hit_rate: ..., mrr: ...}便于快速人工抽查。4.1 结果汇总成表get_retrieval_results_df当需要横向对比多个 retriever例如对比不同 embedding 模型、不同 top_k、不同 reranker时可以用get_retrieval_results_df把多组评估结果聚合成 DataFrame见 notebook_utils.pyfrom llama_index.core.evaluation import get_retrieval_results_df df get_retrieval_results_df( names[retriever_a, retriever_b], results_arr[eval_results_a, eval_results_b], metric_keys[hit_rate, mrr], )它默认取[hit_rate, mrr]两个指标按检索器名称分组后计算每个指标的均值输出一张检索器 × 指标的对比表是排查检索回归的利器。注意该函数依赖pandas需先pip install pandas。五、一个完整的端到端示例把前面所有环节串起来一个完整的检索评估流程如下import asyncio from llama_index.core import VectorStoreIndex, SimpleDirectoryReader from llama_index.core.evaluation import ( RetrieverEvaluator, generate_question_context_pairs, get_retrieval_results_df, ) from llama_index.core.node_parser import SentenceSplitter # 1. 加载文档并切分节点 documents SimpleDirectoryReader(./data).load_data() splitter SentenceSplitter(chunk_size512, chunk_overlap20) nodes splitter.get_nodes_from_documents(documents) # 2. 构建索引并取 retrievertop_k 与业务场景匹配 index VectorStoreIndex(nodes) retriever index.as_retriever(similarity_top_k3) # 3. 合成评估数据集每个 chunk 生成 2 个问题 qa_dataset generate_question_context_pairs(nodes, llmllm, num_questions_per_chunk2) # 4. 定义评估器并批量评估 retriever_evaluator RetrieverEvaluator.from_metric_names( [mrr, hit_rate, precision, recall, ndcg], retrieverretriever, ) eval_results asyncio.run(retriever_evaluator.aevaluate_dataset(qa_dataset)) # 5. 汇总查看 print(get_retrieval_results_df( names[my_retriever], results_arr[eval_results] ))替换 retriever 的构造方式换 embedding、调 top_k、接 reranker并重复第 4、5 步即可形成稳定的检索质量回归基线。六、实践建议与注意事项top_k 与指标口径一致precision、ndcg等指标对检索结果数量敏感评估时的similarity_top_k应与你线上实际使用的取值一致否则指标缺乏可比性。ground-truth 要可解释expected_ids必须对应语料中真实存在的节点 ID。使用generate_question_context_pairs时relevant_docs会自动记录每个问题对应的原始节点天然满足这一要求。多指标联合使用hit_rate高不代表排序好建议至少同时观察hit_rate与mrr必要时补充ndcg以兼顾是否命中与命中的排序位置。异步接口更高效在 Notebook 或异步应用中优先使用aevaluate/aevaluate_datasetevaluate内部也会通过asyncio_run运行异步逻辑适合在同步脚本里使用。数据集可持久化合成数据集生成通常需要调用 LLM成本不低。可把EmbeddingQAFinetuneDataset序列化保存供多次实验复用避免重复生成。多模态检索RetrieverEvaluator还提供MultiModalRetrieverEvaluator变体支持RetrievalEvalMode.TEXT与RetrievalEvalMode.IMAGE两种模态分别评估可用于图文混合检索场景。七、结语检索评估是把感觉还行变成数据说话的关键一步。LlamaIndex 的RetrieverEvaluator配合generate_question_context_pairs合成数据集与aevaluate_dataset批量评估构成了一条从数据准备、指标计算到结果对比的完整链路。相关的核心实现均可在仓库中直接查阅RetrieverEvaluator 实现、评估基类与结果对象、内置指标与注册表以及数据集生成与结果汇总工具与 notebook_utils.py。以本文为起点为你的 RAG 系统建立一套可重复、可量化的检索质量基线吧。【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考