生产级RAG知识库与Agent网关优化实践：从检索到稳定性的全面改造

最近在优化生产级知识库和 Agent 网关这轮改造持续了大概三周踩了不少坑也把之前一直想动但不敢动的几个模块彻底重做了一遍。趁着记忆还热乎把这次的核心思路、改造细节和排查过程整理出来给同样在搞 RAG 知识库和 Agent 生产落地的朋友一个参考。先说背景。我们内部的知识库问答和 Agent 系统不是从零开始的从 demo 到上线跑了大半年稳定性一直靠人肉兜底。业务方从最开始试试看变成了真的在用一旦真的在用问题就藏不住了文档更新了检索不到、多轮对话偶尔断掉、模型供应商一升级全部 Agent 跟着抖、出了问题查半天不知道是哪一环。这轮优化就是围绕生产级三个字来的核心目标四个检索准、网关稳、故障可定位、改动可回滚。1. 为什么突然要大动干戈生产环境里真实暴露的问题任何架构调整都应该是被真实问题逼出来的不是为了追新。这次我们集中动手是因为过去一个月生产环境里连续出现了几件让人坐不住的事。第一件是知识库召回质量明显拖后腿。业务同学问上个月华东区的订单退款率是多少检索模块返回的是一堆关于退换货政策的文档片段跟具体数据完全不沾边。还有更典型的运营把新版产品手册传到知识库之后第二天再问相关问题答案还是旧版本的内容。这类问题出现多了业务方的信任度掉得很快因为用户不会管你底层是向量检索还是 BM25他只知道系统给的答案是错的。第二件是 Agent 执行链路的稳定性问题。我们的 Agent 不是单轮问答而是会调用内部工具完成多步任务比如查库存、算价格、生成报表。生产环境里经常出现报错信息Agent execution terminated due to error.用户看到的就是一个光秃秃的失败提示。翻日志发现有时候是模型工具调用超时有时候是中间某个环节把上下文撑爆了问题五花八门但都导向同一个结论执行链路缺少一个统一的风险控制层。第三件是网关层的不可观测。我们有多个模型 provider 在跑不同业务线注册了不同的知识库和 Agent。某个 Agent 出问题的时候很难快速判断是模型侧的问题、Prompt 的问题、工具的问题还是知识库检索返回的问题。月底对账的时候各个部门用了多少 token、调用频次是多少也全靠估算。这种状态在 demo 阶段能忍到了生产阶段就是定时炸弹。还有一个认知上的坑这里先提个醒标题里的网关指的是系统架构里的 API 网关层别和 BPMN 流程图里的那种排他网关并行网关概念混在一起。流程引擎里的网关是控制流程走向的节点而我们说的 Agent 网关是承载流量的中间层负责路由、鉴权、限流、审计这些系统级职责。这个区分不搞清楚后面沟通需求的时候会非常费劲。2. 知识库检索优化把搜不到变成搜得准的几个具体动作知识库这块我们花的时间最多因为检索质量直接决定 RAG 的上限。这里说的生产级知识库不是指能存多少文档而是指文档解析、文本切分、召回策略、效果评估这套链路都要达到能稳定交付业务结果的水平。2.1 先把文档解析做对PDF 表格、Word、Excel 不能一把梭很多人第一步就栽在文档解析上。我们早期用的是通用文本抽取库PDF 直接按文本流抽结果表格数据全乱了列和列对不上数字串在一起根本没法看。Word 文档更惨标题层级丢了之后切分出来的片段完全没有上下文逻辑。这次改造我们把文档类型分成三类处理。PDF 里带表格的改用专门的表格解析方案尽量保留表格结构把表格转成 Markdown 格式再入库普通文本类 PDF 才走常规文本抽取。Word 文档先转成 Markdown保留标题层级后面切分的时候能按标题边界走。Excel 文件单独一条流水线不走文本切分而是把每个 sheet 转成结构化记录每行作为一个独立条目方便后面做精确匹配。这里插一句Excel 进知识库这个需求在业务侧非常常见但通用切分器处理得极差总要单独写适配与其硬塞进文本链路不如单独设计。2.2 切分策略从固定 512 到父子分块检索准确率明显提升我们早期的切分方式是固定窗口512 token 一段128 token 重叠。这种方案的优点是实现简单缺点也很明显一段完整的业务规则可能被拦腰截断或者一个很短的标题被嵌在一大段无关内容里检索的时候很难命中。这次改成了父子分块方案。父块是一个较大的语义单元比如一个完整章节或一个二级标题下的整段内容用于向量化存索引子块是从父块里切出来的小片段用于精确召回。检索的时候先用子块向量召回命中了之后再把子块对应的父块内容喂给大模型。这么做的好处是召回精度高同时模型能拿到完整的上下文。如果只是想把效果快速提升一截又不想引入太重的框架可以直接在切分器里做标题感知解析文档时把标题级别记录下来切分时优先保持标题边界标题和正文放在同一个块里。这一步看起来不起眼但对我们场景的帮助非常明显尤其是产品手册、制度文档这类标题结构清晰的资料。表格和切分策略改造的效果可以看下面这组对比。项目改造前固定 512改造后父子分块 标题感知召回准确率人工标注测试集约 67%约 88%检索结果上下文完整性经常截断完整保留章节内容新文档生效速度多久取决于手动触发上传完成即入库2.3 召回链路向量 BM25 Rerank 三级召回Embedding 模型选型上我们最后用了开源的中文 Embedding 模型bge-m3 这一档本地部署不走外部 API一个是数据安全考虑另一个是生产环境稳定性考虑自己扛一个 GPU 服务比依赖外部接口心里踏实得多。向量维度不算低但配合 Milvus 做索引性能完全够用。不过光靠向量检索肯定不够。生产环境里很多问题是带专有名词和编号的比如内部系统代码、项目编号、人员工号这类文本向量化之后往往召回效果一般反而是传统的 BM25 关键词匹配更准。我们的做法是混合召回向量检索和 BM25 并行跑各自取 top 20合并后去重再进 Rerank 模型精排一次最后取 top 5 作为上下文。Rerank 这个环节是这次改造里提分最明显的。没有 Rerank 之前top 5 里经常混着一两个语义相似但实际不相关的片段加了 Rerank 之后那种看起来相关的干扰项基本被过滤掉了。不建议省掉这一步尤其生产环境宁可多几十毫秒的延迟也不能把错误上下文喂给模型。2.4 检索质量评估没有测试集一切优化都是玄学改造之前我们优化检索完全靠肉眼抽几条例子看效果这种方式的运气成分太大。这次我们花了差不多两天时间人工标注了 200 条真实业务问答对覆盖高频问题和容易混淆的边界场景比如退款流程和退款率计算口径这种容易张冠李戴的问题。有了这个测试集之后每次调切分参数、换 Embedding 模型、改召回策略都跑一遍回归对比用指标说话。指标上主要看两个Recall5 和 MRR。Recall5 反映的是正确答案有没有出现在前 5 个检索结果里MRR 反映的是正确答案排在第几位。这两项测试集数据从最初的 67% 提升到 88%之后我们对后续改动就有底气了不会出现这次改了感觉变好了但说不清好在哪的情况。3. Agent 网关的隐性职责路由、鉴权、限流和可观测怎么落Agent 网关这个名字听起来很专业实际上它做的事情非常朴素——所有 Agent 的请求都从它这里过一遍。为什么不直接让业务方调用模型 API因为那样的话模型供应商切换、API Key 管理、限流配额、调用审计这些事就会散落在各个业务线里完全失控。3.1 统一模型接入与故障转移生产环境里模型供应商不可能只有一家。OpenAI、国产大模型、开源模型私有化部署我们都在用。不同模型的接口格式、限流策略、计费方式都不一样。网关这一层把它们统一封装成一套内部接口业务方和 Agent 不需要关心底层用的哪家模型。网关层还要做故障转移。我们遇到过一次上游模型服务升级挂了如果网关配置了 failover请求会自动切换到备选模型用户无感知。这个能力在单模型直连的方案里是没法实现的。配置上我们对每个 provider 设置优先级和权重主 provider 超时 3 秒后自动降级到备 provider避免一个供应商抖动拖垮所有业务。3.2 限流和配额防止单个 Agent 耗尽公共资源生产环境里最怕的情况是某个业务方写了个死循环调用或者某个 Agent 的 Prompt 设计非常消耗 token直接把整个网关的资源打满。Agent 网关需要在接入层就做限流按 Agent、按业务线、按用户三个维度分别控制。我们的限流配置是这样的单用户每分钟最多 20 次请求单 Agent 每分钟最多 300 次请求单业务线每日 token 配额固定。超过阈值直接返回 429由客户端自行退避。限流算法用的令牌桶Redis 实现够用且稳定没必要引入更复杂的算法。这里特别提醒一句限流一定要有监控告警否则限流策略本身可能憋死正常流量。3.3 鉴权、审计与全链路追踪网关层一台 Agent 请求进来先校验 API Key 是否有效再校验这个业务方是否有权限访问对应知识库和 Agent。权限这块要细化到知识库级别A 业务线的 Agent 只能检索 A 业务线的知识库不能因为网关路由配错了就拿到 B 业务线的数据。做生产级改造的时候还有一个容易被忽略但非常关键的设计全链路追踪。之前我们排查问题靠翻不同服务的日志效率极低。这次给网关和 Agent 执行链路都接上了统一的 trace每个请求有一个 traceId从网关入口一直贯通到知识库检索、模型调用、工具执行每一步的耗时和状态都能在链路里看到。有了这个再出现Agent execution terminated due to error这类问题定位时间从小时级降到了分钟级。4. 生产级改造中最容易被忽略的几个决策点这一节分享几个我们在改造过程中反复权衡过的点。它们不一定是最高大上的技术但确实是最影响生产稳定性的地方。4.1 缓存设计Embedding 缓存和语义缓存知识库检索的延迟大头往往在向量化和网络请求上缓存能做不少事情。第一层是 Embedding 缓存同一段文本如果已经算过向量直接从 Redis 里取不再调用 Embedding 服务。这个对高频文档非常有效因为生产环境里很多问题都是围绕同一批核心文档打的。第二层是语义缓存。我们的场景里用户问题本身有大量重复和近似退货率怎么算退货率计算公式退货率是如何计算的虽然字面不同但意图一样。这类请求每次都走完整检索链路浪费很大。语义缓存的做法是先算一遍问题的 Embedding在缓存池里做相似度匹配相似度超过阈值我们设的是 0.92就直接返回缓存的答案。这里有个坑要先说清楚合理配置好的语义缓存命中率能到 30%但阈值不是越高越好也不是越低越好。调太高了缓存几乎不命中调太低了容易答非所问。上线后需要根据业务场景持续观察一段时间才能找到合适的平衡点。4.2 超时、重试、熔断的差异化配置生产级系统里超时和重试一定不是一刀切。模型调用和知识库检索的超时时间就应该不同。我们按接口类型分了四档知识库检索 500ms 超时重试 1 次Embedding 调用 800ms 超时重试 1 次模型生成 30s 超时不重试因为重试会导致重复计费和重复生成工具调用 10s 超时可重试 1 次。这个配置反复调过几轮之后才稳定下来网上抄来的默认超时配置在生产环境基本都要重新调。熔断的策略也设计过好几版。早期是简单的失败率熔断后来发现问题不少上游短暂抖动失败率达到阈值就熔断下游恢复了但熔断器还在打开状态反而影响了可用性。最后改成了看连续失败次数连续失败 10 次才打开熔断开关恢复探测间隔设 30 秒。这套更贴合我们上游稳定性不高但不会长时间挂掉的实际情况。4.3 多环境隔离和配置管理生产级改造和 demo 最大的区别之一就是多环境隔离。我们把配置项全部拆成了环境相关和环境无关两类Prompt 模板、切分参数是环境无关的跟着代码走模型 API Key、知识库连接串、Provider 地址是环境相关的放进配置中心按 dev、staging、prod 三套环境隔离。另外一个容易被忽视的点是配置变更需要支持灰度。网关层有个连接池参数调错了影响的可能就是所有业务。所以关键配置项我们做了运行时生效 按业务线灰度的能力在配置中心里针对某个 Agent 单独下发配置观察一段时间没问题再全量推下去。4.4 高可用部署多副本、优雅下线、HPA整个网关和知识库服务都部署在 K8s 里至少 2 副本起步。网关无状态扩容很轻松。知识库的向量检索服务稍微麻烦一点有状态且吃资源但也能通过副本加负载均衡扛过去。这里特别说下优雅下线服务收到 SIGTERM 信号后需要先告诉网关摘除流量等待存量请求处理完再退出而不是直接被杀掉导致请求失败。很多事故就是这么个细节没处理好造成的。5. 线上事故复盘Agent execution terminated due to error 的完整排查链路这一节是本次改造里最有教材价值的部分完整记录了一次线上故障从发现到定位再到修复的全过程希望能给大家一个可复制的排查思路。5.1 事故现象与第一反应现象是业务方在群里反馈某个 Agent 在处理一个复杂任务时经常报错报错信息就是Agent execution terminated due to error.而且不是每次都必现是偶发大概 20% 到 30% 的概率。这种偶发问题在生产里最棘手因为不好复现很多人第一反应是是不是模型抽风了然后就去查模型状态。我们的第一反应不是猜而是拉日志。因为网关已经接入了全链路追踪直接通过 traceId 定位到失败请求从入口开始一层一层往下看。5.2 日志逐层追踪看请求日志发现Agent 执行到调用工具查询数据这一步骤后紧接着就断了。这时候有两个怀疑方向工具服务本身挂了或者工具返回的数据有问题。查工具服务的监控发现服务正常响应时间也正常那就把工具返回的数据拿出来看。这一看问题就出来了。工具返回的结构化查询结果因为命中了一个宽表一次性返回了 3000 多行数据拼进消息上下文之后那个地方的文本长度接近三十几万字符直接把模型的上下文窗口撑爆了。模型端拒绝接收超长上下文Agent 框架接收到模型侧的异常无法继续规划下一步最终就抛出了Agent execution terminated due to error.5.3 根因定位工具返回长度击穿上下文本质原因是 Agent 的工具调用结果没有做长度防护。生产环境里工具返回的数据长度是动态的测试环境查出来 10 行数据没问题生产环境同一张表可能因为数据量增长返回上万行。工具返回的内容直接进上下文就会导致 prompt 长度不可控轻则请求被模型接口拒绝重则 token 花销爆炸。升级为生产级链路之前这类问题只能靠 Agent 自身的异常处理来兜底但大多数框架的兜底策略很简单告诉了模型一次出错了模型再试一次还是同样的长度或者不知道该怎么做最后就终止了。5.4 修复措施与后续预防修复分了三层做。第一层工具的返回结果做截断。无论工具返回多少数据默认最多只保留 top 50 行并且注明数据量过大当前展示前 50 行如需全量数据请联系管理员。这层兜底保证上下文长度永远可控。第二层工具返回内容做摘要。对于确实需要大模型分析全量数据的场景我们不把原始数据拼进去而是先把数据交给一个小模型做聚合统计把摘要结果喂给主线模型。比如5000 行销售数据变成总销售额 500 万环比增长 12%华东区占比最高既控制了 token信息密度反而更高。第三层增强 Agent 执行链路对工具返回异常的处理逻辑。工具返回前检查长度超过阈值走摘要流程如果摘要流程本身超时则给 Agent 返回一个明确的提示而不是让 Agent 在那边瞎试。同时我们在监控里加了工具返回长度的指标超过阈值自动告警防患于未然。这次事故排查完最大的收获是Agent 稳定性的关键不只是模型选得好不好更在于工具层和上下文层的防御机制做没做扎实。框架本身自带的调用机制是解决不了这种长度波动问题的必须自己在工具层设置防线。6. 评估体系怎么建没有评测的模型改动都是盲改如果现在回到开头让我说这次优化里最重要的一个变化那就是我们把评测这件事正式纳入了工程流程。之前改 Prompt、换模型、调切分参数都是感觉变好了就上线现在所有的改动都必须过一遍评估集跑完指标确认没有回归才能合入。6.1 评估集怎么构造我们构建了两套评估集。第一套是知识库检索评估集人工标注了 200 条问答对每条包含用户问题、正确答案所在的文档 ID、期望命中的片段。覆盖范围包括高频业务问题、带编号和专有名词的问题、容易语义混淆的问题、长尾冷门问题。第二套是 Agent 端到端评估集设了 50 个典型的 Agent 任务每个任务有明确的预期输出步骤和结果字段比如查询某订单状态并返回当前节点。构造评估集的过程很枯燥但这一步投入的时间在后面每次改动时都会成倍赚回来。没有评估集任何关于效果提升的说法都是主观的团队内部讨论容易变成各说各话。6.2 回归测试流程与评测方法现在每次改动我们都会跑一遍评估脚本。知识库相关的改动看 Recall5 和 MRRAgent 端到端的改动看任务完成率和关键字段正确率。输出结果直接对比 baseline用表格展示哪些场景变好了、哪些场景变差了。出现回归的场景改回去或者调整方案能上线的改动都是有数据支撑的。端到端评估部分我们也在尝试用 LLM-as-a-judge让一个大模型给 Agent 的回答打分跟人工评分做相关性验证目前相关性还不错但还没有完全替代人工属于辅助手段。人工抽检每周至少做一次确保自动评估没有偏离真实业务需求。6.3 上线流程影子模式与灰度发布评估集通过不代表可以直接全量上线。生产环境里文本数据复杂多变测试集覆盖不到的场景可能直接出问题。我们的流程是新方案先进影子模式把生产环境复制一份流量打到新链路对比新旧链路的输出差异。影子模式跑一天观察输出差异都在预期内再做灰度发布按 5%、20%、50%、100% 逐步放量。这套流程的前后对比非常明显以前改配置是全靠运气出问题再回滚现在是灰度推进每一步都有评估数据、有监控看板出问题能精准定位到批次。生产级改造不是说代码写得有多完美而是把所有相关环节都纳入可控流程。这一轮优化下来我最大的体会是知识库和 Agent 网关的优化真正花力气的地方不在于某一个单点技术有多厉害而是在于把整条链路的边界想清楚——检索质量和网关稳定性是基础可观测性是排查问题的手段评估体系则是所有优化决策的地基。如果你也在做类似的生产级改造建议按这个顺序推进先把链路打通再把可观测性做好然后建评估集最后才谈优化模型和 Prompt。一上来就调 Prompt 和模型没有基础设施工很容易陷入调好了但说不清为什么好的循环。最后再分享两个小技巧。一个是切分参数和召回参数不要拍脑袋定可以对历史线上日志回放一遍看看实际问答场景里的文档长度分布用真实数据来定初始值。另一个是语义缓存上线后记得监控命中率变化跑两周左右就会发现新热点文档出现的规律这时候可以主动预热高频问题让首次访问也不需要走完整链路。