这几周在给团队做 AI 能力中台正好做到第四期多 Provider 切换、RAG 知识库和 Agent 编排。这期内容其实是整个 AI 模块里最容易被低估的部分。很多团队一开始只想“接个 OpenAI API 完事”但真正放到生产环境会发现模型要换、知识库要拆、Agent 要控哪一环都绕不开架构设计。这篇就把我实际落地过程中的方案取舍、关键配置和踩坑记录整理出来希望能给正在做同样事情的朋友一点参考。1. 整体架构思路为什么不能把 Provider 写死在代码里1.1 核心需求拆解所谓 AI 模块架构拆到最底层其实就是三件事模型从哪来、知识从哪查、任务怎么编排。三者互相独立又必须协同工作。先看第一件事。市面上可用的模型服务远不止一家OpenAI、Anthropic、Google、DeepSeek、通义、智谱、Moonshot各家有各家擅长的场景。OpenAI 的 GPT 系列在通用对话和代码生成上表现稳定DeepSeek 在中文理解和性价比上很有优势Claude 在长文本和复杂推理上口碑不错。如果你的系统只在代码里硬编码了一个 provider 的 endpoint 和 api_key那后续每一次模型调整都要改代码重新发布。我见过一个真实案例业务方临时要上线一个法律咨询入口需要调用某国产模型做合规审查因为它的中文法律语料更好。但因为系统写死了 OpenAI 的 SDK 调用整个迭代花了整整一周这还是在顺风的情况下。再看第二件事。模型本身有知识截止时间也没法知道你们公司的内部制度、产品手册、历史故障记录。RAGRetrieval-Augmented Generation知识库就是解决这个问题的把私有文档导入向量数据库用户提问时先检索最相关的片段再把这些片段作为上下文喂给模型。这一层的关键在切块粒度、向量模型选择、命中策略任何一个环节不合适回答质量都会明显掉档。最后是 Agent 编排。单轮问答相对简单但真实业务往往是多步骤任务“查一下客户的上月账单对比他的历史消费习惯生成一份分析报告再推送给他”。这需要 Agent 能拆解任务、按序调用工具、维护中间状态还要能处理失败重试和上下文续接。架构上如果不提前做好编排层后面会陷入无穷无尽的回调地狱。这三件事在架构上对应三个模块Provider 管理模块、RAG 检索模块、Agent 编排模块。三者通过统一的配置中心和状态管理串起来各自又是可独立扩展的。1.2 方案选型为什么用统一网关而非直接调 SDK很多初版实现喜欢直接在业务代码里调某个模型的 SDK图省事。但一旦要加第二个模型代码里就会出现两套 SDK 的初始化逻辑第三套再加进来时已经没法维护了。我采用的方案是在中间加一层Provider Router模型路由网关。这一层对外暴露统一的 OpenAI 兼容接口对内管理各个 provider 的配置、鉴权、路由策略。业务侧不需要知道背后是哪个模型服务商只需要按统一格式提交请求。这么设计的好处有三个。第一业务解耦换模型不需要改业务代码。第二灰度可控可以按用户比例、按请求类型把流量分配到不同模型上。第三成本可观测所有请求都经过网关自然就有了统一的日志和计量点。选择统一网关而非直接调 SDK还解决了一个实际问题不同 SDK 的错误返回格式五花八门。OpenAI 的超时错误是一个样Claude 的限流错误是另一个样国产模型的错误码又不一样。统一网关可以把这些差异在入口处抹平比如把限流错误统一转成 429把上下文超长统一转成 400业务侧只需要处理几种标准错误码即可。2. Provider 切换的配置体系与动态路由实现2.1 统一协议选型以 OpenAI 兼容接口为标准具体实现上我让所有 provider 适配层都输出OpenAI 兼容格式。原因很简单这是目前事实上的行业标准绝大多数开源框架LangChain、LlamaIndex原生支持内部如果要接其他模型只要写一个 adapter 就好。每个 provider 在配置中心里对应一条记录providers: - name: openai-main type: openai base_url: https://api.openai.com/v1 api_key_env: OPENAI_API_KEY models: - gpt-4o - gpt-4o-mini weight: 70 timeout_ms: 30000 - name: deepseek-primary type: openai base_url: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY models: - deepseek-chat - deepseek-coder weight: 30 timeout_ms: 45000这里面有几个字段值得细说。base_url是用来指向各服务商兼容接口入口的很多报错信息里提到“provider 缺少 base_url 配置”就是这里没设置。api_key_env设计成环境变量名而不是明文是避免密钥泄露进代码库或配置中心。weight是权重路由用的比如 70% 流量落到 OpenAI30% 落到 DeepSeek用于灰度验证新模型。timeout_ms必须按模型实际表现配置有些国产模型推理速度慢超时设短了经常误报失败。配置热更新我用的是配置中心加本地缓存的模式。配置中心推送变更事件网关收到后刷新本地缓存不需要重启服务。这样临时把某路流量切走、或紧急下线某个异常模型都能在秒级完成。2.2 动态路由策略权重路由、优先级路由与故障转移配置有了接下来是路由策略。我实现了三种策略按场景可以组合使用。第一种是权重路由适合灰度验证。比如新接入一个模型先让它处理 5% 的流量观察几天效果再逐步放大。实现上就是加权随机算法代码量不大但非常实用。第二种是优先级路由适合成本控制。比如配置一个主 provider 和一个备 provider正常情况下所有流量走主 provider主 provider 不可用时自动切到备。这个场景最典型的是预算控制某个模型月度预算快用完时把一部分请求切到更便宜的备选模型上。第三种是故障转移failover适合稳定性要求高的场景。网关收到上游 5xx、超时、限流错误时自动将请求重试到健康 provider。注意这里的重试逻辑要小心处理因为模型生成接口不是天然幂等的重试可能导致客户被重复计费。我的做法是只有下游返回明确的上游故障错误码时才自动重试而且重试次数限制为一次。实际运行中我还会给每个 provider 维护一个健康状况指标包含连续错误数、平均耗时、P95 延迟。当连续错误超过阈值时自动把该 provider 摘除出路由池等恢复后再加回来。这比完全人工判断省心得多。2.3 上下文窗口与参数差异的适配处理不同模型对上下文窗口的支持差异很大。GPT-4o 能处理 128K token某些国产开源模型只有 32KClaude 长文能力突出但也有自己的 token 计算方式。如果不做适配同一个请求在不同模型之间切换很可能出现“换个模型就报 context_length_exceeded”的情况。我的处理方案是在网关层做一次请求归一化。收到业务请求后按当前路由到的模型能力重新计算 token 占用量如果超出该模型上限就先触发 prompt 压缩策略。压缩策略包括裁剪早期对话轮次、压缩引用文档的详细程度、把摘要提前注入等。还有 temperature 和 top_p 这类采样参数各家实现的默认值也不同。OpenAI 默认 temperature 为 1.0DeepSeek 默认是 0.8如果业务方没显式传参切模型后生成风格会明显变化。我的做法是配置中心里为每个模型维护一套默认参数模板请求进来时如果业务方没指定参数就填充当前模型对应的默认值。3. RAG 知识库的构建路径与检索质量调优3.1 文档切块策略从小粒度到大上下文RAG 的第一步是把文档切成可以向量化的块。切块策略直接决定检索质量很多团队在这里翻车。切得太细比如每块 128 token检索命中会很精准但喂给模型的上下文碎片感强模型经常因为缺少前后文而答非所问。切得太粗比如每块 2000 token上下文完整了但向量化后的语义粒度太粗检索命中率下降而且容易超过模型的上下文窗口限制。我的经验是分文档类型设计切块策略。技术文档、操作手册这类结构化文本按 Markdown 标题层级切保持章节完整性。对话记录、FAQ 这类条目式内容按语义单元切一条问答就是一个完整块。长报告的段落按 512 token 左右大小切并保留 10%-15% 的重叠避免切断语句中间的语义。切块后一个重要步骤是块元数据标注。每块向量化前给它打上来源文档、章节路径、文档类型、更新时间等标签。这一步做在前端的好处是检索阶段可以按元数据过滤。比如用户只想搜“产品说明书”内容就不用被历史故障记录的结果干扰。还有一个小技巧给每块内容生成一个简短的摘要向量检索时先匹配摘要层再根据摘要筛选出的文档定位到具体块。这种“两级检索”能减少精排阶段的运算量效果也不错。3.2 向量化与混合检索为什么纯向量检索不够向量检索目前主流方案是embedding 模型 向量数据库。embedding 模型我试过好几款OpenAI 的 text-embedding-3-large 语义理解强但成本和延迟略高国产的文本向量模型性价比很好尤其中文场景下某些场景指标甚至更强。选型原则是一测中文相似度二测长文档鲁棒性三看部署成本。不过纯向量检索有很明显的毛病对精确关键词匹配不敏感。用户搜索“《劳动法》第37条”向量关系上可能匹配到一堆讨论劳动法总体内容的块精确条款反而不在最前面。解决方式是引入BM25 稀疏检索做混合召回。混合检索的经典流程是向量检索召回 Top 50BM25 召回 Top 50两边做融合重排。融合算法我用的 RRFReciprocal Rank Fusion简单有效实现不到 50 行代码。最终按融合分数取 Top K 作为上下文。还要说一个重要细节query 改写。用户真实提问往往是口语化的“上个月那个谁离职能不能赔 n1 啊”直接拿去检索效果很差。我在检索前加了一步 query 改写用一个轻量模型把口语问题转成规范检索语句再执行混合检索。这一步对整体命中率的提升比我预想的大得多。3.3 知识冲突与时效性处理生产环境里多个版本的文档并存是常态比如新旧两版管理制度同时存在于知识库检索结果可能互相矛盾。我的做法是在元数据里加version字段检索阶段按版本规则过滤默认只召回当前生效版本。时效性是另一个被忽视的点。很多 RAG 项目建好之后文档就不更新了模型就拿旧知识回答问题。我加了一个定时任务定期检查文档源的变更状态增量更新向量库中对应块。同时维护一个知识库快照版本号业务侧可以指定用哪个版本的快照进行检索方便回滚。最后是引用溯源。所有 RAG 回答必须带上引用来源也就是命中了哪些文档块以及这些块的内容摘要。一方面这是合规要求比如法律咨询场景必须能指出依据条款另一方面也是用户信任的关键没有来源的 AI 回答和编造没有区别。从成本角度看RAG 做得好还能显著降低 token 消耗。因为检索出来的上下文是精准的不需要每轮重复灌入大量文档或长对话历史。这一点在按 token 计费的模型上尤其明显有时候 RAG 优化前后单次问答成本能差出 3 到 5 倍。4. Agent 编排层的执行引擎与状态控制4.1 任务拆解与工具注册体系Agent 编排层是整个 AI 模块里最像“操作系统”的部分。它要管理的不只是模型调用还有工具生命周期、任务状态流转、上下文维护和错误恢复机制。任务拆解是 Agent 的第一步。用户丢过来一个复杂需求Agent 需要判断该调用哪个工具、以什么顺序调用、中途是否需要向用户确认。我把工具注册做成声明式配置每个工具描述清楚功能、入参格式、出参格式Agent 根据任务描述自行选择合适的工具组合。一个典型的工具注册配置长这样{ name: query_order, description: 根据订单号查询订单详情包括金额、状态、物流信息, parameters: { type: object, properties: { order_id: { type: string, description: 订单号例如 SO-2024-001 } }, required: [order_id] }, timeout_seconds: 5 }这里有个关键点工具描述写得越清楚Agent 用错的概率越低。我见过一个团队接了个“查库存”工具description 只写了“查库存”结果 Agent 经常在用户问物流信息时也去调它。把 description 改成“查询商品当前可售库存数量参数为商品 SKU返回可售量与锁定量”之后错误率明显下降。4.2 状态机设计与上下文传递Agent 执行一个多步骤任务时必须维护一个可恢复的状态。我用的是一张agent_runs表记录每次任务执行的完整状态信息。CREATE TABLE agent_runs ( run_id UUID PRIMARY KEY, user_id TEXT NOT NULL, agent_name TEXT NOT NULL, status TEXT NOT NULL, -- running / waiting / success / failed current_step INTEGER, total_steps INTEGER, memory_snapshot JSONB, created_at TIMESTAMPTZ DEFAULT now(), updated_at TIMESTAMPTZ DEFAULT now() );每个步骤执行前先读取memory_snapshot还原上下文执行结束后把中间结果写回快照。这种“可随时中断、随时恢复”的设计让超时任务可以接管重启安全性也好很多。比如 Agent 在等用户确认支付时status置为waiting用户回复后继续执行不需要重新跑前置步骤。上下文传递还有一个细节不同任务阶段相关上下文的范围不同。比如第一阶段查订单第二阶段查历史消费第三阶段写报告每个阶段主动压掉无关的历史消息保留核心实体信息订单号、金额、客户等级。这能避免上下文窗口膨胀也减少 token 浪费。4.3 多 Agent 协作与人工介入机制单 Agent 能做的事终究有限复杂业务往往需要多个专业 Agent 协作。我把多 Agent 协作设计成Supervisor Worker的模式。Supervisor 负责任务分解和结果汇总Worker 各管一块专业领域如“订单 Agent”、“售后 Agent”、“财务 Agent”。协作时的核心问题是防止死循环。两个 Agent 互相传递结果可能因为理解偏差踢皮球。我加了两个机制一是最大迭代轮次限制默认 5 轮超过直接转人工二是每一步都要求 Worker 明确输出“任务已解决”或“仍缺少信息”避免模糊输出导致 Supervisor 无法决策。人工介入是生产系统里绝对不能省的环节。Agent 发现无法处理用户意图、或调用工具连续失败时必须有能力把会话平滑转接给人工客服。转接时把所有中间上下文打包成摘要让人工客服一眼看懂已经发生了什么。系统里这个能力叫escalate_to_human本质上也是一个工具但它的定位比普通工具更高。4.4 失败重试与降级策略Agent 执行链路里每一步都可能失败模型调用超时、工具返回异常、数据格式不符合预期。我的策略分三层第一层是单步重试。模型调用失败时直接重试当前步骤重试次数限制为 2间隔递增注意不要对非幂等工具盲目重试。第二层是步骤降级。比如“查天气”工具挂了Agent 可以改用“通用搜索”工具查天气信息虽然结果结构不同但目标达成。第三层是任务降级。连续多步失败时Agent 主动降低任务目标比如从“生成完整报告”降级为“列出关键发现”保证用户至少有一个可用结果。这三层策略在代码上其实不复杂真正复杂的是判断“什么情况下该降级”。我踩过的坑是过度降级工具偶尔超时一次就直接降级任务导致用户拿到残缺结果体验很糟。后来调整策略把单步重试做扎实只有单步重试也失败才降级这才平衡了稳定性和用户体验。5. 生产环境踩坑实录与性能调优笔记5.1 配置错误与常见故障对照表这里把我在多个项目中实际遇到的高频问题整理成表供各位排查时直接对照。现象根因排查方向解决方案上报“provider 缺少 base_url 配置”路由配置里没填 base_url或环境变量没生效检查配置中心的 provider 记录补齐 base_url 指向该服务商 OpenAI 兼容入口确认服务启动时加载了正确环境变量模型切换后频繁时报 context_length_exceeded各模型上下文窗口不一致且请求未按模型能力归一化看路由到的模型 window 参数请求入口统一按模型归一化超出上限走 prompt 压缩流程知识库里明明有内容但检索不到切块过细导致语义断裂或向量模型对专业术语不敏感抽样看向量检索 TopK 结果调整切块策略补混合检索与 query 改写Agent 执行中途状态丢失状态没持久化或只存在内存里查看 agent_runs 表记录每次状态变更持久化关键步骤执行前先恢复快照Agent 走入工具调用死循环缺少迭代轮次限制查看 run 日志中步骤序列加最大轮次限制超限转人工或强制结束多轮对话中模型遗忘前文关键信息上下文管理策略不当查看送入模型的 messages 结构对多轮对话做关键信息摘要压缩替换全量历史限流报错导致业务中断provider 侧限流阈值未感知看网关统计的限流比例配置限流自动重试与故障转移降低单 provider 压力细看可以发现表中的问题大多不是模型本身能力问题而是架构上没把各环节的边界定义清楚。这些基本都能通过配置和流程优化解决不至于推倒重来。5.2 性能瓶颈与调优实战在压测过程中有三个性能指标值得持续观察单请求首 token 延迟、P95 端到端延迟、成功率和重试率。这三个指标看住系统整体健康度就有数了。先说首 token 延迟。很多团队只盯总耗时忽视了首 token 时间。模型生成是一个 token 一个 token 吐的首 token 时间主要反映网络和上游排队情况后续 token 速度反映模型推理效率。如果首 token 时间高问题大概率在网关和服务商之间的链路而不是模型本身。我用 SSE 流式输出时会单独记录首 token 到达时间作为核心监控指标。再说 P95 延迟。RAG 流程里增加检索、重排、query 改写等步骤必然拉长总延迟。我的优化方向是做检索预取与生成并行。在模型生成第一个 token 之前先把检索结果准备好。实现方式是业务请求进来时并行触发两个任务一个跑检索、一个发模型请求模型请求内先不带检索上下文等检索结果回来后在服务端拼装完整上下文。实测下来这种方式能压缩约 30% 的感知延迟。最后是成功率和重试率。成功率低于 99% 时需要重点排查超时阈值和 provider 健康状态。我踩过的一个坑是超时阈值设成和模型最慢情况一致结果单请求挂着 60 秒用户早就跑了。后来改成“P95 延迟的两倍”作为超时阈值保证 95% 的请求能正常完成又不至于让用户无谓等待。5.3 可观测性日志、链路追踪与成本分摊AI 模块的可观测性比传统后端更复杂因为一个请求会穿越网关、检索、Agent 多步、模型生成多个环节。我引入了统一的 trace ID从请求入口生成贯穿到所有内部调用和日志记录。这样排查问题时能按 trace ID 拉出全链路时间线。日志输出上我除了记录错误还记录每次模型请求的 token 用量、耗时和成本估算值。成本按 provider 的实际单价计算汇总到日账单。这一步对成本控制至关重要因为 AI 项目的成本大头就是模型调用没有分摊机制后面难以核算利润。成本分摊的做法是在请求元数据里打上业务线标识网关日志按照业务线聚合 token 消耗和费用。比如“智能客服”和“文档助手”两条业务线用同一套底座月底结算时能清楚看出哪条线消耗了多少钱。这也方便后续按业务线做模型选型决策成本过高的线就切到性价比更高的模型上。6. 架构演进路径与个人经验谈6.1 从单体应用到多模块协同的演进顺序如果你想在一个存量系统里逐步落地这套架构不建议一步到位建议按如下顺序演进。第一步先做Provider 网关层。这是最基础也最紧急的哪怕你暂时只有一家模型供应商先把统一接口、配置中心、日志审计建起来。后续接入新模型时不需要再动业务代码。第二步建设RAG 检索层。业务里开始出现“基于内部知识回答”的需求时再引入向量库和检索模块。前期可以先把文档导入和管理流程跑通检索质量再逐步优化。第三步引入Agent 编排层。编排层最容易做也最容易失控建议只承接确定性较强的流程比如“查询-分析-生成报告”链条先跑通一个场景再扩展。另外强调一点不要一上来就追求全部自动化。人工介入机制、人工审核节点、操作确认机制在生产环境里都是必要的安全阀。AI 能自动化处理 80% 的标准场景剩下 20% 交给人工兜底总成本反而更低。6.2 关于模型选型和成本控制的一些个人建议模型选型不该只看榜单分数要结合自己的场景测试。我通常建议团队做三类测试一是典型业务场景压测确认模型是否理解领域术语二是长文本鲁棒性测试构造超过上下文窗口上限一半的输入看模型是否还能稳定输出三是成本测算把日均请求量、平均 token 消耗、模型单价算在一起得出月度成本预估。成本控制上除了模型选型还可以用缓存策略优化。同类问题如果短时间内重复出现可以直接缓存问答结果不需再调模型。我见过用语义相似度做缓存的方案用户问法稍有不同但含义相同时也能命中缓存成本能省 30% 左右。不过要注意时效性要求高的场景不适合开缓存比如实时的股票行情问答。6.3 最后分享一个实用的运行观察心得一次在压测客服场景 Agent 时我发现任务成功率只有 82%大部分失败集中在用户意图模糊的轮次。后来排查发现并不是模型能力不行而是 Agent 引导意图澄清的设计不到位。用户问“我要退钱”Agent 直接进入退款流程没有先确认是“退款到原路”还是“退回余额”结果后续工具调用参数不足卡死。解决办法是给 Agent 加了一个意图确认步骤当用户请求涉及钱、账号、法律等高风险操作时强制先输出一个确认问题得到用户肯定答复后再继续。这个调整把成功率从 82% 拉到了 96%没有换模型没有改工具只是调整了Agent编排逻辑中的一个小分支。类似这样的问题在纯模型评估阶段很难被发现只有放到真实业务语境里跑才能暴露出来。所以每次调整架构我都会保留一套“真实业务回放”测试集定期拿历史问题重新跑一遍确保改动没有让回答质量倒退。这套架构不是静态的模型在变、业务在变、工具在变只有持续用真实数据打磨它才会越来越好用。