RAGFlow 本地跑起来、知识库也灌进去之后，很多人会卡在下一步：问答界面能问，但一到「自己拆任务、调工具、多轮改稿」就不行了。这篇不讲怎么装 RAGFlow，只讲装完之后怎么把检索接口变成一个智能体：知识库怎么切给 agent、工具怎么挂、什么时候该放弃 agent 退回固定流程，以及上线前拿哪几项自检。
RAGFlow 本地跑起来、知识库也灌进去之后，很多人会卡在下一步：问答界面能问，但一到自己拆任务、调工具、多轮改稿就不灵了。这篇不讲怎么装 RAGFlow，只讲装完之后怎么把检索接口变成一个能跑起来的智能体应用。
先明确一件事：智能体不等于把模型换成更聪明的那个。它真正的差别在于，模型能不能自己决定下一步动作，以及那些动作有没有工具去承接。所以搭建顺序是先把检索变成一个可被调用的工具，再设计循环，最后拿一组固定问题集自检。
先把 RAGFlow 的检索能力变成一个「工具」，而不是一个页面
很多人直接拿 RAGFlow 的对话页面当智能体的一个「环节」，结果会发现上下文完全控不住。原因是那层接口自带它的提示词和会话状态，你插不进自己的编排逻辑。给智能体用，应该走底层的检索接口，只拿片段和来源，剩下的判断自己做。
- 先确认 RAGFlow 对外暴露的是哪一层：对话接口还是检索接口。前者带它自己的提示词和会话历史，后者才是你想要的原料
- 把检索包装成函数式工具：入参是查询串加过滤条件，出参是带来源标识的片段列表，不要让智能体直接吞整段原始返回
- 一份知识库按主题拆成多个可单独检索的工具，颗粒度太粗会塞进无关片段，太细又会让智能体选错工具
- 片段返回时带上分数和来源，后面判断「够不够」才有依据，纯文本片段是判断不了的
工具粒度这件事值得单独说。判断标准很简单：如果两个主题的问题经常需要一起召回，就别拆；如果它们的检索关键词几乎不重叠，就拆。拆错了不会报错，只会让回答质量悄悄变差，所以上线前要拿问题集跑一遍才知道。
另外别忘了容量测算。检索片段变多时，先爆的通常是上下文长度而不是显存。本地部署的并发和上下文上限，到 /models/deploy 按你自己的情况对一遍当时的数字，别凭感觉设。
智能体的循环怎么搭：谁拆任务、谁决定再检索一次
循环本身不复杂，难的是每一步都得有刹车。典型路径是拆解问题、调检索、判断够不够、不够就换关键词再查、最后组织答案。本地部署时算力是自己的，空转的代价是真金白银，所以轮次上限必须写死。
- 拆解让模型把用户问题拆成若干子问题，每个子问题必须能对应到某个具体工具。拆不出对应工具的，直接归为「能力外」。
- 检索按子问题调对应工具，记录每次的查询串和命中片段。这一步不做判断，只收集原料。
- 判断够不够别只让模型说「够了」。用规则兜底：命中的片段里必须出现关键实体或关键数字，否则强制换关键词再查一轮。
- 组织答案把用到的片段和最终答案一起输出，来源必须能追溯到具体知识库条目，方便事后核对。
| 情况 | 该不该用智能体 | 理由 |
|---|---|---|
| 单跳事实查询，知识库干净 | 不用，固定一轮检索加生成 | 更快更稳，智能体只会增加不确定性 |
| 需要跨多份文档拼信息 | 用，但限制检索轮次 | 拆解和换关键词确实有价值 |
| 问题里有歧义需要澄清 | 用，但先反问再检索 | 让模型先确认意图，比盲目检索省算力 |
| 涉及改文件、发请求等写操作 | 用，但只给建议不给执行权 | 本地部署也不该让模型直接落地副作用 |
判断「够不够」这一步，很多人喜欢全交给模型。实际跑下来会发现模型倾向于说够了，尤其是问题稍微模糊的时候。更稳的做法是规则优先：关键实体没出现就再查一轮，查满上限还没出现就让它明说信息不足。
上线前自检：把「能演示」变成「敢给人用」
演示能跑通和敢给人用是两回事。下面这几项检查，本质是回答一个问题：出错的时候，你能不能定位到是哪一环坏了。定位不了，就等于没法维护。
- 准备一组带标准答案的问题集，覆盖能查到、查不到、要跨两份文档三种情况，查不到时必须说不知道而不是编
- 把每轮检索的命中片段和最终答案一起落日志，排查时先分清是检索没召回还是模型没用上召回结果
- 限流和超时按最慢的那条工具链来设，检索慢加模型慢会叠在一起，用户体感就是卡死
- 知识库更新后跑一遍固定用例，之前正确的回答可能因为片段变化而变错，这是最常见的线上回归来源
日志这块多说一句。检索没召回和模型没用上召回结果，现象都是答错，但修法完全不同。前者要动切分策略或检索参数，后者要动提示词或循环判断。日志里两种信息不分开记，你就只能靠猜。
如果你还在选部署方案或者对比不同中转站的实际延迟，可以到 /tools/speed-test 自己测当时的数字，别信别人贴的截图。模型和工具的成本测算，站内也有对应的页面可以核对。
下一步把上面这组问题集先建起来，再去 /models/deploy 对一遍你的上下文和并发上限，最后才考虑接更多工具。顺序反了，后面每次加工具都是在给自己挖坑。→常见问题
RAGFlow 自带的对话功能不够用吗，为什么还要单独搭智能体？
如果只是「问一问答一答」，自带对话够用。需要智能体的场景是：一个问题要拆成几步、要换着关键词反复检索、要顺带调别的工具（查表、算数、读文件）。这些自带对话做不了，得自己写编排层去调它的检索接口。
本地部署的情况下，智能体的模型该怎么配？
通常拆成两个角色：一个负责规划与工具选择，要求指令跟随稳、延迟低；另一个负责最终成文。两者可以用同一个本地模型，只是提示词和温度分开设。具体选哪个模型、多大显存够，到 /models/deploy 按你的上下文长度和并发对一遍再定，别凭感觉挑。
检索结果老是不对，是智能体写错了还是知识库的问题？
先分清两类：一是压根没召回相关片段，那是切分、嵌入模型或过滤条件的问题；二是召回了但答案没用上，那是提示词和上下文组织的问题。把每轮检索片段打进日志，一眼就能分辨，别直接去改智能体逻辑。
