第一章 初识 Spring AI Alibaba 框架

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

"先跑起来, 再谈抽象" -- Hello World 的意义, 就是先把依赖、配置、调用链完整打通。

一、什么是 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 的阿里云实现版本，专门适配了阿里云的 DashScope（百炼）平台。

简单理解：

• Spring AI = Spring 的 AI 标准规范的接口
• Spring AI Alibaba = Spring AI 在阿里云平台的落地实现

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

• 通义千问（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 依赖 和 自动配置类 来实现这个接口：

工作原理：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

💡 这就是 Spring AI 的核心设计思想：面向接口编程 + 自动配置。Controller 的代码完全不用改，只切换依赖和配置，底层就从 DashScope 切到了 OpenAI。学完本课程后，换到其他 AI 提供商会非常容易。

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

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

“为什么 DashScope 要讲 DashScopeChatAutoConfiguration，而 OpenAI 好像不用 configuration 这一套？”

其实不是 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 与 自动配置的区别

比如你之前写过一个 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: https://xxx

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 是一样的，都是：

Starter + AutoConfiguration + Bean 注册 + Controller 注入

区别只在于：

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

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

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

也就是说：

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

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

2.1.6 总结

OpenAI 并不是不用 configuration，而是它使用的是 Starter 内置的自动配置类；你看不见它，不代表它不存在。

这也是为什么 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 可以实现上下文记忆功能

💡 初学者建议：ChatClient 是日常开发的首选，90% 的场景用它就够了。关于两者的详细对比，可以参考第三章的内容。

2.3 阿里云百炼平台科普

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

为什么要用阿里云？

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 依赖分析

<!-- pom.xml 中最核心的依赖 -->
<dependency>
    <!-- 阿里云的 AI Starter -->
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
    <version>1.1.2.0</version>
</dependency>

这里有个大坑提醒：

⚠️ 注意看依赖的 groupId：

• 阿里云starter是 com.alibaba.cloud.ai
• 而不是常见的 org.springframework.ai（那个是pring AI 官方 starter）

另外还需要配置 Maven 仓库（见 pom.xml 中的 repositories 部分），因为阿里云的 starter 放在特定的 Spring 仓库中。

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

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

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 每个配置项的含义

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只存储依赖的版本（\），并不会实际引入依赖。但是有些时候这些BOM可能会没有生效，所以还需要手动进行版本号的添加。

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.5</version>  <!-- 要手动写版本，容易出错 -->
</dependency>
<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
    <version>1.0.0.2</version>  <!-- 还要记住这个版本号 -->
</dependency>

用 BOM（自动获取版本）：

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

⚠️ 注意：dependencyManagement 只是声明依赖，并不实际引入依赖。真正的依赖引入是在子项目的 pom.xml 中完成的。

3.3.7 本教程中的三个 BOM

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

3.4 application.yml 配置

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

spring:
  application:
    name: SAA-01HelloWorld

  # 阿里云百炼 API 配置
  # 这是核心配置，你需要去阿里云免费申请 API Key
spring.ai.dashscope.api-key=${
   aliQwen-api}

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

关于 API Key 获取：

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

💡 小提示：首次使用建议申请免费的 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;

    /**
     * 普通调用方式：发送消息，获取完整回复
     * 
     * 接口地址：http://localhost:8001/hello/dochat?msg=你是谁
     * 
     * @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;
    }

    /**
     * 流式调用方式：类似打字效果，逐字返回
     * 
     * 接口地址：http://localhost:8001/hello/streamchat?msg=介绍下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边生成边返回给用户，体验就像"打字机"一样，会让用户感觉：

"哇，AI正在努力工作中！"

四、启动测试

4.1 运行项目

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

4.2 测试接口

# 测试普通对话
GET http://localhost:8001/hello/dochat?msg=用Java帮我写一个冒泡排序

# 测试流式对话
GET http://localhost:8001/hello/streamchat?msg=今天天气怎么样

五、本章小结

本章重点：

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

下章剧透（s02）：

下一章我们将学习如何使用 Ollama 本地部署的大模型，不需要联网也能玩 AI！

💡 TIP：Spring AI vs Spring AI Alibaba 区别

很多初学者会疑惑：既然有了 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 是"按规矩办事的具体人"（阿里云实现）。

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

📝 编辑者：Flittly
📅 更新时间：2026年3月
🔗 相关资源：阿里云百炼平台 | Spring AI 官方文档