从零认识 Spring AI：Java 开发者的 AI 第一课

"我是一个 Java 开发者，能搞 AI 吗？"

"当然能。而且你不需要先学 Python。"

欢迎来到《Spring AI 从入门到实战》专栏的第一篇。

作为 Java 程序员，你是不是经常遇到这样的场景：公司要上线一个"AI 问答"功能，同事都在讨论大模型、Prompt、Token......你打开 CSDN 一搜，满屏都是 Python 的 LangChain、LlamaIndex。那一刻你可能在想："是不是得先把 Python 学了才能干 AI？"

答案是：完全不用。 Spring 官方已经把 AI 这块硬骨头啃下来了------它叫 Spring AI。Spring AI 是一个为开发 AI 应用程序提供 Spring 友好 API 和抽象层的项目，它将 Spring 生态系统的设计原则（如可移植性和模块化设计）应用到 AI 领域，促进使用 POJO 作为 AI 应用程序的构建块。

今天这一篇，我们先不写复杂代码。咱们先把"Spring AI 到底是什么、它有什么用、怎么搭一个空项目"彻底弄明白。跑通第一个 Hello World，你就迈过了 AI 开发的第一道门槛。

一、痛点场景：你的犹豫我懂

我们先还原几个场景，看看有没有戳中你：

场景一：技术选型纠结

老板说："小王啊，咱们后台是 Spring Boot，能不能接个 AI 做智能客服？"你心想：Spring Boot 我会，但 AI 怎么接？去 GitHub 找开源项目，发现好一点的 AI 框架全是 Python 的。好不容易找到一个 Java 的，文档是英文，版本号还是 0.8.0，跑都跑不起来。

场景二：概念爆炸

你下定决心学 AI，打开一篇教程，第一段就出现了：LLM、Embedding、RAG、Token、Temperature......这些词你都没听说过。你试着去搜，结果发现每篇博客都在用更看不懂的词解释另一个词，像掉进了一个术语怪圈。

场景三：模型选择焦虑

"用 OpenAI 还是 DeepSeek？API Key 怎么搞？本地能跑吗？"光是选模型就耗费了一个下午。教程里有的接入 OpenAI，有的接入国产大模型，各自逻辑还不一样，你不知道哪个适合你。

如果上面任何一个场景让你产生了共鸣，那这篇文章就是为你写的。Spring AI 要解决的，恰恰就是"让 Java 开发者用最熟悉的方式，最简单地接入 AI 能力"。

二、核心概念快览：4 个术语，一次搞懂

在正式写代码之前，我们先花 3 分钟把几个高频术语理清楚。别担心，我会用大白话解释。

2.1 大语言模型（LLM）

大语言模型（Large Language Model，LLM） 就是一种经过海量文本训练的人工智能模型。你可以把它想象成一个"读过全世界所有书、看过所有文章"的超级学霸。你问它问题，它能给你回答；你给它一段代码，它能帮你改 bug。

有意思的是，LLM 的"知道"是静态的------它只知道训练截止日期之前的信息。比如 DeepSeek-V3 的知识截止到 2024 年，你问它 2026 年的事情，它可能说不上来（后面我们会学到 RAG，来解决这个问题）。

2.2 API Key

API Key 就是一把"钥匙"，让你能合法地调用远端的 AI 模型。就像你办了一张健身会员卡，有了卡才能进健身房使用器械，有了 API Key 才能通过互联网调用大模型。各家模型提供商会按照你调用的 Token 数量（你可以理解为"用量"）收费，但学习阶段通常有免费额度。

2.3 ChatClient

ChatClient 是 Spring AI 中最核心的工具。它是给你的应用程序与 AI 模型之间架起的一座"桥梁"------你只需要把问题交给 ChatClient，ChatClient 会帮你封装好请求、发给 AI 模型、再把结果拿回来。

ChatClient 不再是早期版本的单一 AiClient，而是职责更清晰的对话工具，提供流式（Fluent）API，风格类似于 Spring 的 WebClient 或 RestClient。

2.4 Spring AI Alibaba

Spring AI Alibaba 是 Spring AI 在阿里云与 Agent 工程方向上的完整落地实现。它不仅能帮你接入阿里云百炼平台的通义千问等模型，还提供了 Agent 框架、工作流编排、可视化调试等高级能力。我们可以简单理解为：

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

前期我们先用 Spring AI 核心框架接入一个模型把项目跑起来，后面再逐步深入。

三、环境准备：搭一个空项目

3.1 开发环境

正式开始前，请确认以下软件已安装：

工具	最低版本	推荐版本
JDK	17+	21
Maven	3.8+	3.9.x
Spring Boot	3.5.x	3.5.14
IDE	任意	IntelliJ IDEA 2024+

如果你 JDK 还是 8 或 11，请务必升级到 17 以上。Spring AI 1.x 基于 Spring Boot 3.5，要求 JDK 17 起步，这一点卡住了很多新手，一定要注意。

3.2 创建 Spring Boot 项目

我们用 Spring Initializr 创建一个空项目（如果你用 IDEA，可以直接新建 Spring Boot 项目）。访问 start.spring.io，选择以下配置：

• Project：Maven
• Language：Java
• Spring Boot：3.5.14（当前最新稳定版）
• Java：17 或 21

注意 ：Spring AI 目前不在 Spring Initializr 的默认依赖中，所以先勾选 Spring Web 依赖即可（我们需要它提供 REST 接口），AI 相关的依赖后面手动添加。

点击 Generate 下载项目压缩包，解压后用 IDEA 打开。

3.3 手动添加 Spring AI 依赖

打开 pom.xml，我们需要做两件事：引入 Spring AI BOM 来统一管理版本 ，以及引入一个具体的模型依赖。

⚠️ 重要版本说明（写于 2026 年 5 月）：当前 Spring AI 有三个活跃版本线------

• 1.0.7：长期维护版，基于 Spring Boot 3.5.14，适合生产环境
• 1.1.6：功能增强版，修复了大量 bug，同样基于 Spring Boot 3.5.14
• 2.0.0-M6：里程碑预览版，基于 Spring Boot 4.0，引入了大量新特性，预计 2026 年中 GA

作为入门教程，我们选择 1.1.6 版本------它比 1.0 多了很多增强能力，同时又不像 2.0 那样还处于里程碑阶段。你也可以根据自己情况换成 1.0.7 或 2.0.0-M6，核心用法基本兼容。

下面是完整的 pom.xml 关键部分：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.5.14</version>
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>spring-ai-hello-world</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>spring-ai-hello-world</name>
    <description>Spring AI 第一个空项目</description>

    <properties>
        <java.version>17</java.version>
        <!-- Spring AI 版本，请关注官网获取最新版本 -->
        <spring-ai.version>1.1.6</spring-ai.version>
    </properties>

    <dependencies>
        <!-- Spring Web：提供 REST 接口 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- Spring AI 核心依赖 -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-openai</artifactId>
        </dependency>

        <!-- Spring Boot 测试 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <!-- ⭐ Spring AI BOM：统一管理所有 Spring AI 相关依赖的版本 -->
    <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>
        </dependencies>
    </dependencyManagement>

    <!-- Spring AI 里程碑/快照版本仓库（如果使用正式版可以去掉） -->
    <repositories>
        <repository>
            <id>spring-milestones</id>
            <name>Spring Milestones</name>
            <url>https://repo.spring.io/milestone</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
    </repositories>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

关于依赖的说明：

• spring-ai-starter-model-openai 这个依赖看起来是"OpenAI 专用"的，但实际上由于 DeepSeek、通义千问、月之暗面等大量国内外模型都兼容 OpenAI API 格式，所以你用这一个 starter 就能接入绝大多数模型。这就是 Spring AI "统一抽象"的魅力。
• spring-ai-bom 用来统一管理所有 Spring AI 模块的版本，避免依赖冲突。
• 1.1.6 是正式发布版本，不需要额外配置快照仓库。如果你选择 2.0.0-M6（里程碑版），则需要保留上面的 spring-milestones 仓库。

添加完依赖后，执行一下 Maven 刷新（IDEA 中点一下 Maven 面板的刷新按钮），让它把依赖下载下来。

四、代码实战：第一个能跑的空项目

依赖配置好了，我们先写一个最简单的项目骨架，验证整个链路能走通。

补充开始前，介绍一个小技巧：如果你觉得手动配置整个项目麻烦，可以直接去 Spring 官方文档（docs.spring.io/spring-ai/reference）找到 Quick Start 示例代码 clone 下来。

4.1 编写配置文件

创建或编辑 src/main/resources/application.yml：

spring:
  application:
    name: spring-ai-hello-world

  # 多模型配置演示
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}        # 从环境变量读取，更安全
      base-url: https://api.openai.com   # 官方地址，可替换为兼容地址
      chat:
        options:
          model: gpt-4.1                  # 模型名称，根据你申请的模型修改
          temperature: 0.7               # 创造性程度，0=确定性，1=随机性

⚠️ API Key 安全提示 ：永远不要把 API Key 直接硬编码在配置文件里！上面的写法用了 ${OPENAI_API_KEY} 从环境变量读取。你需要在操作系统中设置这个环境变量：

• Mac/Linux ：export OPENAI_API_KEY=sk-你的密钥
• Windows PowerShell ：$env:OPENAI_API_KEY="sk-你的密钥"

或者用 IDEA 的运行配置中设置环境变量也行。

4.2 API Key 怎么搞？

截止 2026 年 5 月，以下是主流模型提供商的 API Key 获取途径：

平台	获取地址	特点
OpenAI	platform.openai.com/api-keys	新用户通常有免费额度
DeepSeek	platform.deepseek.com	国内可用，价格亲民
通义千问（百炼）	dashscope.aliyun.com	阿里云，新用户免费额度丰厚
百度千帆	console.bce.baidu.com/qianfan	文心一言
Moonshot（Kimi）	platform.moonshot.cn	支持长上下文

学习阶段推荐：用 DeepSeek 或通义千问，注册方便、国内访问快、有免费额度。

如果你用 DeepSeek，配置文件改成这样：

spring:
  ai:
    openai:
      api-key: ${DEEPSEEK_API_KEY}
      base-url: https://api.deepseek.com
      chat:
        options:
          model: deepseek-chat
          temperature: 0.7

4.3 默认启动类不做修改

Spring Initializr 会自动生成一个启动类，它一般长这样：

package com.example.springaihelloworld;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SpringAiHelloWorldApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringAiHelloWorldApplication.class, args);
    }
}

这就够了，不需要额外写任何配置类。 Spring Boot 的自动配置（Auto-Configuration）会在启动时自动创建 ChatClient 等 Bean。你后续在 Controller 或 Service 中直接注入就行。

这就是 Spring 哲学的魅力------约定优于配置。你不需要手动 new 任何对象，框架帮你搞定。

五、运行与演示：验证项目跑通

5.1 启动项目

在 IDEA 中直接运行 SpringAiHelloWorldApplication.main() 方法，或者用命令行：

mvn spring-boot:run

如果控制台看到类似这样的输出，说明项目启动成功：

Started SpringAiHelloWorldApplication in 2.345 seconds

5.2 验证自动配置是否生效

我们来写一个最简单的测试，确认 Spring 容器已经帮你准备好了 ChatClient。在 src/test/java 下创建：

package com.example.springaihelloworld;

import org.junit.jupiter.api.Test;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import static org.junit.jupiter.api.Assertions.assertNotNull;

@SpringBootTest
class SpringAiHelloWorldApplicationTests {

    @Autowired
    private ChatClient chatClient;

    @Test
    void contextLoads() {
        // 断言 ChatClient 已被自动配置
        assertNotNull(chatClient, "ChatClient 应该被自动注入");
        System.out.println("✅ ChatClient 自动配置成功！");
    }
}

运行这个测试，如果控制台打印出 ✅ ChatClient 自动配置成功！，说明 Spring AI 的自动配置生效了。

5.3 常见启动错误速查

错误信息	原因	解决办法
java.lang.NoSuchBeanDefinitionException: No qualifying bean of type 'ChatClient'	缺少 API Key 配置	检查 application.yml 中 api-key 是否正确设置
Invalid API Key	API Key 填写错误或已过期	去对应平台重新创建 API Key
Failed to configure a DataSource	引入了 spring-boot-starter-data-jpa 但没有配数据源	删除 data jpa 依赖，或配置 H2 内存数据库
Connection refused: connect	网络问题，访问不到远端模型	确认 API 地址正确，确认网络能连通

新手特别注意 ：如果控制台报 401 Unauthorized，90% 的情况是因为 API Key 格式不对（多了空格、引号没写对、环境变量没生效）。请严格检查 key 的前缀和格式。

六、小结与下一步

本篇回顾

恭喜你！虽然这篇文章还没有写一行真正的 AI 对话代码，但你已经在正确的道路上迈出了最关键的一步。我们来回顾一下你今天学到的：

1. Spring AI 是什么：Spring 官方推出的 AI 框架，让 Java 开发者用 Spring 的风格写 AI 应用。
2. 核心概念：LLM（大语言模型）、API Key（调用凭证）、ChatClient（对话桥梁）、Spring AI Alibaba（阿里云扩展）。
3. 项目搭建 ：Spring Boot 3.5.14 + Spring AI 1.1.6，一个 pom.xml + 一个配置文件，就能让项目就绪。
4. 自动配置：你不写一行配置代码，Spring 也能帮你准备好 ChatClient。

记住这个公式：

Spring Boot 项目 + spring-ai-starter-model-openai + API Key = 能调用 AI 的 Java 项目

下一步预告

下一篇，我们将真正"开口说话"------用 Spring AI 接入 DeepSeek，编写第一个 AI 对话接口。只需要不到 20 行代码，你就能在浏览器里跟 AI 聊天了！我们将一步步实现：

• 编写第一个 /chat 接口
• 发一条消息给 AI，拿到真实的回复
• 理解 ChatClient 的调用链是怎么工作的

下一篇见！

本系列博客基于 Spring AI 1.1.6 版本编写，文中依赖版本均为发布时的最新稳定版。由于 Spring AI 生态更新频繁，建议你在实际开发时查阅 Spring AI 官方文档 和 Spring AI Alibaba 官方文档 获取最新信息。