企业官网建设流程全解析

做检索增强生成，最怕的不是召回率不够高，也不是生成结果不流畅，而是整个系统在一个不可控的状态里运行——用户问一个问题，你明明有知识库，却答非所问；知识库里明明没有答案，模型却在自信地编造；业务量一涨，索引和检索链路先扛不住。我这次要聊的，就是围绕“构建可扩展、生产级的 Agentic RAG Pipeline”这个主题，把一个从原型到上线的完整工程实践拆开讲清楚。标题里藏着三个关键词：Agentic、可扩展、生产级。它适合正在做知识库问答、企业文档智能助手、客服辅助系统的开发者参考，也适合那些已经跑通 demo、但不知道怎么把 RAG 项目往前推到生产环境的人。这篇内容不会绕弯子，全是项目里实打实遇到的取舍和排障过程。

1. 为什么需要 Agentic RAG：从“查资料”变成“用资料”

1.1 传统 RAG 的瓶颈：一次检索定生死

先回到传统 RAG 的流程：用户问题进来，做向量化，去向量库召回 top-k 文档片段，拼进 prompt，让模型基于这些片段回答。这个流程看起来简单，但放到真实业务里会暴露几个扎眼的问题。

第一个问题是“一次检索定生死”。用户的问题往往不是一个单纯的问句，而是带有意图拆解的。比如“过去三个季度华东区的销售数据里，哪个季度环比增长最快”，传统 RAG 会把整句话向量化，然后去库里召回。问题是这句话里既涉及“华东区”“销售数据”“环比增长”多个维度，向量检索对这种复合意图的响应很不稳定，召回回来的片段经常是偏科的，只覆盖其中一两个维度。

第二个问题是“没有条件判断”。知识库里没有答案的时候，传统流程还是会硬答，因为生成模型根本不知道检索结果是不是真的覆盖了问题。你可以在 prompt 里写“没有相关内容就说明不知道”，但实际效果时好时坏，尤其在跨领域知识混合的场景下，模型很容易被无关片段带偏。

第三个问题是“不会用工具”。很多企业知识不是只存在文档里，还存在于数据库、表格、内部系统接口里。传统 RAG 默认检索的是文本片段，遇到需要查实时数据、调用计算接口的场景就彻底卡住。

这三个问题指向同一个本质：传统 RAG 把“检索”当成一次性动作，但真实的知识获取过程是迭代、判断、重试的。Agentic RAG 解决的就是把检索从“一次查询”升级为“一个可编排的过程”。

1.2 Agent 化之后，检索变成了一个可编排的过程

所谓 Agentic RAG，核心区别在于系统里多了一个“编排者”。这个编排者可以是一个显式的工作流状态机，也可以是一个由大模型驱动的规划模块。它的职责是：拆解用户问题、决定需要哪些信息、调用哪个检索工具、判断检索结果是否足够、不足则重新组织查询词再检索，最终把收集到的证据交给生成模块。

我这边做过的一个知识中台项目就是典型的例子。用户问的是“我们采购流程里，如果供应商资质过期了，合同还能不能续签”，传统 RAG 直接检索“供应商资质过期”相关片段，召回结果很散。Agentic 流程会先规划出三个子任务：查采购流程文档、查合同管理办法、查供应商资质审核细则，逐个检索，然后再汇总交叉验证。整个过程是图谱式的，每一步都有明确的输入输出，而不是一股脑把 top-k 片段塞进去。

这种设计带来的好处很直接：召回质量可以从“依赖一次向量检索的运气”变成“通过多轮确认来逼近正确答案”。而且每一步都可以被记录、被回放，出了问题你能看到是哪一步检索错了，而不是对着一个黑盒式生成的答案无从下手。

1.3 不是所有场景都该上 Agentic

但我也要说句实话：Agentic RAG 不是银弹，它带来的额外成本是真实存在的。多轮规划意味着更多的大模型调用，延迟和费用都会上升。如果一个场景就是事实性问答，比如“这个产品的保修期是多久”，知识库覆盖完整、问题模式固定，那传统 RAG 加上良好的召回策略已经够用了，强行上 Agent 反而会把简单问题搞复杂，用户等答案的时间还变长了。

我的判断标准很简单：问题是否需要多源信息合并、是否需要条件判断和重试、是否需要调用外部工具。三个条件一个都不满足，就老实点用传统流程；满足任意两个，才值得投入 Agentic 化改造。这个判断在项目初期就要做，否则后面整个架构都会背着一个不必要的复杂度在跑，维护成本会一路走高。

2. 生产级 Pipeline 的整体架构拆解

2.1 编排层：图状态机还是链路编排

编排层是 Agentic RAG 的大脑。目前在工程上主流有两种实现思路：一种是用图状态机的方式，把每个节点（规划、检索、评估、生成）定义成独立的处理单元，节点之间通过显式的边来流转；另一种是链路编排，用链式或递归的方式把工具调用串起来。

我个人的经验是：生产系统优先选图状态机。原因有三个。第一，图结构天然支持条件分支和循环回退，比如“检索结果不足则回到规划节点重新拆解”，这在链式结构里需要写大量 hack。第二，图上的每个节点都可以单独埋点、单独重试、单独降级，符合生产系统对可控性的要求。第三，复杂流程一旦出问题，图结构可以完整回放所有路径，排查效率高很多。

具体到实现，不一定要上重型框架。如果你的流程就是固定几个节点，完全可以用状态机库或者直接手写一个带状态的执行器；只有当流程需要动态生成、工具数量庞大时，才值得引入编排框架。过度设计是这里最常见的错误，我见过不少项目为了“可扩展”一开始就上了重型编排平台，结果业务逻辑没几行，配置文件和抽象层写了一大堆，最后连改一个提示词都要翻三层代码。

2.2 检索层：多路召回与混合检索

生产级的检索层不能只靠一个向量库。我现在的标准配置是“向量召回 + 关键词召回 + 结构化过滤”三路并行。

向量召回负责语义相似度，这在处理同义改写、口语化表达时优势明显；关键词召回负责精确匹配，尤其适合工单编号、产品型号、法律条款这类对字面精确度要求极高的内容；结构化过滤则负责按照用户身份、时间范围、业务域先做数据裁剪，避免召回结果跨域串味。比如一个普通员工问“最近的项目进展”，不应该召回其他财务预算相关的文档，这个问题靠纯向量检索是拦不住的。

多路召回的结果需要做一个合并排序，这里我建议不要迷信模型重排。模型重排效果好，但成本也高，而且对首屏延迟不友好。可以先做基于分数的加权合并，再用一个轻量的重排模型在最终候选集上跑一遍。候选集控制在 20~30 条以内，重排才有性价比。如果业务场景对延迟特别敏感，甚至可以跳过模型重排，直接用规则加权，效果也不会差太多，关键是前期要把各路召回的分数量纲对齐，否则加权合并就是拍脑袋。

2.3 工具层与记忆管理

Agentic RAG 经常会需要调用外部工具：查数据库、查业务系统接口、执行一个计算脚本、请求另一个模型做摘要。工具层的设计我踩过不少坑，总结下来三条纪律。

第一，工具描述必须写清楚“什么时候用、什么时候不用、需要什么参数”。现在的模型对工具调用的理解高度依赖描述文本，描述写得含糊，模型就会乱调工具。我见过最典型的问题是模型把“查员工在岗状态”的工具拿来回答“公司有多少个部门”，就是因为描述里没有写清边界。

第二，工具入参要做严格校验。大模型填参数偶尔会填出幻字段，直接透传给下游接口，轻则查不到数据，重则触发脏写。在工具层前面加一层 schema 校验，配合兜底重试，是必须的。这个问题后面我会专门放到排查章节里细说，因为它的隐蔽性远超想象。

第三，所有工具调用都要有超时和熔断。一个外部接口变慢，会把整个 Agent 流程拖到超时。我的做法是每个工具调用有独立的超时时间，超过阈值直接返回“工具不可用”而不是继续等，让编排层走降级路径，绝不因为一个辅助工具把主流程拖死。

再来说记忆管理。Agent 在和用户多轮交互时，历史信息不能全部塞进上下文，成本爆炸且容易串扰。生产实现上是两层：短期记忆保留当前会话最近几轮的关键信息和中间结果，放在内存或缓存库；长期记忆里存放用户的持久化偏好和跨会话事实，由独立模块读写。一个容易被忽略的点是：Agent 在检索过程中的“思考链”也是记忆的一部分，这些中间状态要么持久化到 trace 系统，要么在会话结束时清理掉，否则会话一多内存就先爆了。

3. 可扩展性设计：从能跑到能扛

3.1 索引管线的扩展策略

生产级的扩展性，第一关是索引管线。很多团队在本地上跑通索引简单，但一到几十万文档、每天增量更新，就会发现索引过程比检索还容易出问题。

索引管线我拆成四个阶段：文档解析、清洗分块、向量化、写入存储。每个阶段都要支持独立扩容和重试。文档解析是第一个坑，PDF、扫描件、办公文档格式千奇百怪，解析服务最容易成为瓶颈，建议单独拆成独立服务，配合任务队列做异步处理，解析失败的重试队列要设置最大重试次数和死信处理，不然一个坏文件会在队列里反复横跳，把后面的正常任务全堵住。

分块策略直接影响召回质量，这里没有统一标准答案，但有几个经验值可以参考：

分块做完要记录块级别的元数据，包括来源文档、页码、章节路径，这些元数据是后面做引用溯源和过滤的关键。向量化环节要注意批处理的大小。批量过大会把显存打满，批量过小吞吐又上不去。我通常是动态调整 batch size，以单批耗时不超过 2 秒为锚点反推。同时要做幂等：同一批文本如果因故障重复处理，写库时要能去重，否则向量库里会出现大量重复块，检索质量直接下降。

3.2 服务层的水平扩展与状态处理

检索服务的水平扩展，核心问题在于 Agent 流程是有状态的。一次多轮检索，中间状态存在哪里，决定了你能不能随便加机器。

我的建议是：流程状态集中存储，不在每个服务工作节点本地留状态。这样任意节点挂了，另一个节点可以从状态中心恢复执行。状态中心可以是支持事务的内存态存储或者关系库，注意给状态记录加上过期清理策略，否则 Agent 流程一多，状态表会变成一张没人管的垃圾表，内存和磁盘都被无意义地吃掉。

另外一个扩展性要点是“请求放大效应”。Agent 流程内部会调用多次模型推理、多次检索，一个外部用户请求可能放大成几十次内部请求。这意味着服务层的限流不能只限在网关入口，内部每一次模型调用和工具调用都要有独立的配额控制。我见过线上事故就是这样来的：白天流量高峰期入口限流没触发，但放大后的内部请求把模型 API 配额打爆了，全站检索质量崩了一下午，用户端看到的只是“回答变慢变差”，但根因排查花了大半天。

3.3 向量库选型与数据分片

向量库是 Agentic RAG 的底座，选型时我主要看四个维度：过滤能力、扩缩容能力、一致性、生态成熟度。

过滤能力很重要，因为在真实场景里，权限过滤是刚需。有些向量库对 filter 的支持很弱，过滤条件一复杂就退化成全量扫描，延迟完全不可控。扩缩容方面，要确认分片和副本是可以独立调整的，最好支持在线扩容，不然业务增长时要停机迁移就非常被动了。一致性这里有个权衡：向量索引本身是近实时的，写入后到可查询通常有延迟，生产上必须接受这个延迟并处理读后写不一致的问题。生态成熟度指的是周边工具链：索引管理、监控、备份恢复是否齐全，这些在长期运维里会反复影响你的效率。

数据分片策略上，我建议按业务域拆集合，而不是把全量数据放一个大集合里。业务域拆分的收益很大：权限控制更干净、召回时可选项更小、索引重建的影响面更小。当然，跨域查询需求多的话是例外，这种情况下可以考虑多集合并行召回再合并，而不是硬往一个大集合塞。分片粒度要和业务对齐才有意义，纯按字母或哈希分片在跨域检索时反而会制造更多麻烦。

3.4 高并发下的限流与降级

生产级系统必须假设服务的某一部分随时会不可用。对 Agentic RAG 来说，降级设计比容量规划更紧急，因为模型服务、外部工具、向量库故障的概率都不低。

一个完整的降级金字塔大概长这样：

每一层降级要有明确的触发条件和恢复条件，并且降级策略要在上线前演练过，不要等故障来了再现场想。缓存是这里性价比最高的手段。语义相同的问题会在真实流量里反复出现，加一层结果缓存，可以减少大量模型调用。缓存键不能直接用原始问题文本，因为上下文不同会导致同一句话意图不同；稳妥的做法是对“问题规范化文本 + 会话上下文指纹”做键，命中后也要做时效校验，知识库更新后相关缓存要能按文档版本失效，否则用户会一直看到旧答案。

4. 生产化落地：评估、观测、成本三位一体

4.1 评估：Agentic RAG 怎么测才算过关

Agentic RAG 的评估比传统 RAG 麻烦很多，因为输出质量不仅取决于最终答案，还取决于中间过程是否合理。我在项目里会分三层来评估：

自动化评估我建议用小模型当 judge，或跑评测集算指标，但在关键版本发布前，一定要做一轮人工回归。Agentic 系统的行为具有随机性，同一个问题在不同次运行可能走不同路径，所以评估集必须覆盖几条不同的问题类型：单一事实问答、多源合并问答、需要工具的问答、知识库无答案的问答。最后那类最容易翻车，要专门看系统是否诚实地回答“没有找到相关内容”，而不是硬凑一个似是而非的答案。

4.2 可观测性：链路追踪是生产级的底线

生产级的另一个硬指标是链路可观测。Agent 流程里每一步都是模型调用驱动的黑盒，如果没做追踪，出问题等于大海捞针，用户反馈一条坏答案，你可能连复现都无从下手。

我的做法是给整个流程注入统一的 trace id，每个节点的输入输出都记录到结构化日志，至少包含：节点名称、耗时、调用的模型、消耗的 token 数、检索的查询词、召回的文档列表、最终生成的答案。这些信息一方面用于排障，另一方面可以回放完整的推理路径，帮助优化 Agent 的决策逻辑。比如我发现某个场景经常走错工具，就是因为回放了大量 trace 才定位到工具描述有歧义。

还有一个细节：不仅记录成功链路，失败链路和重试路径更要记录。很多线上问题都是偶发的，没有失败日志，你根本不知道平均成功率是多少。我建议给每个节点加成功、失败、超时的状态统计，按天出报表，任何一个节点成功率掉到 95% 以下就应该触发告警。这个数字不是拍脑袋定的，Agent 流程是多节点链路的乘积，单节点 99% 成功率走到五个节点就只有 95% 了，所以单节点的健康红线必须定得比直觉更严格。

4.3 成本与延迟控制

Agentic RAG 的成本模型和传统 RAG 不同，它最大的成本在“规划 + 多轮检索”产生的大量模型调用。如果不加控制，一个复杂问题的模型调用次数可以是传统 RAG 的 5~10 倍，上线第一个月账单就能让人清醒。

控制成本我常用的三个手段：模型分级、缓存复用、步数上限。模型分级是把简单节点用便宜小模型，复杂规划节点用强模型，结束生成再用中档模型润色；缓存复用是同一会话内或跨会话复用重复的检索结果和子任务结论；步数上限是硬性的，Agent 最多执行 N 步，到顶就终止并基于已收集的上下文生成答案，避免失控的连环调用。步数上限设多少要看业务复杂度，我一般从 6 起步，观察日志里的分布再做调整，绝大多数问题在 3~4 步内就能收敛。

延迟方面，最大头通常不在模型推理本身，而在多轮串行调用。能并行的检索任务要并行发起，不要一个个排队等。我在架构里把第一阶段规划完成后、拆出来的多个子检索任务设计成并行扇出，全部返回后再合流，实测整体 p95 延迟能减少一半以上。这个优化几乎没有副作用，纯粹是流程设计问题，很多团队没意识到而已。

5. 常见问题与排查实录

5.1 Agent 反复横跳与检索空转

我遇到最多的故障是 Agent 在同一组检索词上反复横跳，表现为节点状态反复在“规划-检索-评估”之间循环，资源大量消耗但检索结果没有变化。排查下来原因通常是两个：检索工具返回的结果没有进入下一轮的决策上下文，或者评估节点对结果质量打分的标准太模糊，导致 Agent 无法判断“已经够了”。

解决办法是在评估节点里设一个明确的终止条件，比如“当前结果已覆盖问题所有关键实体，并且来源文档可信，则终止检索”，而不是让模型自由判断。同时每轮检索前要把上一轮的查询词和结果摘要作为上下文传给规划节点，避免无方向地重复检索。我在项目里加了一个保护开关：连续两轮检索结果的重叠率超过 80%，就直接强制进入生成阶段，防止资源被空转检索白白耗尽。

5.2 上下文窗口溢出与记忆串扰

Agent 流程会在每轮把检索结果注入上下文，多轮下来很容易把上下文撑爆。常见表现是：后几轮生成的答案质量急剧下降、引用混乱、甚至开始答非所问，但前面几轮看起来一切正常，这类问题特别容易误判为模型能力退化。

排查时先看 token 消耗曲线，如果每轮都在涨，说明上下文管理缺失。解决方法是做摘要压缩：每轮检索结果先过一个压缩模块，提取关键信息后替代原始全文进入上下文；历史轮次的信息也在每轮结束时做一次滚动摘要。这个机制能让上下文长度基本稳定，而不是线性增长。我当时上线这个功能后，长会话场景的 token 消耗直接降了 60% 多，而且答案质量不降反升，因为模型不再被一大堆冗余片段干扰注意力。

5.3 工具调用参数错乱与数据权限穿透

还有一类很危险的故障是工具调用参数错乱。模型在生成工具参数时，偶尔会把用户输入里的类似字段填错位置，比如把“部门”填到“时间范围”里。这类问题一旦发生，会直接污染下游检索条件，而且因为最终答案看起来还是通顺的，用户往往不会立刻察觉，等到发现时已经积累了一批错误输出。

我的排查手法是给每个工具调用记录完整的入参和出参，上线时盯着日志跑几天，把参数异常的样本收集起来，用少量样本优化工具描述，或者在工具层加规则校验。这个阶段的自动化测试别省，准备一份覆盖常见参数组合的测试集，每次改动都完整回归一遍，能挡住大多数回归性问题。另外数据权限穿透也要重点盯，Agentic 流程会拆解问题并扩大检索范围，稍不注意就可能查到当前用户无权访问的内容。生产上必须在检索层强制做权限过滤，不能把权限判断完全交给模型自觉，因为模型对权限边界的理解今天对、明天可能就偏了，而且这种错误在常规评测集里很难覆盖到，必须在架构上兜住。

6. 一点个人体会与后续方向

6.1 这个项目给我最大的教训

做这个项目的过程中，我最大的反思是：Agentic RAG 的复杂度不是来自某个单一环节，而是来自环节之间的协作。传统 RAG 里，你只要把每个环节各自调好，整体效果不会差太多；但 Agentic 系统里，一个规划决策会传导到后面所有的检索和生成，一个环节的小概率异常会被放大成最终答案的严重错误。

所以我现在做这类系统的第一原则是：先把确定性做实，再谈智能性。每个节点的输入输出格式、终止条件、失败处理都要先定死，让模型的自由度只在允许的区间里发挥。这样系统即使是 Agent 驱动，行为依然是可预期、可测试、可回滚的。代码评审的时候，大家现在都会先问“这个节点的失败路径是什么”，而不是只关心“效果看起来多聪明”。

6.2 给正在做类似项目的人一个建议

如果让我给正在做类似项目的人一个建议，我会说：从一个最窄的业务场景开始，把一条完整的 Agent 检索路径跑到生产环境，把观测和评估搭好，再去扩展场景。别一上来就追求大而全的架构，先用最笨的方式把链路跑通，再逐步把智能和弹性加进去。

这个顺序走下来，你收获的不是一个炫酷的框架，而是一套能稳定扛住业务压力的基础设施。我也建议把每次线上故障的复盘都沉淀成文档，尤其记录那些“模型行为不可控”导致的诡异问题，因为这类问题靠经验积累的价值，远高于任何框架层面的技术选型。后续这个项目我打算在两条线上继续深挖：一条是让规划节点更精准地利用本地知识做工具选择，另一条是把检索评估的自动化程度再提一个台阶，目标是让整个 Pipeline 的每一次检索行为都能被量化和审计。