【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

"先跑起来, 再谈抽象" -- 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 模型，需要：

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

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 的起点，主要目标是：

理解 Spring AI 的基本架构
掌握如何引入 Spring AI Alibaba 依赖
学会配置 API Key
完成第一个"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 兼容的代理服务，只需要两步：

加依赖 ：在 pom.xml 中加入 spring-ai-starter-model-openai
排除冲突 ：在启动类上排除 DashScope 自动配置，防止两个自动配置打架：
复制代码
```
@SpringBootApplication(exclude = {
    DashScopeChatAutoConfiguration.class
})
```
改配置 ：把 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 的来源通常有两种：

手写配置类 ：开发者自己写 @Configuration + @Bean
自动配置类：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: https://xxx

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

发现 classpath 中存在 OpenAI Starter
加载 Starter 中内置的自动配置类
读取 spring.ai.openai.* 配置项
创建 OpenAI 相关客户端对象
创建 OpenAiChatModel
将它注册到 Spring 容器中
你的 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 能力：

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

为什么要用阿里云？

中文能力很强（适合国内开发者）
有免费额度可以白嫖
国内访问速度快
和 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 每个配置项的含义

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

3.3.5 为什么要使用 BOM？

版本统一：一个项目可能有几十个依赖，如果没有 BOM，每个依赖都要手动指定版本，很容易出现版本冲突
简化子项目 ：子项目只需要写 groupId 和 artifactId，不需要写 version
降低维护成本：升级版本只需要改父工程的一处地方，所有子项目自动生效
兼容性保证：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	作用
`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

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

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

关于 API Key 获取：

访问 https://dashscope.console.aliyun.com/
注册/登录阿里云账号
在"百炼平台"中找到"API-KEY 管理"
创建并复制你的 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 运行项目

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

4.2 测试接口

复制代码

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

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

五、本章小结

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

本章重点：

了解 Spring AI Alibaba 在生态系统中的位置
掌握如何配置阿里云 API Key
理解 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
定位	AI 框架规范 + 通用实现	阿里云特化实现
支持模型	OpenAI、HuggingFace等	通义千问、百炼平台服务
能力扩展	基础 AI 能力	RAG、Agent、MCP等企业级能力
开发团队	Spring 官方	Alibaba 团队
维护更新	通用迭代	与阿里云服务同步

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

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

📝 编辑者 ：Flittly

📅 更新时间 ：2026年3月

🔗 相关资源 ：阿里云百炼平台 | Spring AI 官方文档

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

第一章 初识 Spring AI Alibaba 框架

一、什么是 Spring AI Alibaba？

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

1.2 Spring AI 的诞生

1.3 Spring AI Alibaba 的角色

1.4 本章的学习目标

二、核心概念详解

2.1 ChatModel（对话模型）

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

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

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

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

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

2.1.6 总结

2.2 ChatClient（对话客户端）

2.3 阿里云百炼平台科普

三、HelloWorld 项目详解

3.1 项目结构

3.2 pom.xml 依赖分析

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

3.3.1 什么是 BOM？

3.3.2 父工程中的 BOM 配置

3.3.3 每个配置项的含义

3.3.4 BOM 如何工作？

3.3.5 为什么要使用 BOM？

3.3.6 实际例子

3.3.7 本教程中的三个 BOM

3.4 application.yml 配置

3.5 控制层代码详解

3.6 Flux 和流式输出

四、启动测试

4.1 运行项目

4.2 测试接口

五、本章小结

第一章初识 Spring AI Alibaba 框架

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

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