AI模块架构实践：多Provider切换、RAG接入与Agent编排

前面三篇我们把 AI 模块的需求拆分、数据流转和基础接口都过了一遍这篇集中讲架构层面的三件核心事多 Provider 切换、RAG 知识库接入、Agent 编排。这三个词单独拎出来都不新鲜但在同一个系统里把它们揉在一起、还要保证切换顺滑、回答不飘、任务不跑飞才是真正费功夫的地方。这篇我会按我自己实际落地项目的顺序来讲先说为什么这三件事必须放在同一套架构里设计再分别拆 Provider 抽象、RAG 链路和 Agent 编排最后给一份可以直接抄作业的最小实现和一堆排坑记录。1. 为什么要把 Provider、RAG、Agent 三件事打包在一起设计1.1 这三件事分别解决什么问题先说定位。Provider 层管的是“让系统能随时换脑子”——今天用 DeepSeek明天换 Qwen后天接一个私有化部署的本地模型上层业务代码不用跟着改。RAG 管的是“让脑子有知识”——模型训练数据里没有你公司的内部文档、没有你刚更新的产品手册RAG 就是把这些外部知识在推理时塞进上下文。Agent 管的是“让脑子会干活”——不只是回答一个问题而是把一个复杂任务拆成几步中间调用搜索、查库、执行命令等工具最后把结果汇总给你。很多人容易犯一个错把这三件事当成三个独立模块先接一个模型 API 跑通后面再单独加知识库再后面引一个 Agent 框架。结果就是系统里到处都是硬编码的模型名、散落的向量库配置、和一套不受控的工具调用逻辑。等模型要换、知识要更新、任务要变复杂的时候每一处都是坑。我自己的感受是这三件事必须在架构图上同时出现边界划清楚再谈各自实现。1.2 模块边界的划分逻辑我习惯画成四层层级职责典型组件应用层对话、问答、任务入口业务 API、Web UI、机器人Agent 层任务拆解、工具编排、状态管理Agent 框架、ReAct 循环、工具注册表能力层RAG 检索、模型调用、工具执行向量库、重排器、Provider 客户端、各类工具基础设施层配置、密钥、日志、监控配置中心、密钥管理、追踪系统核心原则是上层依赖下层但每层只依赖下层的抽象接口不依赖具体实现。Agent 层要调模型它面对的是一个ChatModel接口而不是某一家 SDK 的类Agent 层要检索知识它面对的是一个Retriever接口而不是某个向量库的客户端。这样后面换 Provider、换向量库、换 Agent 框架都只动对应层内部的东西。1.3 四个必须要守的架构原则第一配置与代码分离。模型名称、Base URL、API Key、超时时间、温度参数全部走配置文件或环境变量。这一点看起来简单但我见过不止一个项目把模型名写在业务代码里换模型要发版。第二所有外部依赖都要有降级路径。主模型挂了走备模型检索超时就走纯模型回答Agent 执行失败要有兜底回复。第三可观测性从第一天就做。每一次模型调用、检索耗时、Agent 的每一步思考都要有日志和耗时记录不然问题来了只能瞎猜。第四内容安全底线。在模型输入前、输出后都做合规校验该过滤的过滤该加提示的加提示尤其是面向 C 端用户的产品。2. 多 Provider 切换抽象层设计才是关键2.1 统一接口与模型能力差异多 Provider 切换里最容易踩的坑是“假装统一”。很多封装就是把各家 SDK 的chat.completions.create都包成一个函数看起来是统一了实际上各家在参数、返回格式、能力边界上差异巨大。比如有的模型支持system角色有的模型把这个当普通消息有的模型支持 Function Calling有的只支持 JSON 输出有的模型支持temperature0有的最低只能到 0.1流式输出的 chunk 结构更是各写各的。所以抽象层不能只做一个“发请求”的壳子而是要定义一套“能力契约”。我设计ChatModel接口时核心方法就一个chat(messages, options)但options里包含了调用方真正关心的东西temperature、max_tokens、top_p这些生成参数tools工具定义列表如果目标模型不支持工具由适配层做降级比如把工具描述塞进 System Promptresponse_format要求 JSON 输出还是普通文本stream是否流式返回适配层的职责是把这份统一请求翻译成各家的 SDK 调用再各家返回翻译回统一格式。这一步翻译工作省不了但翻译逻辑集中在适配层业务代码就不需要关心对面是哪家。2.2 路由策略与降级机制Provider 切换不只是“改个配置”那么简单真正好用需要两层路由。第一层是按业务场景路由闲聊、翻译这类轻任务走便宜快速的模型代码生成走代码能力强的模型复杂推理、长文档分析走旗舰模型。第二层是运行时自动降级主模型返回 429 限流、5xx 错误、或者连续多次超时自动切到备选模型重试。降级这块我有一个建议不是所有错误都适合降级。400 这种请求参数错误降级大概率还是错应该直接抛回上层429、500、超时这类服务端问题才值得重试和降级。重试要带指数退避比如第一次等 1 秒、第二次 2 秒、第三次 4 秒别上来就疯狂重试把服务商打爆。路由层的设计还要考虑成本。我现在会在配置里给每个 Provider 标注一个“优先级”和“成本档位”路由层默认选成本最低的可用模型当任务标记为“高价值”时才走贵模型。这套机制上线后我的实际体感是账单能降 30% 左右而且用户无感知。2.3 配置管理密钥、Base URL、默认参数多 Provider 的配置管理最痛苦的就是密钥分散、Base URL 缺失、模型名写错这三个问题。我统一用一份 YAML 管理结构大致是providers: deepseek: type: openai_compatible base_url: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY default_model: deepseek-chat timeout: 30 weight: 10 # 权重越高优先级越高 qwen: type: openai_compatible base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 api_key_env: DASHSCOPE_API_KEY default_model: qwen-plus timeout: 30 weight: 5这里有个容易被忽略的细节很多服务商提供的是 OpenAI 兼容格式的接口但 Base URL 往往不是根地址而是带版本路径的少一个/v1就会报 404 或者 missing base_url 错误。我在排障时见到的错误大概分三类错误现象常见原因处理方式400 配置错误provider 缺少 base_url没配置接入地址或地址格式不对检查配置文件补全完整 URL含版本路径No API Key for provider route环境变量未设置或 key 为空确认密钥已注入且 env 名称与配置一致Missing session id使用了需要会话态的接入方式但请求未携带会话改用标准 API Key 方式或先建立会话再请求密钥管理这块我最开始图省事直接把 key 写在代码里后来不得不做一轮大整改。现在的做法是本地开发用.env文件测试和生产环境用环境变量注入任何情况下 key 不进代码仓库。3. RAG 知识库从切块到检索的完整链路3.1 为什么需要 RAG 而不只是无限拉长上下文模型上下文窗口确实越来越大但把整本手册都塞进 Prompt 有两个问题一是贵token 按量收费塞 10 万字文档一次对话的成本直接起飞二是效果差模型面对超长上下文中混杂的大量无关信息注意力会被稀释反而更答不准。RAG 的思路是不把全部知识给它而是把和问题最相关的几段知识给它。这就像是查资料不是把整座图书馆搬到你面前而是先帮你检索出三本最相关的书翻到相关章节再让你读。这也是 RAG 相比“硬喂长文本”最大的价值可控、可溯源、更新便宜。3.2 切块策略与向量化RAG 链路里最影响效果的反而不是模型而是切块和检索。切块切得好不好直接决定“知识能不能被捞起来”。我的切块经验可以浓缩成三点按语义边界切不按固定字数硬切块的大小看文档类型块与块之间要有重叠。比如产品手册、规章制度这类有明确章节的文档按章节段落切一个小节一块技术文档、代码注释按 Markdown 标题层级切每一节一块PDF 扫描件先做 OCR 再按页切聊天记录、客服问答按“一问一答”为一个单元切块大小我这里给一个参考区间512 token 到 1024 token。太小的块虽然精确但上下文信息不完整太大的块噪声多检索精度下降。我实际用的重叠窗口是 10%-15%也就是说下一块会包含上一块末尾的一小部分内容避免关键句子正好被从中间截断导致语义断裂。向量化模型的选择我建议优先考虑中文效果好的开源嵌入模型比如 bge-large-zh、m3e 这类它们不依赖外部 API离线也能跑而且 embedding 维度在 768-1024 之间检索速度也够。向量库层面数据量小可以用轻量方案数据量大再上专门的向量数据库具体选型看下表的对比方案适合场景优点注意点内存型 / 本地文件个人项目、原型验证部署简单零运维数据量大时检索变慢开源向量库中小规模生产可控性高支持过滤需要自己运维云向量库规模化场景托管省心、扩展性好注意成本和服务商锁定3.3 检索、重排与引用溯源检索这里最忌讳的是“只用向量检索”。关键词精确匹配和语义相似各有所长搜“订单号 ABC123 报错”关键词检索引擎能精确命中向量检索反而可能被“订单”和“报错”两个词的语义带偏。我现在的做法是混合检索向量检索召回一批BM25 关键词检索召回一批融合去重后进入重排阶段。重排Rerank是我强烈建议不要省的一步。召回阶段为了召回率会故意放宽条件多捞一些候选重排模型再按“和问题的真实相关性”对候选精排取 top-k 送进 Prompt。加上重排之后回答质量提升非常明显尤其是在文档库比较大、话题比较杂的场景。一个最小可用的 RAG 检索链路我用伪代码描述大概是def retrieve(query, top_k5): vector_hits vector_search(query, top_k20) keyword_hits keyword_search(query, top_k20) candidates merge_rank(vector_hits, keyword_hits) reranked rerank(query, candidates, top_ktop_k) return reranked还有一个容易漏的引用溯源。RAG 系统的输出如果只是给一段回答用户没法确认“这个回答是编的还是查到的”。我要求 RAG 返回的每一条知识块都带来源信息文档名、页码/章节、原文摘录回答里也标注引用了哪些来源。这既是产品体验也是责任划分——模型说错了你能定位到是知识库的问题还是生成的问题。3.4 RAG 和 MCP 的区别最近经常被人问到 RAG 和 MCP 到底什么关系。我的理解是两者解决的不是一个问题甚至不在一个层级。RAG 是一套数据处理流程——切块、嵌入、检索、注入解决的是“模型不知道的知识去哪里找”MCP 是一套工具调用的协议——它规范了模型如何发现工具、如何调用工具、工具如何返回结果解决的是“模型怎么操作外部系统”。可以理解为 RAG 是给模型“喂资料”MCP 是给模型“接手脚”。在一个完整的智能体系统里RAG 完全可以封装成一个 MCP 服务让模型通过 MCP 协议去调用检索工具。这也引出了所谓 Agentic RAG不再是一次“检索 → 生成”的固定流程而是模型根据任务需要自主决定什么时候检索、检索几轮、检索完之后怎么用这些结果。4. Agent 编排让模型学会用工具4.1 Agent 是什么Harness 和 Agent 的区别Agent 的核心是一种循环模型提出下一步行动 → 系统执行该行动通常是调工具 → 把执行结果作为观察返回给模型 → 模型根据观察提出下一步行动直到模型认为任务完成或达到预设的终止条件。这就是常说的 ReAct 模式。很多人把 Agent 框架和 Agent 本身搞混。框架是“Harness”它是帮你跑循环、调工具、管记忆的脚手架Agent 是这个循环中的“策略”即模型根据当前上下文做出的决策。Claude Code 这类工具里的“Skill”和“Agent”也不是一回事Skill 是一组预先定义好的能力包比如“如何做代码审查”的一整套提示词和工具组合Agent 是动态决定何时启用的执行者。Skill 是武器库Agent 是战士。4.2 任务拆解与工具调用Agent 编排最大的难点不是循环代码怎么写而是工具的定义和任务拆解的粒度。先讲工具定义。给模型的工具描述必须非常具体否则模型不知道什么时候该调用它。我写过一份“内部知识检索工具”的定义最初的描述是“查询内部知识库”模型经常在用户问天气的时候也去调用它。后来改成完整描述“当用户询问公司制度、产品手册、技术规范等内部文档内容时使用此工具检索相关知识。不要用于通用知识问答。”这个改动让工具调用的准确率上升了一截。另一个经验是不要一次性给 Agent 挂十几个工具模型会犯选择困难症要么瞎调用、要么来回尝试。把高频工具控制在 3-5 个其他低频工具放进子 Agent 或按需加载。再讲任务拆解。简单任务不需要拆Agent 直接查一次知识库就能答复杂任务才需要 Planner。我的做法是把任务分为两种模式单步模式——模型基于已有上下文直接生成回答或调用一次工具多步模式——模型先生成一份计划再逐计划执行。一定会有人问“怎么判断要不要多步”我的标准是用户请求里包含多个独立子问题或者第一步的执行结果会影响后续怎么走就必须多步。4.3 状态管理与执行超时Agent 一旦跑起来你就得面对两个很实际的问题状态怎么管跑飞了怎么办。状态管理我强烈建议用显式状态机哪怕简单一点也比分不清强。一个任务至少要有这些状态pending、running、tool_calling、succeeded、failed、needs_human。每次 Agent 循环推进都要把状态落库或写入日志。这样做的好处是用户刷新页面能看到任务进度系统崩溃后能从最近一个持久化状态恢复排查问题时知道它死在哪一步。执行超时是所有 Agent 项目早晚都会撞上的痛。模型陷入死循环、工具调用迟迟不返回、或者某个外部接口 hang 住都会导致“Agent 执行被终止”这类错误。我的防线有三层防线设置目的单轮工具超时30-60 秒防止单个工具调用拖死整个 Agent最大迭代次数10-15 次防止逻辑死循环或无限拆任务总任务超时3-5 分钟防止多步任务整体失控这三条即使配置在 harness 里也要在业务层再做一遍兜底。我现在会把“最大迭代次数”设成 12 次并且每次循环在 Prompt 里提醒模型“你已经进行了 8 次操作请聚焦完成用户目标不要继续无关操作”。实测这种显式提醒比单纯靠终止条件有效得多。另外如果系统支持人工介入在 Agent 执行超过一定次数或遇到不确定结果时把控制权交还给人类是一个很实用的降级策略。5. 实操参考落地一个最小可用的 AI 模块5.1 配置文件的组织方式先给一份可直接参考的目录结构和配置组织。我所有 AI 模块相关的配置都统一收敛到config/下不散落在业务代码里config/ ├── providers.yaml # Provider 列表、路由权重、默认参数 ├── rag.yaml # 切块参数、检索 top_k、embedding 模型配置 ├── agent.yaml # 最大迭代、超时、工具启用开关 └── .env # 存储各类 API Key永远不入库一个关键提醒配置文件里的默认参数要在代码里也有对应的默认值兜底。比如providers.yaml里某个模型没写timeout代码不能直接读到None然后懵掉应该在配置加载阶段做校验发现缺关键字段就启动失败并报清晰的错误而不是运行到一半才炸。5.2 Provider 抽象层代码骨架我给出一个简化但能跑通思路的骨架class ChatModel: def __init__(self, provider_config): self.base_url provider_config[base_url] self.api_key provider_config[api_key] self.default_model provider_config[default_model] def chat(self, messages, optionsNone): raise NotImplementedError class OpenAIChatModel(ChatModel): def chat(self, messages, optionsNone): # 用 OpenAI SDK 请求底层同时兼容多数国内服务商 kwargs {} if options: kwargs.update(options) return self._do_request(messages, **kwargs) class Router: def __init__(self, providers): self.providers providers def route(self, task_type): # 按业务类型选模型带降级 candidates self.providers.for_task(task_type) return candidates[0] # 权重排序后第一个可用 class AIEngine: def __init__(self, router): self.router router def complete(self, messages, task_typenormal): model self.router.route(task_type) try: return model.chat(messages) except RateLimitError: model self.router.route_fallback(task_type) return model.chat(messages)这套骨架最核心的地方在于业务侧只接触AIEngine.complete()完全不感知对面是哪个 Provider。任何新增 Provider只需要新增一个继承ChatModel的实现类并在配置里注册。5.3 RAG 最小链路RAG 链路我不建议自己从头实现向量化和存储直接用现成组件组合最快。一个可运行的最小链路是def build_retriever(): embedding_model load_embedding_model(bge-large-zh) store init_vector_store() # 初始化向量库 return VectorRetriever(embedding_model, store) def rag_pipeline(query, retriever, chat_model): chunks retriever.retrieve(query, top_k5) context build_context(chunks) # 拼接知识文本与来源 prompt f请基于以下资料回答问题...\n资料:\n{context}\n问题: {query} answer chat_model.chat([{role: user, content: prompt}]) return answer, chunks # chunks 用于溯源展示注意build_context这一步不只是把 chunks 拼接起来还要按与问题的相关性降序排列并给每条资料编号。这样模型回答时能提到“根据资料 2”系统再根据编号映射回真实文档完成溯源。5.4 Agent 编排的最小实现Agent 编排的最小实现核心就是一个循环。我的建议是不要一上来就引重型 Agent 框架先用代码把循环写明白等确认需求复杂了再引框架不迟。def run_agent(task, tools, max_iterations10): messages [{role: user, content: task}] for i in range(max_iterations): response model.chat(messages, toolstools) if response.has_tool_calls(): for call in response.tool_calls: action execute_tool(call) # 执行工具拿到观察结果 messages.append(call.to_message()) messages.append({role: tool, content: action.result}) else: return response.content raise AgentTimeout(exceed max iterations)这个简化版循环已经能覆盖 80% 的单任务智能体场景。需要注意的一点是execute_tool内部必须做超时控制而且工具返回的结果如果太长要在进入下一轮模型调用前做截断避免把少量有用的信息淹没在大量工具输出里。6. 常见问题排查与避坑实录6.1 Provider 配置类报错先查配置再查代码我遇到的 Provider 类报错八成以上是配置问题而不是代码问题。“400 配置错误provider 缺少 base_url 配置”这类信息通常意味着配置加载阶段没把 Base URL 填进客户端。排查顺序建议严格执行先看配置是否加载、再看环境变量是否注入、最后看代码里有没有覆盖配置的硬编码。报错现象我的排查步骤缺少 base_url 配置检查配置文件是否包含完整路径含/v1等版本前缀missing api key确认对应环境变量已设置并检查配置里的 env 名称是否拼写一致missing session id优先改用标准 API Key 方式接入不要在会话态上做文章free tier 不可用 / 被拒绝按服务商要求配置正式身份凭证不要用非正规方式规避限制上游请求失败、模型不可用确认模型名是否属于当前服务商、配额是否充足、服务商状态页是否异常一个长期建议把配置加载结果和接口探测结果打点输出。启动时自动打印“已加载 provider: deepseek, base_url: xxx, model: deepseek-chat”能省掉大量靠猜的排障时间。6.2 检索质量类问题八成是切块和重排的锅RAG 问答效果差很多人第一反应是“换更大的模型”但实测下来先检查切块和重排收益更大。常见问题包括检索不到相关内容检查切块是否破坏了语义单元比如一句话被从中间切断或 embedding 模型和文档语言不匹配检索出一堆不相关的结果top_k 设得太大或没做重排建议把召回阶段和精排阶段分开召回多捞一些精排再卡紧回答出现幻觉上下文里混入了太多低相关片段模型被带偏。处理方式是降低 top_k并严格要求模型“只依据资料回答资料没有的内容明确说不知道”切块重叠导致重复内容重叠窗口过大相邻块之间大量内容重复检索去重做掉或用重排把重复项压下去6.3 Agent 执行类问题超时、循环、上下文爆炸Agent 执行报错里最常见的就是超时和循环。“Agent execution terminated due to error”很多人见过解决思路不只是调大超时而是先定位它卡在哪一步。我的做法是在循环的每一步都打结构化日志当前迭代次数、调用的工具、工具返回耗时、本轮模型响应摘要。这样“查出哪一步卡住”通常五分钟内就能搞定。上下文爆炸也是 Agent 项目的高发问题。工具返回内容不断追加进消息列表几轮之后 token 数可能破万甚至更多。我的处理策略是工具返回做摘要再入上下文而不是原样全塞多轮对话只保留最近轮次 历史关键结论必要时把早期上下文向量化需要时再检索回来。6.4 安全合规与成本控制最后提两个很多人会忽略的点。一个是输入输出双向的内容安全校验用户输入要拦截非法意图模型输出要检查是否包含不当内容这两道关卡不能只依赖模型自身。面向公众开放的服务这个说得再怎么强调都不过分。另一个是成本控制多 Provider 架构天然适合成本优化但要配合预算告警。我给每个业务场景设置不同的 token 预算超过 80% 就告警再按日维度统计每个 Provider 的消耗占比哪个模型突然消费暴涨系统自动切流量避免月底账单吓人。在我自己负责的项目里把 Provider、RAG、Agent 三件事收进同一套架构后最大的收益不是某个指标变好了而是“改动成本”降下来了。以前换一个模型要改业务代码、动 Prompt、重测全流程现在只加一条配置加一个适配类改完跑一遍回归用例就能上线。RAG 的检索链路独立文档更新只影响知识库不碰模型逻辑。Agent 层的工具注册和任务编排分开新增工具不会污染已有的执行流程。这套架构运行几个月下来我个人的体会是AI 应用真正的复杂度不在模型而在模型之外的那些工程细节。把这些细节打理好了模型反而成了最省心的部分。