从零构建AI应用开发平台：Agent编排、多供应商接入与RAG实战

1. 为什么我会去折腾一个 AI 应用开发平台先说结论我最初并不是想造一个平台而是被项目里散落一地的 Agent 逻辑逼到没办法了。去年下半年开始团队里陆续接了四五个 AI 相关的需求有做知识库问答的有做流程自动化的还有做多轮对话客服的。每个需求单拎出来都不算复杂但问题出在它们各自为政——A 项目用一套提示词管理B 项目自己写了个工具调用循环C 项目把检索逻辑硬编码在业务代码里。等到要改一个模型供应商、换一个向量库、加一个外部工具的时候我发现自己要在四五个代码库里重复同样的改动。这就是我动手做XXL-AI的直接动机。它本质上是一个AI 应用开发平台核心能力围绕四块展开Agent 编排、多供应商接入、MCP SKILL RAG 三种扩展方式以及一套能扛住真实业务的工程化底座。说白了它想解决的问题是让 AI 应用的开发从每个项目重新造轮子变成在统一底座上拼装能力。这篇文章适合谁看如果你正在做 AI 应用被多模型切换、工具调用、知识库检索这些事反复折磨或者你团队里已经有多个 AI 项目开始出现重复建设那这篇内容应该能帮到你。我会把整个平台的设计思路、核心模块的实现要点、踩过的坑以及可以直接抄的配置方案都摊开讲。哪怕你只是想了解 Agent 编排和 RAG 到底该怎么落地也能从里面挑到有用的部分。需要提前说明的是下面涉及的具体实现细节有一部分是基于我实际项目的做法有一部分是基于行业常见实践的合理补充我会尽量标注清楚哪些是实测结论、哪些是推荐方案方便你按自己的场景取舍。2. 平台整体设计与核心思路拆解2.1 为什么不做成又一个全家桶框架市面上 AI 应用框架已经不少了我一开始也想过直接拿现成的用。但试了一圈之后发现两个问题一是很多框架把编排和运行时绑得太死你想换个模型供应商得改一堆配置甚至改代码二是扩展机制要么太弱只能加提示词要么太重要写完整的插件类。XXL-AI 的设计原则就是反着来——编排归编排运行时归运行时扩展归扩展三层解耦。具体来说平台分成四个层次。最底层是工程化底座负责配置管理、日志追踪、限流熔断、密钥托管这些和 AI 无关但任何生产系统都躲不掉的事。往上一层是供应商抽象层把 OpenAI、Claude、通义、DeepSeek、本地 Ollama 这些模型的调用差异抹平统一成一套接口。再往上是能力扩展层也就是 MCP、SKILL、RAG 这三种扩展方式分别对应接外部工具注入领域能力挂载知识库。最上面才是Agent 编排层用可视化的方式把模型、工具、知识库串成一条可执行的流程。这样分层的好处很直接换模型只动第二层加工具只动第三层改业务流程只动第四层。我实测下来把一个原本写死在代码里的客服 Agent 迁移到平台上只花了半天其中大部分时间还是在整理原来的提示词。2.2 三种扩展方式到底该怎么选这是我在实际项目里被问得最多的问题MCP、SKILL、RAG 到底有什么区别什么时候用哪个很多人一开始会混淆觉得都是给 AI 加能力其实它们的定位完全不同。MCP解决的是AI 怎么和外部系统对话的问题。它是一个协议层的标准让 Agent 能以统一的方式调用外部工具或服务比如查数据库、调 API、操作文件系统。你可以把它理解成 AI 世界的 USB 接口——只要对方支持这个协议插上就能用不用为每个工具单独写适配代码。SKILL解决的是AI 怎么掌握一类特定任务的做法的问题。它更像是一份封装好的操作手册加执行逻辑比如如何做代码审查如何生成周报如何做竞品分析。一个 SKILL 里通常包含提示词模板、few-shot 示例、可选的工具调用链以及输出格式约束。它不依赖外部系统纯粹是能力的沉淀和复用。RAG解决的是AI 怎么获取它训练时没见过的知识的问题。通过检索增强把企业文档、产品手册、历史工单这些私有知识挂载进来让模型在回答时能引用真实资料而不是靠记忆瞎编。我一般给团队的建议是要接外部系统用 MCP要固化一类任务用 SKILL要注入私有知识用 RAG。三者可以叠加使用比如一个技术支持 Agent可以同时挂 RAG 知识库、调用 MCP 查工单系统、再用 SKILL 约束回复格式。2.3 多供应商接入的取舍逻辑多供应商这件事很多人第一反应是我接一个不就够了。但真实业务里你迟早会遇到这几种情况某个模型突然限流了要临时切换、不同任务用不同模型更省钱、客户要求数据必须走本地模型、某个模型对中文支持更好。所以供应商抽象层不是锦上添花而是迟早要用。我的做法是定义一个统一的ModelProvider接口包含chat、embedding、stream三个核心方法每个具体供应商实现这个接口。上层编排只依赖接口不关心底层是谁。配置上用一个 provider 注册表支持运行时热切换。这里有个细节值得说不同供应商的 token 计算方式、上下文窗口、函数调用格式都不一样我在抽象层里加了一层能力描述让编排层能知道当前模型支持什么、不支持什么避免调用到不支持的能力。3. 核心模块的细节解析与实操要点3.1 Agent 编排从写代码到画流程Agent 编排是平台的门面也是最容易做砸的地方。我见过太多编排工具要么抽象过度导致简单事情复杂化要么太底层导致还是要写大量代码。XXL-AI 的编排设计遵循一个原则常见场景零代码复杂场景可插代码。编排的基本单元是节点。一个典型的 Agent 流程包含这几类节点输入节点接收用户请求、模型节点调用 LLM、工具节点调用 MCP 或内置工具、检索节点查 RAG 知识库、条件节点根据结果分支、输出节点返回结果。节点之间用连线表示数据流向每个节点的输出可以作为下游节点的输入变量。这里的关键设计是变量系统。每个节点都有输入变量和输出变量变量名在整个流程内唯一。比如模型节点的输出可以命名为answer下游的条件节点就可以用answer.contains(无法回答)来判断是否要走兜底分支。变量系统让流程具备了真正的数据流转能力而不是简单的线性拼接。实操中我总结了几条经验。第一节点粒度不要太细。有人喜欢把一个提示词拆成好几个节点结果流程图画得像蜘蛛网维护起来很痛苦。我的建议是一个节点做一件完整的事比如生成初稿审核内容格式化输出各是一个节点而不是把拼接提示词调用模型解析结果拆成三个。第二善用子流程。如果一个流程被多个主流程复用就把它抽成子流程通过参数传递数据。第三给每个节点加超时和重试。模型调用偶尔会卡住没有超时保护的流程会一直挂着。3.2 多供应商接入统一接口背后的坑多供应商接入听起来简单实际做起来坑不少。我踩过的第一个坑是流式输出的差异。OpenAI 的流式返回是 SSE 格式每个 chunk 是一个 JSON有些供应商返回的是纯文本流还有些在流式模式下不支持函数调用。我的处理方式是在抽象层做归一化统一转成StreamChunk对象包含delta、finishReason、toolCalls三个字段上层不用关心底层格式。第二个坑是函数调用的格式差异。OpenAI 用tools参数Claude 用tools但结构不同有些国产模型用的是自己的一套。我在抽象层定义了一套标准的工具描述格式然后在每个 provider 里做转换。这里要注意不是所有模型都支持函数调用编排层需要根据模型能力描述来决定是否启用工具节点。第三个坑是错误处理和重试。不同供应商的错误码、限流策略、重试建议都不一样。我统一封装了一个ProviderError包含type限流/超时/参数错误/服务异常、retryable是否可重试、retryAfter建议重试间隔三个字段。编排层根据这些信息决定是重试、降级到备用模型还是直接报错。配置上我用一个 YAML 文件管理所有供应商providers: - name: openai-gpt4 type: openai model: gpt-4-turbo apiKey: ${OPENAI_API_KEY} baseUrl: https://api.openai.com/v1 capabilities: [chat, stream, function_call, vision] limits: maxTokens: 128000 rpm: 500 - name: local-ollama type: ollama model: qwen2.5:14b baseUrl: http://localhost:11434 capabilities: [chat, stream] limits: maxTokens: 32000 rpm: 60这种配置方式的好处是新增一个供应商只需要加一段配置不用改代码。密钥用环境变量注入避免硬编码。3.3 MCP 扩展让 Agent 真正能动手MCP 是这两年 AI 圈讨论很多的一个协议标准它的核心价值是让 AI 应用能以统一方式接入外部工具和数据源。在 XXL-AI 里MCP 是工具节点的底层支撑。我实现 MCP 接入时重点解决了三个问题。第一是工具发现。MCP 服务端会暴露一个工具列表包含每个工具的名称、描述、参数 schema。平台启动时拉取这个列表注册到工具注册表里。编排时模型节点可以根据工具描述自动决定调用哪个工具这就是所谓的 function calling。第二是参数校验和转换。模型生成的工具调用参数是 JSON但不一定符合 schema。我在调用前做一层校验参数不对就返回错误让模型重新生成。这里有个实用技巧在工具描述里写清楚参数示例能显著降低模型生成错误参数的概率。第三是结果处理。工具返回的结果可能是任意结构需要转成模型能理解的文本。我的做法是保留原始 JSON同时生成一段自然语言摘要一起塞回给模型。这样模型既能理解语义又能在需要时引用具体字段。实操中我遇到一个典型问题MCP 服务连接失败时整个 Agent 流程会卡住。解决办法是给每个 MCP 连接加健康检查和超时连接不可用时工具节点直接返回工具暂不可用让模型走兜底逻辑而不是让整个流程挂掉。3.4 SKILL 扩展把经验沉淀成可复用的能力SKILL 是我个人最喜欢的一个设计因为它解决了一个很实际的问题团队里那些会做某件事的经验怎么变成所有人都能用的能力。一个 SKILL 的结构包含四部分元信息名称、描述、适用场景、提示词模板带变量的系统提示、示例集few-shot 示例、输出约束格式要求、校验规则。比如一个代码审查 SKILL它的提示词模板会告诉模型你是一个资深工程师请从可读性、性能、安全三个维度审查代码示例集里放几个审查案例输出约束要求按固定格式返回问题列表。SKILL 和普通提示词的区别在于可组合、可版本化、可测试。可组合是指一个 Agent 可以挂载多个 SKILL根据任务类型动态选择可版本化是指 SKILL 有版本号改了之后可以回滚可测试是指每个 SKILL 可以配一组测试用例改了提示词之后跑一遍测试看输出是否还符合预期。我踩过的一个坑是SKILL 之间会冲突。比如一个 SKILL 要求回答要简洁另一个要求回答要详细同时挂载就会让模型无所适从。解决办法是在编排层做优先级管理同一时刻只激活一个主 SKILL其他作为辅助。3.5 RAG 扩展知识库不是塞进去就行RAG 是三个扩展里最容易上手、也最容易做砸的。很多人以为 RAG 就是把文档切块、向量化、检索、塞给模型但实际效果往往很差。我在项目里踩过的坑基本都集中在检索质量上。第一个问题是切块策略。固定长度切块会把一句话切成两半导致检索到的片段语义不完整。我的做法是按语义边界切块优先在段落、标题、列表项处切分同时保留一定的重叠overlap避免上下文丢失。对于结构化文档还会保留层级信息比如第三章 3.2 节 具体内容。第二个问题是检索召回率。纯向量检索对语义相似但用词不同的查询效果一般。我用了混合检索向量检索 关键词检索BM25两路结果做融合排序。实测下来混合检索的命中率比纯向量检索高不少尤其是在专业术语多的场景。第三个问题是重排序。检索回来的 top-k 片段相关性参差不齐。我加了一个重排序模型rerank对候选片段重新打分只把最相关的几个塞给模型。这一步对最终回答质量的提升非常明显代价是多一次模型调用。第四个问题是知识库更新。文档改了之后向量库要同步更新。我的做法是给每个文档块打上版本标记更新时先删旧块再插新块避免残留过期内容。关于热词里提到的RAG 知识库能存储图片吗我的实践是可以但要看场景。如果图片里有文字可以先做 OCR 提取文本再入库如果是纯图可以用多模态模型生成图片描述把描述文本入库。检索时返回图片 URL 和描述让模型决定是否引用。4. 完整实操流程与关键环节实现4.1 环境准备与依赖安装先把底座搭起来。XXL-AI 的后端我选的是 Java 技术栈Spring Boot LangChain4j原因是团队里 Java 人多而且 LangChain4j 对国内模型的支持比较友好。前端用 Vue3 TypeScript编排画布用的是开源的流程图库。环境要求如下组件版本要求说明JDK17推荐 21虚拟线程对 IO 密集场景友好Maven3.8构建工具Node.js18前端构建PostgreSQL14主数据库存配置和元数据Redis6缓存和限流向量库Milvus 2.3 或 pgvectorRAG 检索安装步骤不复杂核心是配置好数据库和向量库。这里有个细节向量库的选型要看数据量。数据量小百万级以下用 pgvector 就够了省一个组件数据量大或者要高并发上 Milvus。我一开始用 pgvector后来数据涨到千万级检索变慢才迁到 Milvus。4.2 供应商配置与模型接入环境好了之后第一件事是配置模型供应商。前面给过 YAML 示例这里补充几个实操要点。密钥管理绝对不要把 API Key 写进配置文件提交到代码库。我用的是环境变量 配置中心的方式本地开发用.env文件加进.gitignore生产环境用配置中心下发。模型能力声明每个供应商要声明自己支持哪些能力。这个声明会直接影响编排层的可用节点。比如一个不支持 function calling 的模型编排时工具节点就会置灰。连接测试配置完供应商后平台提供一个测试连接功能发一个最简单的请求验证配置是否正确。这一步能省掉很多配了半天发现 key 错了的时间。4.3 编排一个完整的 Agent 流程我拿一个实际项目举例智能客服 Agent。需求是接收用户问题先查知识库如果知识库有答案就直接回复没有就调用工单系统查历史工单还不行就转人工。流程设计如下输入节点接收用户问题question检索节点用question查 RAG 知识库返回kbResults和kbScore条件节点判断kbScore 0.8是则走模型节点 A否则走工具节点模型节点 A基于kbResults生成回答输出answer工具节点调用 MCP 工单查询工具参数question返回ticketResults模型节点 B基于ticketResults生成回答输出answer条件节点判断answer是否包含无法回答是则走转人工节点输出节点返回answer这个流程里每个节点的配置都要仔细。检索节点的 top-k 我设的是 5重排序后取 3条件节点的阈值 0.8 是调了几次才定下来的太低会引入不相关答案太高会漏掉有效答案。4.4 RAG 知识库的搭建与调优知识库搭建分四步文档采集、切块、向量化、入库。文档采集支持多种格式PDF、Word、Markdown、HTML、纯文本。PDF 解析是个坑扫描版 PDF 要先 OCR我用的是开源的 OCR 方案准确率够用。切块策略我前面提过按语义边界切块大小控制在 300-500 字重叠 50 字。这个参数不是拍脑袋定的是实测出来的块太小语义不完整块太大检索精度下降。向量化用 embedding 模型我选的是支持中文的模型。这里要注意embedding 模型和生成模型可以不是同一个供应商。我用国产 embedding 模型做向量化用另一个模型做生成效果和成本都更优。入库后要做检索测试。我准备了一组测试问题每个问题标注了期望命中的文档块然后跑检索看命中率。命中率低就调切块策略或换 embedding 模型反复迭代。4.5 工程化底座的落地细节工程化底座是平台能不能上生产的关键。我重点做了这几件事。可观测性每次 Agent 执行都生成一个 trace记录每个节点的输入、输出、耗时、token 消耗。出问题时能快速定位是哪个节点的问题。这个功能在排查为什么这次回答不对时特别有用。限流与熔断模型调用是外部依赖必须做保护。我用了令牌桶算法做限流每个供应商独立配置 QPS。熔断用 Resilience4j连续失败达到阈值就熔断走降级逻辑。成本控制每次调用记录 token 消耗按供应商和项目维度统计。设置预算告警超了就通知。这个功能帮我们避免过一次某天突然跑了几百万 token的事故。版本管理Agent 流程、SKILL、提示词都支持版本化。改了之后先发布到测试环境验证没问题再上生产。出问题可以一键回滚。5. 常见问题与排查技巧实录5.1 模型调用类问题问题一模型返回结果不稳定同样的输入有时对有时错。这是最常见的抱怨。排查思路先看 temperature 设置如果大于 0.3调低试试再看提示词是否有歧义加几个 few-shot 示例还不行就换模型有些模型在特定任务上就是不稳定。问题二流式输出中断。通常是网络问题或超时设置太短。检查客户端的超时配置服务端的流式响应要有心跳保活。另外注意某些代理层会缓冲流式响应导致看起来不流式。问题三函数调用参数格式错误。模型生成的参数不符合 schema。解决办法是在工具描述里写清楚参数示例同时在调用前做校验不合法就返回错误让模型重试。5.2 RAG 检索类问题问题一检索不到相关内容。先确认文档是否真的入库了再检查 embedding 模型是否适合当前语言。中文场景用英文 embedding 模型效果会很差。还可以试试混合检索关键词检索能兜住向量检索漏掉的情况。问题二检索到不相关内容。调高相似度阈值或者加重排序。如果还是不行可能是切块策略有问题块太大导致语义稀释。问题三知识库更新后检索结果没变。检查向量库是否真的更新了。常见原因是只更新了文档没更新向量或者有缓存没清。我的做法是更新时打版本标记检索时只查最新版本。5.3 编排流程类问题问题一流程执行到某个节点卡住。先看是不是模型调用超时再看是不是工具节点在等外部系统响应。给每个节点加超时是必须的。问题二变量传递错误。检查变量名是否一致上游节点的输出变量名和下游节点的输入变量名要对上。我建议用统一的命名规范比如nodeId_outputName。问题三条件分支判断不符合预期。检查条件表达式的语法以及变量类型。字符串比较和数字比较的写法不一样容易搞错。5.4 常见问题速查表问题现象可能原因排查方向解决建议回答质量差提示词/模型/检索逐层排查先固定模型调提示词再调检索响应慢模型/网络/检索看 trace 耗时分布优化慢节点加缓存成本高token 消耗大看 token 统计精简提示词换小模型检索不准切块/embedding跑检索测试调切块换模型加重排序工具调用失败参数/连接看工具调用日志校验参数加健康检查流程卡死超时/死循环看节点状态加超时检查循环条件5.5 几个独家避坑技巧技巧一提示词要版本化。我见过太多团队提示词改来改去最后不知道哪个版本效果好。把提示词当代码管理每次改动记录原因和效果。技巧二给模型退路。在提示词里明确告诉模型如果不知道就说不知道能显著降低幻觉。同时编排层要有兜底分支模型答不上来时有降级方案。技巧三小步快跑做 A/B 测试。改了提示词或检索策略后不要直接全量上线先拿 10% 流量测试对比效果再决定。技巧四日志要记全。每次调用的输入、输出、耗时、token、模型版本都要记。出问题时这些日志就是救命稻草。技巧五别迷信大模型。很多任务用小模型 好的提示词 RAG效果不比大模型差成本却低很多。先试小模型不够再上大的。6. 我对这套平台的一些真实体会做这个平台最大的收获不是技术上的而是认知上的。我一开始以为 AI 应用开发的核心是选对模型做完之后才发现模型只是其中一环真正决定成败的是工程化能力。同样的模型有没有好的编排、有没有 RAG、有没有工具调用、有没有可观测性效果天差地别。另一个体会是扩展机制的设计比功能本身更重要。MCP、SKILL、RAG 这三种扩展方式本质上是在回答当需求变化时我改哪里。如果每次加需求都要改核心代码这个平台就是失败的如果加需求只是加配置、加 SKILL、加知识库那它就成功了。最后分享一个我一直在用的小习惯每次上线一个新 Agent我都会准备一组回归测试问题包含正常问题、边界问题、恶意问题。每次改动后跑一遍看回答是否还符合预期。这个习惯帮我避免了好几次改了一个地方坏了另一个地方的事故。AI 应用的不确定性比传统软件大得多测试是唯一能给你安全感的东西。