企业官网建设流程全解析

LlamaIndex 评估模块全解析：Response Evaluation 与 Retrieval Evaluation 实战指南

【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index

本指南以 LlamaIndex 官方文档中 评估模块索引页 为骨架，系统梳理"响应评估（Response Evaluation）"与"检索评估（Retrieval Evaluation）"两大模块的完整组件清单、核心评估器实现原理、度量指标算法，以及仓库内配套的可运行 Notebook 资源。阅读完本文，你将掌握每个评估器的适用场景、底层调用链与批量评估方法，能够直接在 RAG 应用中落地质量评估体系。

一、评估模块总览：两大维度

LlamaIndex 将评估能力划分为两个层面，对应 modules.md 中的两大分类：

• Response Evaluation（响应评估）：面向"查询 → 检索上下文 → 生成回答"的完整链路，判断生成的答案是否忠实于上下文、是否与查询相关、是否正确、是否违反给定准则等；
• Retrieval Evaluation（检索评估）：仅面向检索环节，衡量检索器返回的候选文档是否命中预期文档，以及命中文档的排序质量。

所有评估组件均建立在 base.py 定义的抽象基类之上：BaseEvaluator提供同步evaluate()与异步aevaluate()两套接口，并内置evaluate_response()方法，可将Response对象自动拆解为响应字符串与上下文列表（contexts = [node.get_content() for node in response.source_nodes]）后交给底层aevaluate。评估结果统一封装为EvaluationResult模型，字段包括query、contexts、response、passing（布尔通过标记）、feedback（推理过程）、score（0~1 或 1~5 分数）等。

所有评估器类的导出入口集中在 evaluation/init.py，可通过from llama_index.core.evaluation import ...直接导入。

二、Response Evaluation：响应评估组件详解

以下 13 个评估组件对应 modules.md 中 Response Evaluation 小节的全部条目，每个组件都有配套的 Jupyter Notebook 示例，位于 docs/examples/evaluation 目录。

2.1 Faithfulness：忠实度评估

示例 Notebook：faithfulness_eval.ipynb

忠实度评估回答的问题是："生成的回答是否被检索到的上下文所支持？" 即检测回答是否存在幻觉（hallucination）。实现位于 faithfulness.py：

• 核心类FaithfulnessEvaluator只依赖响应字符串与上下文字符串列表；
• 底层实现将每个上下文包装为Document，构建SummaryIndex，然后用text_qa_template（评估模板）与refine_template（精炼模板）驱动 LLM 对"信息是否被上下文支持"做YES/NO判定；
• 默认评估模板DEFAULT_EVAL_TEMPLATE要求 LLM"只要上下文的任何一部分支持该信息就回答 YES"；默认精炼模板DEFAULT_REFINE_TEMPLATE支持多段上下文的分段验证与结果精炼；
• 源码内置了面向llama3:8b的优化模板LLAMA3_8B_EVAL_TEMPLATE，并通过TEMPLATES_CATALOG根据 LLM 的model_name自动选择（见 faithfulness.py）；
• 判定逻辑：响应文本中出现yes（忽略大小写）则passing=True、score=1.0，否则为 0.0；若设置raise_error=True且不通过，则直接抛出ValueError。

核心参数：

2.2 Relevancy：相关性评估

示例 Notebook：relevancy_eval.ipynb

相关性评估判断"响应是否与查询及检索上下文保持一致"，实现位于 relevancy.py。其DEFAULT_EVAL_TEMPLATE将"问题 + 响应"拼接为Query and Response，要求 LLM 判断其与Context是否一致并回答 YES/NO。与忠实度评估不同，它同时考察查询与回答的联合相关性，因此aevaluate()要求query、contexts、response三者都必须提供，缺一即抛ValueError。

RelevancyEvaluator同样基于SummaryIndex+text_qa_template/refine_template实现，并保留旧别名QueryResponseEvaluator以兼容历史版本。

2.3 Answer and Context Relevancy：答案与上下文双重相关性

示例 Notebook：answer_and_context_relevancy.ipynb

该 Notebook 演示将两类相关性评估组合使用：

• Answer Relevancy：由 answer_relevancy.py 中的AnswerRelevancyEvaluator提供，评估生成的答案与查询问题的相关程度；
• Context Relevancy：由 context_relevancy.py 中的ContextRelevancyEvaluator提供，评估检索到的上下文是否与查询相关。

两者均输出EvaluationResult，通过passing、score与feedback字段给出量化结论，可用于分别定位"检索召回不佳"与"生成跑题"两类问题。

2.4 Guideline Eval：准则遵循评估

示例 Notebook：guideline_eval.ipynb

GuidelineEvaluator实现位于 guideline.py，用于评估回答是否遵守自定义的业务准则（如"回答必须以积极语气""不得包含财务建议"）。它接收一个guidelines字符串参数，将准则注入评估提示词，由 LLM 判断响应是否符合全部准则并给出 YES/NO 结论，适合为特定领域的 RAG 系统配置"红线规则"。

2.5 Correctness Eval：正确性评估

示例 Notebook：correctness_eval.ipynb

CorrectnessEvaluator实现位于 correctness.py，用于判断生成答案是否与**参考答案（reference answer）**一致。其特点：

• 采用 1~5 分制评分（1 最差、5 最佳）：与查询无关得 1 分；相关但有错误得 2~3 分；相关且完全正确得 4~5 分；
• 通过DEFAULT_EVAL_TEMPLATE（系统模板 + 用户模板的ChatPromptTemplate）要求 LLM"仅输出一行分数，另起一行给出评分理由"；
• passing定义为分数不低于给定阈值（score >= threshold）；
• 评估时必须额外提供reference参数（参考答案），源码要求"query、response、reference 均不可缺失"。

2.6 Semantic Eval：语义相似度评估

示例 Notebook：semantic_similarity_eval.ipynb

SemanticSimilarityEvaluator实现位于 semantic_similarity.py。它不依赖 LLM 的评判式回答，而是通过嵌入向量计算语义相似度：将生成答案与参考答案分别编码，计算余弦相似度作为score，并通过threshold参数判定passing。该评估器适合快速、低成本的批量回归测试，默认使用全局Settings.embed_model，也可传入自定义embed_model。

2.7 Question Generation：评估数据集生成

示例 Notebook：QuestionGeneration.ipynb

DatasetGenerator与QueryResponseDataset实现位于 dataset_generation.py。其核心价值在于没有标注数据也能启动评估：给定一组文档节点，它利用 LLM 自动生成"查询—回答"对，产出可供各评估器消费的评估数据集。典型流程为：

1. 用DatasetGenerator.from_documents()从文档生成节点，指定num_questions_per_chunk等参数；
2. 调用generate_dataset_from_nodes()得到QueryResponseDataset；
3. 通过qr_pairs属性取出 (query, reference_response) 对，喂给评估器或BatchEvalRunner。

2.8 Batch Eval：批量并行评估

示例 Notebook：batch_eval.ipynb

BatchEvalRunner实现位于 batch_runner.py，是生产环境最常用的评估编排工具：

• 构造参数：evaluators（评估器名字到实例的字典）、workers（并发数，默认 2）、show_progress（是否显示进度条）；
• 三种入口方法，且均有同步/异步双版本：
  • evaluate_response_strs/aevaluate_response_strs：直接喂查询、响应字符串与上下文列表；
  • evaluate_responses/aevaluate_responses：喂查询与Response对象；
  • evaluate_queries/aevaluate_queries：传入QueryEngine与查询列表，自动先执行查询再评估；
• 返回结构为Dict[str, List[EvaluationResult]]，按评估器名称分组；
• 源码内部通过asyncio.Semaphore(workers)控制并发，并为每个 worker 任务附加 tenacity 重试装饰器（最多重试 3 次、指数退避等待），提升大规模评估的稳定性（见 batch_runner.py）；
• 支持eval_kwargs_lists为不同评估器传入不同的额外参数（如references列表）。

2.9 Multi-Modal RAG Evaluation：多模态 RAG 评估

示例 Notebook：multi_modal_rag_evaluation.ipynb

多模态评估的评估器实现位于 multi_modal 目录，包含faithfulness.py与relevancy.py两个文件，即把忠实度与相关性评估扩展到图像 + 文本混合检索场景。配套 Notebook 演示了如何对多模态 RAG 流水线的检索与生成质量进行端到端评估。

2.10~2.12 第三方评估集成：Deepeval、UpTrain 与 RAGChecker

示例 Notebook：Deepeval.ipynb、UpTrain.ipynb、RAGChecker.ipynb

• Deepeval Integration：接入 DeepEval 的评估体系，在 LlamaIndex 的BaseEvaluator框架内复用 DeepEval 的断言与指标；
• Uptrain Integration：接入 UpTrain 平台，利用其云端/本地评估器对 RAG 链路进行监控式评估；
• RAGChecker Integration：接入 RAGChecker 的诊断能力，对检索与生成全链路给出细粒度检查报告。

这三个 Notebook 均位于 docs/examples/evaluation 目录，展示了评估器与第三方质量平台的对接方式，适合已选用相关监控工具的生产团队参考。

2.13 Cleanlab：数据质量评估

示例 Notebook：Cleanlab.ipynb

Cleanlab 集成聚焦于评估数据本身的质量：利用置信学习（confident learning）方法检测评估数据集中标签错误或低质量样本，帮助团队在评估前先清洗数据，避免脏数据污染评估结论。

2.14 补充：Pairwise Comparison（成对比较）

虽未单列于索引页，但仓库中还内置了PairwiseComparisonEvaluator（见 pairwise.py），用于对两个候选回答做相对优劣排序，相关 Notebook 为 pairwise_eval.ipynb。其EvaluationResult会额外携带pairwise_source字段，记录比较顺序是否被翻转，从而抵消位置偏差。

三、Retrieval Evaluation：检索评估详解

3.1 Retriever Eval 核心实现

示例 Notebook：retriever_eval.ipynb

检索评估不关心生成答案，只评估"检索器是否召回预期文档"。核心组件位于 retrieval 目录：

• RetrieverEvaluator（evaluator.py）：包装任意BaseRetriever，可附加node_postprocessors（重排器等后处理器）参与评估链路；评估时调用retriever.aretrieve(query)得到检索节点，再提取node_id与文本；
• MultiModalRetrieverEvaluator：同一文件中针对多模态检索的变体，可按text或image模式分别统计文本节点与图像节点的命中情况；
• 基类BaseRetrievalEvaluator与RetrievalEvalResult位于 retrieval/base.py。

3.2 检索度量指标：从 HitRate 到 NDCG

所有度量指标实现于 retrieval/metrics.py，均以"预期文档 ID 集合 vs 检索文档 ID 有序列表"为输入：

通过resolve_metrics(["hit_rate", "mrr", ...])（metrics.py）可按名称解析指标类列表，METRIC_REGISTRY中注册了全部内置指标。Notebook 中还演示了get_retrieval_results_df（见 notebook_utils.py）将多次评估结果整理为 DataFrame 的用法。

3.3 配套实验数据

检索评估 Notebook 使用 docs/examples/evaluation/test_wiki_data 目录下的纽约市（NYC）文本作为测试语料，你可以直接复用该数据验证自己的检索器与指标计算。

四、实战：组装一套完整的 RAG 评估流水线

综合以上模块，一个典型的评估流程可以按如下步骤组织（所有类均从llama_index.core.evaluation导入）：

from llama_index.core.evaluation import ( DatasetGenerator, # 步骤 1：自动生成评估数据 FaithfulnessEvaluator, # 步骤 2：忠实度 RelevancyEvaluator, # 步骤 2：相关性 CorrectnessEvaluator, # 步骤 2：正确性（需 reference） BatchEvalRunner, # 步骤 3：批量并行 ) from llama_index.core.evaluation.retrieval import RetrieverEvaluator, resolve_metrics # 1. 从文档生成 (query, reference) 评估集 dataset_generator = DatasetGenerator.from_documents(documents) qr_pairs = dataset_generator.generate_dataset_from_nodes() # 2. 注册多个评估器 evaluators = { "faithfulness": FaithfulnessEvaluator(), "relevancy": RelevancyEvaluator(), } # 3. 批量并发评估（自动附带重试与并发控制） runner = BatchEvalRunner(evaluators, workers=4, show_progress=True) results = runner.evaluate_response_strs( queries=[q for q, _ in qr_pairs], response_strs=[r for _, r in qr_pairs], ) # 4. 检索评估：用 HitRate + MRR 度量检索质量 retriever_evaluator = RetrieverEvaluator.from_metric_names( ["hit_rate", "mrr"], retriever=my_retriever ) eval_result = await retriever_evaluator.aevaluate( query="...", expected_ids=expected_node_ids )

五、进一步探索

• 评估模块完整源码：llama-index-core/llama_index/core/evaluation/（核心评估器、batch_runner.py、dataset_generation.py、retrieval/子目录）
• 全部评估示例 Notebook：docs/examples/evaluation（响应评估）与 docs/examples/evaluation/retrieval/retriever_eval.ipynb（检索评估）
• 其余进阶示例（AIMon、BEIR、HotpotQA、RetryQuery、Tonic Validate、mt_bench 等）同样位于该目录，可结合 evaluation/init.py 中导出的类清单按图索骥

评估是 RAG 系统迭代的"仪表盘"：用FaithfulnessEvaluator守住幻觉底线，用RelevancyEvaluator把关相关性，用RetrieverEvaluator的 HitRate/MRR/NDCG 量化检索质量，再借BatchEvalRunner把以上指标沉淀为每次改动后的回归报告——这就是 LlamaIndex 评估模块为你准备好的完整工具箱。

【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index