企业官网建设流程全解析

1. 从 Spring AI 到 Spring AI Alibaba：一个 Java 开发者的真实困惑

Spring AI 刚出来那阵子，我身边不少做 Java 后端的兄弟都在群里讨论，说终于不用在 Python 和 Java 之间来回切了，直接在 Spring Boot 项目里就能调大模型。结果没过多久，Spring AI Alibaba 又冒出来了。当时我第一反应是：这玩意儿是不是就是把 Spring AI 换了个皮，加几个阿里云的 SDK 调用？后来真正花时间把源码拉下来翻了一遍，才发现事情没那么简单。

Spring AI Alibaba 本质上是一个构建在 Spring AI 基础之上的上层框架，它做的事情不是重复造轮子，而是把 Java 生态里做 AI 应用时最缺的那几块拼图给补上了。Spring AI 解决的是“怎么用统一接口调不同厂商的大模型”这个问题，而 Spring AI Alibaba 解决的是“怎么用这套接口真正搭出一个能上线的 AI 应用”这个问题。这两者的关系，有点像 JDBC 和 MyBatis——JDBC 给了你标准接口，但真写业务的时候，你还是需要一个更趁手的上层封装。

这篇文章适合谁看？如果你是一个 Java 开发者，已经大概知道 Spring AI 是什么，但还没搞清楚 Spring AI Alibaba 到底在它上面加了什么、值不值得引入、引入之后项目结构会变成什么样，那这篇内容就是写给你的。我会从整体架构入手，把它的分层逻辑拆开，再结合我实际搭 Demo 的经验，把每一层的关键细节和踩过的坑都讲清楚。

2. 整体架构拆解：它到底在 Spring AI 上面叠了几层

2.1 先搞清楚 Spring AI 自己做了什么

要理解 Spring AI Alibaba 加了什么，得先知道 Spring AI 原本的边界在哪里。Spring AI 的核心抽象其实就几个东西：ChatClient、ChatModel、EmbeddingModel、VectorStore、Advisor。它定义了一套统一的 API，让你可以用类似chatClient.prompt().user("你好").call().content()这样的链式调用来跟大模型交互，底层具体是 OpenAI 还是别的厂商，通过ChatModel的实现来切换。

这个设计思路很 Spring，跟当年 Spring 对 JDBC 的抽象是一个路子。但问题在于，Spring AI 只给了你“调模型”的能力，它没有告诉你“怎么把多个模型串起来完成一个复杂任务”，也没有给你“对话记忆怎么持久化”“工具调用怎么编排”“流程怎么可视化”这些偏应用层的东西。你当然可以自己写，但每个项目都重复写一遍，那就没意思了。

2.2 Spring AI Alibaba 的分层逻辑

Spring AI Alibaba 的架构，我把它理解为三层叠加：

第一层是模型接入层。这一层它做了两件事：一是接入了阿里系自己的模型服务，比如通义千问系列，让你在 Spring AI 的ChatModel接口下多了一个可选实现；二是对 Spring AI 原有的模型接入做了增强，比如在参数配置、流式响应处理上做了一些适配。这一层是最“薄”的，基本上就是适配器模式。

第二层是应用编排层。这是 Spring AI Alibaba 真正花力气的地方。它引入了一个叫 Graph 的概念，你可以把它理解成一张有向图，每个节点是一个执行单元（比如调一次模型、执行一次工具、做一次条件判断），边定义了节点之间的流转关系。这个设计跟 LangChain 里的 Chain 和 LangGraph 的思路很像，但它是用 Java 写的，而且跟 Spring 的依赖注入体系融合得很好。有了这一层，你就能把“先让模型理解用户意图，再根据意图决定调哪个工具，最后把工具结果交给模型生成回复”这种多步骤流程，用声明式的方式描述出来。

第三层是工程化支撑层。这一层包括可观测性、配置管理、与 Spring Boot 自动装配的集成等等。比如它提供了对模型调用链路的追踪能力，你可以看到一次请求经过了哪些节点、每个节点耗时多少、输入输出是什么。这一层的东西看起来不起眼，但真到了线上排查问题的时候，没有它你会非常痛苦。

2.3 为什么要这么分层

这个分层逻辑背后的考量，我觉得核心就一个词：关注点分离。模型接入层的变化频率是最低的，因为模型厂商的 API 一旦定下来，不会天天改；应用编排层的变化频率最高，因为业务逻辑一直在变；工程化支撑层则相对稳定，但需要跟 Spring 生态保持同步。

把这三层分开之后，每一层的演进节奏可以不一样。比如阿里出了新模型，只需要在模型接入层加一个适配器；业务方想改流程，只需要在编排层调整 Graph 的结构；Spring Boot 升级了，工程化支撑层跟着适配就行。这种分层方式，跟我们在做微服务架构时把网关层、业务层、基础设施层分开是一个道理。

注意：分层清晰带来的一个副作用是，新手容易在层与层之间迷失。我刚开始看的时候，经常搞不清楚某个类到底属于哪一层，后来我的办法是看包名，com.alibaba.cloud.ai下面按功能模块分得很清楚，花十分钟把包结构过一遍，比看文档还管用。

3. 核心模块深度解析：每一层里到底有什么

3.1 模型接入层的适配细节

模型接入层最核心的类是DashScopeChatModel，它实现了 Spring AI 的ChatModel接口。你只需要在配置文件里写上 API Key 和模型名称，Spring Boot 的自动装配就会帮你把这个 Bean 注册好。但这里有几个细节值得注意。

第一个细节是流式响应的处理。Spring AI 的ChatModel接口定义了stream方法，返回一个Flux<ChatResponse>。DashScope 的流式接口返回的是 SSE 格式的数据，Spring AI Alibaba 在中间做了一层转换，把 SSE 的每个事件解析成ChatResponse。这个转换过程里有个坑：如果模型返回的内容里包含特殊字符，解析的时候可能会出问题。我实测下来，大部分情况没问题，但如果你的 prompt 里让模型输出 JSON，偶尔会遇到流式解析中断的情况。解决办法是在配置里把流式模式关掉，或者用非流式的call方法。

第二个细节是参数映射。Spring AI 定义了一套通用的ChatOptions，比如temperature、topP、maxTokens这些。但 DashScope 的 API 参数名跟这套通用定义不完全一样，Spring AI Alibaba 在中间做了一层映射。大部分参数是直接对应的，但有些 DashScope 特有的参数，比如seed、enableSearch，就需要通过扩展的 Options 类来设置。这个设计是合理的，因为不同厂商的模型确实有自己特有的参数，强行统一反而会丢失能力。

3.2 应用编排层的 Graph 设计

Graph 是 Spring AI Alibaba 里最值得花时间理解的部分。它的核心概念有这么几个：

• Node：一个执行单元，可以是调用模型、执行工具、做条件判断、甚至是一段自定义的 Java 代码。
• Edge：定义节点之间的流转关系，可以是固定的（A 执行完一定到 B），也可以是条件的（根据 A 的输出决定去 B 还是 C）。
• State：在整个 Graph 执行过程中传递的状态对象，每个节点都可以读取和修改它。

这个设计跟状态机很像，但比状态机灵活，因为节点之间的流转可以是动态的。我举个例子来说明它的价值。假设你要做一个客服机器人，流程是这样的：先判断用户的问题类型，如果是查订单，就调订单查询工具；如果是退换货，就调退换货工具；如果都不是，就直接让模型回答。用传统的写法，你需要在代码里写一堆 if-else，而且这些 if-else 会随着业务复杂度的增加变得越来越难维护。用 Graph 来写，你只需要定义三个节点（意图识别、订单查询、退换货处理）和相应的边，整个流程就是声明式的，改起来也方便。

实操心得：定义 Graph 的时候，State 的设计很关键。我一开始把 State 设计得太复杂，什么信息都往里塞，结果每个节点都要处理一大堆不相关的字段。后来我改成按需设计，每个 Graph 只维护自己需要的状态，节点之间的耦合度一下子就降下来了。

3.3 工程化支撑层的可观测性

可观测性这块，Spring AI Alibaba 提供了对 Micrometer 和 OpenTelemetry 的集成。你可以在配置文件里开启追踪，然后就能在控制台或者你用的 APM 系统里看到每次模型调用的详细信息。

这个功能看起来简单，但实际用起来非常有用。我印象很深的一次，线上有个接口响应特别慢，查了半天以为是数据库问题，后来打开模型调用的追踪一看，发现是某次模型调用因为 prompt 太长，触发了模型的限流，重试了好几次才成功。如果没有这个追踪能力，我可能还在数据库那边瞎找。

追踪信息里比较有用的几个字段：model（用的哪个模型）、promptTokens（输入 token 数）、completionTokens（输出 token 数）、latency（耗时）。这几个字段结合起来看，能帮你快速定位是模型本身慢，还是你的 prompt 写得太长导致 token 数过多。

4. 实操过程：从零搭一个带 Graph 编排的 Demo

4.1 环境准备与依赖引入

先说一下我的环境：JDK 17，Spring Boot 3.2.x，Maven 3.9。Spring AI Alibaba 对 JDK 版本有要求，最低是 17，这个要注意，JDK 8 和 11 都不行。

依赖引入这块，核心就两个：

<dependency> <groupId>com.alibaba.cloud.ai</groupId> <artifactId>spring-ai-alibaba-starter</artifactId> <version>1.0.0-M2</version> </dependency> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-core</artifactId> <version>1.0.0-M2</version> </dependency>

版本号这块要注意，Spring AI 和 Spring AI Alibaba 的版本需要对应，不能随便混搭。我一开始用了 Spring AI 的 1.0.0-M1 配 Spring AI Alibaba 的 1.0.0-M2，结果启动的时候报了一堆类找不到的错误。后来把两个版本对齐到 M2 就好了。

配置文件里需要填 API Key：

spring: ai: dashscope: api-key: ${DASHSCOPE_API_KEY} chat: options: model: qwen-plus temperature: 0.7

这里有个小技巧：API Key 不要直接写在配置文件里，用环境变量的方式注入。我见过有同学直接把 Key 提交到代码仓库，结果被扫出来盗用，损失不小。

4.2 定义第一个 Graph

假设我们要做一个简单的问答流程：用户提问 -> 模型判断是否需要查天气 -> 如果需要就调天气工具 -> 把工具结果交给模型生成最终回复。

先定义 State：

public class WeatherState { private String userQuestion; private boolean needWeather; private String weatherInfo; private String finalAnswer; // getter/setter 省略 }

然后定义节点。第一个节点是意图识别：

Node intentNode = Node.builder() .id("intent") .action(state -> { String question = state.getUserQuestion(); // 这里简化处理，实际可以用模型来判断 boolean needWeather = question.contains("天气"); state.setNeedWeather(needWeather); return state; }) .build();

第二个节点是天气查询工具：

Node weatherNode = Node.builder() .id("weather") .action(state -> { // 调用天气 API，这里用模拟数据 state.setWeatherInfo("晴，25度"); return state; }) .build();

第三个节点是生成最终回复：

Node answerNode = Node.builder() .id("answer") .action(state -> { String prompt = state.getNeedWeather() ? "天气信息：" + state.getWeatherInfo() + "，请回答用户问题：" + state.getUserQuestion() : state.getUserQuestion(); // 调用模型生成回复 String answer = chatClient.prompt().user(prompt).call().content(); state.setFinalAnswer(answer); return state; }) .build();

最后把这些节点和边组装成 Graph：

Graph graph = Graph.builder() .addNode(intentNode) .addNode(weatherNode) .addNode(answerNode) .addEdge("intent", "weather", state -> state.isNeedWeather()) .addEdge("intent", "answer", state -> !state.isNeedWeather()) .addEdge("weather", "answer") .build();

这个 Graph 的执行逻辑是：先走 intent 节点，如果 needWeather 为 true，就去 weather 节点，然后到 answer 节点；如果为 false，直接到 answer 节点。

4.3 执行 Graph 并观察结果

执行的时候，你需要一个GraphExecutor：

GraphExecutor executor = new GraphExecutor(graph); WeatherState initialState = new WeatherState(); initialState.setUserQuestion("今天天气怎么样"); WeatherState result = executor.execute(initialState); System.out.println(result.getFinalAnswer());

跑起来之后，你能看到整个流程按照预期的路径执行。如果开了追踪，还能在日志里看到每个节点的耗时。

注意事项：Graph 的执行默认是同步的，如果你的节点里有耗时的操作（比如调外部 API），整个流程会被阻塞。Spring AI Alibaba 也支持异步执行，但需要你把节点的 action 改成返回CompletableFuture。我建议在节点数量多、或者有耗时操作的时候，优先考虑异步模式。

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

5.1 启动时报 Bean 冲突

这个问题我遇到过一次，报错信息大概是“expected single matching bean but found 2”。原因是我的项目里同时引入了 Spring AI 的 OpenAI starter 和 Spring AI Alibaba 的 starter，两个 starter 都试图注册ChatModel类型的 Bean，Spring 不知道该用哪个。

解决办法有两种：一是用@Primary注解指定一个为主 Bean；二是在配置文件里排除掉不需要的那个 starter 的自动装配。我一般用第二种，因为更干净。

5.2 流式响应中断

前面提到过，流式响应在解析特殊字符时可能会中断。除了关掉流式模式，还有一个办法是自定义一个ResponseErrorHandler，在解析出错的时候做降级处理，比如把已经收到的内容返回，而不是直接抛异常。

5.3 Graph 执行卡死

Graph 执行卡死最常见的原因是边定义错了，导致流程进入死循环。比如 A 到 B 的条件永远为 true，B 又回到 A，那就永远出不来了。排查的办法是在每个节点的 action 里打日志，看看流程到底走到哪一步卡住了。另外，Spring AI Alibaba 的 Graph 支持设置最大执行步数，可以在构建 Graph 的时候加上.maxSteps(50)之类的限制，防止死循环。

5.4 模型返回内容为空

这个问题比较隐蔽，有时候模型明明返回了内容，但content()方法拿到的却是空字符串。我排查下来发现，原因是模型返回的内容里包含了不可见的控制字符，Spring AI 在解析的时候把这些字符过滤掉了，结果就变成了空。解决办法是在 prompt 里明确要求模型不要输出特殊字符，或者在拿到结果后做一次清洗。

6. 我对这套架构的真实看法

用了一段时间之后，我的感受是：Spring AI Alibaba 的价值不在于它接入了多少模型，而在于它把 Java 生态里做 AI 应用的那套工程化思路给补齐了。Spring AI 给了你一把锤子，Spring AI Alibaba 给了你一个工具箱，里面除了锤子还有螺丝刀、扳手和卷尺。

当然它也不是没有缺点。Graph 的概念对新手来说有一定学习成本，而且它的文档目前还不够完善，很多细节需要自己翻源码。另外，它的版本迭代比较快，API 偶尔会有 breaking change，升级的时候需要留个心眼。

但如果你是一个 Java 团队，正在考虑把 AI 能力集成到现有系统里，我觉得 Spring AI Alibaba 是值得花时间研究的。它至少让你不用在 Java 和 Python 之间来回切，也不用自己从零造一套编排引擎。这个方向，我觉得是对的。