【AI开发】—— Spring AI 入门指南：核心特性与基础用法实战

Spring AI 入门指南：核心特性与基础用法实战

随着大模型技术的普及，越来越多开发者希望将AI能力快速集成到Spring项目中，但不同大模型（OpenAI、百度文心一言、阿里通义千问等）的API差异大、开发繁琐，且需手动处理Prompt设计、上下文管理、输出解析等问题。Spring AI的出现，正是为了解决这个痛点------它为Spring生态提供了统一的AI开发抽象，让开发者无需关注不同大模型的底层差异，用Spring熟悉的方式（依赖注入、注解驱动）快速开发AI应用。

本文将从Spring AI核心定位出发，拆解其核心价值与核心组件，再通过具体实战代码，讲解Spring AI的基础用法，帮助新手快速上手，完成第一个AI交互案例。

一、Spring AI 核心介绍

1.1 什么是Spring AI？

Spring AI 是 Spring 官方生态下的一个子项目，并非"造一个新的大模型"，而是一个「大模型集成框架」。它的核心目标是：简化Spring应用与各类大模型的集成过程，提供标准化的API、统一的交互模式，以及丰富的辅助特性（如Prompt模板、对话记忆、结构化输出等），让开发者专注于业务逻辑，而非大模型的调用细节。

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

1.2 Spring AI 核心优势

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

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

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

• 轻量级设计：无侵入式集成，可按需引入对应大模型的依赖，不增加项目冗余。

1.3 核心组件（新手必知）

Spring AI 的核心组件不多，新手只需先掌握以下4个，就能应对大部分基础场景：

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

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

3. PromptTemplate：Prompt模板，解决硬编码Prompt问题，支持参数化替换、外部文件加载。

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

二、Spring AI 基础环境搭建（实战）

本文以「Spring Boot + Spring AI + OpenAI GPT-3.5」为例，搭建基础环境，完成第一个AI对话案例。其他大模型（如文心一言）的配置类似，只需替换依赖和配置项即可。

2.1 环境要求

• JDK 17+（Spring AI 对JDK版本有最低要求）

• Spring Boot 3.2+

• OpenAI API Key（需自行注册OpenAI账号，获取API Key）

2.2 引入依赖（pom.xml）

引入Spring Boot Starter和Spring AI OpenAI依赖，无需手动引入其他额外依赖（Spring AI会自动管理版本）：

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

<dependencies>
<!-- Spring Boot Web 依赖（用于提供接口测试） -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    &lt;/dependency&gt;

    <!-- Spring AI OpenAI 依赖（对接OpenAI大模型） -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-openai-spring-boot-starter</artifactId&gt;
        &lt;version>1.0.0-M1&lt;/version&gt; <!-- 请使用最新稳定版本 -->
    &lt;/dependency&gt;

    <!-- Lombok（简化实体类代码，可选） -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

2.3 配置大模型信息（application.yml）

在配置文件中填写OpenAI的API Key和模型名称，Spring AI会自动配置ChatClient实例，无需手动创建：

spring:
  ai:
    openai:
      api-key: 你的OpenAI API Key # 替换为自己的API Key
      chat:
        model: gpt-3.5-turbo # 模型名称，可选gpt-4等
        temperature: 0.7 # 随机性，0-1之间，值越小越严谨

关键说明：如果需要切换为其他大模型（如百度文心一言），只需替换依赖（如spring-ai-baidu-spring-boot-starter），并修改配置项（如spring.ai.baidu.api-key），无需修改业务代码。

三、Spring AI 基础用法实战

下面通过3个实战案例，讲解Spring AI的核心基础用法：单次对话、Prompt模板、多轮对话（对话记忆），每个案例都提供完整代码和测试方法。

3.1 案例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 // 构造器注入，无需@Autowired
public class AiChatService {

    // 自动注入Spring AI配置好的ChatClient实例
    private final ChatClient chatClient;

    /**
     * 单次对话（无上下文）
     * @param userInput 用户输入的问题
     * @return 大模型的响应结果
     */
    public String singleChat(String userInput) {
        // 1. 构建Prompt（直接传入用户输入，简单场景可省略PromptTemplate）
        // 2. 调用ChatClient的call方法，发送Prompt，获取响应
        // 3. 从响应中提取内容并返回
        return chatClient.call(userInput);
    }
}

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;

/**
 * AI对话接口
 */
@RestController
@RequiredArgsConstructor
@RequestMapping("/ai/chat")
public class AiChatController {

    private final AiChatService aiChatService;

    /**
     * 单次对话接口
     * @param userInput 用户输入
     * @return 响应结果
     */
    @GetMapping("/single")
    public String singleChat(@RequestParam String userInput) {
        return aiChatService.singleChat(userInput);
    }
}

3.1.3 测试效果

启动Spring Boot项目，通过浏览器或Postman访问接口：

请求地址：http://localhost:8080/ai/chat/single?userInput=请介绍一下Spring AI

响应结果（类似）：Spring AI是Spring生态下的大模型集成框架，旨在简化Spring应用与各类大模型的集成过程...（省略具体内容）

3.2 案例2：Prompt模板使用（解决硬编码）

实际开发中，Prompt往往包含固定模板（如系统指令）和动态参数（如用户输入），硬编码Prompt会导致维护困难。Spring AI的PromptTemplate可以解决这个问题，支持参数化替换、外部文件加载。

3.2.1 基础用法（硬编码模板）

在Service中使用PromptTemplate，动态填充用户输入参数：

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

/**
 * Prompt模板测试服务
 */
@Service
@RequiredArgsConstructor
public class PromptTemplateService {

    private final ChatClient chatClient;

    /**
     * 基础Prompt模板（硬编码模板，动态填充参数）
     * @param userInput 用户输入
     * @param language 响应语言（动态参数）
     * @return 大模型响应
     */
    public String promptTemplateTest(String userInput, String language) {
        // 1. 定义Prompt模板，使用{{变量名}}作为占位符
        String templateStr = """
                系统指令：你是一个专业的技术顾问，回答必须简洁、准确，并且使用{{language}}。
                用户输入：{{userInput}}
                要求：不要添加任何额外解释，直接给出答案。
                """;

        // 2. 创建PromptTemplate实例，传入模板字符串
        PromptTemplate promptTemplate = new PromptTemplate(templateStr);

        // 3. 填充模板参数（key对应占位符，value对应实际值）
        promptTemplate.add("language", language);
        promptTemplate.add("userInput", userInput);

        // 4. 生成Prompt对象
        Prompt prompt = promptTemplate.create();

        // 5. 调用大模型并返回结果
        return chatClient.call(prompt).getResult().getOutput().getContent();
    }
}

3.2.2 进阶用法（外部文件加载模板）

对于复杂模板，建议将其放在外部文件中，便于维护。Spring AI支持加载resources/prompts目录下的模板文件（后缀可设为.st、.txt、.md）。

1. 创建模板文件：resources/prompts/tech_consult.st

2. 加载外部模板的代码：

3.3 案例3：多轮对话（对话记忆）

单次对话无法满足连续交互场景（如聊天机器人），Spring AI的ConversationMemory可以保存多轮对话上下文，让大模型"记住"之前的对话内容。

新手入门推荐使用默认的内存级记忆（SimpleConversationMemory + InMemoryMemoryStore），重启应用后记忆丢失；后续可对接Redis/数据库实现持久化（进阶内容，后续详解）。

3.3.1 编写多轮对话Service

import org.springframework.ai.chat.ChatClient;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.memory.conversation.ConversationMemory;
import org.springframework.ai.memory.conversation.ConversationMemoryEntry;
import org.springframework.ai.memory.conversation.SimpleConversationMemory;
import org.springframework.ai.memory.store.InMemoryMemoryStore;
import org.springframework.stereotype.Service;

import java.util.List;
import java.util.stream.Collectors;

/**
 * 多轮对话服务（带内存级对话记忆）
 */
@Service
@RequiredArgsConstructor
public class MultiRoundChatService {

    private final ChatClient chatClient;

    // 对话记忆：内存级存储，重启应用后丢失
    private final ConversationMemory conversationMemory = new SimpleConversationMemory(new InMemoryMemoryStore());

    /**
     * 多轮对话（保存上下文）
     * @param conversationId 对话唯一标识（如用户ID，用于区分不同对话）
     * @param userInput 用户当前输入
     * @return 大模型响应
     */
    public String multiRoundChat(String conversationId, String userInput) {
        // 1. 从对话记忆中获取历史上下文
        List<ConversationMemoryEntry> historyEntries = conversationMemory.get(conversationId);
        String context = historyEntries.stream()
                .map(entry -> entry.getRole() + ": " + entry.getContent()) // 拼接角色和内容
                .reduce("", (a, b) -> a + "\n" + b); // 合并为字符串

        // 2. 构建带上下文的Prompt
        String promptStr = "上下文：" + context + "\n用户当前输入：" + userInput;
        Prompt prompt = new Prompt(promptStr);

        // 3. 调用大模型获取响应
        String aiResponse = chatClient.call(prompt).getResult().getOutput().getContent();

        // 4. 保存本轮对话到记忆中（用户输入 + AI响应）
        conversationMemory.add(conversationId, new ConversationMemoryEntry("user", userInput));
        conversationMemory.add(conversationId, new ConversationMemoryEntry("assistant", aiResponse));

        return aiResponse;
    }
}

3.3.2 测试多轮对话

编写Controller接口后，依次发送以下请求：

1. 第一次请求：http://localhost:8080/ai/chat/multi?conversationId=user123\&userInput=我想学习Spring AI

2. 响应：Spring AI的核心是统一大模型集成接口...（省略）

3. 第二次请求：http://localhost:8080/ai/chat/multi?conversationId=user123\&userInput=它有哪些核心组件

4. 响应：Spring AI的核心组件包括ChatClient、Prompt、PromptTemplate、ConversationMemory...（大模型会关联上一轮的"Spring AI"话题）

关键说明：conversationId用于区分不同用户的对话，确保不同用户的上下文不混淆。

四、常见问题与注意事项

• API Key 配置错误：若出现401错误，大概率是API Key错误或过期，需重新获取并配置。

• JDK版本过低：Spring AI要求JDK 17+，低于该版本会出现启动失败，需升级JDK。

• 对话记忆丢失：本文使用的是内存级记忆，重启应用后丢失，生产环境需对接Redis/数据库实现持久化。

• Prompt 格式问题：结构化输出、多轮对话等场景，需明确Prompt格式要求，否则大模型可能返回非预期结果。

• 版本兼容问题：Spring AI目前处于快速迭代阶段，不同版本的API可能有差异，建议使用最新稳定版本。

五、总结与后续展望

本文介绍了Spring AI的核心定位、优势、基础组件，以及3个最常用的基础用法（单次对话、Prompt模板、多轮对话），通过实战代码让新手能够快速上手，完成第一个Spring AI应用。

Spring AI的强大之处不仅在于基础的大模型调用，更在于其丰富的进阶特性------比如之前提到的自定义Advisor（横切逻辑扩展）、结构化输出（如恋爱报告）、对话记忆持久化等，这些特性能够帮助我们解决更复杂的企业级AI应用场景。

后续将逐步深入讲解这些进阶特性，结合实际业务场景（如AI咨询、结构化报告生成、智能聊天机器人），让大家真正掌握Spring AI的实战技巧，将AI能力落地到实际项目中。

最后，Spring AI作为Spring生态的重要补充，正在快速发展，未来会支持更多大模型、更多实用特性，值得Spring开发者持续关注和学习。