1. 生产级知识库与 Agent 网关的整体设计思路1.1 为什么要把知识库和 Agent 网关放在一起谈单独做一个 RAG 知识库或者单独搭一个 Agent 调度服务其实都不算太难。难的是把这两样东西放到生产环境里让它们稳定地协同工作。我最近这段时间主要就在干这件事一边优化知识库的检索质量一边把 Agent 的调用入口收敛到一个统一的网关上。先说清楚这两个东西各自是什么。知识库负责把文档、FAQ、内部资料切块、向量化、建索引然后对外提供检索能力。Agent 网关则是所有智能体请求的统一入口负责路由、鉴权、限流、日志、模型选择、工具调用编排这些事情。把它们放在一起是因为实际业务里 Agent 回答问题时几乎都要先去知识库里捞一遍相关内容再交给大模型组织语言。如果这两层各自为政延迟、成本、可观测性都会失控。我见过不少团队的做法是Agent 直接调向量库 SDK向量库前面没有任何缓存和降级检索挂了整个问答就挂了。这种架构在 demo 阶段没问题一上生产就原形毕露。所以我的核心思路是——把知识库当成网关后面的一个标准下游服务而不是让 Agent 直接裸连。这样网关可以统一做超时控制、重试、熔断、结果缓存知识库本身也能独立扩容和灰度。这套设计适合谁参考我觉得三类人最有用一是正在从 demo 往生产迁移的 RAG 项目开发者二是需要统一管理多个 Agent 的后端工程师三是想搞清楚 RAG 和 Agent 网关边界的产品或架构同学。哪怕你只是用 Dify 或者类似平台搭个人知识库理解这层分层逻辑也能帮你少踩很多坑。1.2 分层架构与职责边界我把整套系统拆成四层从下往上分别是存储层、检索层、网关层、Agent 编排层。这个分层不是拍脑袋定的而是根据变更频率和故障影响面来划分的。存储层放向量库和全文索引变更频率最低但一旦出问题影响面最大。检索层封装混合检索逻辑向量 BM25是知识库的核心竞争力所在。网关层是所有流量的必经之路变更频率中等但要求极高的稳定性。Agent 编排层变更最频繁业务逻辑天天改所以它必须和下面三层解耦。提示分层的关键判断标准是谁经常改谁就放上面。如果你把频繁变更的业务逻辑和稳定的检索逻辑混在一起每次改需求都要重新测试整条链路维护成本会爆炸。这里有个容易被忽略的点网关不只是转发。它要承担协议转换的职责。比如 Agent 层用统一的内部协议调用网关网关再根据下游是向量库、BM25 服务还是 rerank 模型转换成对应的请求格式。这样做的好处是将来换向量库比如从一款换成另一款Agent 层完全不用动。1.3 技术选型背后的取舍逻辑选型这块我踩过不少坑说几个关键决策。向量检索 BM25 混合而不是纯向量。纯向量检索在语义匹配上强但对专有名词、型号、编号这类精确匹配很弱。比如用户问XX-2000 型号的参数纯向量可能召回一堆语义相近但型号不对的文档。BM25 基于词频和逆文档频率对精确词命中非常敏感。两者融合常用 RRF 倒数排名融合能显著提升召回率。实测下来混合检索比纯向量在内部知识库场景的召回率能高出 15 到 25 个百分点。网关用轻量级反向代理而不是重型 API 网关。很多团队一上来就上全套 API 网关功能是强但配置复杂、资源占用高。我的场景里核心需求就是路由、限流、鉴权、日志这四样用一个轻量方案加自定义中间件就够了。选型原则是功能够用即可运维复杂度要低。Agent 编排层保持无状态。所有会话状态、缓存状态都放到外部存储Redis 之类。这样 Agent 层可以随意水平扩容某个实例挂了也不影响会话连续性。这是生产级和玩具项目的分水岭。2. 知识库检索质量的核心细节与实操要点2.1 文档切块策略切得好检索就成功了一半切块chunking是 RAG 里最被低估的环节。我见过太多项目检索效果差最后发现是切块切得稀碎。切块的核心矛盾是块太大噪声多检索精度低块太小语义不完整大模型拼不出完整答案。我的经验值是中文技术文档单块控制在 300 到 500 字比较合适。但这个数字不能死守要按文档结构动态调整。具体做法是按语义边界切而不是按固定字数切。优先在标题、段落、列表项这些自然边界处断开实在没有边界再按字数硬切。# 基于语义边界的切块示意伪代码思路 def smart_chunk(text, max_len500, overlap50): # 1. 先按标题层级切大段 sections split_by_heading(text) chunks [] for sec in sections: # 2. 段落内再按句子边界聚合接近 max_len 就断开 for para in split_by_paragraph(sec): if len(para) max_len: chunks.append(para) else: chunks.extend(split_by_sentence(para, max_len)) # 3. 相邻块之间保留 overlap避免语义断裂 return add_overlap(chunks, overlap)overlap重叠这个参数很关键。我一般设成块大小的 10% 到 15%。它的作用是防止一个完整语义被切断后两块都检索不到。比如一句话跨在两个块中间有重叠就能保证至少有一块包含完整语义。注意切块时一定要保留元数据。每个块要带上来源文档、章节标题、页码、更新时间。这些元数据在后续过滤和结果展示时非常有用丢了就补不回来了。2.2 BM25 参数调优与中文分词BM25 有两个核心参数k1 和 b。k1 控制词频饱和度b 控制文档长度归一化。默认值一般是 k11.2、b0.75但中文场景我建议微调。b 这个参数特别重要。b0 表示完全不考虑文档长度b1 表示完全归一化。中文文档长度差异大如果 b 设得太低长文档会因为词频高而占便宜。我实测下来中文知识库 b 设在 0.6 到 0.8 之间比较稳具体要看你的文档长度分布。中文分词是另一个坑。BM25 本质是基于词的中文没有天然空格必须分词。分词器选不好BM25 效果直接废掉。我的建议是通用场景用 jieba 这类成熟分词器专业领域一定要加自定义词典。比如你的知识库全是医疗术语通用词典会把心肌梗死切成心肌和梗死检索时就容易漏。import jieba # 加载领域自定义词典这是提升 BM25 命中率的关键一步 jieba.load_userdict(domain_dict.txt) def tokenize(text): # 搜索引擎模式对长词再切分提高召回 return list(jieba.cut_for_search(text))自定义词典怎么建从你的知识库里统计高频专有名词人工筛一遍几百个词就能覆盖大部分场景。这个投入产出比极高比换更贵的 embedding 模型划算多了。2.3 混合检索的融合策略向量检索和 BM25 各出一批结果后怎么融合是个技术活。常见方法有三种加权求和、RRF倒数排名融合、以及先粗排再精排。我最推荐RRF因为它不需要归一化分数对两路检索的分数尺度不敏感。向量相似度是 0 到 1 的余弦值BM25 分数可能是任意正数直接加权求和很容易被量纲带偏。RRF 只看排名公式是每路结果按1/(k rank)累加k 一般取 60。融合方法优点缺点适用场景加权求和实现简单需归一化权重难调两路分数尺度接近RRF无需归一化鲁棒丢失分数信息通用推荐先粗排再精排精度最高需额外 rerank 模型延迟高对精度要求极高融合之后如果对精度要求高可以再加一层 rerank。rerank 模型交叉编码器会把 query 和每个候选块一起过一遍模型精度比向量检索高很多但慢。我的做法是粗排召回 50 条rerank 后取前 5 条。这样既保证精度又控制延迟。2.4 检索结果的缓存与降级生产环境里知识库检索是高频操作缓存能省下大量算力。但缓存有个陷阱知识库更新后缓存必须失效。我的做法是给每个文档块打上版本号缓存 key 里带上版本号文档一更新版本号就变旧缓存自然失效。降级策略也很重要。如果向量库挂了网关应该能自动降级到只用 BM25虽然精度下降但至少服务不中断。这个降级逻辑放在网关层做知识库本身不用感知。提示缓存不要缓存最终答案要缓存检索结果。因为最终答案依赖大模型缓存答案会导致用户拿到过期信息。缓存检索结果让大模型每次重新组织既省算力又保证时效。3. Agent 网关的实操实现与关键环节3.1 网关的核心职责拆解Agent 网关听起来玄乎拆开看就是几件具体的事。我把它归纳成五个职责路由分发、鉴权限流、协议转换、可观测性、故障隔离。这五件事每一件都直接关系到生产稳定性。路由分发是基础。网关要根据请求里的 Agent 标识、租户标识、甚至请求内容决定把请求发给哪个下游。比如知识库检索请求发给检索服务工具调用请求发给工具执行器。路由规则要支持热更新不能改个规则就重启网关。鉴权限流是保命的。没有限流一个异常客户端就能把整个后端打垮。我的限流策略是分层限流按租户限、按接口限、按 IP 限三层叠加。任何一层超限就拒绝返回明确的错误码。协议转换是解耦的关键。Agent 层用统一协议网关负责翻译成下游能懂的格式。这样下游换实现Agent 层无感。可观测性包括日志、指标、链路追踪。每个请求必须有一个贯穿全链路的 trace id从网关入口一直传到知识库和模型调用。出问题时凭一个 trace id 就能还原整个调用过程。故障隔离靠熔断和超时。下游某个服务变慢网关要能快速失败不能让它拖垮整个网关。3.2 请求路由与协议转换的实现路由这块我用的是配置驱动的方式。所有路由规则写在一个配置里网关启动时加载支持运行时热更新。规则匹配用前缀树或者正则看你的规则复杂度。# 路由配置示例 routes [ { match: {path: /v1/retrieve, tenant: *}, upstream: retrieval_service, timeout_ms: 800, retry: 1 }, { match: {path: /v1/agent/chat, tenant: *}, upstream: agent_orchestrator, timeout_ms: 30000, retry: 0 } ]注意这里的 timeout 设置差异很大。检索服务我设 800 毫秒因为检索本身应该很快超过这个时间说明有问题快速失败比让用户干等好。Agent 编排涉及大模型生成设 30 秒因为大模型本来就慢重试也没意义重试一次又是 30 秒所以 retry 设 0。协议转换我举一个具体例子。Agent 层发来的检索请求是统一格式{ query: 如何配置超时, top_k: 5, filters: {doc_type: manual} }网关要把它转换成向量库和 BM25 服务各自的格式分别调用再融合结果。这个转换逻辑封装在网关的适配器里Agent 层完全不用关心下游是什么。3.3 限流、熔断与超时的参数计算限流参数不能拍脑袋定要基于实测容量算。我的方法是先压测出单实例的 QPS 上限然后按 70% 设限流阈值。留 30% 余量是为了应对突发流量和性能波动。举个例子压测发现检索服务单实例能扛 200 QPS部署了 4 个实例总容量 800 QPS。那网关对检索的限流阈值就设 560 QPS800 的 70%。超过就拒绝保护后端。熔断用经典的滑动窗口 错误率阈值。我设的规则是10 秒窗口内如果请求数超过 20 且错误率超过 50%就熔断 30 秒。熔断期间请求直接失败30 秒后放少量请求试探成功就恢复。超时参数要分层设置而且上游超时必须大于下游超时。比如网关到检索服务超时 800 毫秒那检索服务内部调用向量库的超时就得设 500 毫秒留 300 毫秒给网络和序列化。如果反过来网关 800 毫秒超时了检索服务还在等向量库就会产生大量僵尸请求。注意超时时间不是越长越好。超时设太长慢请求会占满连接池导致正常请求也排队。宁可快速失败让客户端重试也不要让请求堆积。3.4 可观测性日志、指标与链路追踪可观测性这块我的原则是三个必须必须有 trace id、必须有结构化日志、必须有核心指标。trace id 在网关入口生成通过 HTTP header 往下传。所有下游服务的日志都带上这个 id。这样排查问题时用 trace id 一搜整条链路的日志全出来了。结构化日志用 JSON 格式字段固定。我必记的字段有trace_id、tenant、path、upstream、status、latency_ms、error。这样日志可以直接进日志系统做聚合分析。核心指标我用四类QPS、延迟分位数P50/P95/P99、错误率、熔断次数。延迟一定要看 P99平均值会骗人。P99 高说明有长尾请求用户体验差。指标含义告警阈值建议P99 延迟99% 请求的延迟上限超过基线 2 倍告警错误率失败请求占比超过 1% 告警熔断次数触发熔断的次数大于 0 就关注限流拒绝率被限流的请求占比持续大于 5% 需扩容4. 常见问题与排查技巧实录4.1 检索召回不准的排查路径召回不准是最常见的问题排查要按顺序来别乱试。我的排查顺序是先看切块再看分词再看 embedding最后看融合。第一步看切块。把召回的块和没召回的块都打印出来人工看。如果没召回的块本身语义就不完整那就是切块问题。我遇到过把一张表格切成十几块的情况每块就几个字检索根本没法用。第二步看分词。把 query 和文档的分词结果都打出来对比。如果 query 里的关键词在文档里被切成了不同的词BM25 就命中不了。这时候加自定义词典。第三步看 embedding。如果语义相近但召回不到可能是 embedding 模型不适合你的领域。可以拿几对已知相似的文本算一下余弦相似度看是否合理。第四步看融合。如果两路单独检索都能召回融合后反而丢了那是融合权重或 RRF 参数的问题。4.2 Agent 调用超时与雪崩的应对Agent 调用超时往往不是单点问题而是雪崩的前兆。我遇到过一次某个下游服务变慢导致网关连接池被占满然后所有请求都超时整个系统瘫痪。应对雪崩的核心是快速失败 隔离。具体措施一是给每个下游设置独立的连接池一个下游慢不影响其他下游二是熔断下游错误率高就快速失败三是超时绝不允许请求无限等待。还有一个容易被忽略的点大模型调用要设最大 token 数。如果不设模型可能生成超长内容占用大量时间和资源。我一般设 2000 token 上限够用且可控。4.3 缓存穿透、击穿、雪崩的防护缓存这三个经典问题在知识库场景里都会遇到。穿透查询一个不存在的文档缓存和数据库都没有每次都打到数据库。防护方法是缓存空结果或者用布隆过滤器拦截。击穿某个热点 key 过期瞬间大量请求同时打到数据库。防护方法是热点 key 永不过期或者加互斥锁只让一个请求去回源。雪崩大量 key 同时过期。防护方法是给过期时间加随机抖动比如基础 10 分钟随机加 0 到 2 分钟。import random def set_cache(key, value, base_ttl600): # 加随机抖动避免同时过期 ttl base_ttl random.randint(0, 120) redis.setex(key, ttl, value)4.4 常见问题速查表现象可能原因排查方向解决手段召回率低切块太碎/分词不当打印召回块和分词结果调整切块、加自定义词典延迟高无缓存/rerank 太重看 P99 延迟分布加缓存、减少 rerank 候选数频繁超时下游慢/连接池满看下游延迟和连接数熔断、隔离连接池、调超时缓存不生效key 设计问题/版本未更新看缓存命中率检查 key、加版本号限流误伤阈值太低/统计窗口太短看限流拒绝率调高阈值、拉长窗口4.5 几个踩坑后的独家经验最后分享几个文档里不会写、但实际很关键的经验。第一知识库更新要有灰度。新文档入库后先只对内部账号可见观察检索效果没问题再全量。我吃过亏一次批量导入了几千篇文档结果里面有不少重复和过期内容检索质量直接崩了回滚又很麻烦。第二网关的配置变更要能回滚。路由规则、限流阈值这些配置改错了影响面很大。我的做法是配置版本化每次变更记录版本出问题一键回滚到上个版本。第三监控要监控业务指标不只是技术指标。技术指标QPS、延迟正常不代表业务正常。比如检索返回了结果但结果全是无关的技术指标看不出来。所以要加业务指标比如检索结果被采纳率、用户追问率。追问率高往往说明首次回答质量差。第四压测要用真实流量回放。用造的数据压测和真实流量差别很大。真实 query 的长度分布、关键词分布、并发模式都不一样。有条件的话把生产流量录下来回放压测结果才可信。这套东西我陆陆续续优化了小半年从最初的能跑到现在能扛住生产流量中间踩的坑基本都写在这了。知识库和 Agent 网关这两块本质上都是细节决定成败的活没有哪个单点技术特别难难的是把每个细节都做扎实让它们稳定地协同起来。