简介这份源码资源面向从事检索增强生成RAG系统开发与调优的技术人员聚焦RAG评估这一关键环节帮助解决生成质量难以量化、检索效果无法系统衡量的问题。内容围绕准确率、忠实度、召回率三大核心指标展开并区分人工评估与自动评估两条技术路径涉及LangSmith、Langfuse等工具及RAGAS框架的落地思路适合具备一定RAG实践基础、希望建立评估体系的开发者参考。资源包共3个文件以inscode工程配置、html页面和gitignore忽略规则为主整体约5KB结构轻量便于快速导入开发环境查看与复用。目前已有191人学习下载。读者可从中获取评估指标定义、人工与自动评估的具体步骤、召回率优化建议以及评估后的数据分析思路为RAG系统的迭代改进提供可操作的参考依据。1. RAG评估到底在评什么从“看起来能答”到“确实答对”很多人第一次搭 RAG 系统跑通链路之后都会经历一个错觉随便问几个问题模型答得头头是道于是觉得“成了”。但真把它丢给业务方用问题立刻暴露——有的答案看着流畅其实引用了错误的文档片段有的明明知识库里有正确内容模型却答了个似是而非的版本还有的多轮对话里把上一轮的上下文串进来答非所问。这些问题的共同点是它们不会在“能跑通”阶段暴露只会在系统化评估里现形。RAG 评估方法要解决的就是把“感觉还行”变成“可量化、可回归、可对比”的工程能力。它评的不是模型本身有多聪明而是整条链路——切块、检索、重排、生成——在给定知识库和问题集上的综合表现。适合谁正在做 rag 项目实战、准备把 demo 推向生产、或者被“rag 知识库答不准”折磨过的工程师。源码层面的评估工具核心价值在于让你能改指标、换数据集、接自己的检索器而不是被某个平台的看板绑死。2. 拆开 RAG 评估的三层指标检索、生成、端到端2.1 检索层命中率之外更要看排序质量检索层评估回答的是“该找的文档找回来了吗排得够前吗”。最基础的两个指标是 Hit Rate 和 MRR。Hit Rate 看正确文档是否出现在 Top-K 里MRR 看它排在第几位。但只盯这两个不够因为 RAG 的生成阶段对“前几条”特别敏感——排在第 8 位的正确文档和排在第 2 位对最终答案的影响完全不同。我一般会同时算 RecallK 和 PrecisionK。RecallK 衡量召回覆盖PrecisionK 衡量噪声比例。K 的取值要结合你的切块大小和生成模型的上下文窗口来定。切块 512 token、生成窗口 8K 的场景K 设 5 到 10 比较常见切块 128 token 的细粒度场景K 可以放到 20。下面是一个用 Python 算这几个指标的骨架# 检索层评估Hit Rate / MRR / RecallK / PrecisionK # retrieved: List[List[str]]每个问题的 Top-K 文档 id 列表 # relevant: List[Set[str]]每个问题的标准答案文档 id 集合 def hit_rate(retrieved, relevant, k): hits 0 for docs, rel in zip(retrieved, relevant): if set(docs[:k]) rel: # Top-K 里有任意一个相关文档即命中 hits 1 return hits / len(retrieved) def mrr(retrieved, relevant): total 0.0 for docs, rel in zip(retrieved, relevant): for rank, doc in enumerate(docs, start1): if doc in rel: total 1.0 / rank # 第一个相关文档的倒数排名 break return total / len(retrieved) def recall_at_k(retrieved, relevant, k): total 0.0 for docs, rel in zip(retrieved, relevant): total len(set(docs[:k]) rel) / len(rel) # 召回比例 return total / len(retrieved) def precision_at_k(retrieved, relevant, k): total 0.0 for docs, rel in zip(retrieved, relevant): total len(set(docs[:k]) rel) / k # 前 K 条里相关占比 return total / len(retrieved)逻辑说明四个函数都按“逐问题计算再平均”的方式聚合。retrieved是检索器返回的文档 id 有序列表relevant是人工标注或从原始问答对里抽出的标准文档集合。参数k控制只看前几条实际调参时建议把 K 从 1 扫到 20画一条曲线看拐点——拐点之后再加 K召回涨得慢但噪声涨得快生成质量反而可能下降。注意标准文档集合的构建质量直接决定评估可信度。如果标注本身有歧义指标再漂亮也是自欺欺人。2.2 生成层忠实度和答案相关性要分开测生成层评估回答的是“答案有没有依据、有没有答到点上”。这里最容易混淆的是两个概念忠实度Faithfulness和答案相关性Answer Relevancy。忠实度看答案是否完全由检索到的上下文支撑不允许模型自己编答案相关性看答案是否切题哪怕它忠实于上下文如果上下文本身跑偏了答案也不相关。常见做法是用一个 LLM 做裁判把“问题 检索上下文 生成答案”一起喂进去让它按维度打分。但 LLM 裁判有位置偏差和打分漂移所以我会做两件事一是固定裁判模型的版本和温度温度设 0二是对同一批样本跑两次取平均观察方差。下面是一个裁判提示词的骨架# 生成层评估用 LLM 裁判打忠实度和相关性 JUDGE_PROMPT 你是一个严格的评估员。根据以下材料打分只输出 JSON。 问题{question} 检索上下文 {context} 生成答案{answer} 请从两个维度打分1-5 分 1. faithfulness答案中的每个事实是否都能在上下文中找到依据。 有编造内容则扣分完全无依据给 1 分。 2. relevancy答案是否直接回应了问题。 答非所问给 1 分完全切题给 5 分。 输出格式{{faithfulness: int, relevancy: int, reason: 简短理由}} import json def judge(question, context, answer, llm_client): prompt JUDGE_PROMPT.format( questionquestion, contextcontext, answeranswer ) # 温度固定为 0减少打分随机性 resp llm_client.chat(prompt, temperature0.0) return json.loads(resp)逻辑说明提示词里把评分标准和扣分条件写死是为了减少裁判模型的自由发挥。temperature0.0是必须的否则同一份输入两次打分可能差 1 到 2 分。参数上context建议只放实际参与生成的那几条不要把整个知识库塞进去否则裁判会被无关内容干扰。如果预算允许用比生成模型更强的模型做裁判区分度会更好。2.3 端到端用回归集守住“不退化”这条底线端到端评估不拆层直接看“问题进、答案出”的整体表现。它的核心作用不是追求高分而是防止迭代退化。你改了切块策略、换了 embedding 模型、调了重排阈值怎么知道整体是变好还是变坏靠的就是一个固定的回归问题集。回归集的构建原则是覆盖高频问题、边界问题、多轮对话场景每个问题都有标准答案或标准文档。规模不用大50 到 200 条就能看出趋势。每次改动后跑一遍对比忠实度、相关性、检索命中率的均值变化。如果某个指标掉了超过阈值我一般设 5%就回滚或定位原因。这套机制是 RAG 项目从“能演示”走向“敢上线”的分水岭。3. 用源码搭一套可复现的评估流水线3.1 数据集格式问题、标准答案、标准文档三件套评估流水线的起点是数据集。我一般用 JSONL每行一条字段固定为question、ground_truth、relevant_doc_ids多轮场景再加history。这样检索层和生成层可以共用同一份数据不用维护两套。{question: RAG 切块大小怎么选, ground_truth: 取决于文档结构和生成窗口常见 256-512 token。, relevant_doc_ids: [doc_012, doc_045]} {question: 检索命中率低先查什么, ground_truth: 先查切块是否破坏了语义完整性再查 embedding 是否适配领域。, relevant_doc_ids: [doc_078]}逻辑说明relevant_doc_ids是检索层评估的输入ground_truth是生成层评估的参照。字段名保持稳定后续换数据集时脚本不用改。参数上relevant_doc_ids允许一个问题的多个相关文档但不要把所有沾边的都塞进去否则 Recall 会虚高。3.2 跑通评估脚本从加载数据到输出报告把前面的指标函数和裁判逻辑串起来就是一个最小可用的评估脚本。核心流程是加载数据集 → 对每个问题跑检索 → 跑生成 → 算检索指标 → 算生成指标 → 汇总输出。# 最小评估流水线检索 生成 指标汇总 import json def load_dataset(path): with open(path, encodingutf-8) as f: return [json.loads(line) for line in f if line.strip()] def evaluate(dataset, retriever, generator, judge_client, k5): retrieved, relevant [], [] faith_scores, rel_scores [], [] for item in dataset: q item[question] docs retriever.search(q, top_kk) # 返回文档 id 列表 context retriever.fetch_text(docs) # 取回文档正文 answer generator.generate(q, context) # 生成答案 retrieved.append(docs) relevant.append(set(item[relevant_doc_ids])) score judge(q, context, answer, judge_client) faith_scores.append(score[faithfulness]) rel_scores.append(score[relevancy]) return { hit_ratek: hit_rate(retrieved, relevant, k), mrr: mrr(retrieved, relevant), recallk: recall_at_k(retrieved, relevant, k), precisionk: precision_at_k(retrieved, relevant, k), faithfulness: sum(faith_scores) / len(faith_scores), relevancy: sum(rel_scores) / len(rel_scores), } if __name__ __main__: data load_dataset(eval_set.jsonl) report evaluate(data, retriever, generator, judge_client, k5) print(json.dumps(report, ensure_asciiFalse, indent2))逻辑说明retriever.search返回有序文档 idfetch_text按 id 取正文两者分开是为了让检索指标和生成指标各取所需。k是全局参数改一处即可。输出用 JSON 是为了方便后续对比不同版本的报告。参数上如果生成很慢可以先把检索指标跑完生成指标单独批量跑避免一次跑太久。3.3 参数怎么调K 值、切块、裁判温度的联动评估不是跑一次就完调参才是重头戏。三个最常动的参数是检索 K、切块大小、裁判温度。它们不是独立的K 变大召回涨但噪声多忠实度可能掉切块变小检索粒度细但上下文碎片化相关性可能掉裁判温度不设 0所有指标都带随机噪声。参数常用范围调大后的影响调小后的影响检索 K3 ~ 20召回涨噪声涨忠实度可能降精度高但可能漏掉正确文档切块大小128 ~ 1024 token上下文完整检索粒度粗检索准但生成缺上下文裁判温度固定 0打分随机不可复现打分稳定区分度靠提示词我一般先固定切块和温度扫 K 值找召回和忠实度的平衡点再固定 K试两三种切块大小最后确认裁判温度是 0。每次只动一个变量否则出了问题说不清是谁的锅。4. 避坑与排查评估流水线最容易翻车的五个地方现象指标高得离谱人工一看全是错的。原因标准文档集合标注太宽松把沾边的文档都算相关。解决重新审标注只保留真正支撑答案的文档宁可少不可滥。现象同一份数据跑两次忠实度差 0.5 分以上。原因裁判模型温度没设 0或者用了会随机采样的接口。解决温度固定 0并在脚本里加断言发现温度不为 0 直接报错。现象检索命中率正常但生成答案总是缺关键信息。原因切块把关键段落切断了检索回来的片段不完整。解决改用按语义切块或加大重叠窗口然后重跑检索指标确认召回没掉。现象多轮对话场景下指标集体下滑。原因评估时没把历史轮次传进去检索器只看了当前问题。解决数据集加history字段检索和生成都把历史拼进输入单独统计多轮子集的指标。现象换了 embedding 模型后所有指标都变了但说不清好坏。原因没有固定回归集新旧模型跑的不是同一批问题。解决先冻结回归集新旧模型各跑一遍逐条对比看是整体漂移还是个别问题退化。5. 进阶把评估接进 CI让每次改动都有后悔药评估流水线跑通之后最有价值的动作是把它接进持续集成。每次改切块、换模型、调提示词自动跑一遍回归集指标掉超阈值就拦住合并。这一步做完RAG 项目才算真正有了工程底线。具体做法是写一个对比脚本读入基线报告和新报告逐指标算变化率# 回归对比新报告 vs 基线掉超阈值则退出码非 0 import json, sys THRESHOLD 0.05 # 允许 5% 波动 def compare(baseline_path, new_path): base json.load(open(baseline_path, encodingutf-8)) new json.load(open(new_path, encodingutf-8)) regressions [] for key in base: if key not in new: continue delta (new[key] - base[key]) / max(abs(base[key]), 1e-6) if delta -THRESHOLD: # 下降超过阈值 regressions.append((key, base[key], new[key], delta)) return regressions if __name__ __main__: regs compare(baseline.json, new_report.json) if regs: for k, b, n, d in regs: print(f退化: {k} 从 {b:.3f} 降到 {n:.3f} ({d:.1%})) sys.exit(1) # 非 0 退出码让 CI 失败 print(所有指标在阈值内)逻辑说明THRESHOLD设 5% 是经验值指标本身波动大的场景可以放宽到 10%但不能再宽否则退化会被放过。sys.exit(1)是接 CI 的关键让流水线能感知失败。参数上基线报告要定期更新——当你确认某次改动是正向的就把新报告设为基线否则基线会越来越旧失去参照意义。除了 CI还有一个我常用的技巧给评估报告加一个“最差样本”列表按忠实度从低到高排每次看前 10 条。指标是均值均值会掩盖极端 case而极端 case 往往就是线上投诉的来源。这个习惯帮我提前发现过好几次切块边界问题。说个我自己的教训早期做 RAG 评估我只盯检索命中率觉得命中率上去了答案自然好。结果上线后业务方反馈“答得不对”一查才发现检索回来的文档是对的但生成阶段把几个片段拼错了忠实度一塌糊涂。从那以后我养成了一个习惯——任何一次改动检索指标和生成指标必须一起看缺一个都不发版。评估这件事省下的每一步后面都会以线上问题的形式还回来。希望帮到你。本文还有配套的精品资源点击获取