总目录
[第 1 章] 你的 RAG 为什么总在「一本正经地胡说」
[第 2 章] 一张图看懂 RAGAS：核心概念与 7 大指标
[第 3 章] 数据构建——样本、数据集与模型接入
[第 4 章] Faithfulness、Context Recall…RAGAS 核心指标怎么算
[第 5 章] 生成侧指标与指标选型：别再乱用 Faithfulness
[第 6 章] 把指标真正跑起来：执行、质控与回归闸门
[第 7 章] 没标注数据？用 RAGAS 自动合成测试集
[第 8 章] 让评估贯穿研发：实验追踪与 @experiment/Dataset 工作流
[第 9 章] 从笔记本到 CI：把 RAGAS 做成生产级流水线
[第 10 章] 内置不够用？手搓 RAGAS 自定义指标（含 SQL/MultiHop）
[第 11 章] RAGAS 不是唯一：6 大评估工具横向对比（功能篇）
[第 12 章] 怎么选？不同团队画像的选型决策矩阵
[第 13 章] 团队落地 RAGAS 的五阶段路线图（可直接抄作业）
在上一篇文章《3 步把 RAG 输出变成可评估数据集（附代码）》中，我们跑通了从真实 RAG 输出到分数的最小闭环，用SingleTurnSample/EvaluationDataset把数据组织起来。接下来，我们逐一拆解 RAGAS 的核心指标——先从检索侧（Faithfulness、Context Recall 等）说起。
本章定位：在第 2 章"指标全景"与第 3 章"跑通第一个评估"的基础上，逐一拆解 RAGAS 的核心指标。每个指标都按测什么 → 怎么算 → 代码怎么跑 → 怎么解读四步展开，让你既能读懂分数，也能知道"分低了去改哪一段"。
前置章节：第 1–3 章（已学完 RAGAS 是什么、reference-free 思想、数据流与最小可运行评估）。
运行依赖：ragas==0.4.3、openai（建议 Python ≥ 3.9）。约定（呼应第 2 章）：
- 事实：标注客观、可通过官方文档/源码与实测验证的陈述（API 行为、输入字段、分数区间等）。
- 观点：标注主观建议（选型、阈值、改进方向），请在你的团队/业务里自行校准。
- 全章代码示例统一使用collections 类式 API，并以
print(result.value)取MetricResult的分数。
4.1 指标体系总览（呼应第 2 章全景）
第 2 章把指标按"它在评估系统的哪一段"分成了检索侧与生成侧。本章就沿着这条线，把每个指标拆开讲透。先给一张"带输入与是否需参考"的速查表，作为全章地图。
事实：下表"是否需要 reference"由指标的输入字段决定——需要reference（标准答案/参考文本）的指标，离线有黄金集才能算；不需要的（reference-free）可在生产流量上直接跑。
| 指标 | 所属侧 | 是否需要 reference | 关键输入 | 分数方向 |
|---|---|---|---|---|
| Context Precision（含 with_reference） | 检索 | 是（with_reference） | user_input,reference,retrieved_contexts | 越大越好 |
| Context Recall | 检索 | 是 | user_input,reference,retrieved_contexts | 越大越好 |
| Context Entities Recall | 检索 | 是 | reference,retrieved_contexts | 越大越好 |
| Noise Sensitivity（噪声敏感度） | 检索 | 是 | user_input,response,reference,retrieved_contexts | 越小越好 |
| Response Relevancy | 检索（相关性闸门） | 否 | user_input,response | 越大越好 |
| ContextUtilization（上下文利用率） | 检索 | 否 | user_input,response,retrieved_contexts | 越大越好 |
| Faithfulness（忠实度） | 生成 | 否 | user_input,response,retrieved_contexts | 越大越好 |
| Answer Relevancy（答案相关性） | 生成 | 否 | user_input,response | 越大越好 |
观点：把"是否需要 reference"当成你选型的第一道筛子。离线有黄金集（CI 门禁）就优先用 reference 类指标拿绝对值；线上无标注流量则用 reference-free 指标（Faithfulness、ContextUtilization、Response/Answer Relevancy）做回归监控。详见 4.4。
哪些是 reference-free（无参考）？明确标注：
- 检索侧 reference-free：
ContextUtilization、Response Relevancy。 - 生成侧 reference-free：
Faithfulness、Answer Relevancy。 - 必须带 reference：
Context Precision（with_reference 形态）、Context Recall、Context Entities Recall、Noise Sensitivity。
事实：上述归属来自 v0.4.3 各指标
ascore()的必需入参（见官方迁移指南与指标文档，链接见 4.7）。其中Context Precision的"无参考形态"即ContextUtilization（见 4.2.6），Context Recall不存在无参考形态（见 4.2.2）。
本节小结
- 指标按"检索侧/生成侧"划分；检索侧看"召回的上下文好不好"，生成侧看"基于上下文生成的答案好不好"。
- 选型第一步先分清reference-free vs 需要 reference；前者可上生产，后者宜进离线黄金集。
- 注意方向陷阱：
Noise Sensitivity是"越小越好"，其余指标均"越大越好"。
4.2 检索侧指标
检索侧回答一个问题：“召回的上下文本身质量如何，以及它有没有把答案带偏？”
下面 6 个指标每个都按"测什么 / 怎么算 / 代码怎么跑 / 怎么解读"展开。先放一段公共环境准备，后续每个示例都假设已执行它（保证每个片段可独立粘贴运行）。
# 环境准备（ragas==0.4.3, openai）# ——只需执行一次fromopenaiimportOpenAIfromragas.llmsimportllm_factoryfromragas.embeddings.baseimport(embedding_factory,)fromragas.metrics.collectionsimport(ContextPrecision,ContextRecall,ContextEntityRecall,NoiseSensitivity,ContextUtilization,AnswerRelevancy,Faithfulness,)client=(OpenAI())# 同步客户端，配合 .score()llm=llm_factory("gpt-4o-mini",client=client)# 裁判 LLM# 仅 AnswerRelevancy 需要embeddings=embedding_factory("openai",model="text-embedding-3-small",client=client,)事实：
llm_factory是 v0.4 推荐的模型注入方式，会从模型名推断厂商；embedding_factory同步注入 Embedding。两者均来自 collections API。
版本说明：evaluate()（legacy）在 v0.4.3 会触发DeprecationWarning，官方对"何时移除"表述不一（指标文档曾写 v1.0，迁移指南写"未来版本"）——以你实际安装的版本实测为准。ragas.metrics小写单例（如ragas.metrics.faithfulness）官方明确计划在v1.0 移除，新代码请用ragas.metrics.collections。
4.2.1 Context Precision（上下文精确率，含 with_reference 变体）
测什么
衡量"召回的上下文里，到底有多少对回答问题真的有用"，并且对排序敏感——排在前面的相关上下文越多，分数越高。它判断的是"检索的精确率（precision）"。
怎么算
事实：在 collections API 中，ContextPrecision是ContextPrecisionWithReference的别名（默认即"带参考"形态）。算法让 LLM 逐条判断"这个上下文是否对得出 reference 答案有用"，得到 verdict 序列[1,0,1,...]，再算平均精度（Average Precision）：
AP = Σ_k (Precision@k × rel_k) / (相关上下文总数)其中rel_k为第 k 个上下文是否有用（1/0）。相关上下文排得越靠前，Precision@k越高，总分越高。
代码怎么跑
scorer=ContextPrecision(llm=llm)# 默认即 with_reference 形态result=scorer.score(user_input="埃菲尔铁塔位于哪里？",reference=("埃菲尔铁塔位于法""国巴黎。"),retrieved_contexts=["埃菲尔铁塔位于法国巴黎。","勃兰登堡门位于德国柏林。",],)print(result.value)with_reference 变体说明（事实）：
ContextPrecision=ContextPrecisionWithReference，必须传reference。它的"无参考"孪生兄弟是ContextUtilization（=ContextPrecisionWithoutReference，见 4.2.6），后者把"对照物"从 reference 换成生成的response，因此不需要 reference。两者导入写法：
fromragas.metrics.collectionsimport(ContextPrecision,)# 带参考fromragas.metrics.collectionsimport(ContextUtilization,)# 无参考（对照 response）怎么解读
- 分数高：相关上下文排在前面、噪声少 → 检索/重排质量好。
- 分数低：要么召回了大量无关上下文，要么相关项被埋在后面 → 优先检查召回策略、重排器、chunk 切分。
- 观点：它是"检索精确率"的代理指标，适合在离线黄金集上衡量"检索是否干净"；线上无 reference 时改用
ContextUtilization。
4.2.2 Context Recall（上下文召回率，含 with_reference 变体）
测什么
衡量"回答所需的事实，是否都被召回了"——即检索的召回率（recall）。它关心"该找的有没有找全"，与 4.2.1 的"找得准不准"互补。
怎么算
事实：算法把reference拆成若干陈述句，逐句判断是否能被至少一段retrieved_contexts支撑，得到[1,0,1,...]，分数 = 被支撑句数 / 总句数：
Context Recall = Σ(被支撑的陈述) / (reference 总陈述数)代码怎么跑
scorer=ContextRecall(llm=llm)result=scorer.score(user_input="埃菲尔铁塔位于哪里？",reference=("埃菲尔铁塔位于法""国巴黎。它建于 ""1889 年。"),retrieved_contexts=["埃菲尔铁塔位于法国巴黎。","勃兰登堡门位于德国柏林。",],)print(result.value)with_reference 变体说明（事实）：
Context Recall在 RAGAS 中只存在"带参考"形态——reference是必需输入，因为它要拿 reference 做拆分与归因。换言之，它没有无参考（without_reference）变体，这是它与Context Precision（有 with/without 两种）在设计上的关键区别。如果你只有线上流量、没有标准答案，就无法直接计算 Context Recall，应改用ContextUtilization或Faithfulness。
怎么解读
- 分数高：reference 里的关键事实基本都被检索命中 → 召回覆盖充分。
- 分数低：大量事实没被召回（漏检）→ 优先扩召回：混合检索、query 改写、放宽 top-k、补索引。
- 观点：Precision 与 Recall 通常是trade-off。改进时别只盯一个：把 Context Precision 拉满却牺牲 Recall，答案是"干净但答不全"。建议两个一起看（见 4.4 选型）。
4.2.3 Context Entities Recall（关键实体召回率）
测什么
衡量"reference 里出现的关键命名实体（人、地、机构、术语等），有多大比例出现在召回的上下文中"。它是 Context Recall 的"实体粒度"补充，对实体密集的问答（如医疗、法律、金融）尤其敏感。
怎么算
事实：先从reference中抽取实体集合，再判断每个实体是否出现在retrieved_contexts（通常结合精确/语义匹配），分数 = 命中的实体数 / reference 实体总数。注意它只需要reference与retrieved_contexts，不需要user_input/response。
代码怎么跑
scorer=ContextEntityRecall(llm=llm)result=scorer.score(reference=("OpenAI 于 2015 ""年在旧金山成立，""由 Sam Altman ""等人创办。"),retrieved_contexts=[("OpenAI ""是一家人工智能公司，""总部位于旧金山。"),("Sam Altman 是 ""OpenAI ""的联合创始人之一。"),],)print(result.value)怎么解读
- 分数高：关键实体基本被召回 → 检索在"抓重点对象"上表现好。
- 分数低：reference 里的核心实体没被检索到 → 可能 entity 相关文档未被索引，或 chunk 没覆盖到实体出现处。
- 观点：当你的业务"答错一个实体就出大事"（如用药剂量、法律条款主体）时，把它和 Context Recall 一起纳入门禁，比单看 Context Recall 更稳。
4.2.4 Noise Sensitivity（噪声敏感度）
测什么
衡量"当检索结果里混入了无关上下文时，生成答案是否被带偏、产生错误声明"。它专门测系统的抗噪鲁棒性。
怎么算
事实：对response中的每条声明，判断它（a）相对reference是否正确、（b）能否归因到相关/无关上下文。默认mode="relevant"时：
noise sensitivity(相关) = (response 中错误声明的总数) / (response 中声明的总数)分数范围0–1，越小越好（注意方向！）。还支持mode="irrelevant"，改测"在无关上下文干扰下是否仍出错"。
代码怎么跑
scorer=NoiseSensitivity(llm=llm)# 默认 mode="relevant"# scorer = NoiseSensitivity(llm=llm,# mode="irrelevant")result=scorer.score(user_input=("印度人寿保险公司""（LIC）""以什么闻名？"),response=("LIC ""是印度最大的保险公司，""以庞大的投资组合闻名，""并为国家金融稳定""做出贡献。"),reference=("LIC ""是印度最大的保险公司，""成立于 1956 年，""以管理庞大投资组合闻名""。"),retrieved_contexts=["LIC 成立于 1956 年。",("LIC ""是印度最大的保险公司，""拥有庞大的保单网络与投""资。"),("LIC ""管理巨额资金，""贡献国家金融稳定。"),("印度经济是增长最""快的主要经济体之""一。"),# 噪声],)print(result.value)怎么解读
- 分数低（接近 0）：即使混入噪声，答案仍基本正确 → 抗噪好。
- 分数高：噪声让模型产生了错误声明 → 脆弱，需加强重排/过滤、或在生成侧加"仅依据给定上下文作答"的约束。
- 观点：这是少数"越小越好"的指标，也是 4.5 要讲的"高分≠好"陷阱的典型反例——别把它和其他指标一起求平均时忘了取反。建议把它单列监控。
4.2.5 Response Relevancy（回答相关性，检索侧视角）
测什么
衡量"生成的回答是否紧扣原始问题"。事实：在 RAGAS 文档中，该指标亦称Response Relevancy，其 collections 实现类就是AnswerRelevancy（见 4.3.2）。第 2 章把它列在检索侧，是因为它常被用作"检索→生成链路上的相关性闸门"——召回的上下文是否足以支撑一个切题的回答。它不需要 reference，属于 reference-free。
怎么算
事实：让 LLM 从response逆向生成 N 个问题（默认 3，由strictness控制），计算"原始user_input的 embedding"与"各生成问题的 embedding"之间的余弦相似度均值：
Answer Relevancy = mean( cosine_sim(E_原始问题, E_生成问题_i) )只衡量"切题"，不衡量事实对错（事实对错看 Faithfulness）。
代码怎么跑
scorer=AnswerRelevancy(llm=llm,embeddings=embeddings)# 需注入 embeddingsresult=scorer.score(user_input=("第一届超级碗是什""么时候举行的？"),response=("第一届超级碗于 ""1967 年 1 月 15 ""日举行。"),)print(result.value)事实：该指标只吃
user_input与response（外加一个 Embedding 组件），不接收reference，因此可纯线上运行。分数范围通常 0–1（但余弦相似度数学上可达 -1~1，极端情况未必严格落在 0–1）。
怎么解读
- 分数高：回答切题、没有跑题或答非所问。
- 分数低：回答空洞、偏离问题，或只覆盖了问题的一个侧面 → 检查问题理解/检索是否命中了正确意图。
- 观点：把它放在检索侧，是为了用"回答是否切题"反向校验"检索是否把对的内容喂进来了"。若检索侧 Context Precision 高、但 Response Relevancy 低，往往是生成/问题理解环节的问题，而非检索。
4.2.6 ContextUtilization（上下文利用率）——必补指标
测什么
衡量"召回的上下文中，有多少真正被生成的回答用到了"。它是ContextPrecisionWithoutReference的现代别名，不需要 reference，只用response做对照。第 2 章指标全景把它列为检索侧第 6 个指标，这里补全。
怎么算
事实：ContextUtilization是ContextPrecisionWithoutReference的包装别名（name="context_utilization"）。与 4.2.1 的ContextPrecision（对照reference）不同，它把"对照物"换成生成的response：逐条判断"这个上下文是否对生成该response有用"，再算平均精度（AP）。因此它是reference-free的"上下文有用性"指标。
ContextUtilization = AP( 逐上下文是否有用于生成 response )代码怎么跑
scorer=ContextUtilization(llm=llm)# = ContextPrecisionWithoutReferenceresult=scorer.score(user_input="埃菲尔铁塔位于哪里？",response="埃菲尔铁塔位于法国巴黎。",retrieved_contexts=["埃菲尔铁塔位于法国巴黎。",("勃兰登堡门位于德""国柏林。"),# 无关，应被降权],)print(result.value)事实：导入写法
from ragas.metrics.collections import ContextUtilization；等价地也可写from ragas.metrics.collections import ContextPrecisionWithoutReference。两者在 v0.4.3 行为一致（迁移指南明确 ContextUtilization 现在是后者的兼容包装）。
怎么解读
- 分数高：回答几乎用到了召回的大部分上下文 → 检索"召得准且用得上"，冗余少。
- 分数低：召回了大量但回答根本没用到的上下文 → 检索噪声大、或生成时没善用上下文。可与
Noise Sensitivity、Context Precision联动看。 - 观点：当你没有标准答案、又想评估"检索质量"时，
ContextUtilization是Context Precision的最佳无参考替代；它和第 2 章"reference-free 评估"的初衷最契合。
4.2 检索侧小结
- 检索侧 6 指标覆盖：精确率（Context Precision）、召回率（Context Recall、Entities Recall）、抗噪（Noise Sensitivity）、相关性闸门（Response Relevancy）、无参考有用性（ContextUtilization）。
- 需要 reference：
Context Precision(with_reference)、Context Recall、Context Entities Recall、Noise Sensitivity。 - 不需要 reference：
ContextUtilization、Response Relevancy——可上生产。 - 方向唯一反例：
Noise Sensitivity越小越好，别在汇总时误当"越大越好"。
前一章：《3 步把 RAG 输出变成可评估数据集（附代码）》
后一章：生成侧指标与指标选型：别再乱用 Faithfulness
