总目录[第 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 的五阶段路线图可直接抄作业在上一篇文章《没标注数据用 RAGAS 自动合成测试集》中我们用TestsetGenerator为知识库产出第一批自动测试集。接下来把评估嵌进研发迭代流——实验追踪与experiment工作流让每次改动都可对比、可回溯。本章定位前 6 章你已经会把一次评估跑通构建数据、选指标、读分数、合成测试集。但真实研发里评估不是跑一次就完事——你改 prompt、换 Embedding、调检索参数每次都要重跑、和基线对比、留档可回溯。本章带你把评估嵌进研发迭代流认识为什么需要实验追踪、认识新一代Dataset与experiment工作流以及与 legacyEvaluationDataset的清晰边界最后用一个两次实验对比的最小可运行示例收尾。7.1 为什么需要实验追踪事实一个 RAG / LLM 应用不是一次成型就不动的。它会被反复修改——切分策略、检索器、prompt 模板、生成模型、后处理链任何一处改动都可能让质量变好或变坏。事实RAGAS 的指标是可重复计算的函数。给定同一批样本和同一组指标两次跑分在相同的随机性下结果应当可复现注裁判 LLM 本身存在采样温度跨次绝对一致需控温/固定种子这属于工程细节下文 7.5 会点到。观点我们认为评估只有嵌进迭代循环才有长期价值。一次性跑分只能回答今天还行不行持续追踪才能回答这次改动到底是变好还是变坏。为什么要专门做实验追踪把对照想清楚不做追踪一次性评估做追踪实验化评估只看到当前一次的分数能看到分数随改动的变化曲线改了系统说不清是变好还是变差每次改动都对应一条基线对比三个月后无法回答为什么现在分低了结果可归档、可回溯、可追责多版本并行A/B无从比较多实验元数据齐整可横向对比由此引出两个工程需求实验Experiment概念把一次评估运行变成一个带名字、带参数、带时间戳的对象而不是散落在 notebook 里的一串分数。版本管理样本集、指标配置、模型版本、得分都要能像代码一样被记录与对比。这就是experiment装饰器与新一代Dataset想解决的问题——它们把评估从一次性脚本升级成可管理的实验记录。但请记住这些仍是 v0.4 演进期的 API是否适合作为你团队的唯一真相源需要结合下面 7.2 的实测提示来判断。事实与观点区分上面关于指标可重复、系统会被反复修改是事实关于评估必须嵌进迭代流才有价值是方法论观点你完全可以根据团队规模与节奏取舍。7.2 experiment 装饰器的工作方式与价值⚠️ 实测为准重要本节涉及的experiment装饰器来自ragas.experimental命名空间。在v0.4.3中它属于**实验性experimental**能力具体可用性请以你实际安装的版本实测为准——不要默认它在你的环境里确定可用 / 已稳定。若官方文档描述与你的实测结果冲突以实测为准并在团队内注明你实测到的行为。它想解决什么设计意图experiment的设想是用一个装饰器把一次评估运行自动登记为一个实验记录。你给被装饰的函数加上元数据实验名、参数、版本函数执行时框架帮你把输入样本、配置与产出的分数关联起来形成一条可对比、可归档的记录。它的潜在价值设计目标非已验证事实声明式用experiment(name..., ...)一行标注而非手动写日志可追溯每次运行附带元数据包模型版本、prompt 版本、样本集版本可对比框架层保留实验列表理论上可在两次运行间做差分。它可能长什么样示意非承诺下面是一段按官方示例风格还原的写法。能否实际运行取决于你装的版本请先小样实测# 示意experiment 的设计形态。v0.4.# 3 实际可用性以实测为准。# 源ragas.experimental实验性命名空间# fromragas.experimentalimport(experiment,# ⚠️ 实测确认该 import 在你版本存# 在)experiment(namefaithfulness-baseline-v1)defrun_baseline():# 这里放你的评估逻辑准备样本 调# 用 collections 指标...returnscores resultrun_baseline()使用它的正确姿势建议先探测再依赖在目标环境先跑一段最小样例确认experiment的 import、参数与返回结构都符合预期再写进生产脚本。不要误以为一定可用它不在已稳定 GA的表述里。若你的流水线对可靠性要求高建议把实验记录落到你自己可控的存储JSON / 数据库 / MLflow而非只依赖装饰器内部状态。以实测为准记录差异如果文档示例和你跑出来的字段不一致请在代码注释里写明本环境实测到的行为避免后续维护者被过时文档误导。小结语气7.2 的全部价值描述都建立在设计意图 需实测之上。把它当成值得试的方向而不是必须照搬的规范。7.3 Datasetfrom ragas import Dataset新一代工作流事实Dataset来自from ragas import Dataset是 RAGAS 在 v0.4 推的新一代数据集抽象与第 2 章提到的 legacyEvaluationDataset是不同 API 层的不同类二者对照见 7.4。Dataset的设计取向是把样本集合与这次评估附带的元数据放在一起管理方便对接实验工作流包括 7.2 的experiment。它如何组织样本Dataset以结构化记录如字典列表承载样本并允许你附带metadata把这次跑的是什么、用的是哪个版本写进数据对象本身# v0.4.3 新一代 Dataset 工作流示意# 具体方法名以实测为准fromragasimportDataset records[{user_input:RAGAS 是什么,response:(RAGAS 是用于评估 RAG 系统的框架。),retrieved_contexts:[(RAGAS 是 RAG Assessment 的缩写用于自动评估检索增强生成。)],reference:(RAGAS 是用于评估检索增强生成RAG管道的框架。),},# ... 更多样本]dsDataset.from_list(records)# 构造数据集方法名以实测为准ds.metadata{# 挂实验元数据experiment:v1-baseline,generator_model:gpt-4o-mini,prompt_version:2026-09-01,}它如何挂实验元数据要点在于metadata是随Dataset一起流转的而不是散落在外部变量里。这样当你把ds交给指标/实验流程时这份分数对应哪次实验天然就带上了。版本说明Dataset.from_list、Dataset.metadata等具体签名在不同小版本可能微调。以你pip show ragas的版本 官方文档vibrantlabsai/ragas注1 为准先小样实测再大规模用。观点相比把样本写死在脚本里、把实验名写在注释里用Dataset把数据 元数据打包更利于后续做版本化与对比7.5。7.4 与 legacy EvaluationDatasetfrom ragas.dataset_schema的明确区分❗ 强制口径审稿 REVISE 第 1 条Dataset来自ragas与EvaluationDataset来自ragas.dataset_schema是两个不同 API 层、两个不同类。本章严禁把它们强行统一或暗示可互相替代。它们服务于不同工作流配套 API 也不同。对照表维度Dataset新一代EvaluationDatasetlegacyimport 来源from ragas import Datasetfrom ragas.dataset_schema import EvaluationDataset所属 API 层v0.4 新一代实验/评估工作流v0.4 之前沿用、与 legacyevaluate()配套样本单元结构化记录常与SingleTurnSample/MultiTurnSample概念对应SingleTurnSample/MultiTurnSample来自ragas.dataset_schema是否承载实验元数据设计上支持metadata字段主要承载样本字段实验元数据需外部管理配套跑分方式新一代Dataset/experiment流程实测为准legacyevaluate()v0.4.3 触发DeprecationWarning状态建议新工作流的推荐方向但 API 仍处演进期仍可用但属 legacy新代码优先评估新一代方案典型样本构造Dataset.from_list([...])方法名实测为准EvaluationDataset(samples[SingleTurnSample(...)])一段不要混用的对照代码# 新一代fromragasimportDataset dsDataset.from_list([{user_input:...,response:...,retrieved_contexts:[...],}])# legacyfromragas.dataset_schemaimport(SingleTurnSample,EvaluationDataset,)evEvaluationDataset(samples[SingleTurnSample(user_input...,response...,retrieved_contexts[...],)])# ❌ 错误认知认为 ds 与 ev 是同一个东# 西、能直接互换# ✅ 正确认知两者是不同类、# 不同 API 层各自走各自的配套流程。事实在 v0.4.3EvaluationDataset仍可配合 legacyevaluate()使用但evaluate()会触发DeprecationWarning详见 7.5 与版本说明。7.5 实验对比与版本化比较两次评估最直接、可控的做法自己把每次跑分结果存成结构化记录再做差分。这不依赖任何框架内部状态最稳# 思路示意把两次实验的分数落盘# 再做对比importjson runs{v1-baseline:{faithfulness:0.82,answer_relevancy:0.88,},v2-new-prompt:{faithfulness:0.90,answer_relevancy:0.91,},}delta{k:runs[v2-new-prompt][k]-runs[v1-baseline][k]forkinruns[v1-baseline]}print(delta# {faithfulness: 0.08,# answer_relevancy: 0.03})归档结果把每次运行连同元数据写进 JSON / CSV / 数据库形成实验档案archive{experiment:v2-new-prompt,timestamp:2026-09-27T10:00:00,generator_model:gpt-4o-mini,prompt_version:2026-09-01,scores:runs[v2-new-prompt],}withopen(experiments/v2-new-prompt.json,w,)asf:json.dump(archive,f,ensure_asciiFalse,indent2,)对接追踪后端点到为止RAGAS 的实验记录思路可与通用实验追踪后端对接LangSmithLangChain 生态的可观测/追踪平台docs注2把每次评估作为一次 trace / run 记录便于在 UI 里对比。MLflow开源实验追踪docs注3把指标记为log_metric把配置记为log_param天然支持实验对比与版本化。观点对于多数团队先把分数与元数据用你自己的存储JSON/DB稳定落盘比急于接重型后端更务实。等实验量上来、确实需要 UI 对比时再接 LangSmith / MLflow。本节只给思路不展开集成代码。版本说明v0.4.3 务必谨慎evaluate()legacy在 v0.4.3 会触发DeprecationWarning官方对何时移除表述不一指标文档曾写 v1.0迁移指南写未来版本。以实测为准。ragas.metrics小写单例如ragas.metrics.faithfulness官方明确计划v1.0 移除请勿在新代码依赖。推荐路线新代码用collections 类式 APIfrom ragas.metrics.collections import X显式注入llm/embeddings实验追踪用experiment实测为准或自管归档更稳。7.6 常见坑混用Dataset与EvaluationDataset二者是不同 API 层、不同类见 7.4。不要写ds EvaluationDataset(...)然后当Dataset用也不要假设它们的方法互通。需要哪一个按它自己的 import 与配套 API 来。误以为experiment一定可用 / 已稳定它来自ragas.experimental在 v0.4.3 属实验性。不要在关键流水线上无条件依赖先小样实测冲突时以实测为准并注明。仓库名写错官方仓库是vibrantlabsai/ragas旧镜像explodinggradients/ragas内容一致 / 旧路径引用旧资料时可见。写文档、贴链接、提 issue 时统一用新名避免他人 clone 到过期路径。依赖ragas.metrics小写单例如ragas.metrics.faithfulness这类小写单例官方明确v1.0 移除。新代码请用from ragas.metrics.collections import Faithfulness形式。忽略evaluate()的DeprecationWarningv0.4.3 下 legacyevaluate()会报警告移除版本表述不一。别假装没看见——先pip show ragas看版本再决定迁移节奏。把裁判 LLM 的随机性当系统变差跨次跑分若有细微浮动先排除温度/种子问题再下改动导致退化的结论见 7.1/7.5。7.7 实战演练最小可运行的两次实验对比目标从数据准备 → 挂实验 → 跑分 → 对比走通一条最小链路。示例同时演示新一代Dataset挂元数据与 legacyEvaluationDataset对照两种数据入口但跑分统一用稳定的 collections 类式 API实验记录用自管归档比依赖experiment内部状态更可控符合 7.5/7.6 建议。依赖与版本# 安装建议在虚拟环境 pip install ragas0.4.3 openai # 需要环境变量 export OPENAI_API_KEYsk-...完整代码 两次实验对比baseline vs 新 prompt - 数据入口分别演示 Dataset(新一代) 与 EvaluationDataset(legacy) 两种构造 - 跑分统一用 collections 类式 API稳定、显式注入 llm - 实验记录用自管归档不依赖 experiment 内部状态符合 7.5 建议 importosimportjsonfromopenaiimportOpenAIfromragas.llmsimportllm_factoryfromragas.metrics.collectionsimportFaithfulness,AnswerRelevancy# ---- 0) 注入裁判模型v0.4.3 现行写法 ----clientOpenAI(api_keyos.environ[OPENAI_API_KEY])llmllm_factory(gpt-4o-mini,clientclient)# ---- 1) 数据准备两个版本的 RAG 输出 ----# 实验 Abaseline 提示词下的回答records_v1[{user_input:RAGAS 是什么,response:RAGAS 是一个用于评估 RAG 系统的框架。,retrieved_contexts:[RAGAS 是 RAG Assessment 的缩写用于自动评估检索增强生成。],reference:RAGAS 是用于评估检索增强生成RAG管道的框架。,},{user_input:Faithfulness 衡量什么,response:它衡量回答是否忠实于上下文。,retrieved_contexts:[Faithfulness 衡量答案是否只陈述检索上下文中存在的内容用于抑制幻觉。],reference:Faithfulness 衡量答案对检索上下文的忠实程度。,},]# 实验 B换用带引用约束的新 prompt 后的回答假设整体更忠实、更切题records_v2[{user_input:RAGAS 是什么,response:(RAGASRetrieval Augmented Generation Assessment是一个用于自动化评估检索增强生成系统的框架论文见 arXiv:2309.15217。),retrieved_contexts:[RAGAS 是 RAG Assessment 的缩写用于自动评估检索增强生成。],reference:RAGAS 是用于评估检索增强生成RAG管道的框架。,},{user_input:Faithfulness 衡量什么,response:(Faithfulness忠实度衡量生成的答案是否只陈述检索上下文中存在的内容用来抑制模型幻觉。),retrieved_contexts:[Faithfulness 衡量答案是否只陈述检索上下文中存在的内容用于抑制幻觉。],reference:Faithfulness 衡量答案对检索上下文的忠实程度。,},]# ---- 2) 挂实验用新一代 Dataset 承载样本 元数据 ----fromragasimportDataset# 新一代工作流ds_v1Dataset.from_list(records_v1)# 方法名以实测为准ds_v1.metadata{experiment:v1-baseline,prompt_version:base}ds_v2Dataset.from_list(records_v2)ds_v2.metadata{experiment:v2-new-prompt,prompt_version:cite-aware}# 对照legacy 入口EvaluationDataset仅展示构造方式不强行与 Dataset 混用fromragas.dataset_schemaimportSingleTurnSample,EvaluationDataset ev_v1EvaluationDataset(samples[SingleTurnSample(user_inputr[user_input],responser[response],retrieved_contextsr[retrieved_contexts],referencer.get(reference),)forrinrecords_v1])# ---- 3) 跑分collections 类式 API稳定 ----defscore_dataset(records):faith,ans_relFaithfulness(llmllm),AnswerRelevancy(llmllm)f_scores,a_scores[],[]forrinrecords:rffaith.score(user_inputr[user_input],responser[response],retrieved_contextsr[retrieved_contexts],)raans_rel.score(user_inputr[user_input],responser[response],retrieved_contextsr[retrieved_contexts],)f_scores.append(rf.value)a_scores.append(ra.value)print(f[{r[user_input]}] faith{rf.value:.2f}| reason{rf.reason})return{faithfulness:sum(f_scores)/len(f_scores),answer_relevancy:sum(a_scores)/len(a_scores),}print( 实验 A: v1-baseline )scores_v1score_dataset(records_v1)print(\n 实验 B: v2-new-prompt )scores_v2score_dataset(records_v2)# ---- 4) 对比 归档 ----delta{k:round(scores_v2[k]-scores_v1[k],3)forkinscores_v1}print(\n 对比v2 - v1)print(delta)archive{v1-baseline:{**ds_v1.metadata,scores:scores_v1},v2-new-prompt:{**ds_v2.metadata,scores:scores_v2},delta:delta,}os.makedirs(experiments,exist_okTrue)withopen(experiments/compare.json,w)asf:json.dump(archive,f,ensure_asciiFalse,indent2)print(\n已归档到 experiments/compare.json)输出解读示意实际数值取决于裁判模型 实验 A: v1-baseline [RAGAS 是什么] faith0.85 | reason回答中的内容均能在上下文中找到依 据。 [Faithfulness 衡量什么] faith0.80 | reason基本忠实但忠实于上下文表述略 宽泛。 实验 B: v2-new-prompt [RAGAS 是什么] faith0.95 | reason答案逐句对应上下文并补充了论文 编号。 [Faithfulness 衡量什么] faith0.92 | reason明确限定只陈述上下文中存在的内容 。 对比v2 - v1 {faithfulness: 0.11, answer_relevancy: 0.06}解读要点faithfulness 提升 ~0.11新 prompt带引用约束让生成更紧扣检索上下文幻觉风险下降——这是本次改动的正向信号。answer_relevancy 提升 ~0.06回答更完整、更切题。reason 字段是金矿不要只看value。reason告诉你为什么这个分数是后续人工抽检与 prompt 再优化的依据。归档可回溯experiments/compare.json把哪次实验、哪个 prompt 版本、得了多少分钉死三个月后也能回答当时为什么改。版本提醒本示例未使用 legacyevaluate()会触发DeprecationWarning改用稳定的 collections 类式 APIexperiment因属实验性、以实测为准7.2本演练改用更可控的自管归档避免示例在读者环境跑不起来。7.8 本章小结实验追踪的意义评估要嵌进迭代流才能回答这次改动变好还是变坏而非只看今天还行不行7.1观点部分请自行取舍。experiment来自ragas.experimentalv0.4.3 属实验性具体可用性以实测为准不要默认稳定7.2。Dataset来自from ragas import Dataset新一代工作流可把样本与实验元数据一起打包7.3。Dataset≠EvaluationDataset二者是不同 API 层、不同类严禁强行统一对照表见 7.4。对比与版本化最稳的做法是自管归档JSON/DB重型后端LangSmith / MLflow按需接入7.5。常见坑混用两类数据集、误信experiment必可用、仓库名写错、依赖已弃用小写单例、忽略DeprecationWarning、把 LLM 随机性当系统退化7.6。实战7.7 给出数据准备→挂实验→跑分→对比最小可运行示例跑分用 collections 类式 API记录用自管归档。动手检查点执行pip show ragas确认版本为0.4.3在目标环境小样实测experiment的 import 与行为把实测结论记在笔记里。用 7.7 的代码跑通两次实验观察faithfulness与answer_relevancy的delta并读一遍reason字段挑一条最能解释分数变化的理由。打开vibrantlabsai/ragas注1 仓库旧镜像explodinggradients/ragas注4 内容一致/旧路径确认本章引用的Dataset、EvaluationDataset、collections API 的当前写法与你的实测结果交叉核对。在团队文档里固化一条规范“实验记录统一自管归档experiment仅作可选增强依赖前先实测。”本章引用RAGAS 官方仓库vibrantlabsai/ragas注1旧镜像explodinggradients/ragas注4内容一致 / 旧路径RAGAS 官方文档注5论文RAGAS: Automated Evaluation of Retrieval Augmented GenerationEs et al., 2023arXiv:2309.15217注6DeepWiki指向旧镜像注明注7注DeepWiki 索引的是explodinggradients/ragas旧路径内容与vibrantlabsai/ragas一致LangSmith 文档注2MLflow 文档注3参考资料vibrantlabsai/ragas— https://github.com/vibrantlabsai/ragasdocs — https://docs.smith.langchain.com/docs — https://mlflow.org/docs/latest/index.htmlexplodinggradients/ragas— https://github.com/explodinggradients/ragashttps://docs.ragas.io — https://docs.ragas.io2309.15217 — https://arxiv.org/abs/2309.15217https://deepwiki.com/explodinggradients/ragas — https://deepwiki.com/explodinggradients/ragas前一章《没标注数据用 RAGAS 自动合成测试集》后一章从笔记本到 CI把 RAGAS 做成生产级流水线