Spring 部落格

所有文章
工程
釋出
新聞和活動

Spring AI 1.0.0 M8 釋出

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

在審查了我們自 M7 以來進行的 API 設計和棄用後，我們確定一些重大更改將在 RC1 版本中成為破壞性更改。因此，我們引入了這個額外的里程碑版本，為開發者提供一個過渡版本，其中已棄用的 API 與其替代項共存，從而在 RC1 之前實現更順暢的升級體驗。

以下是此版本中的主要更改。

  • 升級說明
  • 您可以使用 OpenRewrite Recipe 自動化升級到 1.0.0-M8 的過程。此 Recipe 有助於應用此版本的許多必要程式碼更改。可在 Arconia Spring AI Migrations 查詢該 Recipe 和使用說明。

破壞性更改

從 Spring AI 1.0 M7 升級到 1.0 M8 時，之前註冊了工具回撥的使用者會遇到破壞性更改，導致工具呼叫功能靜默失敗。這特別影響了使用已棄用的 tools() 方法的程式碼。

示例

以下是在 M7 中可以工作但在 M8 中不再按預期工作的程式碼示例

// Old code in M7 - no longer works correctly in M8
chatClient.prompt("What day is tomorrow?")
    .tools(toolCallback)
    .call()
    .content();

如何調整你的程式碼

要在升級到 M8 時解決此問題，你需要更新程式碼以使用新的 toolCallbacks() 方法

// Updated code for M8
chatClient.prompt("What day is tomorrow?")
    .toolCallbacks(toolCallback)
    .call()
    .content();

為何進行此更改

Spring AI 團隊重新命名了過載的 tools() 方法，以提高畫質晰度並防止方法分派中的歧義。以前的 API 設計導致 Java 編譯器在根據引數型別從多個過載方法中進行選擇時產生混淆。

M7 到 M8 的方法對映

以下是舊方法如何對映到新方法：

  1. tools(String... toolNames) → toolNames(String... toolNames)

    • 用於引用在其他地方註冊的工具（例如，透過帶有 @Description 的 @Bean）

  2. tools(ToolCallback... toolCallbacks) → toolCallbacks(ToolCallback... toolCallbacks)

    • 用於內聯工具回撥註冊

  3. tools(List<ToolCallback> toolCallbacks) → toolCallbacks(List<ToolCallback> toolCallbacks)

    • 當您擁有工具回撥集合時使用

  4. tools(ToolCallbackProvider... toolCallbackProviders) → toolCallbacks(ToolCallbackProvider... toolCallbackProviders)

    • 用於實現 ToolCallbackProvider 介面的物件

  5. tools(Object... toolObjects) 保持不變

    • 僅用於其方法帶有 @Tool 註解的物件

改進的錯誤處理

在 最新的 PR (spring-projects/spring-ai#2964) 中，當提供的物件上沒有找到 @Tool 方法時，tools(Object... toolObjects) 方法現在會丟擲異常，而不是靜默失敗。這有助於開發者立即識別遷移問題。

遷移總結

如果你正在從 M7 升級到 M8

  1. 將所有對 .tools(toolCallback) 的呼叫替換為 .toolCallbacks(toolCallback)
  2. 將所有對 .tools(toolCallbackProvider) 的呼叫替換為 .toolCallbacks(toolCallbackProvider)
  3. 將所有對 .tools("toolName") 的呼叫替換為 .toolNames("toolName")

這些更改將確保你在升級到 Spring AI 1.0 M8 後，工具呼叫功能繼續正常工作。

新特性

  1. 聊天記憶增強
  • 增強的聊天記憶架構
    • 改進的 ChatMemory API，用於更靈活的對話歷史管理
    • 新的 ChatMemoryRepository 介面支援不同的儲存策略
    • 增加了 MessageWindowChatMemory 用於維護訊息視窗
    • 改進屬性命名，以實現不同實現之間的一致性
    • 支援多種儲存後端
      • InMemoryChatMemoryRepository（預設）
      • 用於關係型資料庫的 JdbcChatMemoryRepository
    • 有關聊天記憶配置的更多詳細資訊，請參閱 記憶型別 和 記憶儲存。
  1. 模板渲染*
  • 引入 TemplateRenderer 用於提示詞模板化
    • 一個新的靈活的模板渲染 API，為不同的模板引擎提供了統一的介面
    • 包含新的 StTemplateRenderer，支援內建函式和自定義驗證選項。請在此處檢視如何使用它：here。
    • 直接整合到 ChatClient 中，實現精簡的提示詞模板化
    • 添加了 NoOpTemplateRenderer，用於不需要模板化的場景
    • 相關："在 ChatClient 中配置 TemplateRenderer"，"更新文件以提及 NoOpTemplateRenderer"
  1. MCP 改進
  • 增強的 MCP 工具回撥配置
    • 將工具回撥配置新增到 MCP 客戶端屬性
    • MCP 伺服器支援完成規範
    • 增加了 MCP 伺服器的指令支援
    • 向 WebFlux 和 WebMvc 傳輸提供者添加了 SSE 端點引數
  1. 提示詞工程模式
  • 新增提示詞工程模式文件
    • 關於高階提示詞工程技術的新綜合文件
    • 為開發者提供了有效提示詞設計的最佳實踐
    • 包括各種用例的示例和模式
  1. 向量儲存增強
  • Cosmos DB Entra ID 支援和修復
    • 為 Cosmos DB 添加了 Azure Entra ID（原 Azure AD）認證
    • 改進了 Azure 部署的安全和認證選項
  • Cassandra 向量儲存改進
    • 修復了 Cassandra 聊天記憶中的訊息順序問題
    • 添加了更清晰的錯誤訊息並修復了各種問題

棄用

需要注意的重要棄用如下：

  1. 聊天客戶端增強:

    • ChatClient 已更新，確保在顧問執行之前始終渲染使用者和系統提示詞。此更改將 AdvisedRequest 和 AdvisedResponse API 替換為 ChatClientRequest 和 ChatClientResponse。

  2. 提示詞模板化和顧問:

    • 與提示詞建立和顧問定製相關的類和方法已被棄用，取而代之的是 Builder 模式和 TemplateRenderer 介面。

  3. QuestionAnswerAdvisor 棄用:

    • 棄用了依賴於簡單 userTextAdvise 字串的建構函式和 Builder 方法。

  4. 聊天記憶配置:

    • spring.ai.chat.memory.jdbc.initialize-schema 屬性已被棄用，取而代之的是 spring.ai.chat.memory.repository.jdbc.initialize-schema。

  5. 文件處理:

    • DocumentPostProcessor API 替換了諸如 DocumentCompressor、DocumentRanker 和 DocumentSelector 等已棄用的 API。

  6. 聊天記憶棄用:

    • @Deprecated List<Message> get(String conversationId, int lastN); 在 ChatMemory 中已棄用。

貢獻者

各領域的廣泛貢獻者還進行了其他重構、錯誤修復和文件增強。如果你的 PR 我們尚未處理，我們會的，請耐心等待。感謝以下貢獻者：

訂閱 Spring 新聞郵件

透過 Spring 新聞郵件保持聯絡

訂閱

取得領先

VMware 提供培訓和認證，助力你加速進步。

瞭解更多

獲得支援

Tanzu Spring 透過一份簡單的訂閱提供 OpenJDK™、Spring 和 Apache Tomcat® 的支援和二進位制檔案。

瞭解更多

即將到來的活動

檢視 Spring 社群所有即將到來的活動。

檢視全部