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

本指南以 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。

核心参数：

参数	默认值	说明
llm	Settings.llm	用于评估的 LLM，缺省时读取全局设置
raise_error	False	评估不通过时是否抛异常
eval_template	内置默认模板	可传入字符串或 BasePromptTemplate 自定义
refine_template	内置默认模板	分段上下文精炼判定模板

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 有序列表"为输入：

指标	metric_name	计算逻辑
HitRate	hit_rate	默认：任一检索文档命中预期集合即记 1 分；use_granular_hit_rate=True 时按命中数/预期文档数给出细粒度比例
MRR	mrr	默认：第一个命中文档排名的倒数；use_granular_mrr=True 时对全部命中排名倒数求和后按相关文档数取均值
Precision	precision	检索结果中命中数 / 检索结果总数（对应 Precision@K，K 为检索器 top_k）
Recall	recall	检索结果中命中数 / 预期文档总数
AveragePrecision	ap	逐位累计精确率并按预期文档数归一化
NDCG	ndcg	折损累计增益，支持 linear 与 exponential 两种折损模式，位置 p 取检索结果规模
CohereRerankRelevancyMetric	cohere_rerank_relevancy	调用 Cohere 重排 API 对检索文本打分，支持 max/median/mean 聚合

通过 resolve_metrics(<a href="https://link.gitcode.com/i/ba06fcc75cb929ee636d7b9dfbcbe595" target="_blank">"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 评估模块为你准备好的完整工具箱。