1. 从一次线上抖动说起知识库和 Agent 网关到底在解决什么问题做生产级知识库和 Agent 网关这件事最初并不是因为我想造一个多复杂的系统而是被一次线上抖动逼出来的。当时我们内部有一个问答助手底层挂着一个不算大的文档库大概几万份文档日调用量在几千次左右。平时用着还行直到某天运营同事批量导入了一批新文档检索结果突然开始出现大量不相关的片段回答质量肉眼可见地下滑。排查了一圈才发现问题不在模型而在检索层向量召回把语义相近但业务上完全无关的内容排到了前面而原本负责兜底的 BM25 关键词召回权重被压得太低导致专有名词、编号、型号这类精确匹配需求直接失效。这件事让我意识到一个能跑 demo 的知识库和一个生产级知识库之间差的不是模型能力而是检索策略的工程化和请求入口的统一治理。前者决定回答准不准后者决定系统稳不稳。而 Agent 网关就是那个把所有模型调用、工具调用、检索调用收口到一起的入口层。它要处理的不只是转发还有限流、降级、路由、可观测性、成本核算这些脏活累活。所以这篇内容我想聊的是我在优化生产级知识库和 Agent 网关过程中踩过的坑、做过的取舍以及那些文档里不会写但实际会要命的细节。适合正在做 RAG 项目、准备把知识库从 demo 推向生产、或者正在设计 Agent 网关的同行参考。不管你是刚接触 RAG 和 BM25 的新手还是已经在调 Agent 框架的老手应该都能从里面找到一些能直接抄作业的东西。2. 检索层优化BM25 和向量召回到底该怎么配比2.1 为什么纯向量召回在生产环境里经常翻车很多人做 RAG 的第一反应是上向量数据库做 embedding语义检索一把梭。demo 阶段确实好用因为文档少、问题简单、语义匹配就能覆盖大部分场景。但一旦进入生产问题就暴露了。向量召回的本质是语义相似度它擅长处理意思相近但用词不同的情况比如用户问怎么重置密码文档里写的是账户密码恢复流程这种它能召回。但它有个致命弱点对精确匹配不敏感。当用户问的是ERR-4021 报错怎么处理而文档里恰好有一篇专门讲 ERR-4021 的向量召回很可能因为这篇文档整体语义和问题不够像把它排到第五第六位甚至召回不进来。而 BM25 这种基于词频和逆文档频率的算法恰恰能把这种精确匹配顶到最前面。我在实际项目里做过对比测试同一批 200 条真实用户 query纯向量召回的 Top5 命中率大概在 72% 左右而 BM25 单独跑只有 58%但两者混合之后能到 89%。这个差距在生产环境里就是能用和不能用的区别。2.2 BM25 的分数为什么不能直接和向量分数相加这是我最开始踩的一个大坑。想当然地认为把 BM25 分数和向量相似度分数加权相加调个权重就完事了。结果发现两个分数的量纲完全不一样BM25 分数是无上界的正数可能是个位数也可能是几十而向量相似度通常是0 到 1 之间的余弦值。直接相加等于让 BM25 主导了整个排序向量召回形同虚设。正确的做法是先做分数归一化把两路分数映射到同一个区间再融合。常见的融合方式有三种融合方式原理适用场景注意事项加权求和归一化后按权重相加两路召回质量接近权重需要按业务调建议从 0.5 起步RRF 倒数排名融合按排名而非分数融合两路分数量纲差异大对异常分数不敏感鲁棒性好级联召回先向量粗排再 BM25 精排文档量极大延迟会叠加需控制候选集大小我个人在生产环境里更倾向RRF因为它只看排名不看绝对分数天然规避了归一化带来的偏差。RRF 的核心公式是score Σ 1/(k rank)k 一般取 60。这个值不是拍脑袋来的k 越大排名靠后的文档权重被拉得越平适合召回结果质量参差的情况k 越小头部文档优势越明显。我实测下来 k 在 40 到 80 之间对结果影响不大60 是个稳妥的默认值。2.3 分块策略对检索质量的影响被严重低估聊检索策略的时候很多人只盯着召回算法却忽略了分块这个上游环节。分块分得不好再好的召回算法也救不回来。我见过最常见的错误是按固定字数硬切比如每 500 字一块。这种做法在技术文档上会直接把一个完整的操作步骤切成两半用户召回上半块看到的是第一步打开配置面板然后没了。正确的做法是按语义边界切优先在段落、标题、列表项这些自然边界处断开。具体到实操我一般用这样的策略先按 Markdown 标题层级切大块再在大块内部按段落切如果单个段落超过阈值比如 800 字再按句子边界二次切分。同时给每个块加上上下文前缀比如把所属的章节标题拼到块内容前面。这个前缀看起来不起眼但对向量召回帮助很大因为它给块补充了语义背景。还有一个细节是块重叠。相邻块之间保留 10% 到 20% 的重叠能避免关键信息正好卡在切分点上被割裂。重叠太多会引入冗余太少又起不到保护作用15% 左右是个比较舒服的值。2.4 元数据过滤被忽视的召回精度放大器生产级知识库和 demo 最大的区别之一是元数据的丰富程度。demo 里文档就是一堆文本生产里每份文档都带着来源、部门、版本、生效时间、密级这些属性。这些元数据在检索时能发挥巨大作用。比如用户问的是最新的报销标准你可以在召回前先按生效时间倒序过滤把过期文档直接排除掉。再比如用户是财务部门的可以优先召回财务相关的文档。这种前置过滤比事后重排高效得多因为它直接缩小了候选集。我在网关层做了一个元数据过滤的 DSL让业务方可以声明式地配置过滤条件比如dept finance AND status active。这样检索层不用关心业务规则只负责执行过滤职责清晰。3. Agent 网关不只是转发而是治理3.1 网关要解决的核心问题把散落的调用收口在没有网关之前我们的 Agent 调用是散落在各个业务代码里的。A 服务直接调模型 APIB 服务直接调检索接口C 服务自己拼 prompt。结果就是想加个限流得改五个地方想统计 token 消耗得在每个调用点埋点某个模型挂了想切备用得挨个改配置。Agent 网关的核心价值就是收口。所有对模型、检索、工具的调用都经过网关网关统一处理鉴权、限流、路由、重试、日志、计费。业务方只需要关心我要什么能力不用关心这个能力背后是谁提供的。这个思路和微服务里的 API 网关是一脉相承的只不过 Agent 网关多了几个特殊维度模型路由同一个请求可以路由到不同模型、工具编排一次请求可能触发多个工具调用、上下文管理多轮对话的状态维护。3.2 模型路由的三种策略和它们的代价模型路由是网关里最容易被低估的部分。很多人以为路由就是配个权重轮询实际上要考虑的维度多得多。第一种是按成本路由。便宜的模型处理简单请求贵的模型处理复杂请求。判断简单和复杂可以用请求长度、历史轮次、是否包含工具调用等信号。这种策略省钱效果明显但代价是质量不稳定因为简单和复杂的边界很难划准。第二种是按能力路由。比如需要长上下文的路由到支持大窗口的模型需要函数调用的路由到支持 tool use 的模型。这种策略质量有保障但需要维护一张能力矩阵模型一多维护成本就上来了。第三种是按可用性路由。主模型超时或报错时自动切备用。这是保底策略必须有但要注意熔断不能主模型一抖动就疯狂切备用否则备用也会被打挂。我在实际项目里是三种策略叠加使用先按能力筛出候选模型再按成本排序最后按可用性做兜底。路由决策的日志一定要打全否则出了问题根本不知道请求被路由到了哪里。3.3 限流和降级生产环境的保命机制限流这件事不做的时候觉得没必要做的时候才发现处处是坑。最朴素的限流是固定窗口计数比如每分钟最多 100 次。但它有个临界问题第 59 秒来 100 次第 61 秒又来 100 次等于两秒内放了 200 次。滑动窗口能缓解这个问题但实现复杂度上来了。令牌桶则允许一定程度的突发更适合 Agent 这种请求不均匀的场景。我最后选的是令牌桶桶容量设为平均 QPS 的 2 倍填充速率按平均 QPS。这样既能扛住短时突发又不会让长期速率超标。降级比限流更微妙。当检索服务挂了Agent 是直接报错还是退化成纯模型回答我的做法是分级降级检索超时先重试一次还失败就退化成不带检索的纯生成同时在响应里标记本次回答未使用知识库。这样用户至少能拿到一个回答而不是一个错误页。但降级一定要可观测否则你会以为系统一切正常实际上检索早就挂了。3.4 可观测性没有它优化就是盲人摸象Agent 网关的可观测性我建议至少覆盖四个维度请求维度QPS、延迟分布P50/P95/P99、错误率模型维度各模型的调用量、token 消耗、首 token 延迟检索维度召回数量、召回耗时、命中率业务维度按租户、按场景拆分的调用量和成本这里有个经验延迟一定要看 P99不能只看平均值。平均值 200ms 看着很美但 P99 可能是 5 秒那 1% 的用户体验就是灾难。Agent 场景里一次请求可能串行调用多个模型和工具延迟是累加的P99 超标往往意味着某个环节有长尾。trace 的粒度也很关键。我建议给每次请求打一个 trace id把网关、检索、模型调用、工具调用的 span 都串起来。这样排查问题时能一眼看出时间花在了哪。没有 trace 的时候排查一次慢请求要翻好几个服务的日志有了 trace 直接看火焰图。4. 知识库和 Agent 的协同RAG 在网关里怎么落地4.1 RAG 不应该是一个独立服务而应该是网关的一个能力早期我把 RAG 做成了一个独立服务Agent 需要检索时去调它。后来发现这样有个问题检索和生成的上下文管理割裂了。检索服务不知道这次对话的历史Agent 不知道检索的原始分数两边信息不对称导致重排和 prompt 拼接都很别扭。后来我把 RAG 能力下沉到网关内部作为网关的一个内置能力。Agent 发起请求时网关根据配置决定是否触发检索检索结果直接在网关内部完成重排和 prompt 拼接再送给模型。这样上下文是连贯的检索分数、元数据、历史轮次都能参与决策。这个改动带来的直接好处是延迟降低。原来检索和生成之间有一次网络往返现在都在网关进程内完成省掉了序列化和网络开销。实测 P95 延迟降了大概 15%。4.2 多轮对话里的检索 query 改写多轮对话是 RAG 的一个难点。用户第一轮问报销标准是什么第二轮问那出差呢如果直接拿那出差呢去检索召回质量会惨不忍睹因为这句话本身信息量太低。解决办法是query 改写结合对话历史把当前 query 补全成一个自包含的检索 query。上面那个例子改写后应该是出差报销标准是什么。改写可以用小模型来做成本低、延迟小。但改写也有风险就是改写跑偏。小模型可能把用户的原意改没了。我的做法是双路检索改写后的 query 和原始 query 都去检索结果合并。这样即使改写失败原始 query 还能兜底。代价是检索次数翻倍但检索本身比生成便宜得多这个成本可以接受。4.3 工具调用和检索的编排顺序Agent 场景里检索和工具调用经常要混在一起。比如用户问帮我查一下上个月的销售数据并对比一下去年同期这需要先调数据库工具再检索知识库里的分析模板最后生成对比。编排顺序直接影响效果。我的经验是先检索后工具因为检索能提供背景知识帮助模型更好地构造工具调用参数。但也有例外如果工具调用的结果是检索的必要输入比如先查到订单号再检索这个订单的文档那就得反过来。网关层我做了声明式编排业务方用配置描述先做什么、再做什么、什么条件下跳过网关按配置执行。这样不用写代码就能调整编排逻辑迭代速度快很多。5. 那些文档里不会写的踩坑记录5.1 embedding 模型换版本导致的召回漂移这个坑我踩得最惨。有次升级了 embedding 模型从 v1 换到 v2想着新版本效果更好。结果上线后召回质量不升反降。排查了半天才发现新旧模型的向量空间不兼容库里存的还是 v1 的向量query 用的是 v2 的向量两者根本不在一个空间里算出来的相似度毫无意义。教训是换 embedding 模型必须全量重建索引不能只换 query 侧。而且重建期间要有双写或灰度方案否则服务会中断。后来我加了个校验网关启动时检查 embedding 模型版本和索引版本是否一致不一致直接拒绝启动避免带病上线。5.2 长文档截断导致的答非所问模型有上下文窗口限制超长文档必须截断。但截断的位置很讲究。如果从中间硬截可能把结论截掉只留下铺垫模型基于残缺信息生成就会答非所问。我的做法是按重要性截断优先保留文档的开头通常是概述和结尾通常是结论中间部分按段落重要性排序后填充。段落重要性可以用 BM25 对 query 打分来算和 query 相关的段落优先保留。这样即使截断保留的也是和问题最相关的部分。5.3 网关超时设置和模型实际延迟的错配网关的超时设置如果比模型的实际 P99 延迟还短就会导致大量请求被误杀。我见过一个配置网关超时设 10 秒但某个模型在高峰期 P99 能到 12 秒结果高峰期错误率飙升还以为是模型服务挂了。正确的做法是超时设置要参考实测的 P99 再加 buffer而且不同模型、不同场景的超时应该分开配。简单问答可以设短一点复杂推理要设长一点。同时网关要记录超时发生时的实际耗时这样才能知道是超时设短了还是模型真的慢了。5.4 缓存失效策略没做好导致的旧答案给检索和生成加缓存能大幅降低成本但缓存失效是个大坑。文档更新了缓存里的旧答案还在用户就会拿到过时信息。我的策略是按文档版本做缓存 key。每份文档有个版本号文档更新时版本号递增缓存 key 里带上版本号版本一变缓存自然失效。对于生成结果的缓存还要考虑 prompt 模板的版本模板改了缓存也得失效。这些版本号统一由网关管理业务方不用操心。6. 性能调优从能用走向好用6.1 检索层的并行化和批量化检索层最容易优化的点是并行。向量召回和 BM25 召回本来就可以并行跑没必要串行。我用 asyncio 把两路召回并发执行整体检索延迟从两路之和变成了两路的最大值效果立竿见影。批量化也很重要。如果一次请求要检索多个 query比如多轮对话的 query 改写场景不要一个个串行查而是攒成一批一次性查。向量数据库和 BM25 引擎通常都支持批量查询批量查的吞吐比单条查高一个数量级。6.2 网关层的连接池和预热网关作为所有请求的入口连接管理直接影响吞吐。到模型服务、检索服务、数据库的连接都要用连接池避免每次请求都新建连接。连接池大小要按并发量调太小会成为瓶颈太大又会浪费资源。还有一个容易被忽略的是预热。网关刚启动时连接池是空的第一批请求会慢。我的做法是启动时主动建立一批连接把连接池填到最小空闲数这样第一批请求也能快速响应。6.3 成本优化的几个实操手段Agent 的成本大头在 token 消耗。几个实测有效的优化手段prompt 压缩把冗余的 system prompt 精简去掉重复的指令。我见过一个 system prompt 写了 2000 字精简到 500 字后效果没变成本降了 30%。结果缓存高频重复问题直接返回缓存不调模型。内部问答场景里重复问题占比能到 20% 以上。小模型兜底简单问题用小模型只有复杂问题才升级到大模型。判断逻辑放在网关层业务方无感。流式输出虽然不直接省钱但能改善体验让用户更早看到内容减少因等待而重复发起的请求。7. 我个人的一些经验和建议做生产级知识库和 Agent 网关这两年最大的体会是别追求一步到位要追求可迭代。一开始就设计一个完美架构往往因为过度设计而迟迟上不了线。不如先做一个能跑的最小版本把可观测性做扎实然后在真实流量里发现问题、迭代优化。另一个体会是检索质量比模型能力更重要。很多人一上来就想换更强的模型但实际项目里检索召回不准才是回答质量差的主因。把 BM25 和向量召回的融合调好把分块策略优化好效果提升比换模型明显得多而且成本低。最后一点是网关的配置要能热更新。生产环境里限流阈值、路由权重、超时时间这些参数经常要调如果每次调都要重启服务那运维成本太高。我用的方案是配置中心加监听配置一变网关自动生效不用重启。这个能力在应急的时候特别有用比如某个模型突然变慢可以立刻调低它的路由权重把流量切走。还有个小技巧给每次请求打上业务标签。比如标记这次请求来自哪个租户、哪个场景、哪个版本。这样出问题时能快速定位影响范围做成本分析时也能按标签拆分。标签的维度不要太多三五个就够太多反而增加维护负担。这套东西没有银弹每个业务场景的取舍都不一样。但把检索、路由、限流、可观测性这几块做扎实系统就能从能跑变成敢跑。剩下的就是在真实流量里慢慢磨了。