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: xxxbase-url: xxxchat:options:model: xxx
#  completions-path 屬性用于指定調用 OpenAI 聊天補全接口的具體路徑，默認值：/v1/chat/completions（對應 OpenAI 官方接口路徑）
#        completions-path: /v1/chat/completionstemperature: 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 {@Autowiredprivate 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: xxxbase-url: xxxchat:options:model: xxx
#  completions-path 屬性用于指定調用 OpenAI 聊天補全接口的具體路徑，默認值：/v1/chat/completions（對應 OpenAI 官方接口路徑）
#        completions-path: /v1/chat/completionstemperature: 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 發布！支持 MCP 很炸裂！!

SpringAI實踐（一）

接入SpringAI實現流式對話

Spring AI 1.0 正式發布！AI 開發從未如此簡單，不懂它的三層開發模式你就輸麻了！