Spring AI 从零开始学习（2026最新版）—— 从入门到实战，Java开发者快速上手

前言：随着大模型技术的普及，越来越多Java开发者希望将AI能力快速集成到Spring项目中，但不同大模型（OpenAI、DeepSeek、百度文心一言等）的API差异大、开发繁琐，且需手动处理Prompt设计、上下文管理等问题。Spring AI的出现，正是为了解决这个痛点——它作为Spring生态官方的AI集成框架，让开发者用熟悉的Spring方式（依赖注入、注解驱动），无需关注底层差异，快速开发AI应用。本文面向零基础开发者，从核心认知、环境搭建、实战案例到进阶方向，一步步带你吃透Spring AI，全程附完整代码，复制即可运行。

一、Spring AI 核心认知（新手必懂）

1.1 什么是Spring AI？

Spring AI 是 Spring 官方生态下的子项目，并非“创造新的大模型”，而是一个「大模型集成框架」。它的核心目标是简化Spring应用与各类大模型的集成过程，提供标准化的API、统一的交互模式，以及丰富的辅助特性，让开发者专注于业务逻辑，而非大模型的调用细节。

类比理解：Spring AI 之于大模型，就像 Spring Data 之于数据库——无需手动编写JDBC代码，通过统一接口即可操作不同数据库；同样，无需手动封装大模型的HTTP API，通过Spring AI的统一接口，即可切换调用不同厂商的大模型。

1.2 Spring AI 核心优势（为什么值得学）

  • 统一API抽象：封装了大模型的调用逻辑，提供ChatClient（对话交互）、EmbeddingClient（向量生成）等统一接口，切换OpenAI、DeepSeek等大模型时，无需修改业务代码。

  • 无缝集成Spring生态：支持Spring Boot自动配置、依赖注入、AOP等特性，符合Spring开发者的使用习惯，学习成本极低，Java开发者可快速上手。

  • 丰富的辅助特性：内置Prompt模板、对话记忆、结构化输出、自定义Advisor等功能，解决AI开发中的常见痛点（如硬编码Prompt、上下文丢失、输出格式混乱）。

  • 轻量级设计：无侵入式集成，可按需引入对应大模型的依赖，不增加项目冗余；同时支持本地模型（如Ollama部署的DeepSeek），零成本调试。

  • 完善的生态支持：支持所有主流AI模型提供商（OpenAI、Anthropic、Google等）和向量数据库（Redis、Milvus等），满足各类AI应用场景需求。

1.3 核心组件（新手先掌握这4个）

Spring AI的核心组件不多，新手只需先掌握以下4个，就能应对大部分基础场景，后续进阶再补充其他组件：

  • ChatClient：对话交互核心客户端，是开发者与大模型交互的入口，负责发送Prompt、接收响应，支持同步/异步调用。

  • Prompt：提示信息封装，包含用户输入、系统指令等内容，是大模型的“输入载体”。

  • PromptTemplate：Prompt模板，解决硬编码Prompt问题，支持参数化替换、外部文件加载，提升代码复用性。

  • ConversationMemory：对话记忆，负责存储多轮对话上下文，让AI能够“记住”之前的对话内容，实现连续交互。

二、环境搭建（零基础手把手操作）

本文以「Spring Boot 3.2 + Spring AI 1.1.4（2026最新稳定版）」为基础，提供两种搭建方案：① 对接OpenAI云端模型（需API Key）；② 本地部署DeepSeek模型（零成本，无需API Key），新手可根据自身情况选择。

2.1 环境要求（必看）

  • JDK：17+（Spring AI对JDK版本有最低要求，推荐JDK 17/21，与Spring Boot 3.x适配）。

  • Spring Boot：3.2+（推荐3.2.4，与Spring AI 1.1.4版本兼容）。

  • 构建工具：Maven 3.6+ 或 Gradle 7.0+（本文以Maven为例）。

  • 可选依赖：Lombok（简化实体类代码，非必需但推荐）。

2.2 方案1：对接OpenAI云端模型（需API Key）

2.2.1 创建Spring Boot项目

通过Spring Initializr（https://start.spring.io/）创建项目，选择：

  • Spring Boot版本：3.2.4

  • 依赖：Spring Web（用于提供接口测试）、Lombok（可选）

2.2.2 引入Spring AI依赖

在pom.xml中添加Spring AI OpenAI依赖和BOM（统一版本管理），避免版本冲突：

<!-- Spring AI BOM 统一版本管理 -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>1.1.4</version>
            pom<scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- Spring Boot Web 依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    
    <!-- Spring AI OpenAI 依赖（对接OpenAI大模型） -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    </dependency>
    
    <!-- Lombok 依赖（可选） -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
    
    <!-- 测试依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>
2.2.3 配置OpenAI信息

在src/main/resources/application.yml中配置OpenAI的API Key和模型信息，Spring AI会自动配置ChatClient实例，无需手动创建：


spring:
  ai:
    openai:
      api-key: 你的OpenAI API Key  # 替换为自己的API Key（从OpenAI官网获取）
      chat:
        model: gpt-3.5-turbo  # 模型名称，可选gpt-4等
        temperature: 0.7  # 随机性，0-1之间，值越小越严谨
        timeout: 30000  # 超时时间，单位ms

提示：API Key获取方式：登录OpenAI官网（https://platform.openai.com/），进入API Keys页面创建，注意保密，不要硬编码到生产环境（可通过环境变量配置）。

2.3 方案2：本地部署DeepSeek模型（零成本，无需API Key）

如果没有OpenAI API Key，可通过Ollama本地部署DeepSeek模型，全程零成本，数据不出本机，适合新手调试。

2.3.1 安装Ollama（本地模型运行工具）

  • Windows/macOS：访问https://ollama.com/，下载对应平台安装包，双击安装即可。

  • Linux：执行命令：curl -fsSL https://ollama.com/install.sh | sh

安装完成后，Ollama会作为后台服务自动启动，默认监听localhost:11434。

2.3.2 拉取并运行DeepSeek模型

打开终端，执行以下命令，拉取并启动DeepSeek模型（以1.5B版本为例，约1.1GB，低配电脑也能运行）：


ollama run deepseek-r1:1.5b

提示：模型大小选择参考（根据自身硬件配置）：1.5B（2GB内存）、7B（8GB内存）、14B（16GB内存），越大效果越好。

2.3.3 配置Spring AI对接本地模型

修改pom.xml，替换OpenAI依赖为Ollama依赖：

<!-- 替换OpenAI依赖为Ollama依赖 -->
<dependency>
    <groupId>org.springframework.ai</groupId>
   <artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
</dependency>

修改application.yml配置：


spring:
  ai:
    ollama:
      base-url: http://localhost:11434  # Ollama默认服务地址
      chat:
        model: deepseek-r1  # 模型名称，与终端启动的模型一致
        options:
          temperature: 0.7
          num-predict: 2048  # 最大输出长度
2.4 验证环境是否搭建成功

启动Spring Boot项目，若控制台无报错，且能看到“Started Application in xxx seconds”，说明环境搭建成功。

三、核心实战（4个案例，从简单到复杂）

以下案例均基于两种环境（OpenAI/本地DeepSeek）通用，只需确保配置正确，代码无需修改，复制即可运行。

案例1：单次对话（无上下文，一问一答）

最基础的用法：通过ChatClient发送单次Prompt，获取大模型响应，无需保存对话上下文。

3.1.1 编写Service层（核心逻辑）

import lombok.RequiredArgsConstructor;
import org.springframework.ai.chat.ChatClient;
import org.springframework.stereotype.Service;

/**
 * Spring AI 基础对话服务
 */
@Service
@RequiredArgsConstructor  // 构造器注入ChatClient（Spring AI自动配置）
public class ChatService {

    private final ChatClient chatClient;

    /**
     * 单次对话（无上下文）
     * @param prompt 用户输入的提示词
     * @return 大模型响应结果
     */
    public String singleChat(String prompt) {
        // 直接调用ChatClient的prompt方法，发送提示词并获取响应
        return chatClient.prompt().user(prompt).call().content();
    }
}
3.1.2 编写Controller层（提供接口测试）

import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequiredArgsConstructor
public class ChatController {

    private final ChatService chatService;

    // 接口地址：http://localhost:8080/chat/single?prompt=你的问题
    @GetMapping("/chat/single")
    public String singleChat(@RequestParam String prompt) {
        return chatService.singleChat(prompt);
    }
}
3.1.3 测试接口

启动项目后，访问：http://localhost:8080/chat/single?prompt=用一句话解释Spring AI，即可看到大模型的响应结果，说明单次对话功能正常。

案例2：Prompt模板（解决硬编码问题）

实际开发中，Prompt通常需要参数化（如动态替换用户需求），使用PromptTemplate可实现模板复用，避免硬编码。

3.2.1 编写Service层扩展方法

import org.springframework.ai.chat.prompt.PromptTemplate;
import org.springframework.stereotype.Service;

@Service
@RequiredArgsConstructor
public class ChatService {

    private final ChatClient chatClient;

    // 案例1：单次对话（无上下文）
    public String singleChat(String prompt) {
        return chatClient.prompt().user(prompt).call().content();
    }

    // 案例2：Prompt模板（参数化）
    public String templateChat(String user需求, String 语言类型) {
        // 定义Prompt模板，{}中的是参数，可动态替换
        String promptTemplate = "作为一名Java开发者，请用{语言类型}回答用户需求：{user需求}，要求简洁明了，不超过50字。";
        
        // 创建PromptTemplate实例，替换参数
        PromptTemplate template = new PromptTemplate(promptTemplate);
        String prompt = template.create(Map.of("user需求", user需求, "语言类型", 语言类型));
        
        // 发送Prompt并获取响应
        return chatClient.prompt().user(prompt).call().content();
    }
}
3.2.2 编写Controller扩展接口

@RestController
@RequiredArgsConstructor
public class ChatController {

    private final ChatService chatService;

    // 案例1接口
    @GetMapping("/chat/single")
    public String singleChat(@RequestParam String prompt) {
        return chatService.singleChat(prompt);
    }

    // 案例2接口：http://localhost:8080/chat/template?user需求=Spring AI怎么用&语言类型=中文
    @GetMapping("/chat/template")
    public String templateChat(@RequestParam String user需求, @RequestParam String 语言类型) {
        return chatService.templateChat(user需求, 语言类型);
    }
}

案例3：多轮对话（保存上下文，连续交互）

单次对话无法保存上下文，多轮对话需要使用ConversationMemory存储历史对话，让AI“记住”之前的内容。

3.3.1 编写Service层扩展方法

import org.springframework.ai.chat.Conversation;
import org.springframework.ai.chat.ConversationMemory;
import org.springframework.ai.chat.memory.InMemoryConversationMemory;
import org.springframework.stereotype.Service;

@Service
@RequiredArgsConstructor
public class ChatService {

    private final ChatClient chatClient;

    // 案例1：单次对话（无上下文）
    public String singleChat(String prompt) {
        return chatClient.prompt().user(prompt).call().content();
    }

    // 案例2：Prompt模板（参数化）
    public String templateChat(String user需求, String 语言类型) {
        String promptTemplate = "作为一名Java开发者，请用{语言类型}回答用户需求：{user需求}，要求简洁明了，不超过50字。";
        PromptTemplate template = new PromptTemplate(promptTemplate);
        String prompt = template.create(Map.of("user需求", user需求, "语言类型", 语言类型));
        return chatClient.prompt().user(prompt).call().content();
    }

    // 案例3：多轮对话（保存上下文）
    public String multiChat(String prompt, String sessionId) {
        // 1. 创建对话记忆（基于内存，生产环境可替换为Redis等持久化存储）
        ConversationMemory memory = new InMemoryConversationMemory();
        // 2. 创建对话实例，关联ChatClient和对话记忆
        Conversation conversation = new Conversation(chatClient, memory);
        // 3. 发送当前Prompt，自动关联历史对话
        conversation.prompt().user(prompt).call();
        // 4. 返回最新响应
        return conversation.getLatestResponse().get().getContent();
    }
}

提示：生产环境中，InMemoryConversationMemory（内存存储）会随服务重启丢失，建议替换为RedisConversationMemory（Redis存储），实现会话持久化。

案例4：结构化输出（将AI响应映射为Java实体）

AI默认返回文本字符串，实际开发中常需要将响应映射为Java实体（如用户信息、商品信息），Spring AI支持结构化输出，无需手动解析JSON。

3.4.1 定义Java实体类

import lombok.Data;

/**
 * 结构化输出实体：用户信息
 */
@Data
public class UserInfo {
    private String name;    // 姓名
    private Integer age;    // 年龄
    private String city;    // 城市
    private String job;     // 职业
}
3.4.2 编写Service层扩展方法

import org.springframework.ai.chat.prompt.PromptTemplate;
import org.springframework.ai.chat.response.JsonResponseExtractor;
import org.springframework.stereotype.Service;

@Service
@RequiredArgsConstructor
public class ChatService {

    private final ChatClient chatClient;

    // 案例4：结构化输出（映射为Java实体）
    public UserInfo structuredOutput(String prompt) {
        // 定义Prompt，指定输出格式为JSON（对应UserInfo实体）
        String promptTemplate = "根据用户需求：{prompt}，返回一个UserInfo对象，格式为JSON，不要多余文本，字段严格匹配实体类。";
        PromptTemplate template = new PromptTemplate(promptTemplate);
        String finalPrompt = template.create(Map.of("prompt", prompt));
        
        // 调用ChatClient，指定JSON响应提取器，自动映射为UserInfo实体
        return chatClient.prompt()
                .user(finalPrompt)
                .call()
                .extract(new JsonResponseExtractor<>(UserInfo.class));
    }
}
3.4.3 编写Controller扩展接口

@RestController
@RequiredArgsConstructor
public class ChatController {

    private final ChatService chatService;

    // 案例4接口：http://localhost:8080/chat/structured?prompt=生成一个25岁、广州、Java后端开发者的用户信息
    @GetMapping("/chat/structured")
    public UserInfo structuredOutput(@RequestParam String prompt) {
        return chatService.structuredOutput(prompt);
    }
}

测试接口后，会直接返回UserInfo实体的JSON格式，无需手动解析，极大提升开发效率。

四、常见问题与避坑指南

新手学习过程中，容易遇到以下问题，提前规避可节省大量调试时间：

4.1 配置相关问题

  • API Key错误：启动报错“Invalid API Key”，检查application.yml中的api-key是否正确，OpenAI API Key需避免空格、换行，建议通过环境变量配置。

  • 模型连接超时：报错“ConnectTimeoutException”，检查网络是否通畅，OpenAI需科学上网，本地模型检查Ollama服务是否正常启动（localhost:11434可访问）。

  • 版本冲突：Spring AI与Spring Boot版本不兼容，建议使用本文推荐的版本组合（Spring Boot 3.2.4 + Spring AI 1.1.4），并通过BOM统一版本。

4.2 代码相关问题

  • ChatClient注入失败：检查是否引入了对应大模型的Starter依赖（如OpenAI/Ollama），Spring AI会自动配置ChatClient，无需手动创建。

  • 结构化输出失败：确保Prompt中明确要求输出JSON格式，且字段与Java实体类严格匹配（大小写、字段名一致），避免多余文本。

  • 对话记忆丢失：InMemoryConversationMemory仅适用于测试，生产环境需使用Redis等持久化存储，确保会话上下文不丢失。

4.3 性能与优化建议

  • 启用日志调试：在application.yml中设置日志级别为DEBUG，可查看Prompt发送、响应接收的完整过程，便于排查问题。

  • 配置重试机制：大模型调用可能失败，可通过Spring AI的重试配置，设置重试次数和超时时间。

  • 本地模型优化：部署DeepSeek模型时，根据硬件配置选择合适的模型大小，避免内存不足导致服务崩溃。

五、进阶学习方向（新手进阶路线）

掌握基础用法后，可按照以下方向进阶，提升Spring AI实战能力，适配企业级开发需求：

  1. 向量数据库集成：学习Spring AI与Redis、Milvus等向量数据库的集成，实现RAG（检索增强生成），解决大模型“失忆”和知识更新问题。

  2. 函数调用（Function Calling）：学习让大模型调用外部工具（如数据库查询、接口调用），实现更复杂的业务逻辑（如AI客服查询订单）。

  3. 流式输出：实现AI响应的流式返回（类似ChatGPT的打字效果），提升用户体验，适用于对话类应用。

  4. 多模型集成：学习切换不同大模型（如OpenAI、DeepSeek、文心一言），根据场景动态选择最优模型，提升应用灵活性。

  5. 企业级部署：学习Spring AI应用的容器化部署（Docker）、集群部署，以及API Key的安全管理、流量控制。

六、学习资源推荐（官方+实用）

  • 官方文档（最权威）：Spring AI 官方参考文档 https://docs.spring.io/spring-ai/reference/index.html

  • 官方示例：Spring AI GitHub示例库 https://github.com/spring-projects/spring-ai/tree/main/samples

  • 版本更新：Spring AI 官方博客 https://spring.io/blog/categories/spring-ai（获取最新版本和特性）

  • 本地模型：Ollama 官方文档 https://ollama.com/docs（部署本地大模型）

总结

Spring AI 是Java开发者集成AI能力的最佳选择，它降低了大模型集成的门槛，让开发者无需关注底层细节，专注于业务逻辑。本文从零基础出发，讲解了Spring AI的核心认知、环境搭建、4个实战案例，以及常见问题和进阶方向，全程附完整代码，新手可直接复制运行。

学习Spring AI的关键是多动手实践，从简单的单次对话到复杂的RAG应用，逐步积累经验。随着大模型技术的不断发展，Spring AI的生态会越来越完善，掌握它将成为Java开发者的核心竞争力之一。

最后，祝大家学习顺利，早日用Spring AI开发出自己的AI应用！如果本文对你有帮助，欢迎点赞、收藏、关注，后续会持续更新Spring AI进阶内容~

# java # spring # 人工智能
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

鸿蒙PCElectron框架实现网络测速实现原理深度解析 - WiFi管理大师技术专栏

avatar AtomGit开源社区

人机回环（Human-in-the-loop）在金融风控 Agent 中的落地模式

前两年AI技术爆发的时候，很多金融机构喊出了"全自动化风控"的口号，希望用AI模型100%替代人工审核，结果踩了无数坑：要么是模型对新出现的欺诈手段完全识别不出来，坏账率飙升；要么是模型误拒了很多优质客户，业务量掉了30%；更麻烦的是监管要求风控决策可解释、可追溯，黑箱AI模型根本过不了合规检查。本文的目的就是给大家提供一个成熟的解决方案：人机回环风控系统。我们会覆盖从核心概念到落地代码的全流程，

avatar AtomGit开源社区
cover

RAG 检索效果翻倍的秘密：重排序（Re-ranking）原理 + 实战

avatar AtomGit开源社区