企业官网建设流程全解析

1. 为什么我要自己搭一套 AI 应用开发平台

先说结论：市面上能用的 Agent 框架我基本都摸过一遍，从早期的 LangChain 到后来的各种编排工具，最后促使我自己动手做 XXL-AI 的原因只有一个——没有一个平台能同时把「编排灵活度」「多供应商切换」「扩展能力」和「工程化落地」这四件事都做扎实。

大部分框架的典型问题是：Demo 跑起来很惊艳，一上生产就露馅。要么是编排逻辑写死在代码里，改一个流程要重新发版；要么是模型供应商锁死，想从一家换到另一家得改几十处调用；要么是扩展能力弱，想接个知识库、加个自定义工具，得从底层改起。更别提工程化那部分——日志、监控、限流、重试、成本统计，这些真正决定能不能上生产的东西，很多框架压根没认真做。

XXL-AI 这个项目就是冲着这些痛点去的。它的定位很明确：一个面向生产环境的 AI 应用开发平台，核心能力包括 Agent 编排、多供应商接入、MCP + SKILL + RAG 三层扩展体系，以及一整套工程化底座。说白了，它想解决的是「从想法到上线」这条链路上所有的脏活累活。

这篇文章适合谁看？如果你正在做 AI 应用开发，被编排逻辑折磨过，被供应商切换坑过，或者正在纠结 RAG 到底怎么落地，那这篇内容应该能给你不少参考。我会把每个模块的设计思路、实操细节、踩过的坑都摊开讲，尽量做到你照着就能复现。

2. 整体架构设计与核心思路拆解

2.1 四层架构的分层逻辑

XXL-AI 的整体架构我分成了四层，从上到下依次是：应用层、编排层、能力层、底座层。这个分层不是拍脑袋定的，而是根据实际开发中「变化频率」来划分的——越往上变化越快，越往下越稳定。

应用层是面向具体业务场景的，比如客服机器人、文档助手、代码审查工具。这一层变化最频繁，今天做个新场景，明天调个流程，所以它必须足够轻，不能有太多约束。

编排层是 Agent 的核心，负责定义「谁在什么时候做什么」。这一层的关键是可视化 + 可编程双模式——简单流程拖拽搞定，复杂逻辑写代码扩展。我见过太多团队在纯可视化工具里挣扎，稍微复杂点的条件分支就画不出来了。

能力层就是 MCP、SKILL、RAG 这三块。MCP 负责对接外部工具和数据源，SKILL 负责封装可复用的能力单元，RAG 负责知识增强。这三者各司其职，又能互相组合。

底座层是工程化的部分：模型供应商抽象、日志监控、限流熔断、成本统计、权限管理。这层最不起眼，但决定了平台能不能扛住生产流量。

提示：分层的关键原则是「依赖单向」——上层可以调下层，下层不能反向依赖上层。我见过不少项目因为底座层反向依赖了业务逻辑，导致换个场景就得改底层，非常痛苦。

2.2 为什么选择「编排 + 扩展 + 底座」三件套

很多人问我，为什么不直接用一个现成的 Agent 框架，非要自己搭？我的回答是：现成框架解决的是「能不能跑」，我要解决的是「能不能规模化跑」。

编排解决的是「流程怎么定义」。一个真实的 AI 应用，流程往往不是线性的——有并行、有分支、有循环、有中断恢复。纯代码写编排，改起来痛苦；纯可视化画编排，复杂场景画不出来。所以 XXL-AI 的做法是：用 DSL 描述编排，可视化工具生成 DSL，代码也能直接写 DSL。这样既保证了灵活性，又降低了门槛。

扩展解决的是「能力怎么复用」。MCP 是工具接入的标准协议，SKILL 是能力封装的单元，RAG 是知识注入的方式。这三者组合起来，能让一个 Agent 快速获得「查资料、调工具、用知识」的能力，而不用每次从零写。

底座解决的是「怎么稳定运行」。这部分最容易被忽视，但恰恰是生产环境和 Demo 的分水岭。模型调用失败怎么重试？供应商限流怎么切换？成本超预算怎么告警？这些问题不解决，平台就是个玩具。

2.3 多供应商抽象的设计取舍

多供应商接入这块，我踩过最大的坑就是抽象层次选错了。一开始我想做一个「万能接口」，把所有供应商的差异都抹平，结果发现根本做不到——不同供应商的参数、能力、返回格式差异太大，强行统一反而丢了很多特性。

后来我改成了两层抽象：底层是「供应商适配器」，每个供应商一个适配器，负责把统一请求转成该供应商的格式；上层是「能力接口」，定义平台需要的能力（比如对话、嵌入、重排），由适配器实现。这样既保留了供应商特性，又保证了上层调用的一致性。

具体来说，一个对话请求进来，平台会先根据路由策略选一个供应商，然后调用对应的适配器。适配器负责处理参数映射、鉴权、重试、错误转换。如果这个供应商挂了，平台会自动降级到备用供应商。整个过程对上层透明。

这个设计的核心好处是：加一个新供应商，只需要写一个适配器，不用动上层任何代码。我实测下来，接一个新供应商平均半天就能搞定。

3. Agent 编排的核心细节与实操要点

3.1 编排 DSL 的设计哲学

XXL-AI 的编排 DSL 我改了三版才定型。第一版是纯 JSON，写起来太啰嗦；第二版是 YAML，可读性好但表达能力有限；第三版是基于 YAML 的领域特定语法，在 YAML 基础上加了变量引用、条件表达式、循环语法。

一个最简单的编排定义长这样：

name: customer_service nodes: - id: receive type: input schema: question: string - id: classify type: llm model: gpt-4 prompt: | 判断用户问题类型：{{question}} 只返回：售前/售后/投诉 - id: route type: switch condition: "{{classify.output}}" cases: "售前": sales_flow "售后": after_sales_flow "投诉": complaint_flow

这个 DSL 的关键设计点是：节点之间通过变量引用连接，而不是硬编码的连线。{{classify.output}}这种写法，让流程的依赖关系一目了然，也方便做静态分析——比如检测循环依赖、未定义变量。

注意：变量引用一定要做类型检查。我早期版本没做，结果运行时才发现类型不匹配，排查起来很痛苦。现在 DSL 编译阶段就会做类型推导，提前报错。

3.2 节点类型与执行引擎

编排引擎支持的核心节点类型有这几类：

• 输入输出节点：定义流程的入口和出口，负责参数校验和结果格式化。
• LLM 节点：调用大模型，支持提示词模板、参数配置、输出解析。
• 工具节点：调用 MCP 工具或 SKILL，支持参数映射和结果处理。
• 控制节点：条件分支、循环、并行、等待、中断。
• 知识节点：RAG 检索，支持多路召回和重排。

执行引擎的核心是状态机 + 事件驱动。每个节点执行完会发出事件，引擎根据事件决定下一步。这样做的好处是支持中断恢复——如果流程执行到一半服务重启了，可以从最后一个成功节点继续，不用从头再来。

执行引擎还有一个关键设计是并发控制。并行节点会同时执行多个分支，但引擎会限制最大并发数，避免打爆下游服务。这个限制可以在编排定义里配置，也可以全局配置。

3.3 实操：从零编排一个多 Agent 协作流程

光说理论没意思，我拿一个实际场景来演示：一个「技术文档问答」的多 Agent 协作流程。这个流程有三个 Agent：检索 Agent 负责找相关文档，推理 Agent 负责组织答案，审核 Agent 负责检查答案质量。

第一步，定义检索 Agent：

name: retrieval_agent nodes: - id: embed type: llm model: embedding-model input: "{{question}}" - id: search type: rag index: tech_docs query_vector: "{{embed.output}}" top_k: 10 - id: rerank type: llm model: rerank-model query: "{{question}}" documents: "{{search.output}}" top_k: 3

第二步，定义推理 Agent：

name: reasoning_agent nodes: - id: generate type: llm model: gpt-4 prompt: | 根据以下文档回答问题： 文档：{{documents}} 问题：{{question}} 要求：只基于文档内容回答，不确定的地方明确说明。

第三步，定义审核 Agent：

name: review_agent nodes: - id: check type: llm model: gpt-4 prompt: | 检查以下答案是否基于给定文档： 答案：{{answer}} 文档：{{documents}} 返回：PASS 或 FAIL + 原因 - id: decide type: switch condition: "{{check.output}}" cases: "PASS": end "FAIL": reasoning_agent

最后，把三个 Agent 串起来：

name: doc_qa nodes: - id: retrieval type: agent ref: retrieval_agent - id: reasoning type: agent ref: reasoning_agent input: documents: "{{retrieval.output}}" - id: review type: agent ref: review_agent input: answer: "{{reasoning.output}}"

这个流程跑下来，实测效果比单 Agent 好很多。检索 Agent 专注找资料，推理 Agent 专注组织答案，审核 Agent 专注质量把关，各司其职。审核不通过会自动回到推理 Agent 重来，最多重试 3 次。

3.4 编排的注意事项与踩坑记录

第一个坑是循环控制。审核 Agent 失败后回到推理 Agent，这个循环必须有次数限制，否则可能死循环。我在 DSL 里加了max_iterations配置，默认 3 次，超过就强制结束并返回当前结果。

第二个坑是上下文膨胀。多 Agent 协作时，每个 Agent 的输出都会传给下一个，如果不做裁剪，上下文会越来越大，最后超出模型窗口。我的做法是只传必要字段，比如审核 Agent 只需要答案和文档，不需要检索 Agent 的中间过程。

第三个坑是错误传播。一个 Agent 失败了，是让整个流程失败，还是降级处理？这个要按场景配置。我的默认策略是：关键节点失败则流程失败，非关键节点失败则降级。比如检索失败可以降级到只用模型知识回答，但推理失败就没法降级了。

4. MCP + SKILL + RAG 三层扩展体系

4.1 MCP：工具接入的标准协议

MCP 这块我理解下来，它的核心价值是把「工具接入」这件事标准化。在没有 MCP 之前，每接一个工具都要写一套适配代码，工具多了就是灾难。MCP 定义了工具的描述格式、调用协议、返回格式，让工具可以像插件一样即插即用。

XXL-AI 对 MCP 的支持分两部分：作为 MCP 客户端，能调用外部 MCP 服务；作为 MCP 服务端，能把平台能力暴露给其他系统。这两部分我都做了，实测下来客户端用得更多。

接一个 MCP 工具的过程大概是这样的：

mcp_servers: - name: filesystem transport: stdio command: npx args: ["-y", "@modelcontextprotocol/server-filesystem", "/data"] - name: database transport: http url: http://localhost:8080/mcp headers: Authorization: "Bearer {{token}}"

配置好之后，平台会自动发现这些 MCP 服务提供的工具，并在编排里可用。调用的时候直接引用工具名就行：

- id: read_file type: mcp server: filesystem tool: read_file input: path: "{{file_path}}"

提示：MCP 服务的鉴权信息不要硬编码在配置里，用变量引用，从环境变量或密钥管理服务注入。我见过有人把 token 直接写配置文件提交到仓库，非常危险。

4.2 SKILL：可复用能力的封装单元

SKILL 和 MCP 的区别，我用一句话概括：MCP 是「接外部工具」，SKILL 是「封装内部能力」。MCP 解决的是「怎么调别人的东西」，SKILL 解决的是「怎么把自己的东西复用起来」。

一个 SKILL 本质上是一段可复用的编排逻辑，加上输入输出定义。比如「文档摘要」这个 SKILL：

name: summarize description: 对长文档生成摘要 input: document: string max_length: integer output: summary: string nodes: - id: chunk type: split input: "{{document}}" chunk_size: 2000 - id: summarize_each type: map over: "{{chunk.output}}" nodes: - id: sum type: llm model: gpt-4 prompt: "总结以下内容：{{item}}" - id: merge type: llm model: gpt-4 prompt: | 合并以下摘要，控制在 {{max_length}} 字以内： {{summarize_each.output}}

SKILL 的好处是一次封装，处处复用。我在多个项目里都用到了这个摘要 SKILL，不用每次重写。而且 SKILL 可以嵌套——一个 SKILL 里可以调另一个 SKILL，形成能力组合。

SKILL 的管理我做了版本控制。每次修改 SKILL 会生成新版本，编排里可以指定用哪个版本。这样升级 SKILL 不会影响正在运行的流程，非常实用。

4.3 RAG：知识增强的落地细节

RAG 这块是问得最多的，也是坑最多的。我先说一个常见误区：很多人以为 RAG 就是「向量检索 + 拼提示词」，其实远不止。一个能用的 RAG 系统，至少包含这几个环节：文档解析、分块、嵌入、索引、检索、重排、生成。

文档解析这块，不同格式差异很大。PDF 要处理表格和图片，Word 要处理样式，Markdown 要处理代码块。我的做法是按格式选解析器，解析结果统一成结构化文本。图片和表格单独提取，作为元数据附加。

分块是最影响效果的环节。分太大，检索精度低；分太小，上下文不完整。我的经验值是500-1000 字一块，重叠 100-200 字。但这不是固定的，代码类文档要按函数分块，法律文档要按条款分块。XXL-AI 支持自定义分块策略，按文档类型配置。

嵌入和索引这块，关键是选对嵌入模型。中文场景我实测下来，多语言模型比纯中文模型效果好，因为很多技术文档是中英混合的。索引我用的是向量 + 关键词混合索引，检索时两路召回再融合，命中率比纯向量高不少。

检索和重排是提升效果的关键。我的做法是先粗召回 20-50 条，再用重排模型精排到 3-5 条。重排模型比嵌入模型更准，但更慢，所以只用在精排阶段。实测下来，加了重排之后，答案准确率能提升 20% 以上。

生成这块，提示词模板很关键。我的模板里会明确要求「只基于给定文档回答」「不确定就说不确定」「引用来源」。这样能有效减少幻觉。

4.4 三层体系怎么组合使用

MCP、SKILL、RAG 这三者不是孤立的，组合起来才能发挥最大价值。我举一个实际例子：一个「合同审查」Agent。

它用 RAG 检索相关法条和公司历史合同，用 SKILL 封装「条款提取」「风险识别」这些可复用能力，用 MCP 接入外部工具比如「企业信息查询」「印章识别」。整个流程是：先 RAG 找相关法条，再 SKILL 提取合同条款，然后 MCP 查企业信息，最后综合判断风险。

这种组合的价值在于每个能力都专注做一件事，通过编排组合成复杂能力。这比写一个巨大的单体 Agent 要好维护得多。

5. 工程化底座的实现细节

5.1 模型供应商抽象与路由

多供应商这块，前面说了是两层抽象。这里补充一下路由策略的实现。路由决策考虑这几个因素：成本、延迟、可用性、能力匹配。

成本这块，每个供应商每个模型都有单价配置，路由时会估算这次调用的成本，优先选便宜的。延迟这块，平台会实时统计每个供应商的响应时间，优先选快的。可用性这块，会做健康检查，挂了的供应商自动剔除。能力匹配这块，比如需要长上下文就选支持长上下文的模型。

路由策略是可配置的，不同场景可以用不同策略。比如客服场景优先延迟，批处理场景优先成本。

routing: strategy: cost_first fallback: - provider: openai model: gpt-4 - provider: anthropic model: claude-3 circuit_breaker: failure_threshold: 5 recovery_timeout: 60

熔断这块，我用的是经典的滑动窗口 + 失败率阈值。一个供应商在 60 秒内失败超过 5 次，就熔断 60 秒，期间请求走备用供应商。60 秒后放一个请求试探，成功就恢复。

5.2 日志、监控与成本统计

工程化底座里，我觉得最重要的是可观测性。一个 AI 应用出问题了，你得能快速定位是哪个环节的问题。XXL-AI 的日志分三层：请求日志、节点日志、模型调用日志。

请求日志记录整个流程的输入输出、耗时、状态。节点日志记录每个节点的执行情况。模型调用日志记录每次模型调用的提示词、返回、token 数、成本。这三层日志通过 trace_id 关联，排查问题时可以一路追下去。

监控这块，我做了几个关键指标：QPS、P99 延迟、错误率、token 消耗、成本。这些指标按供应商、按模型、按场景维度统计，方便发现异常。比如某个供应商的错误率突然升高，或者某个场景的成本超预算，都能及时告警。

成本统计是很多团队忽视的，但很重要。我见过有团队一个月烧了几万块才发现，因为没做成本监控。XXL-AI 的成本统计精确到每次调用，能按天、按场景、按用户维度汇总。

5.3 限流、重试与降级

限流这块，我做了多级限流：全局限流、供应商限流、用户限流。全局限流保护平台本身，供应商限流保护下游，用户限流防止单个用户打爆。

重试策略要区分错误类型。网络错误、超时错误可以重试，参数错误、鉴权错误不能重试。重试要用指数退避，避免雪崩。我的默认配置是：最多重试 3 次，间隔 1s、2s、4s。

降级策略按场景配置。比如模型调用失败，可以降级到备用模型；备用模型也失败，可以降级到缓存结果；缓存也没有，就返回兜底话术。降级链路要提前设计好，不能等出问题了才想。

注意：重试和降级都要考虑幂等性。如果一个操作不是幂等的，重试可能导致重复执行。比如「下单」这种操作，重试前要确认是否已经成功。

5.4 权限与多租户

如果平台要给多个团队用，权限和多租户是必须的。XXL-AI 的权限模型是RBAC + 资源隔离。角色分管理员、开发者、使用者，权限控制到「能不能创建编排」「能不能调用某个 SKILL」「能不能看某个场景的日志」。

多租户这块，每个租户有独立的编排、SKILL、知识库、配置。租户之间数据隔离，但可以共享公共的 MCP 工具和模型供应商。这样既保证了隔离性，又避免了重复配置。

6. 常见问题与排查技巧实录

6.1 编排执行常见问题速查

6.2 RAG 效果差的排查思路

RAG 效果差是最常见的问题，我总结了一套排查流程：

第一步，确认是检索问题还是生成问题。把检索到的文档单独拿出来看，如果文档本身就不相关，那是检索问题；如果文档相关但答案不对，那是生成问题。

第二步，如果是检索问题，检查这几个点：分块是否合理（太大太小都不行）、嵌入模型是否适合（中文场景要用多语言模型）、相似度阈值是否合适（太高召回少，太低噪音多）、是否需要重排（加了重排通常能提升）。

第三步，如果是生成问题，检查提示词模板。常见问题是提示词没有明确要求「只基于文档回答」，导致模型自由发挥。另外要检查上下文是否太长，太长的上下文会稀释关键信息。

第四步，如果都不行，考虑换嵌入模型或加重排。我实测下来，换一个更好的嵌入模型，效果提升最明显。

6.3 多供应商切换的坑

多供应商切换有几个坑我踩过：

第一个坑是参数不兼容。不同供应商的参数名不一样，比如有的叫max_tokens，有的叫max_output_tokens。适配器要做好映射，不能直接透传。

第二个坑是返回格式不一致。有的返回content，有的返回message.content，有的返回choices[0].text。适配器要统一成平台格式。

第三个坑是错误码不统一。限流错误，有的返回 429，有的返回 503。适配器要统一错误类型，上层才能正确处理。

第四个坑是能力差异。不是所有模型都支持函数调用、JSON 模式、流式输出。路由时要检查能力匹配，不支持的特性要降级处理。

6.4 性能优化的实操心得

性能优化这块，我最大的心得是先测量再优化。很多人一上来就优化，结果优化了不关键的地方，白费功夫。

我的做法是先做全链路追踪，找出耗时最长的环节。通常瓶颈在这几个地方：模型调用（占大头）、RAG 检索（如果索引大）、工具调用（如果外部服务慢）。

模型调用优化，主要是缓存 + 并发。相同请求可以缓存结果，多个独立调用可以并发。我实测下来，加缓存能减少 30% 的调用量，加并发能减少 50% 的延迟。

RAG 检索优化，主要是索引优化 + 召回策略。索引用 HNSW 比 IVF 快，召回用混合检索比纯向量准。如果数据量大，可以做分层索引，先粗筛再精筛。

工具调用优化，主要是超时 + 降级。外部服务不可控，必须设超时，超时就走降级。我见过因为一个外部工具卡住，导致整个流程挂掉的案例。

7. 我在实际项目中的一些体会

搭这套平台的过程中，我最大的体会是：AI 应用的难点不在模型，而在工程。模型能力再强，如果编排不灵活、扩展不方便、运行不稳定，也做不出好产品。

另一个体会是抽象要适度。抽象太少，代码重复；抽象太多，灵活性差。XXL-AI 的抽象层次是我改了好几版才找到的平衡点——编排层足够灵活，能力层足够复用，底座层足够稳定。

最后分享一个小技巧：做 AI 应用一定要做灰度。新模型、新提示词、新流程，先小流量试，确认效果再全量。我见过太多直接全量上线，结果效果崩了的案例。灰度不仅能降低风险，还能积累对比数据，帮你做决策。

这套平台后续我还会继续迭代，比如加入更多的编排节点类型、支持更多的供应商、优化 RAG 的检索效果。如果你也在做类似的事情，欢迎交流，踩过的坑可以一起填。