使用 Spring AI 1.0.0 M7 已釋出

釋出 | Mark Pollack | 2025 年 4 月 10 日 | ...

我們很高興地宣佈 Spring AI 1.0.0 里程碑 7 已釋出。這將是最後一個里程碑版本。下個月將釋出 RC1 版本，緊接著將在巴塞羅那舉行的 Spring IO 大會前釋出 GA 版本。

為了慶祝這個版本，我們在我們的 AI 生成的音樂播放列表中添加了一首新歌，由 Josh Long 和 Claude 作詞！檢視最新曲目以增強您的部落格閱讀和編碼體驗。

以下是此版本的關鍵變化。請注意，存在破壞性變更！

破壞性變更

Spring AI 1.0.0-M7 引入了幾項重要變更，這些變更與之前在 SNAPSHOT 版本中引入的結構改進一致。這些變更建立了一個更模組化和更易於維護的程式碼庫，同時減少了應用程式中不必要的依賴項。

Artifact ID 變更

最重要的變化是 Spring AI starter artifact 的命名模式

Model starters: spring-ai-{model}-spring-boot-starter → spring-ai-starter-model-{model}
Vector Store starters: spring-ai-{store}-store-spring-boot-starter → spring-ai-starter-vector-store-{store}
MCP starters: spring-ai-mcp-{type}-spring-boot-starter → spring-ai-starter-mcp-{type}

包變更

一些類已移至新包以更好地反映其領域職責

KeywordMetadataEnricher 和 SummaryMetadataEnricher 從 org.springframework.ai.transformer 移至 org.springframework.ai.chat.transformer
Content, MediaContent, 和 Media 從 org.springframework.ai.model 移至 org.springframework.ai.content

您的 IDE 應該能夠輕鬆處理這些重構。

新模組結構

如上文核心架構改進部分所述，專案已從整體式核心重構為專業領域模組。

這種模組化方法允許您只包含所需的功能，從而減小部署規模並明確元件之間的邊界。

重要的是，**如果您使用 Spring AI starter，此更改不應是破壞性變更**，因為它們現在會自動匯入新的模組化依賴項。只有直接引用舊的整體式 artifact 的應用程式才需要更新其依賴項。

ToolContext 變更

ToolContext 類已增強，支援顯式和隱式工具解析，僅在明確請求時才在模型呼叫中包含工具。

附加資源

有關這些更改的更多詳細資訊，請參閱

Spring AI Snapshots 更新 - 結構變更的初步公告
Spring AI 使用 Snapshots 第二部分 - 模組重組的詳細解釋
參考指南中的升級說明

有兩種方法可以將您的專案更新到 Spring AI 1.0.0-M7

使用 Claude Code CLI tool 工具並使用此 prompt。您也可以使用其他 AI 助手工具，但我們只測試了使用 Claude Code。請注意，此自動化方法處理 artifact ID 更改、包重定位和模組結構更改，但尚未包含升級到 MCP 0.9.0 的自動更改。
請參閱升級說明以獲取詳細說明，包括有關手動更新 MCP 相關程式碼的指導。

核心架構改進

全面的模組化架構
- 徹底將專案從整體式核心重構為專業領域模組，提供
  - 減少依賴足跡：應用程式只需要包含它們實際使用的模組
  - 最小化傳遞依賴：減少與第三方庫的衝突
  - 更清晰的關注點分離：每個模組都有明確定義的職責
- spring-ai-commons：基礎模組，不依賴於其他 Spring AI 模組
  - 核心領域模型（Document、TextSplitter 等）
  - JSON 工具和資源處理
  - 結構化日誌記錄和可觀察性支援
- spring-ai-model：在 commons 的基礎上提供 AI 能力抽象
  - 介面如 ChatModel、EmbeddingModel 和 ImageModel
  - 訊息型別和 prompt 模板
  - 函式呼叫框架（ToolDefinition、ToolCallback）
  - 內容過濾和觀察支援
- spring-ai-vector-store：統一的向量資料庫抽象
  - 用於相似性搜尋的 VectorStore 介面
  - 使用類似 SQL 的表示式進行高階過濾
  - 用於記憶體使用的 SimpleVectorStore
  - embeddings 的批次處理支援
- spring-ai-client-chat：高階會話 AI API
  - ChatClient 介面
  - 透過 ChatMemory 進行會話持久化
  - 使用 OutputConverter 進行響應轉換
  - 基於 Advisor 的攔截
  - 同步和響應式流支援
- spring-ai-advisors-vector-store：橋接聊天與向量儲存以實現 RAG
  - QuestionAnswerAdvisor：將上下文注入到 prompts 中
  - VectorStoreChatMemoryAdvisor：儲存/檢索會話歷史記錄
- spring-ai-model-chat-memory-*：專業的持久化實現
  - Cassandra、Neo4j 和 JDBC 實現
- spring-ai-rag：用於檢索增強生成 (Retrieval Augmented Generation) 的綜合框架
  - RAG pipelines 的模組化架構
  - RetrievalAugmentationAdvisor 作為主要入口點
  - 採用函數語言程式設計原則，元件可組合
模組化自動配置
- 將單個整體式自動配置 artifact 替換為每個元件的獨立自動配置 artifact
  - 模型自動配置：spring-ai-autoconfigure-model-{model}
  - 向量儲存自動配置：spring-ai-autoconfigure-vector-store-{store}
  - MCP 自動配置：spring-ai-autoconfigure-mcp-{type}
- 此變更最大程度地減少了與 Google Protocol Buffers 和 gRPC 等庫的依賴衝突
- 應用程式現在只包含它們實際使用的元件的自動配置
- 使用相應的 starter 依賴項時，這些自動配置 artifact 會被傳遞地包含
包重組
- 戰略性地重新定位類以更好地反映其領域職責
  - KeywordMetadataEnricher 和 SummaryMetadataEnricher 從 org.springframework.ai.transformer 移至 org.springframework.ai.chat.transformer
  - Content, MediaContent, 和 Media 從 org.springframework.ai.model 移至 org.springframework.ai.content
- 改進包命名約定，以提高可發現性和組織性
框架增強
- 為 MethodToolCallbackProvider 添加了 AOP 代理支援，以實現更靈活的整合
- 增強了 JSON 序列化的執行時提示配置，以改善 native image 支援
- 透過標準化配置改進了 Spring Boot 整合
- 增強了所有模組的可觀察性和指標收集

升級到 MCP 0.9.0

Spring AI 1.0.0-M7 集成了最新的 MCP 參考實現 Java SDK 版本 0.9.0，帶來了顯著的架構改進

基於會話的架構：改進了多併發客戶端連線的處理，會話之間具有更好的隔離性
基於互動的通訊：新的互動物件提供了客戶端和伺服器之間感知上下文的互動
增強的傳輸提供者抽象：連線管理和通訊處理之間更清晰的分離
改進的工具管理：更好的工具名稱處理和去重，以避免複雜場景中的衝突
簡化的伺服器配置：配置和管理 MCP 伺服器的 API 已簡化
全面的 WebFlux 和 WebMvc 支援：增強了響應式和基於 Servlet 的應用程式的傳輸提供者

這些改進使得 MCP 實現更加健壯、可伸縮，並且更好地與 MCP 規範保持一致。有關詳細的遷移指南，請參閱升級說明中關於 MCP Java SDK 變更的部分。

Spring AI Examples repository 中的所有示例已更新，以與最新的 MCP 實現協同工作。

新增和增強的模型整合

Anthropic Claude 更新
- 添加了對 Claude 3.7 Sonnet 模型的支援並將其設定為預設
- 增強了“思考”能力（THINKING 和 REDACTED_THINKING 塊）
- 將函式相關的 API 重新命名為工具相關的 API 以保持一致性
- 在 Anthropic API 請求中添加了對自定義 HTTP header 的支援
- 改進了 options，支援 equals、hashCode 和深度複製
Mistral AI 增強
- 添加了 moderation 模型支援，用於檢測潛在的有害內容
- 實現了帶有 JSON schema 能力的自定義結構化輸出
- 增強了安全功能和內容過濾
Ollama 改進
- 添加了 min_p 引數以改進取樣控制
- 添加了對 qwq 模型的支援
- 添加了對 LLAMA3_2_3B 模型的支援
Azure OpenAI 更新
- 增強了 AzureOpenAiChatOptions
- 修復了自動配置的 opt-in 行為
- 改進了與 Azure 服務的整合
OpenAI 增強
- 在 OpenAI Audio Speech API 中將 voice 引數更改為 string 型別
- 為 OpenAI Audio API 添加了缺失的音訊格式
- 增強了 OpenAiChatOptions，新增了 equals、hashCode 和深度複製功能

Docker Model Runner 支援

Spring AI 1.0.0-M7 添加了對 Docker Desktop 4.40 的 Model Runner 的支援，提供了與本地執行的 AI 模型的無縫整合

OpenAI 相容 API：Docker Model Runner 提供了一個設計上與 OpenAI API 相容的本地推理 API，方便與 Spring AI 整合
標準 OCI Artifacts：模型以標準 OCI artifact 的形式分發，位於 Docker Hub 的 ai 名稱空間下
多種配置選項:
- 直接 TCP 連線到 Model Runner
- 透過 Testcontainers 進行開發和測試整合

簡單配置：只需使用自定義基本 URL 配置 OpenAI 客戶端即可

spring.ai.openai.api-key=ignored
spring.ai.openai.base-url=https://:12434/engines
spring.ai.openai.chat.options.model=ai/gemma3

完整功能支援：所有 Spring AI 功能（包括函式呼叫、流式處理等）均可與 Docker Model Runner 協同工作
本地模型執行：無需將資料傳送到外部服務，即可在 Apple Silicon 上本地執行模型

有關詳細資訊，請檢視 Spring AI Docker Model Runner 文件以及我們配套的部落格文章 Spring AI with Docker Model Runner，其中深入探討了這一整合。

特別感謝 Eddú Meléndez 為此功能做出的重要貢獻。

工具和多模態能力

工具執行框架
- 引入了 ToolExecutionEligibilityPredicate 介面
- 改進了 MCP server 中按名稱進行的工具去重
- 增強了 MCP 工具回撥中的錯誤處理
- 標準化了 MCP 工具名稱格式
多模態支援
- 支援工具呼叫結果中的 base64 編碼影像
- 處理 JSON 響應中的 base64 編碼影像
- 增強了影像轉換能力
- 支援工具響應中的自定義 MIME 型別
文件處理
- 添加了 JSoup HTML 文件讀取器用於解析網頁內容
- 增強了文件格式化能力
- 為 ContextualQueryAugmenter 添加了 documentFormatter 引數

記憶體和儲存

聊天記憶體實現
- 添加了 JDBC 實現的 ChatMemory
- 將 Cassandra 聊天記憶體實現遷移到其自己的模組中
- 添加了 Neo4j 聊天記憶體實現
向量儲存增強
- 添加了 Couchbase 向量儲存支援
- 移除了 CosmosDBVectorStore 中對 partition key path 的斷言
- 透過 native expressions 增強了 Milvus 向量儲存
- 為 Milvus 中的資料庫集合添加了配置選項
- 對單個向量儲存實現進行條件啟用
- 使用基於 PgIdType 的 schema 生成增強了 PgVectorStore

查詢處理

檢索增強
- 在 RetrievalAugmentationAdvisor 中為 Query 添加了上下文支援
- 移除了所有 QueryTransformer 實現上的預設 temperature
- 增強了上下文處理以提高相關性

開發者體驗

Spring Boot 整合
- 更新了支援的 Spring Boot 版本
- 改進了自動配置模式
- 為 MCP 自動配置添加了 boot configuration processor
AOT 和 Native Image 支援
- 改進了 ahead-of-time 編譯支援
- 增強了 native image 相容性的執行時提示
- 全面掃描 JsonInclude 註解
文件
- 添加了遷移到 M7 的升級說明
- 改進了帶有架構圖的模組文件
- 增強了新功能的 API 文件

貢獻者

還有許多其他 refactoring、bug fixing、文件增強，由廣泛的貢獻者完成。如果您的 PR 還沒有被處理，請耐心等待，我們會處理的。感謝以下貢獻者：

Spring 部落格