AI Agent Guide Interactive
模块三 · RAG 检索与证据 3 个交互实验台 TypeScript 可运行示例

RAG 评测与 Agentic RAG:先量化断点,再决定是否动态检索

改完分块、换了 Embedding、调了 Prompt,团队觉得“好像变好了”,直到线上跨文档问题持续漏答。没有分层评测,调参就是盲猜;不看延迟与 Token 账本,盲目上 Agentic RAG 只会让简单查询变慢 3 倍。

30 秒核心结论 先定位瓶颈,再做架构升级
1. 检索层和生成层必须拆开测:相关文档没进 Top-K,再怎么改 Prompt 都救不回来。先用 Recall@K 与 MRR 锁死检索问题。
去实验 01 →
2. RAGAS 四指标对应四条修法:忠实度低修 Prompt 约束,上下文召回低修 Top-K 或切片,精准度低提 Reranker 阈值。
去实验 02 →
3. Agentic RAG 只赚复杂多跳的钱:单文档事实查询走固定链路更快更省;只有跨文档推理或首轮证据不足时,动态多步检索才值得引入。
去实验 03 →

一、检索层评测:先分清“没找到”还是“排太后”

RAG 评测必须拆成两层:检索质量评测看证据有没有进 Top-K,答案质量评测看模型有没有用对证据。混在一起只看最终得分,往往会把检索故障错当成 Prompt 问题来修。

检索层最实用的两个指标是 Recall@K 和 MRR(Mean Reciprocal Rank)。Recall@K 计算的是“所有人工标注的相关文档里,有多少比例进入了前 K 位”;MRR 计算的是“第一篇相关文档出现位置的倒数均值”,排在第 1 位得 1.0,第 2 位得 0.5,第 4 位得 0.25。

这两个数字合在一起看才不会误判。Recall@5 达标但 Recall@3 偏低、同时 MRR 尚可,说明文档已经被召回,只是被 Reranker 挤到了第 4、5 位;如果 Recall@5 和 MRR 一起掉下去,才是 Embedding 模型或分块粒度出了问题。

LAB 01 · RETRIEVAL METRICS MATRIX
Top-K 截断线与排序位次实验台
基于 5 条真实业务问答数据集(覆盖 6 篇标注文档),拖动 K 值切线或切换检索配置,观察 Recall@K 与 MRR 如何分叉并指向不同的修复动作。
检索状态
来自 retrieval-metrics.ts 实时计算
送入 LLM 的 Top-K 窗口 K = 3
实线绿色 = 命中且在 Top-K 内;虚线红色 = 相关文档但被截断在 K 之外
Recall@3 --
--
起始参考门槛:≥ 80.0%
MRR --
--
起始参考门槛:≥ 0.600
漏召回片段数
--
--
查看对应的 TypeScript 评测实现(同步当前 K 值)
examples/rag/rag-evaluation-agentic-rag/retrieval-metrics.ts

完整可运行脚本:retrieval-metrics.ts

二、生成层评测:用 RAGAS 四指标定位链路断点

检索通过不代表回答可靠。RAGAS(docs.ragas.io)把端到端质量拆成四个独立指标,每个指标只负责盯紧链路上的一个断点。

用户问题 Question 检索与重排 Top-K Contexts LLM 生成回答 Grounded Answer 人工参考答案 Ground Truth(离线) Context Precision 检索噪音高不高? 低 → 缩 K / 提 Reranker 阈值 Context Recall 关键事实漏没漏? 低 → 扩 K / 改切片 / 多步检索 Faithfulness 有没有脱离证据编造? 低 → 严约束 Prompt / 触发拒答 Answer Relevancy 回答切不切题? 低 → 聚焦提问 / 裁掉冗余背景
图 1:RAGAS 四指标与 RAG 链路断点的对应关系。两个看检索层,两个看生成层,修错层就会白费力气。

注意三条实战底线:第一,评测集必须来自真实用户问题,用 LLM 根据文档反向生成的合成问题措辞和原文太像,Recall 会虚高;第二,RAGAS 官方只定义算法,0.8 只是社区常用的起始门槛,更重要的是单指标不能低于 0.6;第三,当精准度与召回率冲突时,优先保证 Context Recall,漏掉关键步骤比多带两段无关文本更危险。

LAB 02 · RAGAS FAILURE DIAGNOSIS
RAG 故障工单诊断台
切换 3 条典型评测病例,阅读四项得分后,从 4 个工程动作中选出最先该改的那一项,验证你的排障直觉。
选择病例
教学诊断样本 · 还原常见故障形态
如果你是值班工程师,第一步优先做什么改动?
查看并发 LLM-as-Judge 评测核心代码(OpenAI 兼容接口)
examples/rag/rag-evaluation-agentic-rag/ragas-evaluation.ts
async function evaluateSample(sample: EvalSample): Promise<RagasScore> {
  const [faithfulness, answerRelevancy, contextPrecision, contextRecall] =
    await Promise.all([
      scoreFaithfulness(sample.contexts, sample.answer),
      scoreAnswerRelevancy(sample.question, sample.answer),
      scoreContextPrecision(sample.question, sample.contexts),
      scoreContextRecall(sample.contexts, sample.groundTruth),
    ]);

  const overall = (faithfulness + answerRelevancy + contextPrecision + contextRecall) / 4;
  return { faithfulness, answerRelevancy, contextPrecision, contextRecall, overall };
}

完整可运行脚本:ragas-evaluation.ts

三、固定 RAG 的天花板,与 Agentic RAG 的真实代价

评测跑了一轮又一轮,你会遇到一类固定流水线怎么调都卡死的问题:跨文档多跳推理。第一份文档里只写着“详见《审计日志合规规范》”,在拿到第一份文档之前,单轮检索根本不知道要去搜“SOC2 7 年归档”。

Agentic RAG 的本质并不神秘:不再把“检索 → 生成”写死成一次单向调用,而是把检索器封装成 Agent 的工具(Tool),让模型先判断当前证据够不够,不够就拆分子查询、换词再查,直到满足证据要求或触达最大步数预算(MAX_STEPS)。

但它不是免费午餐。每多一轮工具调用,就会多一次完整上下文的 LLM 推理、多一段网络延迟、多一层失败路径。下面先做个直觉预测,再进沙盒对照账本。

先猜再验 面对“deleteAccount 报 409 时该走什么删除流程?审计日志能不能一起物理删除?”这类跨 3 份文档的问题,把固定 RAG 的 Top-K 从 3 拉大到 15,对比 Agentic RAG 跑 2 轮工具检索,最容易出现什么结果?
LAB 03 · FIXED PIPELINE VS. AGENTIC RAG
固定检索 vs. Agent 自主检索:步进轨迹与成本对照台
切换 3 类查询难度,单步或自动播放执行过程,对比左右两套架构的证据覆盖率、LLM 调用次数、延迟与 Token 消耗。
查询类型
Fixed RAG(固定单轮检索 Top-2) 待运行
Agentic RAG(工具调用 + 步数预算 MAX=4) 待运行
查看带 MAX_STEPS 预算的最小 Agentic RAG 循环(TypeScript)
examples/rag/rag-evaluation-agentic-rag/agentic-rag-loop.ts
for (let step = 1; step <= MAX_STEPS; step++) {
  const res = await client.chat.completions.create({
    model: MODEL,
    temperature: 0,
    messages,
    tools,
  });

  const msg = res.choices[0]?.message;
  if (!msg) break;
  messages.push(msg);

  // 模型判断证据已充足,不再调用检索工具,直接返回答案
  if (!msg.tool_calls || msg.tool_calls.length === 0) {
    return msg.content;
  }

  for (const call of msg.tool_calls) {
    const { query } = JSON.parse(call.function.arguments);
    const docs = searchKnowledgeBase(query, 2);
    messages.push({
      role: "tool",
      tool_call_id: call.id,
      content: JSON.stringify(docs),
    });
  }
}

完整可运行脚本:agentic-rag-loop.ts

四、务实落地顺序与架构选型

不要一上来就搭建全套评测平台和复杂 Agentic RAG。最稳的演进路径是:先用 20 条真实业务问题跑出 Recall@5 基线,再用 RAGAS 锁定线上 bad case,最后只把固定链路解不了的高价值多跳问题路由给 Agentic RAG。

另一个高频踩坑是在同一批评测题上反复调参,导致指标虚高。手里有 100 条标注数据时,拆出 80 条做调优集、20 条锁死做验证集,上线前只跑一次验证集看是否真的泛化。

按场景筛选架构

Fixed RAG(混合检索 + Reranker) 默认起点

适用场景:FAQ、API 手册、单文档政策查询,要求 P95 延迟低于 2 秒且成本可控。

工程要点:先把 Recall@5 推到 80% 以上、MRR 稳定在 0.6 以上,90% 的常规企业知识库问题不需要升级架构。

Router + 条件升级(Hybrid) 生产推荐

适用场景:80% 是简单查询、20% 是跨文档排查的真实线上流量。

工程要点:入口加一层轻量分类器或首轮相关性分数门槛:高置信度直接走固定生成,低置信度或复合问题才进入多步检索。

Full Agentic RAG 按需引入

适用场景:故障根因排查、法务/合规跨条款核对、代码库深度研究等高价值复杂任务。

工程要点:必须配齐 MAX_STEPS 步数上限、Token 预算、重复查询去重和降级拒答,防止陷入死循环。

最小离线评测门禁 必备护栏

适用场景:每次修改切片大小、Embedding 模型、Prompt 或引入 Agentic 循环之前。

工程要点:20 到 50 条真实提问 + Ground Truth ID 跑 Recall@K 与 MRR;出现幻觉或跑题投诉再加 RAGAS 回归,单指标不低于 0.6。

到这里,整个 RAG 模块从文档解析、向量检索、混合重排、引用溯源,到分层评测与 Agentic RAG 的演进闭环已经完整。评测把“凭感觉调优”变成了工程循环,而把检索器交到 Agent 手里作为工具,也正好把 RAG 自然接入了下一阶段要深入拆解的 Agent Runtime 与 Tool Calling 世界。