【SpringAIAlibaba新手村系列】（1）初识 Spring AI Alibaba 框架

第一章 初识 Spring AI Alibaba 框架

[ s01 ] > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18

---

一、什么是 Spring AI Alibaba？

1.1 AI 与大语言模型（LLM）科普

在正式学习之前，我们需要先弄清楚几个核心概念：

大语言模型（LLM） 是一种经过海量文本训练的人工智能模型，它能够：

• 理解和生成自然语言
• 回答问题、写作文、编写代码
• 进行翻译、总结等任务

就像一个读遍了全世界图书馆的"超级学霸"，你问它什么问题，它都能给你相关的回答。

AI 模型 就是这个"超级学霸"，而 API 就像是让你能够联系到这个学霸的电话号码。

1.2 Spring AI 的诞生

Spring AI 是 Spring 官方在 2024 年推出的 AI 框架，它的核心思想就是：让 Java 开发者像使用 Spring Boot 一样方便地调用 AI 模型。

以前我们要调用某个 AI 模型，需要：

1. 学习该模型的专属 API
2. 处理各种特殊的请求格式
3. 处理不同的响应格式
4. 管理连接、超时等问题

Spring AI 就像是一个"万能转接头"，它把所有主流 AI 模型的 API 都统一了起来，你只需要学会一套接口，就能调用 OpenAI、阿里云、Meta、Ollama 等各种模型。

1.3 Spring AI Alibaba 的角色

Spring AI Alibaba 当然包含 Spring AI 在阿里云上的模型接入能力，但在 1.1.2.x 版本里，它已经不再只是“阿里云实现版”这么简单。

更准确的理解是：

• Spring AI：负责统一 AI 应用编程模型，比如 ChatModel、ChatClient、Prompt、Embedding、VectorStore、MCP 等基础抽象
• Spring AI Alibaba Extensions：负责 DashScope 等阿里云能力接入
• Spring AI Alibaba Agent Framework：负责 ReactAgent、多智能体编排、上下文工程、Human In The Loop 等 Agent 能力
• Spring AI Alibaba Graph：负责底层工作流编排、状态流转、并行执行、条件路由、中断与恢复
• Spring AI Alibaba Studio/Admin：负责可视化调试、观测、评估、MCP 管理和平台化集成

简单理解：

• Spring AI = Spring 的 AI 标准规范的接口
• Spring AI Alibaba = Spring AI 在阿里云与 Agent 工程方向上的完整落地实现

阿里云百炼平台提供了很多免费/付费的模型能力，比如：

• 通义千问（Qwen） ：中文能力很强的对话模型
• DeepSeek：开源的高性能模型
• 文本生成图像：可以用文字描述生成图片
• 文本合成语音：可以把文字变成声音

1.4 本章的学习目标

本章是我们学习 Spring AI Alibaba 的起点，主要目标是：

1. 理解 Spring AI 的基本架构
2. 掌握如何引入 Spring AI Alibaba 依赖
3. 学会配置 API Key
4. 完成第一个"Hello World"级别的基础调用

---

二、核心概念详解

2.1 ChatModel（对话模型）

在 Spring AI 中，ChatModel 是一个核心接口，它代表了与 AI 大模型的对话能力。

大白话解释：把 ChatModel 想象成一个"智能对话机器人"，你给它发消息，它回复你答案。

// ChatModel 就是我们调用 AI 的入口
@Resource
private ChatModel chatModel;

ChatModel 的主要方法：

• call(String message)：发送一条消息，获取完整回复
• stream(String message)：以流式方式获取回复（类似打字效果）

2.1.1 ChatModel 的自动配置机制（关键知识点）

ChatModel 是 Spring AI 定义的统一接口，不管底层用哪个厂商的模型服务，Controller 中注入的都是同一个类型：

@Resource
private ChatModel chatModel;

不同的 AI 厂商各自提供自己的 Starter 依赖 和 自动配置类 来实现这个接口：

Starter 依赖	自动配置类	所需配置项
spring-ai-alibaba-starter-dashscope	DashScopeChatAutoConfiguration	spring.ai.dashscope.api-key
spring-ai-starter-model-openai	OpenAiChatAutoConfiguration	spring.ai.openai.api-key

工作原理：Spring Boot 启动时，自动配置类会检查 classpath 上有没有对应的依赖，如果有，就自动创建一个 ChatModel 的实现类（Bean），注入到 IoC 容器中。Controller 通过 @Resource 注入时，拿到的就是这个 Bean。

实际应用——如何切换底层模型服务？

场景：你不想用阿里云百炼，想换成 OpenAI 兼容的代理服务，只需要两步：

1. 加依赖：在 pom.xml 中加入 spring-ai-starter-model-openai

2. 排除冲突：在启动类上排除 DashScope 自动配置，防止两个自动配置打架：

   @SpringBootApplication(exclude = {
       DashScopeChatAutoConfiguration.class
   })
   

3. 改配置：把 spring.ai.dashscope.api-key 改成 spring.ai.openai.api-key，并配置 base-url 和 model

2.1.2 为什么 OpenAI 看起来“不需要 Configuration”？

很多初学者在切换到 OpenAI 之后会产生一个错觉：

其实不是 OpenAI 不用，而是 OpenAI 也在用 configuration，只不过这个 configuration 不是你自己写的，而是 Starter 内置好的自动配置类。

换句话说，Spring 项目里 Bean 的来源通常有两种：

1. 手写配置类：开发者自己写 @Configuration + @Bean
2. 自动配置类：Starter 在 jar 包里提前写好，启动时由 Spring Boot 自动加载

例如，自己手写配置类时通常是这样：

@Configuration
public class MyConfig {

    @Bean
    public ChatModel chatModel() {
        return ...;
    }
}

而使用 OpenAI Starter 时，你虽然没有写上面的代码，但 Starter 内部其实已经帮你准备了类似的自动配置类，例如：

• OpenAiAutoConfiguration
• OpenAiChatAutoConfiguration

它们本质上也是 @Configuration 类，只是被打包在依赖 jar 中，由框架作者维护，而不是由你亲自编写。

因此，OpenAI 不是“不需要配置类”，而是“你不需要自己写配置类” 。

2.1.3 手写 Configuration 与 自动配置的区别

方式	谁来写	Bean 怎么来	适用场景
手写 @Configuration	开发者自己	自己通过 @Bean 创建	需要高度定制时
Starter 自动配置	框架/Starter 作者	启动时按条件自动创建	标准接入场景

比如你之前写过一个 SaaLLMConfig，那就是手写配置；而现在 OpenAI 能直接注入 ChatModel，走的就是 Starter 自动配置。

2.1.4 OpenAI 自动配置的实际启动过程

当你引入下面的依赖：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

并在 application.yml 中配置：

spring:
  ai:
    openai:
      api-key: your-key
      base-url: 

Spring Boot 启动时大致会经历这样的过程：

1. 发现 classpath 中存在 OpenAI Starter
2. 加载 Starter 中内置的自动配置类
3. 读取 spring.ai.openai.* 配置项
4. 创建 OpenAI 相关客户端对象
5. 创建 OpenAiChatModel
6. 将它注册到 Spring 容器中
7. 你的 Controller 中 @Resource private ChatModel chatModel; 注入成功

所以从底层原理上看，OpenAI 和 DashScope 是一样的，都是：

区别只在于：

• DashScope 对应的是 DashScopeChatAutoConfiguration
• OpenAI 对应的是 OpenAiChatAutoConfiguration

2.1.5 为什么之前的 SaaLLMConfig 后来可以删除？

因为在已经引入 OpenAI Starter 的前提下，ChatModel 所需的 Bean 已经由自动配置创建好了，项目并不需要你再手动写一个配置类去造 Bean。

也就是说：

• 没有 Starter 自动配置时：你需要自己写 @Configuration
• 有 Starter 自动配置且满足默认场景时：通常不需要自己再写

这正是 Spring Boot 提倡的理念：约定优于配置。

2.1.6 总结

这也是为什么 Spring AI 项目看起来“只加依赖、写配置、直接注入就能用”——真正复杂的 Bean 创建过程，已经被自动配置封装起来了。

2.2 ChatClient（对话客户端）

ChatClient 是构建在 ChatModel 之上的高级 API，它提供了更加便捷的链式调用写法。

大白话解释：如果说 ChatModel 是"功能手机"，那 ChatClient 就是"智能手机"——它不仅能打电话，还自带了通讯录、短信、应用商店等丰富功能。

// ChatClient 的典型用法：链式调用
@Resource
private ChatClient chatClient;

public String chat(String msg)
{
    // 链式调用，一气呵成
    String result = chatClient.prompt()
        .system("你是一个专业的Java助手")   // 设置系统提示词
        .user(msg)                          // 设置用户消息
        .call()                             // 调用 AI
        .content();                         // 获取回复内容
    return result;
}

ChatClient 的主要特点：

• 链式调用：通过 .prompt().system().user().call().content() 这样的方式，语义清晰
• 内置模板支持：可以使用占位符，如 .system("你是一个%s工程师", "Java")
• 结构化输出：通过 .entity(MyClass.class) 直接映射 AI 返回为 Java 对象
• 对话记忆：通过 Advisor 可以实现上下文记忆功能

2.3 阿里云百炼平台科普

阿里云百炼平台是阿里云提供的一站式大模型服务平台，你可以把它理解为"AI 应用商店"，里面有很多现成的 AI 能力：

模型类型	模型名称	主要用途
对话模型	qwen-plus, qwen-turbo	日常问答、写作
对话模型	deepseek-v3	开源高性能模型
文本转图像	wanx2.1-t2i-turbo	文字生成图片
文本转语音	cosyvoice-v2	文字生成语音
向量嵌入	text-embedding-v3	文本向量化

为什么要用阿里云？

1. 中文能力很强（适合国内开发者）
2. 有免费额度可以白嫖
3. 国内访问速度快
4. 和 Spring AI 集成得很好

---

三、HelloWorld 项目详解

3.1 项目结构

SAA-01HelloWorld/
├── pom.xml                    # Maven 配置文件
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/atguigu/study/
│   │   │       ├── Saa01HelloWorldApplication.java   # 启动类
│   │   │       ├── config/
│   │   │       │   └── SaaLLMConfig.java             # LLM 配置类
│   │   │       └── controller/
│   │   │           └── ChatHelloController.java      # 控制器
│   │   └── resources/
│   │       └── application.yml                      # 配置文件
│   └── test/
│       └── java/.../Saa01HelloWorldApplicationTests.java

3.2 pom.xml 依赖分析

<properties>
    <java.version>17</java.version>
    <spring-ai.version>1.1.2</spring-ai.version>
    <spring-ai-alibaba.version>1.1.2.2</spring-ai-alibaba.version>
    <spring-ai-alibaba-extensions.version>1.1.2.2</spring-ai-alibaba-extensions.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>${spring-ai.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>com.alibaba.cloud.ai</groupId>
            <artifactId>spring-ai-alibaba-bom</artifactId>
            <version>${spring-ai-alibaba.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>com.alibaba.cloud.ai</groupId>
            <artifactId>spring-ai-alibaba-extensions-bom</artifactId>
            <version>${spring-ai-alibaba-extensions.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
    </dependency>
</dependencies>

这里有个大坑提醒：

在 1.1.2.x 里，更推荐直接用 BOM 统一管理版本，而不是给每个 starter 单独写版本号。

3.3 父工程 pom.xml 中的 BOM 依赖管理详解

本项目SAA-01HelloWorld只是父工程下面的一个子工程，在父工程的 pom.xml 中有一个重要的配置：dependencyManagement。这里我们重点讲解什么是 BOM 以及它在 Spring AI Alibaba 项目中的作用。
Pasted image 20260326161132.png

3.3.1 什么是 BOM？

BOM（Bill of Materials，物料清单） 是 Maven 中用于统一管理依赖版本的机制。你可以把它理解成"一份购物清单"——

• 没有 BOM 时：你买一台电脑，显示器、键盘、鼠标、主机都要自己分别挑选型号，还要担心它们之间是否兼容
• 有 BOM 时：就像直接买"整机配置单"，清单里已经帮你配好了所有部件的兼容版本，你只需要勾选要哪些部件即可

3.3.2 父工程中的 BOM 配置

<!-- 父工程 pom.xml 中的 dependencyManagement 配置 -->
<dependencyManagement>
    <dependencies>
        <!-- Spring Boot BOM -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>${spring-boot.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        
        <!-- Spring AI BOM -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>${spring-ai.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        
        <!-- Spring AI Alibaba BOM -->
        <dependency>
            <groupId>com.alibaba.cloud.ai</groupId>
            <artifactId>spring-ai-alibaba-bom</artifactId>
            <version>${SpringAIAlibaba.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

3.3.3 每个配置项的含义

配置项	说明
groupId	组织的标识，类似 Java 包名
artifactId	库的唯一标识，类似类名
version	版本号，这里使用变量占位
type=pom	表示引入的是一个 POM 类型的依赖（即 BOM 本身）
scope=import	表示这是"导入"类型的依赖，会将 BOM 中的依赖"合并"进来

3.3.4 BOM 如何工作？

当你在一个子项目（比如 SAA-01HelloWorld）的 pom.xml 中写下这样的依赖时：

<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
</dependency>

Maven 会自动在 BOM 中查找这个 artifactId 对应的版本，然后使用 BOM 中定义的版本。BOM 只负责统一版本，不负责真正把依赖放进项目；真正引入依赖，仍然要写在 <dependencies> 中。

3.3.5 为什么要使用 BOM？

1. 版本统一：一个项目可能有几十个依赖，如果没有 BOM，每个依赖都要手动指定版本，很容易出现版本冲突
2. 简化子项目：子项目只需要写 groupId 和 artifactId，不需要写 version
3. 降低维护成本：升级版本只需要改父工程的一处地方，所有子项目自动生效
4. 兼容性保证：BOM 中的依赖版本都是经过测试的兼容组合

3.3.6 实际例子

不用 BOM（自己指定版本） ：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.5.7</version>
</dependency>
<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
    <version>1.1.2.2</version>
</dependency>

用 BOM（自动获取版本） ：

<!-- 子项目中只需要这样写 -->
<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
</dependency>
<!-- 版本号自动从父工程的 BOM 中获取 -->

3.3.7 本教程中的三个 BOM

BOM	作用
spring-boot-dependencies	管理 Spring Boot 全家桶依赖
spring-ai-bom	管理 Spring AI 核心依赖
spring-ai-alibaba-bom	管理阿里云 AI 实现依赖

这就是为什么我们的项目可以稳定运行的原因——三个 BOM 各司其职，确保了所有依赖版本的兼容性。

---

3.4 application.yml 配置

server:
  port: 8001                  # 服务器端口，我们改成了8001避免冲突

spring:
  application:
    name: SAA-01HelloWorld

  ai:
    dashscope:
      api-key: ${AI_DASHSCOPE_API_KEY:}

# `AI_DASHSCOPE_API_KEY` 是环境变量，我们可以在 IDEA 里配置
# 配置方式：Run/Debug Configurations -> Environment Variables
# 添加: AI_DASHSCOPE_API_KEY=你的阿里云APIKey

关于 API Key 获取：

1. 访问 dashscope.console.aliyun.com/
2. 注册/登录阿里云账号
3. 在"百炼平台"中找到"API-KEY 管理"
4. 创建并复制你的 API Key

3.5 控制层代码详解

这才是我们的重头戏！

package com.atguigu.study.controller;

import jakarta.annotation.Resource;
import org.springframework.ai.chat.model.ChatModel;   // 对话模型接口
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * 这是一个 REST 风格的控制器
 * 类似于 Spring MVC 的 @Controller 但自动返回 JSON
 */
@RestController
public class ChatHelloController
{
    // @Resource 是 JDK 自带的依赖注入注解
    // 相当于 Spring 的 @Autowired
    // 这里注入的是阿里云百炼平台的对话模型实现
    
    @Resource
    private ChatModel chatModel;

    /**
     * 普通调用方式：发送消息，获取完整回复
     * 
     * 接口地址：你是谁
     * 
     * @param msg 用户发送的消息
     * @return AI 的回复
     */
    @GetMapping(value = "/hello/dochat")
    public String doChat(@RequestParam(name = "msg", defaultValue = "你是谁") String msg)
    {
        // 调用大模型的 call 方法
        // 参数：用户的消息
        // 返回：AI 的完整回复（字符串形式）
        String result = chatModel.call(msg);
        return result;
    }

    /**
     * 流式调用方式：类似打字效果，逐字返回
     * 
     * 接口地址：介绍下Java
     * 
     * @param msg 用户发送的消息
     * @return Flux<String> 流式返回的字符串
     */
    @GetMapping(value = "/hello/streamchat")
    public Flux<String> stream(@RequestParam(name = "msg", defaultValue = "你是谁") String msg)
    {
        // stream 方法返回一个 Flux（响应式流）
        // 类似于 RxJava 或 Java Stream
        // 它会一个字一个字地把答案返回给你
        // 实际使用中，通常配合 SSE（Server-Sent Events）实现实时显示
        return chatModel.stream(msg);
    }
}

3.6 Flux 和流式输出

什么是 Flux？

Flux 来自 Project Reactor（Spring WebFlux 也在用），是一种响应式编程的体现。

大白话解释：

• 普通方法：return "你好" → 一次性返回完整内容
• Flux 方法：return fluxXxx() → 像玩水管游戏，水流一点一点流出

为什么需要流式输出？

因为 AI 生成内容需要时间，如果等它全部生成完再返回，用户要等待很久。

流式输出可以让AI边生成边返回给用户，体验就像"打字机"一样，会让用户感觉：

---

四、启动测试

4.1 运行项目

1. 在 IDEA 中运行 Saa01HelloWorldApplication
2. 看到 Started Saa01HelloWorldApplication in x.xxx seconds 表示启动成功
3. 打开浏览器或 Postman 测试

4.2 测试接口

# 测试普通对话
GET 用Java帮我写一个冒泡排序

# 测试流式对话
GET 今天天气怎么样

---

五、本章小结

概念	说明
Spring AI	Spring 官方 AI 框架，统一各厂商 AI 调用
Spring AI Alibaba	阿里云百炼平台的 Spring AI 实现
ChatModel	AI 对话模型的核心接口
DashScope	模型服务灵积（现在已经变成阿里云百炼平台）
API Key	调用百炼服务的凭证
Flux	响应式流，用于流式输出

本章重点：

1. 了解 Spring AI Alibaba 在生态系统中的位置
2. 掌握如何配置阿里云 API Key
3. 理解 ChatModel 的两种调用方式（call vs stream）

下章剧透（s02）：

---

很多初学者会疑惑：既然有了 Spring AI，为什么还需要 Spring AI Alibaba？

Spring AI 是 Spring 官方提供的 AI 框架，它定义了一套标准的接口和规范，让开发者可以用统一的方式调用不同的 AI _provider（如 OpenAI、Azure OpenAI、HuggingFace 等）。但它本身并不直接提供 AI _provider 的连接实现。

Spring AI Alibaba 则是 Alibaba 团队基于 Spring AI 的接口规范，针对阿里云百炼平台做的具体实现。它提供了：

特性	Spring AI	Spring AI Alibaba
定位	AI 框架规范 + 通用实现	阿里云特化实现
支持模型	OpenAI、HuggingFace等	通义千问、百炼平台服务
能力扩展	基础 AI 能力	RAG、Agent、MCP等企业级能力
开发团队	Spring 官方	Alibaba 团队
维护更新	通用迭代	与阿里云服务同步

简单理解：Spring AI 是"规矩"（接口规范），Spring AI Alibaba 是"按规矩办事的具体人"（阿里云实现） 。

不过好消息是，Spring AI Alibaba 完全兼容 Spring AI 的接口！你学习完本课程后，会发现换到其他 AI _provider 非常容易。

---