升級說明

升級到 1.1.0-RC1

破壞性變更

文字轉語音 (TTS) API 遷移

OpenAI 文字轉語音實現已從特定於提供商的類遷移到共享介面。這使得編寫可在多個 TTS 提供商（OpenAI、ElevenLabs 和未來的提供商）之間工作的可移植程式碼成為可能。

已移除的類

以下已棄用的類已從 org.springframework.ai.openai.audio.speech 包中移除

SpeechModel → 使用 TextToSpeechModel (來自 org.springframework.ai.audio.tts)
StreamingSpeechModel → 使用 StreamingTextToSpeechModel (來自 org.springframework.ai.audio.tts)
SpeechPrompt → 使用 TextToSpeechPrompt (來自 org.springframework.ai.audio.tts)
SpeechResponse → 使用 TextToSpeechResponse (來自 org.springframework.ai.audio.tts)
SpeechMessage → 使用 TextToSpeechMessage (來自 org.springframework.ai.audio.tts)
Speech (在 org.springframework.ai.openai.audio.speech 中) → 使用 Speech (來自 org.springframework.ai.audio.tts)

此外，為了與其他 TTS 提供商保持一致，所有 OpenAI TTS 元件中的 speed 引數型別已從 Float 更改為 Double。

遷移步驟

更新匯入：將所有來自 org.springframework.ai.openai.audio.speech. 的匯入替換為 org.springframework.ai.audio.tts.

更新型別引用：將舊類名的所有出現替換為新類名

Find:    SpeechModel
Replace: TextToSpeechModel

Find:    StreamingSpeechModel
Replace: StreamingTextToSpeechModel

Find:    SpeechPrompt
Replace: TextToSpeechPrompt

Find:    SpeechResponse
Replace: TextToSpeechResponse

Find:    SpeechMessage
Replace: TextToSpeechMessage

更新速度引數：從 Float 更改為 Double

Find:    .speed(1.0f)
Replace: .speed(1.0)

Find:    Float speed
Replace: Double speed

更新依賴注入：如果您注入 SpeechModel，請更新為 TextToSpeechModel

// Before
public MyService(SpeechModel speechModel) { ... }

// After
public MyService(TextToSpeechModel textToSpeechModel) { ... }

好處

可移植性：一次編寫程式碼，輕鬆在 OpenAI、ElevenLabs 或其他 TTS 提供商之間切換
一致性：與 ChatModel 和其他 Spring AI 抽象的模式相同
型別安全：透過適當的介面實現改進了型別層次結構
面向未來：新的 TTS 提供商將自動與您現有的程式碼一起工作

其他資源

有關包含詳細程式碼示例的全面遷移指南，請參閱

升級到 1.0.0-SNAPSHOT

概述

1.0.0-SNAPSHOT 版本包括對 artifact ID、包名和模組結構的重大更改。本節提供使用 SNAPSHOT 版本的具體指導。

新增 Snapshot 倉庫

要使用 1.0.0-SNAPSHOT 版本，您需要將 snapshot 倉庫新增到構建檔案中。有關詳細說明，請參閱入門指南中的 Snapshots - Add Snapshot Repositories 部分。

更新依賴管理

在您的構建配置中將 Spring AI BOM 版本更新為 1.0.0-SNAPSHOT。有關配置依賴管理的詳細說明，請參閱入門指南中的 Dependency Management 部分。

Artifact ID、包和模組更改

1.0.0-SNAPSHOT 包括對 artifact ID、包名和模組結構的更改。

有關詳細資訊，請參閱： - 通用 Artifact ID 更改 - 通用包更改 - 通用模組結構

升級到 1.0.0-RC1

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

重大更改

聊天客戶端和顧問

影響終端使用者程式碼的主要更改是

在 VectorStoreChatMemoryAdvisor 中
- 常量 CHAT_MEMORY_RETRIEVE_SIZE_KEY 已重新命名為 TOP_K。
- 常量 DEFAULT_CHAT_MEMORY_RESPONSE_SIZE (值: 100) 已重新命名為 DEFAULT_TOP_K，新預設值為 20。
常量 CHAT_MEMORY_CONVERSATION_ID_KEY 已重新命名為 CONVERSATION_ID 並從 AbstractChatMemoryAdvisor 移動到 ChatMemory 介面。更新您的匯入以使用 org.springframework.ai.chat.memory.ChatMemory.CONVERSATION_ID。

顧問中的自包含模板

執行提示增強的內建顧問已更新為使用自包含模板。目標是使每個顧問都能夠執行模板操作，而不影響也不受其他顧問中模板和提示決策的影響。

如果您為以下顧問提供自定義模板，則需要更新它們以確保包含所有預期的佔位符。

QuestionAnswerAdvisor 需要一個包含以下佔位符的模板（參見更多詳細資訊）
- 一個 query 佔位符，用於接收使用者問題。
- 一個 question_answer_context 佔位符用於接收檢索到的上下文。
PromptChatMemoryAdvisor 需要一個包含以下佔位符的模板（參見更多詳細資訊）
- 一個 instructions 佔位符用於接收原始系統訊息。
- 一個 memory 佔位符用於接收檢索到的對話記憶體。
VectorStoreChatMemoryAdvisor 需要一個包含以下佔位符的模板（參見更多詳細資訊）
- 一個 instructions 佔位符用於接收原始系統訊息。
- 一個 long_term_memory 佔位符用於接收檢索到的對話記憶體。

可觀察性

重構了內容觀察以使用日誌而不是跟蹤（ca843e8）
- 將內容觀察過濾器替換為日誌處理程式
- 重新命名配置屬性以更好地反映其目的
  - include-prompt → log-prompt
  - include-completion → log-completion
  - include-query-response → log-query-response
- 添加了 TracingAwareLoggingObservationHandler 用於跟蹤感知日誌
- 將 micrometer-tracing-bridge-otel 替換為 micrometer-tracing
- 刪除了基於事件的跟蹤，轉而採用直接日誌記錄
- 刪除了對 OTel SDK 的直接依賴
- 在觀察屬性中將 includePrompt 重新命名為 logPrompt（在 ChatClientBuilderProperties、ChatObservationProperties 和 ImageObservationProperties 中）

聊天記憶體倉庫模組和自動配置重新命名

我們透過在整個程式碼庫中新增倉庫字尾來標準化聊天記憶體元件的命名模式。此更改影響 Cassandra、JDBC 和 Neo4j 實現，影響 artifact ID、Java 包名和類名以提高畫質晰度。

Artifact ID

所有與記憶體相關的 artifact 現在都遵循一致的模式

spring-ai-model-chat-memory- → spring-ai-model-chat-memory-repository-
spring-ai-autoconfigure-model-chat-memory- → spring-ai-autoconfigure-model-chat-memory-repository-
spring-ai-starter-model-chat-memory- → spring-ai-starter-model-chat-memory-repository-

Java 包

包路徑現在包含 .repository. 段
示例：org.springframework.ai.chat.memory.jdbc → org.springframework.ai.chat.memory.repository.jdbc

配置類

主要自動配置類現在使用 Repository 字尾
示例：JdbcChatMemoryAutoConfiguration → JdbcChatMemoryRepositoryAutoConfiguration

屬性

配置屬性從 spring.ai.chat.memory.<storage>… 重新命名為 spring.ai.chat.memory.repository.<storage>…

需要遷移： - 更新您的 Maven/Gradle 依賴項以使用新的 artifact ID。 - 更新所有使用舊包或類名的匯入、類引用或配置。

訊息聚合器重構

更改

MessageAggregator 類已從 spring-ai-client-chat 模組中的 org.springframework.ai.chat.model 包移動到 spring-ai-model 模組（相同的包名）
aggregateChatClientResponse 方法已從 MessageAggregator 中移除，並移動到 org.springframework.ai.chat.client 包中的新類 ChatClientMessageAggregator

遷移指南

如果您直接使用 MessageAggregator 的 aggregateChatClientResponse 方法，則需要改用新的 ChatClientMessageAggregator 類

// Before
new MessageAggregator().aggregateChatClientResponse(chatClientResponses, aggregationHandler);

// After
new ChatClientMessageAggregator().aggregateChatClientResponse(chatClientResponses, aggregationHandler);

不要忘記新增適當的匯入

import org.springframework.ai.chat.client.ChatClientMessageAggregator;

Watson

Watson AI 模型被移除，因為它基於較舊的文字生成，這被認為是過時的，因為有新的聊天生成模型可用。希望 Watson 會在 Spring AI 的未來版本中重新出現

MoonShot 和 QianFan

Moonshot 和 Qianfan 已被移除，因為它們無法在中國境外訪問。這些已移至 Spring AI 社群倉庫。

已移除的向量儲存

移除 HanaDB 向量儲存自動配置 (f3b4624)

記憶體管理

移除 CassandraChatMemory 實現 (11e3c8f)
簡化了聊天記憶體顧問層次結構並移除了已棄用的 API (848a3fd)
移除了 JdbcChatMemory 中的棄用 (356a68f)
重構了聊天記憶體倉庫 artifact 以提高畫質晰度 (2d517ee)
重構了聊天記憶體倉庫自動配置和 Spring Boot 啟動器以提高畫質晰度 (f6dba1b)

訊息和模板 API

移除了已棄用的 UserMessage 建構函式 (06edee4)
移除了已棄用的 PromptTemplate 建構函式 (722c77e)
移除了 Media 中的已棄用方法 (228ef10)
重構了 StTemplateRenderer：將 supportStFunctions 重新命名為 validateStFunctions (0e15197)
移除了移動後剩餘的 TemplateRender 介面 (52675d8)

額外的客戶端 API 更改

移除了 ChatClient 和 Advisors 中的棄用 (4fe74d8)
移除了 OllamaApi 和 AnthropicApi 中的棄用 (46be898)

包結構更改

移除了 spring-ai-model 中的包間依賴迴圈 (ebfa5b9)
將 MessageAggregator 移動到 spring-ai-model 模組 (54e5c07)

依賴關係

移除了 spring-ai-openai 中未使用的 json-path 依賴項 (9de13d1)

行為更改

Azure OpenAI

為 Azure OpenAI 添加了 Entra ID 身份管理，並進行了乾淨的自動配置 (3dc86d3)

一般清理

移除了所有程式碼棄用 (76bee8c) 和 (b6ce7f3)

升級到 1.0.0-M8

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

重大更改

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

示例

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

// This worked in M7 but silently fails in M8
ChatClient chatClient = new OpenAiChatClient(api)
    .tools(List.of(
        new Tool("get_current_weather", "Get the current weather in a given location",
            new ToolSpecification.ToolParameter("location", "The city and state, e.g. San Francisco, CA", true))
    ))
    .toolCallbacks(List.of(
        new ToolCallback("get_current_weather", (toolName, params) -> {
            // Weather retrieval logic
            return Map.of("temperature", 72, "unit", "fahrenheit", "description", "Sunny");
        })
    ));

解決方案

解決方案是使用 toolSpecifications() 方法而不是已棄用的 tools() 方法

// This works in M8
ChatClient chatClient = new OpenAiChatClient(api)
    .toolSpecifications(List.of(
        new Tool("get_current_weather", "Get the current weather in a given location",
            new ToolSpecification.ToolParameter("location", "The city and state, e.g. San Francisco, CA", true))
    ))
    .toolCallbacks(List.of(
        new ToolCallback("get_current_weather", (toolName, params) -> {
            // Weather retrieval logic
            return Map.of("temperature", 72, "unit", "fahrenheit", "description", "Sunny");
        })
    ));

已移除的實現和 API

記憶體管理

移除 CassandraChatMemory 實現 (11e3c8f)
簡化了聊天記憶體顧問層次結構並移除了已棄用的 API (848a3fd)
移除了 JdbcChatMemory 中的棄用 (356a68f)
重構了聊天記憶體倉庫 artifact 以提高畫質晰度 (2d517ee)
重構了聊天記憶體倉庫自動配置和 Spring Boot 啟動器以提高畫質晰度 (f6dba1b)

客戶端 API

移除了 ChatClient 和 Advisors 中的棄用 (4fe74d8)
對聊天客戶端工具呼叫的重大更改 (5b7849d)
移除了 OllamaApi 和 AnthropicApi 中的棄用 (46be898)

訊息和模板 API

移除了已棄用的 UserMessage 建構函式 (06edee4)
移除了已棄用的 PromptTemplate 建構函式 (722c77e)
移除了 Media 中的已棄用方法 (228ef10)
重構了 StTemplateRenderer：將 supportStFunctions 重新命名為 validateStFunctions (0e15197)
移除了移動後剩餘的 TemplateRender 介面 (52675d8)

模型實現

移除 Watson 文字生成模型 (9e71b16)
移除 Qianfan 程式碼 (bfcaad7)
移除 HanaDB 向量儲存自動配置 (f3b4624)
從 OpenAiApi 中移除 Deepseek 選項 (59b36d1)

包結構更改

移除了 spring-ai-model 中的包間依賴迴圈 (ebfa5b9)
將 MessageAggregator 移動到 spring-ai-model 模組 (54e5c07)

依賴關係

移除了 spring-ai-openai 中未使用的 json-path 依賴項 (9de13d1)

行為更改

可觀察性

重構了內容觀察以使用日誌而不是跟蹤（ca843e8）
- 將內容觀察過濾器替換為日誌處理程式
- 重新命名配置屬性以更好地反映其目的
  - include-prompt → log-prompt
  - include-completion → log-completion
  - include-query-response → log-query-response
- 添加了 TracingAwareLoggingObservationHandler 用於跟蹤感知日誌
- 將 micrometer-tracing-bridge-otel 替換為 micrometer-tracing
- 刪除了基於事件的跟蹤，轉而採用直接日誌記錄
- 刪除了對 OTel SDK 的直接依賴
- 在觀察屬性中將 includePrompt 重新命名為 logPrompt（在 ChatClientBuilderProperties、ChatObservationProperties 和 ImageObservationProperties 中）

Azure OpenAI

為 Azure OpenAI 添加了 Entra ID 身份管理，並進行了乾淨的自動配置 (3dc86d3)

一般清理

移除了 1.0.0-M8 的所有棄用 (76bee8c)
一般棄用清理 (b6ce7f3)

升級到 1.0.0-M7

變更概述

Spring AI 1.0.0-M7 是 RC1 和 GA 版本之前的最後一個里程碑版本。它引入了對 artifact ID、包名和模組結構的幾項重要更改，這些更改將在最終版本中保留。

Artifact ID、包和模組更改

1.0.0-M7 包含與 1.0.0-SNAPSHOT 相同的結構更改。

有關詳細資訊，請參閱： - 通用 Artifact ID 更改 - 通用包更改 - 通用模組結構

MCP Java SDK 升級到 0.9.0

Spring AI 1.0.0-M7 現在使用 MCP Java SDK 0.9.0 版本，該版本包含與以前版本不同的重大更改。如果您在應用程式中使用 MCP，則需要更新程式碼以適應這些更改。

主要變化包括

介面重新命名

ClientMcpTransport → McpClientTransport
ServerMcpTransport → McpServerTransport
DefaultMcpSession → McpClientSession 或 McpServerSession
所有 *Registration 類 → *Specification 類

伺服器建立更改

使用 McpServerTransportProvider 而不是 ServerMcpTransport

// Before
ServerMcpTransport transport = new WebFluxSseServerTransport(objectMapper, "/mcp/message");
var server = McpServer.sync(transport)
    .serverInfo("my-server", "1.0.0")
    .build();

// After
McpServerTransportProvider transportProvider = new WebFluxSseServerTransportProvider(objectMapper, "/mcp/message");
var server = McpServer.sync(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .build();

處理程式簽名更改

所有處理程式現在都將 exchange 引數作為第一個引數接收

// Before
.tool(calculatorTool, args -> new CallToolResult("Result: " + calculate(args)))

// After
.tool(calculatorTool, (exchange, args) -> new CallToolResult("Result: " + calculate(args)))

透過 Exchange 進行客戶端互動

以前在伺服器上可用的方法現在透過 exchange 物件訪問

// Before
ClientCapabilities capabilities = server.getClientCapabilities();
CreateMessageResult result = server.createMessage(new CreateMessageRequest(...));

// After
ClientCapabilities capabilities = exchange.getClientCapabilities();
CreateMessageResult result = exchange.createMessage(new CreateMessageRequest(...));

根更改處理程式

// Before
.rootsChangeConsumers(List.of(
    roots -> System.out.println("Roots changed: " + roots)
))

// After
.rootsChangeHandlers(List.of(
    (exchange, roots) -> System.out.println("Roots changed: " + roots)
))

有關遷移 MCP 程式碼的完整指南，請參閱 MCP 遷移指南。

啟用/停用模型自動配置

以前用於啟用/停用模型自動配置的配置屬性已移除

spring.ai.<provider>.chat.enabled
spring.ai.<provider>.embedding.enabled
spring.ai.<provider>.image.enabled
spring.ai.<provider>.moderation.enabled

預設情況下，如果在類路徑中找到模型提供商（例如，OpenAI、Ollama），則其相應模型型別（聊天、嵌入等）的自動配置將啟用。如果存在同一模型型別的多個提供商（例如，spring-ai-openai-spring-boot-starter 和 spring-ai-ollama-spring-boot-starter），您可以使用以下屬性來選擇哪個提供商的自動配置應處於活動狀態，從而有效地停用其他提供商的該特定模型型別。

要完全停用特定模型型別的自動配置，即使只有一個提供商存在，也請將相應屬性設定為與類路徑上任何提供商都不匹配的值（例如，none 或 disabled）。

您可以參考 SpringAIModels 列舉以獲取已知提供商值的列表。

spring.ai.model.audio.speech=<model-provider|none>
spring.ai.model.audio.transcription=<model-provider|none>
spring.ai.model.chat=<model-provider|none>
spring.ai.model.embedding=<model-provider|none>
spring.ai.model.embedding.multimodal=<model-provider|none>
spring.ai.model.embedding.text=<model-provider|none>
spring.ai.model.image=<model-provider|none>
spring.ai.model.moderation=<model-provider|none>

使用 AI 自動化升級

您可以使用 Claude Code CLI 工具和提供的提示自動化升級到 1.0.0-M7 的過程

下載 Claude Code CLI 工具
從 update-to-m7.txt 檔案複製提示
將提示貼上到 Claude Code CLI 中
AI 將分析您的專案並進行必要的更改

自動化升級提示目前處理 artifact ID 更改、包重定位和模組結構更改，但尚不包括升級到 MCP 0.9.0 的自動更改。如果您正在使用 MCP，則需要按照 MCP Java SDK 升級部分的指導手動更新程式碼。

跨版本的通用更改

Artifact ID 更改

Spring AI 啟動器 artifact 的命名模式已更改。您需要根據以下模式更新您的依賴項

模型啟動器：spring-ai-{model}-spring-boot-starter → spring-ai-starter-model-{model}
向量儲存啟動器：spring-ai-{store}-store-spring-boot-starter → spring-ai-starter-vector-store-{store}
MCP 啟動器：spring-ai-mcp-{type}-spring-boot-starter → spring-ai-starter-mcp-{type}

示例

Maven
Gradle

<!-- BEFORE -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>

<!-- AFTER -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

// BEFORE
implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter'
implementation 'org.springframework.ai:spring-ai-redis-store-spring-boot-starter'

// AFTER
implementation 'org.springframework.ai:spring-ai-starter-model-openai'
implementation 'org.springframework.ai:spring-ai-starter-vector-store-redis'

Spring AI 自動配置 Artifact 的更改

Spring AI 自動配置已從單個整體 artifact 更改為每個模型、向量儲存和其他元件的單獨自動配置 artifact。進行此更改是為了最大程度地減少不同版本的依賴庫衝突的影響，例如 Google Protocol Buffers、Google RPC 等。透過將自動配置分離到特定於元件的 artifact 中，您可以避免引入不必要的依賴項並降低應用程式中版本衝突的風險。

原始的整體 artifact 不再可用

<!-- NO LONGER AVAILABLE -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-spring-boot-autoconfigure</artifactId>
    <version>${project.version}</version>
</dependency>

相反，每個元件現在都有自己的自動配置 artifact，遵循以下模式

模型自動配置：spring-ai-autoconfigure-model-{model}
向量儲存自動配置：spring-ai-autoconfigure-vector-store-{store}
MCP 自動配置：spring-ai-autoconfigure-mcp-{type}

新自動配置 Artifact 的示例

模型
向量儲存
MCP

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-autoconfigure-model-openai</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-autoconfigure-model-anthropic</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-autoconfigure-model-vertex-ai</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-autoconfigure-vector-store-redis</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-autoconfigure-vector-store-pgvector</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-autoconfigure-vector-store-chroma</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-autoconfigure-mcp-client</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-autoconfigure-mcp-server</artifactId>
</dependency>

在大多數情況下，您不需要顯式新增這些自動配置依賴項。它們在使用相應的啟動器依賴項時會傳遞性地包含。

包名更改

您的 IDE 應該幫助重構到新的包位置。

KeywordMetadataEnricher 和 SummaryMetadataEnricher 已從 org.springframework.ai.transformer 移動到 org.springframework.ai.chat.transformer。
Content、MediaContent 和 Media 已從 org.springframework.ai.model 移動到 org.springframework.ai.content。

模組結構

專案對其模組和 artifact 結構進行了重大更改。以前，spring-ai-core 包含所有中心介面，但現在已將其拆分為專門的領域模組，以減少應用程式中不必要的依賴項。

spring-ai-commons

基本模組，不依賴於其他 Spring AI 模組。包含： - 核心領域模型（Document、TextSplitter） - JSON 工具和資源處理 - 結構化日誌記錄和可觀察性支援

spring-ai-model

提供 AI 功能抽象： - ChatModel、EmbeddingModel 和 ImageModel 等介面 - 訊息型別和提示模板 - 函式呼叫框架（ToolDefinition、ToolCallback） - 內容過濾和觀察支援

spring-ai-vector-store

統一向量資料庫抽象： - 用於相似性搜尋的 VectorStore 介面 - 具有 SQL 樣表示式的高階過濾 - 用於記憶體使用的 SimpleVectorStore - 嵌入的批次處理支援

spring-ai-client-chat

高階對話 AI API： - ChatClient 介面 - 透過 ChatMemory 進行對話持久化 - 使用 OutputConverter 進行響應轉換 - 基於顧問的攔截 - 同步和響應式流支援

spring-ai-advisors-vector-store

將聊天與向量儲存橋接以用於 RAG： - QuestionAnswerAdvisor：將上下文注入提示 - VectorStoreChatMemoryAdvisor：儲存/檢索對話歷史記錄

spring-ai-model-chat-memory-cassandra

Apache Cassandra 對 ChatMemory 的持久化： - CassandraChatMemory 實現 - 使用 Cassandra 的 QueryBuilder 進行型別安全的 CQL ==== spring-ai-model-chat-memory-neo4j

Neo4j 圖資料庫用於聊天對話的持久化。

spring-ai-rag

用於檢索增強生成 (Retrieval Augmented Generation) 的綜合框架： - RAG 管道的模組化架構 - RetrievalAugmentationAdvisor 作為主要入口點 - 具有可組合元件的函數語言程式設計原則

依賴結構

依賴層次結構可概括為

spring-ai-commons (基礎)
spring-ai-model (依賴於 commons)
spring-ai-vector-store 和 spring-ai-client-chat (都依賴於 model)
spring-ai-advisors-vector-store 和 spring-ai-rag (依賴於 client-chat 和 vector-store)
spring-ai-model-chat-memory-* 模組 (依賴於 client-chat)

ToolContext 更改

ToolContext 類已增強以支援顯式和隱式工具解析。工具現在可以

顯式包含：在提示中顯式請求幷包含在模型呼叫中的工具。
隱式可用：可用於執行時動態解析的工具，但除非顯式請求，否則永遠不會包含在任何模型呼叫中。

從 1.0.0-M7 開始，只有當工具在提示中顯式請求或在呼叫中顯式包含時，才會將其包含在對模型的呼叫中。

此外，ToolContext 類現在已被標記為 final，並且不能再被擴充套件。它從來不應該被子類化。您可以在例項化 ToolContext 時以 Map<String, Object> 的形式新增所有需要的上下文資料。有關更多資訊，請檢視 [文件](docs.spring.io/spring-ai/reference/api/tools.html#_tool_context)。

升級到 1.0.0-M6

Usage 介面和 DefaultUsage 實現的更改

Usage 介面及其預設實現 DefaultUsage 經歷了以下更改

方法重新命名
- getGenerationTokens() 現在是 getCompletionTokens()
型別更改
- DefaultUsage 中的所有令牌計數字段都從 Long 更改為 Integer
  - promptTokens
  - completionTokens (以前是 generationTokens)
  - totalTokens

所需操作

將所有對 getGenerationTokens() 的呼叫替換為 getCompletionTokens()
更新 DefaultUsage 建構函式呼叫

// Old (M5)
new DefaultUsage(Long promptTokens, Long generationTokens, Long totalTokens)

// New (M6)
new DefaultUsage(Integer promptTokens, Integer completionTokens, Integer totalTokens)

有關處理 Usage 的更多資訊，請參閱此處

JSON 序列化/反序列化更改

雖然 M6 保持了 generationTokens 欄位的 JSON 反序列化向後相容性，但該欄位將在 M7 中移除。任何使用舊欄位名的持久化 JSON 文件都應更新為使用 completionTokens。

新 JSON 格式的示例

{
  "promptTokens": 100,
  "completionTokens": 50,
  "totalTokens": 150
}

FunctionCallingOptions 用於工具呼叫的用法更改

每個 ChatModel 例項在構造時接受一個可選的 ChatOptions 或 FunctionCallingOptions 例項，可用於配置用於呼叫模型的預設工具。

在 1.0.0-M6 之前

透過預設 FunctionCallingOptions 例項的 functions() 方法傳遞的任何工具都包含在該 ChatModel 例項對模型的每次呼叫中，可能會被執行時選項覆蓋。
透過預設 FunctionCallingOptions 例項的 functionCallbacks() 方法傳遞的任何工具僅用於執行時動態解析（參見工具解析），但除非明確請求，否則不會包含在任何模型呼叫中。

從 1.0.0-M6 開始

透過預設 FunctionCallingOptions 例項的 functions() 方法或 functionCallbacks() 傳遞的任何工具現在都以相同的方式處理：它們包含在該 ChatModel 例項對模型的每次呼叫中，可能會被執行時選項覆蓋。這樣，工具包含在對模型的呼叫中的方式就保持了一致性，並防止了由於 functionCallbacks() 與所有其他選項之間的行為差異而造成的混淆。

如果您想讓一個工具可用於執行時動態解析，並且僅在明確請求時才將其包含在對模型的聊天請求中，您可以使用工具解析中描述的策略之一。

1.0.0-M6 引入了處理工具呼叫的新 API。除了上述情況外，舊 API 在所有場景中都保持向後相容性。舊 API 仍然可用，但它們已被棄用，並將在 1.0.0-M7 中移除。

移除已棄用的 Amazon Bedrock 聊天模型

從 1.0.0-M6 開始，Spring AI 轉換為使用 Amazon Bedrock 的 Converse API 進行 Spring AI 中的所有聊天對話實現。所有 Amazon Bedrock 聊天模型都已移除，除了 Cohere 和 Titan 的嵌入模型。

有關使用聊天模型的資訊，請參閱 Bedrock Converse 文件。

更改為使用 Spring Boot 3.4.2 進行依賴管理

Spring AI 更新為使用 Spring Boot 3.4.2 進行依賴管理。您可以參考此處獲取 Spring Boot 3.4.2 管理的依賴項。

所需操作

如果您要升級到 Spring Boot 3.4.2，請務必參考此文件，瞭解配置 REST 客戶端所需的更改。值得注意的是，如果類路徑上沒有 HTTP 客戶端庫，這可能會導致使用 JdkClientHttpRequestFactory，而以前會使用 SimpleClientHttpRequestFactory。要切換到使用 SimpleClientHttpRequestFactory，您需要設定 spring.http.client.factory=simple。
如果您使用的是不同版本的 Spring Boot（例如 Spring Boot 3.3.x）並且需要特定版本的依賴項，您可以在構建配置中覆蓋它。

向量儲存 API 更改

在 1.0.0-M6 版本中，VectorStore 介面中的 delete 方法已被修改為 void 操作，而不是返回 Optional<Boolean>。如果您的程式碼以前檢查了刪除操作的返回值，則需要移除此檢查。現在，如果刪除失敗，該操作將丟擲異常，從而提供更直接的錯誤處理。

1.0.0-M6 之前

Optional<Boolean> result = vectorStore.delete(ids);
if (result.isPresent() && result.get()) {
    // handle successful deletion
}

1.0.0-M6 及之後

vectorStore.delete(ids);
// deletion successful if no exception is thrown

升級到 1.0.0.M5

Vector Builders 已重構以保持一致性。
當前 VectorStore 實現建構函式已被棄用，請使用構建器模式。
VectorStore 實現包已移動到唯一的包名，避免了跨 artifact 的衝突。例如 org.springframework.ai.vectorstore 到 org.springframework.ai.pgvector.vectorstore。

升級到 1.0.0.RC3

可移植聊天選項（frequencyPenalty、presencePenalty、temperature、topP）的型別已從 Float 更改為 Double。

升級到 1.0.0.M2

Chroma 向量儲存的配置字首已從 spring.ai.vectorstore.chroma.store 更改為 spring.ai.vectorstore.chroma，以與其他向量儲存的命名約定保持一致。
能夠初始化模式的向量儲存上的 initialize-schema 屬性的預設值現在設定為 false。這意味著應用程式現在需要顯式選擇在支援的向量儲存上進行模式初始化，如果期望在應用程式啟動時建立模式。並非所有向量儲存都支援此屬性。有關更多詳細資訊，請參閱相應的向量儲存文件。以下是目前不支援 initialize-schema 屬性的向量儲存。
1. Hana
2. Pinecone
3. Weaviate
在 Bedrock Jurassic 2 中，聊天選項 countPenalty、frequencyPenalty 和 presencePenalty 已重新命名為 countPenaltyOptions、frequencyPenaltyOptions 和 presencePenaltyOptions。此外，聊天選項 stopSequences 的型別已從 String[] 更改為 List<String>。
在 Azure OpenAI 中，聊天選項 frequencyPenalty 和 presencePenalty 的型別已從 Double 更改為 Float，與其他所有實現保持一致。

升級到 1.0.0.M1

在釋出 1.0.0 M1 的征程中，我們做了一些重大更改。抱歉，但這是為了更好！

ChatClient 更改

進行了一項重大更改，將“舊”的 ChatClient 功能移動到 ChatModel 中。現在“新”的 ChatClient 接受一個 ChatModel 例項。這樣做是為了支援一種流式 API，用於以類似於 Spring 生態系統中其他客戶端類（如 RestClient、WebClient 和 JdbcClient）的方式建立和執行提示。有關流式 API 的更多資訊，請參閱 [JavaDoc](docs.spring.io/spring-ai/docs/api)，適當的參考文件即將推出。

我們將“舊”的 ModelClient 重新命名為 Model，並重命名了實現類，例如 ImageClient 重新命名為 ImageModel。Model 實現表示在 Spring AI API 和底層 AI 模型 API 之間轉換的可移植性層。

一個新的 model 包，其中包含介面和基類，以支援為任何輸入/輸出資料型別組合建立 AI 模型客戶端。目前，聊天和影像模型包實現了這一點。我們很快就會將嵌入包更新為這個新模型。

一種新的“可移植選項”設計模式。我們希望在不同基於聊天的 AI 模型之間，ModelCall 中儘可能提供可移植性。有一組通用的生成選項，然後是特定於模型提供商的選項。使用了一種“鴨子型別”方法。模型包中的 ModelOptions 是一個標記介面，指示此類的實現將為模型提供選項。請參閱 ImageOptions，這是一個子介面，定義了所有文字→影像 ImageModel 實現的可移植選項。然後 StabilityAiImageOptions 和 OpenAiImageOptions 提供了特定於每個模型提供商的選項。所有選項類都是透過流式 API 構建器建立的，所有選項都可以傳遞到可移植的 ImageModel API 中。這些選項資料型別用於 ImageModel 實現的自動配置/配置屬性中。

Artifact 名稱更改

重新命名了 POM artifact 名稱： - spring-ai-qdrant → spring-ai-qdrant-store - spring-ai-cassandra → spring-ai-cassandra-store - spring-ai-pinecone → spring-ai-pinecone-store - spring-ai-redis → spring-ai-redis-store - spring-ai-qdrant → spring-ai-qdrant-store - spring-ai-gemfire → spring-ai-gemfire-store - spring-ai-azure-vector-store-spring-boot-starter → spring-ai-azure-store-spring-boot-starter - spring-ai-redis-spring-boot-starter → spring-ai-starter-vector-store-redis

升級到 0.8.1

以前的 spring-ai-vertex-ai 已重新命名為 spring-ai-vertex-ai-palm2，spring-ai-vertex-ai-spring-boot-starter 已重新命名為 spring-ai-vertex-ai-palm2-spring-boot-starter。

因此，您需要更改依賴項，從

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vertex-ai</artifactId>
</dependency>

到

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vertex-ai-palm2</artifactId>
</dependency>

Palm2 模型的相關 Boot 啟動器已從

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vertex-ai-spring-boot-starter</artifactId>
</dependency>

到

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vertex-ai-palm2-spring-boot-starter</artifactId>
</dependency>

重新命名的類（2024 年 1 月 3 日）
- VertexAiApi → VertexAiPalm2Api
- VertexAiClientChat → VertexAiPalm2ChatClient
- VertexAiEmbeddingClient → VertexAiPalm2EmbeddingClient
- VertexAiChatOptions → VertexAiPalm2ChatOptions

升級到 0.8.0

2024 年 1 月 24 日更新

將 prompt 和 messages 以及 metadata 包移動到 org.springframework.ai.chat 的子包
新功能是 文字到影像 客戶端。類是 OpenAiImageModel 和 StabilityAiImageModel。有關用法，請參閱整合測試，文件即將推出。
一個新的 model 包，其中包含介面和基類，以支援為任何輸入/輸出資料型別組合建立 AI 模型客戶端。目前，聊天和影像模型包實現了這一點。我們很快就會將嵌入包更新為這個新模型。
一種新的“可移植選項”設計模式。我們希望在不同基於聊天的 AI 模型之間，ModelCall 中儘可能提供可移植性。有一組通用的生成選項，然後是特定於模型提供商的選項。使用了一種“鴨子型別”方法。模型包中的 ModelOptions 是一個標記介面，指示此類的實現將為模型提供選項。請參閱 ImageOptions，這是一個子介面，定義了所有文字→影像 ImageModel 實現的可移植選項。然後 StabilityAiImageOptions 和 OpenAiImageOptions 提供了特定於每個模型提供商的選項。所有選項類都是透過流式 API 構建器建立的，所有選項都可以傳遞到可移植的 ImageModel API 中。這些選項資料型別用於 ImageModel 實現的自動配置/配置屬性中。

2024 年 1 月 13 日更新

以下 OpenAi 自動配置聊天屬性已更改

從 spring.ai.openai.model 到 spring.ai.openai.chat.options.model。
從 spring.ai.openai.temperature 到 spring.ai.openai.chat.options.temperature。

查詢有關 OpenAi 屬性的更新文件：docs.spring.io/spring-ai/reference/api/chat/openai-chat.html

2023 年 12 月 27 日更新

將 SimplePersistentVectorStore 和 InMemoryVectorStore 合併到 SimpleVectorStore * 將 InMemoryVectorStore 替換為 SimpleVectorStore

2023 年 12 月 20 日更新

重構 Ollama 客戶端及相關類和包名

將 org.springframework.ai.ollama.client.OllamaClient 替換為 org.springframework.ai.ollama.OllamaModelCall。
OllamaChatClient 方法簽名已更改。
將 org.springframework.ai.autoconfigure.ollama.OllamaProperties 重新命名為 org.springframework.ai.model.ollama.autoconfigure.OllamaChatProperties，並將字尾更改為：spring.ai.ollama.chat。一些屬性也已更改。

2023 年 12 月 19 日更新

AiClient 及相關類和包名重新命名

將 AiClient 重新命名為 ChatClient
將 AiResponse 重新命名為 ChatResponse
將 AiStreamClient 重新命名為 StreamingChatClient
將包 org.sf.ai.client 重新命名為 org.sf.ai.chat

重新命名 artifact ID

transformers-embedding 到 spring-ai-transformers

將 Maven 模組從頂層目錄和 embedding-clients 子目錄移動到單個 models 目錄下。

2023 年 12 月 1 日

我們正在轉換專案的 Group ID

從: org.springframework.experimental.ai
到: org.springframework.ai

Artifact 將仍託管在快照倉庫中，如下所示。

主分支將移動到 0.8.0-SNAPSHOT 版本。它將在一兩週內不穩定。如果您不想使用最新版本，請使用 0.7.1-SNAPSHOT。

您可以像以前一樣訪問 0.7.1-SNAPSHOT artifact，並且仍然可以訪問 0.7.1-SNAPSHOT 文件。

0.7.1-SNAPSHOT 依賴項

Azure OpenAI

<dependency>
    <groupId>org.springframework.experimental.ai</groupId>
    <artifactId>spring-ai-azure-openai-spring-boot-starter</artifactId>
    <version>0.7.1-SNAPSHOT</version>
</dependency>

OpenAI

<dependency>
    <groupId>org.springframework.experimental.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    <version>0.7.1-SNAPSHOT</version>
</dependency>