1. 为什么我会盯上 XXL-AI 这个项目第一次看到“XXL-AIAI应用开发平台Agent编排、多供应商、「MCP SKILL RAG」扩展、工程化底座”这个标题我的直觉是这不是又一个套壳聊天界面而是想把 AI 应用开发里最脏最累的那几块活——模型接入、工具调用、知识检索、流程编排——全部收进一个统一的工程底座里。做过 AI 应用的人都知道Demo 跑通只要一个下午但要让它在生产环境里稳定、可观测、可扩展那基本是另一个维度的战争。XXL-AI 这个命名本身就带着很强的工程基因。熟悉 Java 生态的朋友对 XXL 系列不会陌生这个系列一贯的风格是“轻量、开箱即用、配置驱动、不搞过度抽象”。所以当我看到它把 Agent 编排、多供应商、MCP、SKILL、RAG 这几个关键词堆在一起时我判断它的目标用户非常明确一类是想快速搭出可用 AI 应用的后端开发者另一类是手里已经有一堆模型和工具、但被胶水代码折磨到崩溃的团队。这篇文章我不打算写成产品说明书。我想做的是把这个平台背后的设计逻辑拆开讲清楚每个模块为什么这么设计、实际落地时会遇到什么坑、以及我自己在类似架构里踩过的那些教训。如果你正在选型 AI 应用开发框架或者正准备从零搭一套 Agent 系统这篇内容应该能帮你少走不少弯路。核心关键词我会反复提到Agent 编排、多供应商、MCP、SKILL、RAG这几个词基本构成了现代 AI 应用工程化的全部骨架。2. 整体架构设计与选型思路拆解2.1 为什么是“平台”而不是“框架”很多人会把平台和框架混着说但这两者的定位差别很大。框架是给你一套 API你自己组装平台是给你一套运行时你往里填配置和插件。XXL-AI 选择做平台我认为核心原因是 AI 应用的复杂度已经从“调一次模型”变成了“编排多个 Agent、调用多个工具、检索多个知识库”。如果只做框架用户拿到手还是要自己解决会话管理、上下文裁剪、工具注册、失败重试、流式输出这些问题。而平台化的思路是把这些通用能力沉淀成底座用户只需要关注业务逻辑本身。这就像 Spring 之于 Java Web——你不会想每次都手写 Servlet 容器。从标题里的“工程化底座”四个字能看出这个项目的野心不在功能堆砌而在把 AI 应用开发中那些重复、易错、难维护的部分标准化。这个定位决定了它的架构必须是分层的底层是模型接入层中间是能力扩展层MCP/SKILL/RAG上层是编排层Agent最外面是应用接入层。2.2 多供应商抽象别把鸡蛋放在一个篮子里多供应商支持是我最看重的一点。实际项目里只接一家模型服务是非常危险的价格会变、限流会来、接口会改、某天可能直接不可用。我见过太多项目因为硬编码了某家 SDK结果对方一调整接口就得连夜改代码。XXL-AI 的多供应商设计核心是统一抽象 差异化适配。统一抽象指的是把“对话补全”“流式输出”“函数调用”“嵌入向量”这些能力定义成标准接口差异化适配指的是每家模型服务的参数、返回格式、错误码都不一样需要单独处理。这里有个关键设计点能力声明机制。不是所有模型都支持函数调用不是所有模型都支持流式不是所有模型都有相同的上下文窗口。平台需要知道每个供应商、每个模型具体支持什么才能在编排时做出正确决策。我建议在配置里显式声明这些能力而不是靠运行时试探因为试探的代价是真实的 token 消耗和延迟。2.3 MCP SKILL RAG 的三层扩展模型标题里把 MCP、SKILL、RAG 并列我认为它们代表了三种不同维度的扩展能力理解这个分层对用好平台至关重要。MCP解决的是“工具接入标准化”问题。它定义了一套协议让外部工具能以统一的方式暴露给 AI 使用。你可以把它理解成 AI 世界的 USB 接口——不管背后是数据库、文件系统还是第三方 API只要符合 MCP 协议平台就能识别和调用。SKILL解决的是“能力封装复用”问题。一个 Skill 通常是一段可复用的提示词模板加执行逻辑比如“总结会议纪要”“生成周报”“代码审查”。它比 MCP 更贴近业务是给非技术用户也能理解和使用的封装单元。RAG解决的是“私有知识注入”问题。模型本身不知道你的业务数据RAG 通过检索增强的方式把相关知识在推理时喂给模型。这是目前让 AI 应用“懂业务”最实用的手段。这三层的关系是MCP 提供原子工具SKILL 组合工具和提示词形成业务能力RAG 为整个流程提供知识支撑。理解这个分层后面配置和排查问题时思路会清晰很多。2.4 Agent 编排从单 Agent 到多 Agent 协作Agent 编排是这个平台最核心也最复杂的部分。单 Agent 就是“一个模型 一组工具 一个循环”多 Agent 则是多个 Agent 之间分工协作。标题里提到“Agent 编排”说明平台至少支持把多个 Agent 组织成一个工作流。我在实际项目里的经验是能用单 Agent 解决的就别上多 Agent。多 Agent 带来的协调成本、上下文传递成本、调试难度都是指数级上升的。只有当任务确实需要不同角色比如一个负责检索、一个负责推理、一个负责校验时多 Agent 才有价值。平台的编排能力应该支持顺序、并行、条件分支、循环这几种基本结构。顺序用于流水线式任务并行用于独立子任务加速条件分支用于根据中间结果走不同路径循环用于需要迭代优化的场景。这四种结构组合起来基本能覆盖 90% 的业务需求。3. 核心模块的细节解析与实操要点3.1 多供应商配置参数怎么填才不出错配置多供应商时最容易出问题的是参数映射。不同厂商对同一个概念用的名字不一样有的叫temperature有的叫top_p有的把系统提示词放在system字段有的要求拼进messages数组。平台的价值就在于把这些差异屏蔽掉但前提是你要正确配置映射关系。我建议的配置顺序是先配连接信息endpoint、密钥再配模型清单最后配能力声明。连接信息里要注意超时设置AI 接口的响应时间波动很大超时设太短会频繁失败设太长会拖垮整个流程。我的经验值是普通对话 30 秒流式输出 120 秒嵌入向量 15 秒。能力声明这块要特别小心。如果你声明了某个模型支持函数调用但实际它不支持编排时就会报错。反过来如果模型支持但你没声明平台就不会用它白白浪费能力。我的做法是新接入一个模型时先用最小化的测试用例验证每一项能力确认无误再写进配置。注意密钥管理千万不要硬编码在配置文件里。用环境变量或者专门的密钥管理服务这是底线。我见过太多因为密钥泄露导致账单爆炸的案例。3.2 MCP 工具接入协议理解与调试技巧MCP 的核心是让工具以标准化方式暴露能力。接入一个 MCP 工具通常需要三步声明工具元信息名称、描述、参数 schema、实现调用逻辑、注册到平台。工具描述写得越清楚模型调用得越准确。这不是玄学而是因为模型是根据描述来判断该不该调用、怎么填参数的。我见过很多工具调用失败根源就是描述太模糊。比如一个查询订单的工具描述写“查询订单”模型不知道要传什么参数写成“根据订单号查询订单详情需要传入订单号字符串”模型就能正确调用。参数 schema 要用标准的 JSON Schema 格式明确每个参数的类型、是否必填、取值范围。对于枚举类型的参数一定要把可选值列全否则模型可能编造出不存在的值。调试 MCP 工具时我的习惯是先脱离 AI 单独测试工具本身确认工具能正常工作再接入编排流程。这样能把“工具问题”和“编排问题”分开排查效率高很多。平台一般会提供工具调用的日志重点看模型传了什么参数、工具返回了什么结果这两个信息能定位绝大多数问题。3.3 SKILL 封装让能力可复用的关键SKILL 的价值在于复用。一个好的 Skill 应该做到输入明确、输出稳定、边界清晰。我见过太多 Skill 写得像万能提示词什么都能干结果什么都干不好。封装 Skill 时我建议遵循几个原则。第一单一职责一个 Skill 只做一件事。第二输入输出结构化尽量用 JSON 而不是自由文本方便上下游衔接。第三内置容错比如输入为空时返回明确提示而不是报错。第四版本管理Skill 的提示词会迭代要能追溯哪个版本产生了哪个结果。提示词工程在 Skill 里体现得最明显。我的经验是示例比描述更重要。与其写一大段“你要如何如何”不如给两三个输入输出示例模型模仿示例的准确率远高于理解抽象描述。另外把约束条件写在前面把期望格式写在后面这个顺序对输出稳定性有实际影响。3.4 RAG 检索增强从切分到重排的完整链路RAG 是让 AI 懂业务的核心手段但也是最容易做砸的环节。一个完整的 RAG 链路包括文档加载、文本切分、向量化、存储、检索、重排、注入上下文。每一环都有坑。文本切分是最容易被低估的一步。切太大检索精度下降切太小语义不完整。我的经验值是中文 300 到 500 字一段英文 200 到 300 词一段并且要保留一定的重叠overlap通常 10% 到 20%。重叠的作用是防止关键信息正好被切在边界上。向量化模型的选择直接影响检索质量。通用嵌入模型对专业领域的效果往往一般如果预算允许用领域数据微调过的嵌入模型效果会好很多。检索时纯向量检索对精确匹配不友好比如查一个具体的订单号向量检索可能返回语义相近但号码不同的结果。所以生产环境建议用混合检索向量检索加关键词检索再融合排序。重排rerank是提升精度的关键一步。初步检索召回一批候选再用重排模型精排取 top-k 注入上下文。这一步能显著提升最终答案的相关性代价是额外的延迟。我的建议是候选集召回 20 到 50 条重排后取 3 到 5 条注入这个比例在精度和延迟之间比较平衡。提示RAG 的效果不好时先别急着换模型。八成问题出在切分和检索环节。把检索到的原文打印出来看看如果检索结果本身就不相关那再强的模型也救不回来。4. 实操过程与核心环节实现4.1 从零搭一个带 RAG 的问答 Agent我拿一个典型场景来演示搭一个能回答内部文档问题的 Agent。这个场景覆盖了多供应商、RAG、Agent 编排三个核心模块。第一步配置模型供应商。对话模型选一个支持函数调用的嵌入模型选一个中文效果好的。配置里声明对话模型支持流式和函数调用嵌入模型只支持向量化。这里要注意对话模型和嵌入模型可以是不同供应商的平台的多供应商抽象就是为了支持这种混搭。第二步构建知识库。把文档加载进来按 400 字切分重叠 80 字。向量化后存入向量库。这里有个实操细节文档里的表格和图片要单独处理。表格转成结构化文本图片用多模态模型生成描述再入库。直接切分原始文档会把表格切得乱七八糟检索出来没法用。第三步定义检索工具。把知识库检索封装成一个 MCP 工具输入是查询语句输出是相关文档片段。工具描述要写清楚“用于查询内部文档知识库输入自然语言问题”。第四步编排 Agent。Agent 的系统提示词里说明回答用户问题前先调用知识库检索工具获取相关资料基于资料回答资料中没有的信息要明确说明不知道。这个约束非常重要能大幅降低幻觉。第五步测试和调优。准备一批测试问题覆盖知识库内有答案的、没有答案的、需要多段资料综合的。观察 Agent 是否正确调用工具、检索结果是否相关、最终答案是否准确。根据问题调整切分策略、检索参数、提示词。4.2 多 Agent 协作的编排示例再来看一个多 Agent 场景一个负责资料检索一个负责分析推理一个负责结果校验。这种结构适合对准确性要求高的任务。编排逻辑是这样的检索 Agent 先工作把相关资料整理成结构化摘要分析 Agent 拿到摘要后做推理产出初步结论校验 Agent 检查结论是否有资料支撑、逻辑是否自洽不通过就打回分析 Agent 重做。这里需要一个循环控制设置最大重试次数防止死循环。多 Agent 编排的关键是上下文传递。Agent 之间传的不是原始对话历史而是经过提炼的中间结果。传太多会浪费 token 且引入噪声传太少下游 Agent 信息不足。我的做法是定义一个明确的中间数据结构每个 Agent 只填自己负责的字段。调试多 Agent 时一定要能看到每个 Agent 的输入输出。平台如果支持执行轨迹追踪务必打开。我排查过一个案例最终发现是校验 Agent 的提示词里有个歧义表述导致它把正确结论判成了错误白白触发重试。4.3 流式输出与工程化细节流式输出是提升用户体验的关键。用户不用等完整结果生成可以边生成边看。但流式输出和工具调用、多 Agent 编排结合时会有复杂性。工具调用需要等模型输出完整的调用意图才能执行这期间流式输出会暂停。多 Agent 场景下每个 Agent 的输出是分段的。平台需要处理好这些边界把流式事件正确地推送给前端。工程化方面我特别关注几个点可观测性每次调用的输入输出、耗时、token 消耗都要有记录、限流与重试对供应商接口要做限流保护失败要有退避重试、成本控制设置单次请求和单日的 token 上限。这些在 Demo 阶段可以不管但上线前必须补齐。注意流式输出时如果发生错误已经推送出去的内容是收不回来的。所以要在流开始前做好参数校验把能提前发现的问题都提前拦掉。5. 常见问题与排查技巧实录5.1 工具调用失败排查表现象可能原因排查方法模型不调用工具工具描述模糊或与问题无关检查描述是否清晰说明使用场景调用参数错误参数 schema 定义不清核对 schema 类型和必填项工具执行报错工具本身逻辑问题脱离 AI 单独测试工具调用结果被忽略提示词未要求使用工具结果在系统提示词中明确要求频繁重复调用未设置调用次数上限增加最大调用次数限制这张表是我从实际项目里总结的基本覆盖了工具调用 90% 的问题。排查时按顺序来先确认模型有没有调用再确认参数对不对最后看结果有没有被用上。5.2 RAG 效果差的典型原因RAG 效果差我总结下来无非几个原因。切分不当是最常见的把完整语义切碎了。嵌入模型不匹配用英文模型处理中文或者用通用模型处理专业领域。检索策略单一只做向量检索遇到精确匹配就歇菜。上下文注入过多塞了一堆不相关的片段反而干扰模型。提示词没约束模型不看检索结果自己编。排查 RAG 问题的顺序应该是先看检索结果再看注入上下文最后看模型输出。如果检索结果就不对后面都是白搭。如果检索对但输出不对那是提示词的问题。5.3 多供应商切换的坑多供应商听起来美好实际切换时会遇到不少问题。输出格式不一致有的返回content有的返回text平台要统一。错误码不统一限流、超时、参数错误的表示方式各家不同要映射成统一错误类型。token 计算方式不同同样一段文本各家算出来的 token 数不一样成本核算要按供应商分别统计。我的建议是切换供应商前用同一批测试用例跑一遍对比输出质量和延迟。不要假设换个模型结果就一样不同模型的“性格”差异很大提示词可能需要针对性调整。5.4 性能与成本优化经验性能优化上缓存是最有效的手段。相同的问题和上下文结果可以缓存复用。并行化也很关键多个独立的工具调用或检索可以并行执行。上下文裁剪能显著降低延迟和成本只保留相关的历史对话。成本控制上我习惯给每个应用设置预算上限超过就告警或降级。选择模型时不要一味追求最强很多任务用小模型就够了。嵌入模型和对话模型分开选嵌入模型通常便宜很多可以放心用好的。6. 我在实际落地中的几点体会搭 AI 应用这件事工具和平台能帮你解决 70% 的问题剩下 30% 永远需要你自己对业务的理解。XXL-AI 这类平台的价值在于把通用能力标准化让你把精力放在业务逻辑上。但业务逻辑本身——什么该检索、什么该调用工具、什么该直接回答——这些判断只有你最清楚。我踩过最大的坑是过早追求架构完美。一开始就想把多 Agent、多供应商、RAG 全上齐结果调试成本高到离谱。后来我改成先用单 Agent 加 RAG 跑通核心场景确认价值后再逐步引入工具调用和多 Agent。这个渐进式路线帮我省了大量时间。还有一个体会是提示词和检索策略要一起调。很多人分开调调完提示词发现检索不行调完检索发现提示词又不对了。这两者是耦合的检索给什么料提示词就该怎么引导要放在一起迭代。最后分享一个实用技巧给每个 Agent 和 Skill 建一个测试用例集每次改动后跑一遍回归。AI 应用的行为不像传统代码那么确定没有回归测试你根本不知道改了一处会不会影响另一处。这个习惯看起来麻烦但长期看能省下大量排查时间。
1. 为什么我会盯上 XXL-AI 这个项目第一次看到“XXL-AIAI应用开发平台Agent编排、多供应商、「MCP SKILL RAG」扩展、工程化底座”这个标题我的直觉是这不是又一个套壳聊天界面而是想把 AI 应用开发里最脏最累的那几块活——模型接入、工具调用、知识检索、流程编排——全部收进一个统一的工程底座里。做过 AI 应用的人都知道Demo 跑通只要一个下午但要让它在生产环境里稳定、可观测、可扩展那基本是另一个维度的战争。XXL-AI 这个命名本身就带着很强的工程基因。熟悉 Java 生态的朋友对 XXL 系列不会陌生这个系列一贯的风格是“轻量、开箱即用、配置驱动、不搞过度抽象”。所以当我看到它把 Agent 编排、多供应商、MCP、SKILL、RAG 这几个关键词堆在一起时我判断它的目标用户非常明确一类是想快速搭出可用 AI 应用的后端开发者另一类是手里已经有一堆模型和工具、但被胶水代码折磨到崩溃的团队。这篇文章我不打算写成产品说明书。我想做的是把这个平台背后的设计逻辑拆开讲清楚每个模块为什么这么设计、实际落地时会遇到什么坑、以及我自己在类似架构里踩过的那些教训。如果你正在选型 AI 应用开发框架或者正准备从零搭一套 Agent 系统这篇内容应该能帮你少走不少弯路。核心关键词我会反复提到Agent 编排、多供应商、MCP、SKILL、RAG这几个词基本构成了现代 AI 应用工程化的全部骨架。2. 整体架构设计与选型思路拆解2.1 为什么是“平台”而不是“框架”很多人会把平台和框架混着说但这两者的定位差别很大。框架是给你一套 API你自己组装平台是给你一套运行时你往里填配置和插件。XXL-AI 选择做平台我认为核心原因是 AI 应用的复杂度已经从“调一次模型”变成了“编排多个 Agent、调用多个工具、检索多个知识库”。如果只做框架用户拿到手还是要自己解决会话管理、上下文裁剪、工具注册、失败重试、流式输出这些问题。而平台化的思路是把这些通用能力沉淀成底座用户只需要关注业务逻辑本身。这就像 Spring 之于 Java Web——你不会想每次都手写 Servlet 容器。从标题里的“工程化底座”四个字能看出这个项目的野心不在功能堆砌而在把 AI 应用开发中那些重复、易错、难维护的部分标准化。这个定位决定了它的架构必须是分层的底层是模型接入层中间是能力扩展层MCP/SKILL/RAG上层是编排层Agent最外面是应用接入层。2.2 多供应商抽象别把鸡蛋放在一个篮子里多供应商支持是我最看重的一点。实际项目里只接一家模型服务是非常危险的价格会变、限流会来、接口会改、某天可能直接不可用。我见过太多项目因为硬编码了某家 SDK结果对方一调整接口就得连夜改代码。XXL-AI 的多供应商设计核心是统一抽象 差异化适配。统一抽象指的是把“对话补全”“流式输出”“函数调用”“嵌入向量”这些能力定义成标准接口差异化适配指的是每家模型服务的参数、返回格式、错误码都不一样需要单独处理。这里有个关键设计点能力声明机制。不是所有模型都支持函数调用不是所有模型都支持流式不是所有模型都有相同的上下文窗口。平台需要知道每个供应商、每个模型具体支持什么才能在编排时做出正确决策。我建议在配置里显式声明这些能力而不是靠运行时试探因为试探的代价是真实的 token 消耗和延迟。2.3 MCP SKILL RAG 的三层扩展模型标题里把 MCP、SKILL、RAG 并列我认为它们代表了三种不同维度的扩展能力理解这个分层对用好平台至关重要。MCP解决的是“工具接入标准化”问题。它定义了一套协议让外部工具能以统一的方式暴露给 AI 使用。你可以把它理解成 AI 世界的 USB 接口——不管背后是数据库、文件系统还是第三方 API只要符合 MCP 协议平台就能识别和调用。SKILL解决的是“能力封装复用”问题。一个 Skill 通常是一段可复用的提示词模板加执行逻辑比如“总结会议纪要”“生成周报”“代码审查”。它比 MCP 更贴近业务是给非技术用户也能理解和使用的封装单元。RAG解决的是“私有知识注入”问题。模型本身不知道你的业务数据RAG 通过检索增强的方式把相关知识在推理时喂给模型。这是目前让 AI 应用“懂业务”最实用的手段。这三层的关系是MCP 提供原子工具SKILL 组合工具和提示词形成业务能力RAG 为整个流程提供知识支撑。理解这个分层后面配置和排查问题时思路会清晰很多。2.4 Agent 编排从单 Agent 到多 Agent 协作Agent 编排是这个平台最核心也最复杂的部分。单 Agent 就是“一个模型 一组工具 一个循环”多 Agent 则是多个 Agent 之间分工协作。标题里提到“Agent 编排”说明平台至少支持把多个 Agent 组织成一个工作流。我在实际项目里的经验是能用单 Agent 解决的就别上多 Agent。多 Agent 带来的协调成本、上下文传递成本、调试难度都是指数级上升的。只有当任务确实需要不同角色比如一个负责检索、一个负责推理、一个负责校验时多 Agent 才有价值。平台的编排能力应该支持顺序、并行、条件分支、循环这几种基本结构。顺序用于流水线式任务并行用于独立子任务加速条件分支用于根据中间结果走不同路径循环用于需要迭代优化的场景。这四种结构组合起来基本能覆盖 90% 的业务需求。3. 核心模块的细节解析与实操要点3.1 多供应商配置参数怎么填才不出错配置多供应商时最容易出问题的是参数映射。不同厂商对同一个概念用的名字不一样有的叫temperature有的叫top_p有的把系统提示词放在system字段有的要求拼进messages数组。平台的价值就在于把这些差异屏蔽掉但前提是你要正确配置映射关系。我建议的配置顺序是先配连接信息endpoint、密钥再配模型清单最后配能力声明。连接信息里要注意超时设置AI 接口的响应时间波动很大超时设太短会频繁失败设太长会拖垮整个流程。我的经验值是普通对话 30 秒流式输出 120 秒嵌入向量 15 秒。能力声明这块要特别小心。如果你声明了某个模型支持函数调用但实际它不支持编排时就会报错。反过来如果模型支持但你没声明平台就不会用它白白浪费能力。我的做法是新接入一个模型时先用最小化的测试用例验证每一项能力确认无误再写进配置。注意密钥管理千万不要硬编码在配置文件里。用环境变量或者专门的密钥管理服务这是底线。我见过太多因为密钥泄露导致账单爆炸的案例。3.2 MCP 工具接入协议理解与调试技巧MCP 的核心是让工具以标准化方式暴露能力。接入一个 MCP 工具通常需要三步声明工具元信息名称、描述、参数 schema、实现调用逻辑、注册到平台。工具描述写得越清楚模型调用得越准确。这不是玄学而是因为模型是根据描述来判断该不该调用、怎么填参数的。我见过很多工具调用失败根源就是描述太模糊。比如一个查询订单的工具描述写“查询订单”模型不知道要传什么参数写成“根据订单号查询订单详情需要传入订单号字符串”模型就能正确调用。参数 schema 要用标准的 JSON Schema 格式明确每个参数的类型、是否必填、取值范围。对于枚举类型的参数一定要把可选值列全否则模型可能编造出不存在的值。调试 MCP 工具时我的习惯是先脱离 AI 单独测试工具本身确认工具能正常工作再接入编排流程。这样能把“工具问题”和“编排问题”分开排查效率高很多。平台一般会提供工具调用的日志重点看模型传了什么参数、工具返回了什么结果这两个信息能定位绝大多数问题。3.3 SKILL 封装让能力可复用的关键SKILL 的价值在于复用。一个好的 Skill 应该做到输入明确、输出稳定、边界清晰。我见过太多 Skill 写得像万能提示词什么都能干结果什么都干不好。封装 Skill 时我建议遵循几个原则。第一单一职责一个 Skill 只做一件事。第二输入输出结构化尽量用 JSON 而不是自由文本方便上下游衔接。第三内置容错比如输入为空时返回明确提示而不是报错。第四版本管理Skill 的提示词会迭代要能追溯哪个版本产生了哪个结果。提示词工程在 Skill 里体现得最明显。我的经验是示例比描述更重要。与其写一大段“你要如何如何”不如给两三个输入输出示例模型模仿示例的准确率远高于理解抽象描述。另外把约束条件写在前面把期望格式写在后面这个顺序对输出稳定性有实际影响。3.4 RAG 检索增强从切分到重排的完整链路RAG 是让 AI 懂业务的核心手段但也是最容易做砸的环节。一个完整的 RAG 链路包括文档加载、文本切分、向量化、存储、检索、重排、注入上下文。每一环都有坑。文本切分是最容易被低估的一步。切太大检索精度下降切太小语义不完整。我的经验值是中文 300 到 500 字一段英文 200 到 300 词一段并且要保留一定的重叠overlap通常 10% 到 20%。重叠的作用是防止关键信息正好被切在边界上。向量化模型的选择直接影响检索质量。通用嵌入模型对专业领域的效果往往一般如果预算允许用领域数据微调过的嵌入模型效果会好很多。检索时纯向量检索对精确匹配不友好比如查一个具体的订单号向量检索可能返回语义相近但号码不同的结果。所以生产环境建议用混合检索向量检索加关键词检索再融合排序。重排rerank是提升精度的关键一步。初步检索召回一批候选再用重排模型精排取 top-k 注入上下文。这一步能显著提升最终答案的相关性代价是额外的延迟。我的建议是候选集召回 20 到 50 条重排后取 3 到 5 条注入这个比例在精度和延迟之间比较平衡。提示RAG 的效果不好时先别急着换模型。八成问题出在切分和检索环节。把检索到的原文打印出来看看如果检索结果本身就不相关那再强的模型也救不回来。4. 实操过程与核心环节实现4.1 从零搭一个带 RAG 的问答 Agent我拿一个典型场景来演示搭一个能回答内部文档问题的 Agent。这个场景覆盖了多供应商、RAG、Agent 编排三个核心模块。第一步配置模型供应商。对话模型选一个支持函数调用的嵌入模型选一个中文效果好的。配置里声明对话模型支持流式和函数调用嵌入模型只支持向量化。这里要注意对话模型和嵌入模型可以是不同供应商的平台的多供应商抽象就是为了支持这种混搭。第二步构建知识库。把文档加载进来按 400 字切分重叠 80 字。向量化后存入向量库。这里有个实操细节文档里的表格和图片要单独处理。表格转成结构化文本图片用多模态模型生成描述再入库。直接切分原始文档会把表格切得乱七八糟检索出来没法用。第三步定义检索工具。把知识库检索封装成一个 MCP 工具输入是查询语句输出是相关文档片段。工具描述要写清楚“用于查询内部文档知识库输入自然语言问题”。第四步编排 Agent。Agent 的系统提示词里说明回答用户问题前先调用知识库检索工具获取相关资料基于资料回答资料中没有的信息要明确说明不知道。这个约束非常重要能大幅降低幻觉。第五步测试和调优。准备一批测试问题覆盖知识库内有答案的、没有答案的、需要多段资料综合的。观察 Agent 是否正确调用工具、检索结果是否相关、最终答案是否准确。根据问题调整切分策略、检索参数、提示词。4.2 多 Agent 协作的编排示例再来看一个多 Agent 场景一个负责资料检索一个负责分析推理一个负责结果校验。这种结构适合对准确性要求高的任务。编排逻辑是这样的检索 Agent 先工作把相关资料整理成结构化摘要分析 Agent 拿到摘要后做推理产出初步结论校验 Agent 检查结论是否有资料支撑、逻辑是否自洽不通过就打回分析 Agent 重做。这里需要一个循环控制设置最大重试次数防止死循环。多 Agent 编排的关键是上下文传递。Agent 之间传的不是原始对话历史而是经过提炼的中间结果。传太多会浪费 token 且引入噪声传太少下游 Agent 信息不足。我的做法是定义一个明确的中间数据结构每个 Agent 只填自己负责的字段。调试多 Agent 时一定要能看到每个 Agent 的输入输出。平台如果支持执行轨迹追踪务必打开。我排查过一个案例最终发现是校验 Agent 的提示词里有个歧义表述导致它把正确结论判成了错误白白触发重试。4.3 流式输出与工程化细节流式输出是提升用户体验的关键。用户不用等完整结果生成可以边生成边看。但流式输出和工具调用、多 Agent 编排结合时会有复杂性。工具调用需要等模型输出完整的调用意图才能执行这期间流式输出会暂停。多 Agent 场景下每个 Agent 的输出是分段的。平台需要处理好这些边界把流式事件正确地推送给前端。工程化方面我特别关注几个点可观测性每次调用的输入输出、耗时、token 消耗都要有记录、限流与重试对供应商接口要做限流保护失败要有退避重试、成本控制设置单次请求和单日的 token 上限。这些在 Demo 阶段可以不管但上线前必须补齐。注意流式输出时如果发生错误已经推送出去的内容是收不回来的。所以要在流开始前做好参数校验把能提前发现的问题都提前拦掉。5. 常见问题与排查技巧实录5.1 工具调用失败排查表现象可能原因排查方法模型不调用工具工具描述模糊或与问题无关检查描述是否清晰说明使用场景调用参数错误参数 schema 定义不清核对 schema 类型和必填项工具执行报错工具本身逻辑问题脱离 AI 单独测试工具调用结果被忽略提示词未要求使用工具结果在系统提示词中明确要求频繁重复调用未设置调用次数上限增加最大调用次数限制这张表是我从实际项目里总结的基本覆盖了工具调用 90% 的问题。排查时按顺序来先确认模型有没有调用再确认参数对不对最后看结果有没有被用上。5.2 RAG 效果差的典型原因RAG 效果差我总结下来无非几个原因。切分不当是最常见的把完整语义切碎了。嵌入模型不匹配用英文模型处理中文或者用通用模型处理专业领域。检索策略单一只做向量检索遇到精确匹配就歇菜。上下文注入过多塞了一堆不相关的片段反而干扰模型。提示词没约束模型不看检索结果自己编。排查 RAG 问题的顺序应该是先看检索结果再看注入上下文最后看模型输出。如果检索结果就不对后面都是白搭。如果检索对但输出不对那是提示词的问题。5.3 多供应商切换的坑多供应商听起来美好实际切换时会遇到不少问题。输出格式不一致有的返回content有的返回text平台要统一。错误码不统一限流、超时、参数错误的表示方式各家不同要映射成统一错误类型。token 计算方式不同同样一段文本各家算出来的 token 数不一样成本核算要按供应商分别统计。我的建议是切换供应商前用同一批测试用例跑一遍对比输出质量和延迟。不要假设换个模型结果就一样不同模型的“性格”差异很大提示词可能需要针对性调整。5.4 性能与成本优化经验性能优化上缓存是最有效的手段。相同的问题和上下文结果可以缓存复用。并行化也很关键多个独立的工具调用或检索可以并行执行。上下文裁剪能显著降低延迟和成本只保留相关的历史对话。成本控制上我习惯给每个应用设置预算上限超过就告警或降级。选择模型时不要一味追求最强很多任务用小模型就够了。嵌入模型和对话模型分开选嵌入模型通常便宜很多可以放心用好的。6. 我在实际落地中的几点体会搭 AI 应用这件事工具和平台能帮你解决 70% 的问题剩下 30% 永远需要你自己对业务的理解。XXL-AI 这类平台的价值在于把通用能力标准化让你把精力放在业务逻辑上。但业务逻辑本身——什么该检索、什么该调用工具、什么该直接回答——这些判断只有你最清楚。我踩过最大的坑是过早追求架构完美。一开始就想把多 Agent、多供应商、RAG 全上齐结果调试成本高到离谱。后来我改成先用单 Agent 加 RAG 跑通核心场景确认价值后再逐步引入工具调用和多 Agent。这个渐进式路线帮我省了大量时间。还有一个体会是提示词和检索策略要一起调。很多人分开调调完提示词发现检索不行调完检索发现提示词又不对了。这两者是耦合的检索给什么料提示词就该怎么引导要放在一起迭代。最后分享一个实用技巧给每个 Agent 和 Skill 建一个测试用例集每次改动后跑一遍回归。AI 应用的行为不像传统代码那么确定没有回归测试你根本不知道改了一处会不会影响另一处。这个习惯看起来麻烦但长期看能省下大量排查时间。
