跳到主要内容

升级说明

Deepseek 3.2 中英对照 Upgrade Notes

升级到 1.1.0-RC1​

重大变更​

文本转语音 (TTS) API 迁移​

OpenAI文本转语音（TTS）的实现已从特定提供商类迁移至共享接口。这使得编写的代码具有可移植性，能够在多个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。

迁移步骤​

  1. 更新导入语句：将所有从 org.springframework.ai.openai.audio.speech. 的导入替换为 org.springframework.ai.audio.tts.

  2. 更新类型引用：将所有出现的旧类名替换为新的类名：

    查找：    SpeechModel
    替换为： TextToSpeechModel

    查找：    StreamingSpeechModel
    替换为： StreamingTextToSpeechModel

    查找：    SpeechPrompt
    替换为： TextToSpeechPrompt

    查找：    SpeechResponse
    替换为： TextToSpeechResponse

    查找：    SpeechMessage
    替换为： TextToSpeechMessage

  3. 更新速度参数：将类型从 Float 更改为 Double：

    查找：    .speed(1.0f)
    替换为： .speed(1.0)

    查找：    Float speed
    替换为： Double speed

  4. 更新依赖注入：如果你注入了 SpeechModel，请更新为 TextToSpeechModel：

    // 之前
    public MyService(SpeechModel speechModel) { ... }

    // 之后
    public MyService(TextToSpeechModel textToSpeechModel) { ... }
优点​

  • 可移植性：编写一次代码，即可轻松在 OpenAI、ElevenLabs 或其他 TTS 提供商之间切换

  • 一致性：与 ChatModel 及其他 Spring AI 抽象保持相同的模式

  • 类型安全：通过正确的接口实现改进类型层次结构

  • 面向未来：新的 TTS 提供商将自动与您现有代码兼容

附加资源​

如需查看包含详细代码示例的完整迁移指南，请参阅：

升级到 1.0.0-SNAPSHOT​

概述​

1.0.0-SNAPSHOT 版本在构件 ID、包名和模块结构方面进行了重大变更。本节提供了针对使用 SNAPSHOT 版本的特定指导。

添加快照存储库​

要使用 1.0.0-SNAPSHOT 版本，你需要在构建文件中添加快照仓库。详细操作说明，请参阅入门指南中的 快照 - 添加快照仓库 部分。

更新依赖管理​

将构建配置中的Spring AI BOM版本更新至1.0.0-SNAPSHOT。有关配置依赖管理的详细说明，请参阅入门指南中的依赖管理章节。

Artifact ID、Package 和 Module 变更​

1.0.0-SNAPSHOT 版本包含了 artifact ID、包名以及模块结构的变更。

升级到 1.0.0-RC1​

您可以使用 OpenRewrite 配方自动化升级到 1.0.0-RC1 的过程。此配方有助于应用此版本所需的许多代码更改。配方和使用说明请参见 Arconia Spring AI 迁移指南。

重大变更​

聊天客户端与顾问​

影响最终用户代码的主要变化有：

  • 在 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 的直接依赖

    • 在观测属性中（ChatClientBuilderProperties、ChatObservationProperties 和 ImageObservationProperties 内）将 includePrompt 重命名为 logPrompt

聊天记忆仓库模块与自动配置重命名​

我们已通过在代码库中统一添加repository后缀，标准化了聊天记忆组件的命名模式。此项调整涉及Cassandra、JDBC和Neo4j实现，为提升清晰度，将影响相关构件ID、Java包名及类名。

Artifact IDs​

所有与内存相关的产物现在都遵循一致的模式：

  • 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 模块（包名相同）

  • MessageAggregator 中的 aggregateChatClientResponse 方法已被移除，并移至 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与千帆​

Moonshot和Qianfan因无法从中国境外访问已被移除，这些模型已迁移至Spring AI社区仓库。

已移除向量存储​

  • 移除了 HanaDB 向量存储的自动配置 (f3b4624)

内存管理​

  • 移除了 CassandraChatMemory 实现 (11e3c8f)

  • 简化了聊天记忆顾问层次结构并移除了已弃用的 API (848a3fd)

  • 移除了 JdbcChatMemory 中的已弃用内容 (356a68f)

  • 重构了聊天记忆仓库构件以提高清晰度 (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)

常规清理​

升级到 1.0.0-M8​

您可以使用 OpenRewrite 配方自动化升级到 1.0.0-M8 的过程。该配方有助于应用此版本所需的许多代码更改。配方和使用说明请访问 Arconia Spring AI 迁移。

破坏性变更​

在从 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)

  • 重构了聊天记忆仓库构件以提高清晰度 (2d517ee)

  • 重构了聊天记忆仓库自动配置和 Spring Boot starter 以提高清晰度 (f6dba1b)

客户端 API​

  • 移除了 ChatClient 和 Advisors 中的废弃功能 (4fe74d8)

  • 对 ChatClient 的工具调用进行了破坏性变更 (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、Package 和 Module 的变更​

1.0.0-M7 包含了与 1.0.0-SNAPSHOT 相同的结构更改。

升级 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 对象访问：

// 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的过程：

  1. 下载 Claude Code CLI 工具

  2. 从 update-to-m7.txt 文件中复制提示词

  3. 将提示词粘贴到 Claude Code CLI 中

  4. AI 将分析您的项目并进行必要的更改

备注

当前自动化升级提示能够处理 artifact ID 变更、包重定位以及模块结构变更，但尚未包含升级至 MCP 0.9.0 的自动变更。如果你正在使用 MCP，你需要按照 MCP Java SDK 升级至 0.9.0 部分的指引手动更新你的代码。

各版本通用变更​

Artifact ID 变更​

Spring AI starter 构件的命名模式已更改。您需要根据以下模式更新您的依赖项：

  • 模型启动器：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}

示例​

<!-- 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>

Spring AI 自动配置 Artifact 的更改​

Spring AI 自动配置已从单一整体构件转变为针对每个模型、向量存储及其他组件的独立自动配置构件。此项变更旨在最小化相关依赖库（如 Google Protocol Buffers、Google RPC 等）因版本差异引发的冲突影响。通过将自动配置拆分为组件专属构件，您可以避免引入不必要的依赖项，从而降低应用程序中版本冲突的风险。

原始的单体工件不再可用：

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

相反，每个组件现在都拥有遵循以下模式的自配置工件：

  • 模型自动配置：spring-ai-autoconfigure-model-{model}

  • 向量存储自动配置：spring-ai-autoconfigure-vector-store-{store}

  • MCP 自动配置：spring-ai-autoconfigure-mcp-{type}

新自动配置构件示例​

<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>
备注

在大多数情况下，您无需显式地添加这些自动配置依赖项。当使用相应的 starter 依赖时，它们会以传递方式被包含进来。

包名称变更​

您的 IDE 应该协助进行重构，以迁移到新的包位置。

  • KeywordMetadataEnricher 和 SummaryMetadataEnricher 已从 org.springframework.ai.transformer 迁移至 org.springframework.ai.chat.transformer。

  • Content、MediaContent 和 Media 已从 org.springframework.ai.model 迁移至 org.springframework.ai.content。

模块结构​

该项目对其模块和工件结构进行了重大调整。原先 spring-ai-core 包含了所有核心接口，如今这些接口已被拆分到专门的领域模块中，旨在减少应用程序中不必要的依赖。

Spring AI 依赖项

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​

高级对话式人工智能 API：

  • ChatClient 接口
  • 通过 ChatMemory 实现对话持久化
  • 使用 OutputConverter 进行响应转换
  • 基于 Advisor 的拦截机制
  • 同步与响应式流处理支持

spring-ai-advisors-vector-store​

桥接与向量存储的聊天以实现RAG：- QuestionAnswerAdvisor：将上下文注入提示中 - VectorStoreChatMemoryAdvisor：存储/检索对话历史

spring-ai-model-chat-memory-cassandra​

ChatMemory的Apache Cassandra持久化： - CassandraChatMemory 实现 - 使用Cassandra QueryBuilder实现类型安全的CQL ===== spring-ai-model-chat-memory-neo4j

聊天对话的Neo4j图数据库持久化存储。

spring-ai-rag​

全面的检索增强生成框架：- 模块化的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 类已增强，支持显式和隐式工具解析。工具现在可以通过以下方式使用：

  1. 显式包含：在提示中明确请求并包含在模型调用中的工具。

  2. 隐式可用：为运行时动态解析提供的工具，除非被明确请求，否则永远不会包含在任何模型调用中。

从 1.0.0-M7 版本开始，只有在提示中明确请求或在调用中明确包含的情况下，工具才会被包含在模型的调用中。

此外，ToolContext 类现在已被标记为 final，无法再被扩展。它原本就不应该被继承。你可以在实例化 ToolContext 时，以 Map<String, Object> 的形式添加所有需要的上下文数据。欲了解更多信息，请查看文档。

升级到 1.0.0-M6​

使用接口与默认实现类的变更​

Usage接口及其默认实现DefaultUsage已进行以下变更：

  1. 方法重命名：

    • getGenerationTokens() 现在更名为 getCompletionTokens()

  2. 类型变更：

    • 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)
备注

有关处理使用情况的更多信息，请参阅此处

JSON 序列化/反序列化变更​

虽然M6在JSON反序列化中保持了对generationTokens字段的向后兼容性，但该字段将在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。除 Cohere 和 Titan 的 Embedding 模型外，所有 Amazon Bedrock Chat 模型均已移除。

备注

关于使用聊天模型，请参考 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 Client 所需的变更。特别需要注意的是，如果您的类路径中没有 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 Builder 已重构以保持一致性。

  • 当前 VectorStore 实现的构造函数已被弃用，请使用构建器模式。

  • VectorStore 实现包已移至唯一的包名中，避免跨构件冲突。例如 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）的风格来创建和执行提示。有关 Fluent API 的更多信息，请参阅 [JavaDoc](docs.spring.io/spring-ai/docs/api)，正式的参考文档即将发布。

我们将旧的 ModelClient 更名为 Model，并对实现类进行了重命名，例如 ImageClient 更名为 ImageModel。Model 实现代表可移植性层，它在 Spring AI API 与底层 AI 模型 API 之间进行转换。

新增一个名为 model 的包，其中包含接口和基类，用于支持为任意输入/输出数据类型组合创建 AI 模型客户端。目前，聊天和图像模型包已实现此功能。我们即将更新嵌入包以适配这一新模型。

一种新的"便携式选项"设计模式。我们希望在ModelCall中为不同聊天AI模型提供最大程度的可移植性。其中包含一组通用的生成选项，以及特定于模型提供商的选项。采用了类似"鸭子类型"的方法。模型包中的ModelOptions是一个标记接口，表明实现此类的对象将提供模型的选项。参见ImageOptions，这是一个子接口，定义了所有文本→图像ImageModel实现中通用的便携式选项。而StabilityAiImageOptions和OpenAiImageOptions则提供特定于每个模型提供商的选项。所有选项类均通过流畅的API构建器创建，并可传入便携式ImageModel API。这些选项数据类型用于ImageModel实现的自动配置/配置属性中。

制品名称变更​

重命名的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>

to

<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 提供可移植性。这包括一组通用的生成选项以及特定于模型提供商的选项。采用了一种类似“鸭子类型”的方法。model 包中的 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 * 用SimpleVectorStore替换InMemoryVectorStore

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：

  • FROM: org.springframework.experimental.ai

  • TO: org.springframework.ai

快照仓库中仍将托管构件，如下所示。

主分支将迁移至版本 0.8.0-SNAPSHOT。它在一到两周内会处于不稳定状态。如果您不想使用前沿版本，请使用 0.7.1-SNAPSHOT。

您可以像以前一样访问 0.7.1-SNAPSHOT 构件，并且仍然可以访问 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>

章节概要​