Spring AI框架快速入门

​**​前言：**在经历了八个里程碑式的版本之后（M1~M8），Spring AI 1.0 正式版本，终于在 2025 年 5 月 20 日正式发布，这是另一个新高度的里程碑式的版本，标志着 Spring 生态系统正式全面拥抱人工智能技术，并且意味着 Spring AI 将会给企业带来稳定 API 支持。Spring AI​​ 是 Spring 生态中一个新兴的子项目，旨在简化人工智能（尤其是生成式 AI）在 Java 应用中的集成。它提供了一套标准化 API 和工具，帮助开发者快速接入LLM大语言模型、向量数据库等 AI 组件，同时与 Spring 的核心特性（如依赖注入、响应式编程）无缝结合。

---

一、​​Spring AI 主要解决哪些痛点？

Spring AI 新架构设计主要旨在解决以下3个关键问题：

1.1、 统一的 API 抽象，隐藏底层复杂性

SpringAI 的核心价值在于统一不同 AI 供应商的差异化 API 。无论是 OpenAI、Qwen还是 DeepSeek，开发者都通过同一套 ChatClient 接口进行操作。这种设计完美契合六边形架构思想，将 AI 能力作为可插拔的端口（Port）接入系统，业务核心逻辑则通过适配器（Adapter）与具体实现解耦。

public interface ChatClient { ChatResponse call(ChatRequest request); 
Flux<ChatResponse> stream(ChatRequest request); }

Spring AI 支持市面上几乎所有主流的大模型提供商（包括聊天模型和图像生成模型）以及向量数据库。统一接口支持多种 AI 服务**，**无论你使用的是 OpenAI 的 GPT、深度求索的 DeepSeek、谷歌的 Gemini、Anthropic 的 Claude，还是 Hugging Face 上的开源模型，Spring AI 都旨在提供一套统一且可移植的 API，让你能够轻松调用。对于向量数据库，比如：Milvus、Pinecone、Redis、PGVector 等，它同样提供了统一的 API 和查询方法。这样，你的代码就可以更灵活地在不同的 AI 服务和数据库之间切换，不会被某个特定供应商锁定。

1.2、简化 AI 应用开发，广泛支持模型、向量数据库、RAG和MCP等

构建一个稍微复杂的 AI 应用，集成向量数据库（如 Pinecone、Milvus），支持 RAG（检索增强生成）场景。比如：RAG（检索增强生成），通常需要涉及数据加载、分割、向量化、存储、检索、调用大语言模型（LLM）等多个步骤。Spring AI 提供了 ETL 框架、ChatClient、VectorStore 等组件和抽象，大大简化了这些流程的实现。对话管理​,封装 ChatClient 和 ChatModel，管理上下文、消息历史、提示词模板。

1.3、配置即连接，深度集成 Spring 生态

这是 Spring 的强项，支持 Spring Boot 自动配置、Spring WebFlux 响应式调用。Spring AI 提供了各种 Spring Boot Starter，使得配置和集成 AI 模型、向量数据库变得非常简单，遵循"约定优于配置"的原则，即开箱即用，无需复杂的配置。

通过 Spring Boot 的 application.yaml，特别适合需要动态切换大模型供应商的企业场景。：

spring:
  ai:
    openai:
      api-key: xxx
      base-url: xxx
      chat:
        options:
          model: xxx
#  completions-path 属性用于指定调用 OpenAI 聊天补全接口的具体路径，默认值：/v1/chat/completions（对应 OpenAI 官方接口路径）
#        completions-path: /v1/chat/completions
          temperature: 0.7

---

二、Spring AI 涉及的基础概念

• 模型(Model)

就是接收用户行为，以及根据用户行为生成内容的算法，本质还是算法，这些算法可以接收文本、图片、音视频，生成满足用户需要的文本、图片、音频视频等内容，其中有一种输入文本叫嵌入文本(embedding text),输出多维度的数组，表示AI模型使用的内部数据结构，用来判断多个样本之间的相似性。

• 提示词(Prompt)

prompt是引导AI模型生成特定输出的输入，它的设计会显著影响模型的响应，一开始prompt是简单的文本输入，就好比是智能对话中的问题，随着事件的推移，prompt演变成了包含多个"角色"的结构体，这些角色对消息进行分类，明确了上下文，可以实现历史问答等的相关功能等。角色有：系统角色(System Role)、用户角色(User Role)、助手角色(Assistant Role)、工具/功能角色(Tool/Function Role)。

• 提示词模板(Prompt Template)

就是模板格式，在实际运用中可以提供占位符的格式，使用用户的输入替换占位符，增加灵活性。Spring AI采用开源库StringTemplate来实现。

• 嵌入(Embedding)

原理就是把输入的文本、图像和视频转换为称为向量（Vector）的浮点数数组来表示，数组长度就是向量的维度，可以把多维度的向量数组映射到空间坐标轴中，依次找到他们之间的接近性，这种接近性有助于文本分类、语义搜索，甚至产品推荐等任务。也可以把数组存入到向量数据库中，提供给RAG使用。

• Token

token是 AI 模型工作原理的基石。输入时，模型将单词转换为token。输出时，它们将token转换回单词。在英语中，一个token大约对应一个单词的 75%，实际使用第三方大模型的过程中，也是根据token进行收费的，具体收费情况根据模型和输入输出类型而定。

• 结构化输出(Structured Output)

就是把从大模型输出的结果转换成我们想要类型，可以是json格式、xml格式、或者是java类，这对于我们应用开发者比较重要，可以自定义实体类来接收结果，在应用中使用。

• 检索增强生成(RAG)

我理解是一种方法，目的是为大模型提供额外的知识输入，辅助模型更好的回答问题，当用户输入问题时，RAG技术从矢量数据库查询出所有"类似"的文档片段，连同用户的问题，一起放入发送给 AI 模型的提示中。该方法涉及到：从文档中读取非结构化数据、对其进行转换、然后将其写入矢量数据库。

• 函数调用(Function Calling)

大型语言模型 (LLM) 在训练后即被冻结，导致知识陈旧，并且无法访问或修改外部数据。该方式提供了一种方法，解决大模型训练后知识陈旧的问题，可以引入自定义的功能函数，函数中可以调取外部的API来获取最新的数据返回给大模型，并最终向用户提供响应。

---

三、​​Spring AI 的核心组件​​

3.1、​​ChatModel（模型抽象）​​

• ​作用​ ：定义生成式 AI 模型的统一接口（如 generate(prompt)）。

• ​实现示例​ ：

  // 配置 OpenAI 模型
  @Bean
  OpenAiChatModel openAiModel() {
      return new OpenAiChatModel("sk-xxx");
  }

• ​调用​ ：

  String reply = chatModel.generate("Hello, how are you?");

3.2、ChatClient（客户端封装）​​

• ​作用​：简化与模型的交互，支持流式响应和上下文管理。

• ​示例​ ：

  @Autowired
  private ChatClient chatClient;
  
  // 发送消息并获取流式响应
  Flux<String> response = chatClient.stream("Explain quantum computing.");

3.3、PromptTemplate（提示词模板）​​

• ​作用​：动态生成结构化提示词，支持变量插值。

• ​示例​ ：

  PromptTemplate template = new PromptTemplate("Translate '{text}' to French.");
  Prompt prompt = template.create(Map.of("text", "Hello world"));
  String translation = chatModel.generate(prompt);

---

四、​​与 WebFlux 的集成（响应式 AI 服务）​​

Spring AI 天然支持与 ​​Spring WebFlux​​ 结合，构建非阻塞的高并发 AI 服务。

示例：实时聊天 API

@RestController
public class ChatController {
    @Autowired
    private ChatClient chatClient;

    // 流式聊天接口（SSE 协议）
    @GetMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> streamChat(@RequestParam String message) {
        return chatClient.stream(message);
    }

    // 同步聊天接口
    @PostMapping("/chat")
    public Mono<String> chat(@RequestBody String message) {
        return chatClient.generate(message);
    }
}

---

​五、快速入门 Spring AI​​

5.1、添加Maven依赖​​

   <!-- Spring AI -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
            <version>1.0.0-M6</version>
   </dependency>

5.2、​​配置 API 密钥​ ​（application.yml）

spring:
  ai:
    openai:
      api-key: xxx
      base-url: xxx
      chat:
        options:
          model: xxx
#  completions-path 属性用于指定调用 OpenAI 聊天补全接口的具体路径，默认值：/v1/chat/completions（对应 OpenAI 官方接口路径）
#        completions-path: /v1/chat/completions
          temperature: 0.7

5.3、OpenAiChatClientController实现流式调用和同步调用

package com.hs.demo.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.client.advisor.AbstractChatMemoryAdvisor;
import org.springframework.ai.chat.client.advisor.MessageChatMemoryAdvisor;
import org.springframework.ai.chat.client.advisor.SimpleLoggerAdvisor;
import org.springframework.ai.chat.memory.InMemoryChatMemory;
import org.springframework.ai.openai.OpenAiChatOptions;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.http.codec.ServerSentEvent;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Flux;

/**
 * 实现调用逻辑，可以设置默认的系统Prompt，定义模型的参数
 *
 * 使用InMemoryChatMemory聊天记录的存储，可以让模型记住对话记录，结合上下文去回答，chatId就是会话窗口的id，在这个id不变的情况下，它会自定义的去在总结100条对话记录，然后再回答你的问题
 */
@RestController
@RequestMapping("/openai/chat")
@Tag(name = "AI对话")
public class OpenAiChatClientController {

    private final ChatClient openAiChatClient;

    private static final String DEFAULT_PROMPT = "你是一个聊天助手，请根据用户提问回答！";

     public OpenAiChatClientController(ChatClient.Builder chatClientBuilder) {

       this.openAiChatClient = chatClientBuilder
             .defaultSystem(DEFAULT_PROMPT)
              // 实现 Chat Memory 的 Advisor              // 在使用 Chat Memory 时，需要指定对话 ID，以便 Spring AI 处理上下文。
              .defaultAdvisors(
                    new MessageChatMemoryAdvisor(new InMemoryChatMemory())
              )
              // 实现 Logger 的 Advisor
              .defaultAdvisors(
                    new SimpleLoggerAdvisor()
              )
              // 设置 ChatClient 中 ChatModel 的 Options 参数
              .defaultOptions(
                    OpenAiChatOptions.builder()
                          .topP(0.7)
                          .build()
              )
             .build();
     }

    /**
     * ChatClient 简单调用
     */
    @GetMapping("/simple/chat")
    @Operation(summary = "ChatClient 简单调用")
    public String simpleChat(@RequestParam String message) {

       String str = openAiChatClient.prompt(message).advisors(new SimpleLoggerAdvisor()).call().content();
       System.out.println("输出结果"+str);
       return str;
    }

	/**
	 * ChatClient 简单调用
	 * 默认使用 InMemoryChatMemory
	 ** @param message 消息
	 * @param chatId  会话ID
	 */
    @GetMapping("/simple/chat/conversaion")
    @Operation(summary = "ChatClient 简单调用附带会话")
	public String simpleChat(@RequestParam String message, @RequestParam String chatId) {
	    return openAiChatClient
	          .prompt(message)
	              .advisors(a -> a
	                       .param(AbstractChatMemoryAdvisor.CHAT_MEMORY_CONVERSATION_ID_KEY, chatId) // 设置聊天会话ID
	                       .param(AbstractChatMemoryAdvisor.CHAT_MEMORY_RETRIEVE_SIZE_KEY, 100)) // 设置聊天记录检索数量
	          .call().content();
	}

    /**
     * ChatClient 流式调用
     */
    @GetMapping("/stream/chat")
    @Operation(summary = "ChatClient 流式调用")
    public Flux<String> streamChat(@RequestParam String message,
                            HttpServletResponse response) {

       response.setCharacterEncoding("UTF-8");
       return openAiChatClient.prompt(message).stream().content();
    }

    /**
     * ChatClient 流式响应
     */
    @GetMapping(value = "/stream/response", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    @Operation(summary = "ChatClient 流式调用1")
    public Flux<ServerSentEvent<String>> streamChat(@RequestParam String message) {
       return openAiChatClient.prompt()
             .user(message)
             .stream()
             .content()
             .map(content -> ServerSentEvent.<String>builder()
                   .data(content)
                   .build());
    }

}

---

​总结​ ​：Spring AI 通过标准化接口和 Spring 原生集成，显著降低了 Java 应用中集成 AI 能力的门槛。开发者可以更专注于业务逻辑，而非底层协议实现。对于需要快速迭代且依赖 Spring 生态的项目，它是比手动封装 ChatClient/ChatModel 更高效的选择。

---

参考链接：

Spring AI 1.0.0 发布，顺手整了下中文文档

Spring AI 1.0.0 发布！支持 MCP 很炸裂！!

SpringAI实践（一）

接入SpringAI实现流式对话

Spring AI 1.0 正式发布！AI 开发从未如此简单，不懂它的三层开发模式你就输麻了！

增强器 API - 零基础入门Java AI