agentic rag 搭建

很多人搭 RAG 是先检索再塞给模型，碰上「一次检索不够用」的问题就卡住了——比如要跨多份文档比对、要先查目录再决定看哪页、要拿到结果再决定是否补一次查询。这篇讲的就是在原有检索链路上加一层 Agent 决策：让模型自己判断要不要查、查什么、查几次、什么时候停，以及这套东西在什么情况下反而不该上。

很多人搭 RAG 的默认姿势是「先检索再塞给模型」，链路短、好调试，大部分 FAQ 和单跳问答靠它就能跑通。可一旦碰上要跨多份文档比对、先看目录再决定翻哪一页、或者拿到中间结果才知道下一步该查什么的问题，固定管线就开始露怯——它不会自己决定「要不要再查一次」。Agentic RAG 要解决的就是这件事：在原来的检索链路上叠一层决策循环，让模型自己判断查不查、查什么、查几次、什么时候停。

这篇只讲搭建思路和判断标准，不讲概念科普。核心是三件事：先想清楚你的场景配不配得上这层循环，再把检索拆成模型能选的工具，最后给循环装上刹车。全程不用看具体数字，涉及成本和模型选择的地方，文中都给了站内页面的核对入口。

先判断：你的场景到底需不需要 Agent 化

这层循环不是免费的，它换来的是多跳能力，代价是延迟变长、调用次数上升、调试难度翻倍。所以第一步不是写代码，是拿你自己的业务问题去筛一遍。下面这张对照表可以直接往场景上套。

场景特征	该不该上 Agent 循环	理由
固定 FAQ、产品参数查询	不上	一次检索就能命中，循环只是多绕几圈
单跳问答、摘要类	不上	检索词由用户问题直接决定，模型插不上手
先查 A 再根据 A 查 B	上	第二跳的查询词依赖第一跳结果，固定管线写不出来
跨多份文档比对	上	需要分别检索、逐份取证再汇总
问题本身决定检索策略	上	比如同义词多、需要换多个角度召回

自检一：同一个问题换不同检索词，召回结果差异大不大？差异越大，越说明检索词该交给模型生成
自检二：跑一批真实问题，统计「一次检索能否答对」，答不对的比例高才有改造价值
自检三：答错的那些问题，是真的缺信息，还是检索没召回？后者优先修检索层，不是加 Agent
自检四：业务能接受多等几秒、多花几次调用吗？不能接受就别硬上

循环怎么搭：把检索包装成一个工具

搭法上最容易走歪的一点，是把所有检索能力塞进一个大而全的函数，然后让模型调它。更好的做法是把向量检索、关键词检索、按文档 ID 取全文分别注册成独立工具，参数写清楚，让模型自己选。工具拆得越干净，模型选错的概率越低，排查时也更容易定位是哪个环节挂了。

注册工具向量检索、关键词检索、按 ID 取全文各一个工具，description 里写清适用场景和不适用场景，别只写一句「检索文档」
跑骨架模型输出工具调用 → 执行检索 → 结果按条附加引用标识回填 → 模型继续或给出最终答案，先用最简单的一条循环跑通
加可追溯 ID每条召回结果带上来源和片段 ID，最终答案里的引用编号要能对应回去，否则人工抽查无从下手
控制上下文只回填得分靠前的若干条摘要或片段，全文按需再取，避免几轮下来把窗口撑爆

工具粒度: 一个工具只做一件事，参数语义清晰，模型才选得准
引用标识: 每条召回结果的可追溯编号，答案引用和日志排查都靠它
回填策略: 每轮只把命中的关键片段放回上下文，全文按需再取

循环骨架本身不复杂，难的是几轮之后上下文里堆了什么东西。建议每轮回填时只保留命中片段的关键句，把完整文档留在外部，模型需要哪一段再用工具去取。这样即使轮数上去，窗口也不会被无关内容撑满。

止损设计：步数、白名单与终止条件

没有刹车的循环一定会失控，最常见的表现是反复查同一件事，或者一直查到超时。止损要分三层：轮数上限、工具白名单、重复查询识别。三层都装上，再谈效果。

设最大循环轮数，超出就强制用现有材料作答，并在答案里明确说明「资料可能不足」
工具白名单只放开只读检索接口，任何写操作、外部请求都不要放进这个循环
记录已用过的查询词，命中重复就提示模型换角度或收尾，别让它原地打转
给单次工具调用设超时，某一路检索卡住不至于拖垮整轮
把每轮的查询词和召回条数落进日志，出问题时能一眼看出卡在哪

轮数上限定多少，得按你实际的调用次数和 token 消耗倒推，不能拍脑袋。这套东西的成本口径可以到模型成本计算器和 Token 单价换算里，用你真实的轮数算一遍再定上限。注意这类数字随模型和供应商调整会变，以页面上当时的数字为准。

出答案与验证：怎么知道这套东西没白搭

搭完不代表有效，得有一套固定的验证办法。最省事的做法是攒一批真实问题做回归，每次都跑同一批，看两个方向：答对率有没有提升，平均检索轮数有没有失控。只看答对率不看轮数，很容易被「靠多查硬堆出来」的假象骗过去。

观察项	健康表现	异常信号与处理
答对率	相对固定管线有提升	三轮循环后没明显变化，退回固定管线更划算
平均轮数	稳定在设定上限以内	持续贴上限，多半是工具描述不清或终止条件缺失
重复查询	很少出现	频繁重复，说明缺重复识别或提示词没讲清收尾条件
引用可追溯	每个编号都能点回原文	对不上，回填时丢了 ID，先修数据链路

日志要能看到每轮的查询词和召回条数。出问题时按这个顺序看：检索到底有没有召回对应内容，召回了模型有没有用上。前者是检索层的事，后者是提示词和工具设计的事，别混在一起调。

常见踩坑与排查顺序

搭 Agentic RAG 踩的坑其实很集中，按固定顺序排查能省下大量时间。下面这几个是最常遇到的，建议直接当成检查清单。

模型该调工具却不调先检查工具的 description 写得够不够清楚，再检查是不是有强制纯文本输出的约束把它堵住了
循环不收敛按「查询词重复 → 阈值太高召回为空 → 缺终止提示」这个顺序排查，一层一层排
多轮之后答案变差多半是上下文堆了太多无关片段，改成只保留每轮命中片段的关键句再试
换个模型就跑不动工具调用的格式和兼容性各家有差异，到模型库和框架目录里对照着挑，别硬套

选模型和框架时，别只看宣传，重点看它对你这套工具调用格式的支持程度。推荐模型差异和框架兼容性可以到 Agent 框架与 SDK 目录和 AI 模型库对照着挑，具体的能力和参数以页面上当时的资料为准，不要凭记忆下判断。

下一步搭之前先算清楚这套循环的成本上限和模型选择，免得写完才发现跑不起。这两个页面的数字会随供应商调整变化，看之前先核对当时的数值。

常见问题

Agentic RAG 和普通 RAG 的核心差别在哪？

普通 RAG 的检索是写死在代码里的固定步骤，先查什么、查几次都是你定；Agentic RAG 是把检索做成工具交给模型，由模型决定要不要查、查什么词、查几轮。差别不在向量库，而在控制权归谁。代价是延迟和成本都会涨，所以只在需要多跳推理的场景才值。

检索循环最多跑几轮比较合适？

没有统一答案，但可以从三轮起步试：一轮解决大部分问题，两轮覆盖需要补查的，三轮以上要警惕是不是检索本身质量不行。建议先设一个你能接受的轮数上限，跑一批真实问题看答对率和轮数分布，再调。同时把轮数和单轮召回条数一起算成本，别只看轮数。

怎么防止 Agent 反复查同一件事停不下来？

两个动作：一是记录已经用过的查询词，检测到高度重复就给模型一个「换角度或收尾」的提示；二是设硬性步数上限，到了就强制用已有材料作答并注明资料可能不完整。别指望靠提示词里的「请勿重复」解决，一定要有代码层面的兜底。