跳到主要内容
版本:2.0.1

升级说明

QWen 3.8 中英对照 Upgrade Notes

升级至 2.0.1​

Redis Chat Memory Repository Auto-Configuration Module 重命名​

Redis 聊天记忆自动配置模块已重命名为 spring-ai-autoconfigure-model-chat-memory-repository-redis。

影响​

Redis 聊天内存自动配置模块的构件 ID 和配置属性已更改:

  • Artifact: spring-ai-autoconfigure-model-chat-memory-redis → spring-ai-autoconfigure-model-chat-memory-repository-redis

  • Configuration properties: spring.ai.chat.memory.redis. → spring.ai.chat.memory.repository.redis.

迁移​

  • 更新您的 Maven/Gradle 依赖项,以使用新的 artifact ID:
<!-- Before -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-autoconfigure-model-chat-memory-redis</artifactId>
</dependency>

<!-- After -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-autoconfigure-model-chat-memory-repository-redis</artifactId>
</dependency>
  • 更新您的配置属性以使用新的前缀:
# Before
spring.ai.chat.memory.redis.*=xxx

# After
spring.ai.chat.memory.repository.redis.*=xxx

平滑过渡​

新模块提供了从已弃用模块的平滑过渡:

  • 已弃用的 spring-ai-autoconfigure-model-chat-memory-redis 模块仍然存在,并通过传递依赖依赖于新模块,因此现有依赖关系无需更改即可继续正常工作。

  • 已弃用的 RedisChatMemoryProperties(spring.ai.chat.memory.redis)会将所有属性委托给当前的 RedisChatMemoryRepositoryProperties(spring.ai.chat.memory.repository.redis),这与本文档下文提到的 .options 弃用机制相同,因此现有的属性配置可以继续正常工作。

备注

弃用的模块和旧版配置前缀将在未来的版本中移除。

Mistral AI 审核类别重构​

Mistral AI 内容审核模型已从 mistral-moderation-2411(将于 2026 年 6 月 30 日退役)迁移至 mistral-moderation-2603。作为此次迁移的一部分,原有的单一 dangerousAndCriminalContent 类别被拆分为两个独立的类别:dangerous 和 criminal。同时,还新增了 jailbreaking 类别。

影响​

以下 Categories 和 CategoryScores 上的方法已弃用,并将在未来版本中移除:

  • Categories.isDangerousAndCriminalContent()

  • Categories.Builder.dangerousAndCriminalContent(boolean)

  • CategoryScores.getDangerousAndCriminalContent()

  • CategoryScores.Builder.dangerousAndCriminalContent(double)

迁移​

将已弃用的 dangerousAndCriminalContent 方法替换为新的 criminal 和 dangerous 等效方法:

// Before
boolean flagged = categories.isDangerousAndCriminalContent();
double score = categoryScores.getDangerousAndCriminalContent();

Categories categories = Categories.builder()
.dangerousAndCriminalContent(true)
.build();

// After
boolean flagged = categories.isCriminal() || categories.isDangerous();
double score = categoryScores.getCriminal() + categoryScores.getDangerous();

Categories categories = Categories.builder()
.criminal(true)
.dangerous(true)
.build();

此外,您还可以查看新增的 jailbreaking 分类,该分类此前没有对应的等价项:

boolean jailbreakAttempt = categories.isJailbreaking();
double jailbreakScore = categoryScores.getJailbreaking();

Mistral AI 聊天模型枚举更新​

MistralAiApi.ChatModel 已更新,以跟踪 Mistral AI 的当前模型列表。部分常量指向的模型已被 Mistral AI 下架。

影响​

  • ChatModel.MAGISTRAL_MEDIUM、ChatModel.MAGISTRAL_SMALL、ChatModel.DEVSTRAL 和 ChatModel.OPEN_MISTRAL_NEMO 已被移除。这些常量所指向的模型(magistral-medium-latest、magistral-small-latest、devstral-latest、open-mistral-nemo)均已超过其退役日期,因此引用这些常量的代码将无法再编译。

  • ChatModel.MISTRAL_SMALL 现在指向 mistral-small-2603(此前为 mistral-small-latest)。

  • ChatModel.MISTRAL_MEDIUM 现在指向 mistral-medium-3-5(此前为 mistral-medium-latest)。

  • ChatModel.MISTRAL_LARGE 现在同样指向 mistral-medium-3-5。Mistral Large 已退役,Mistral AI 推荐 Mistral Medium 3.5 作为其替代方案;MISTRAL_LARGE 仅作为别名保留,以维持向后兼容性。

迁移​

将任何对已移除常量的引用替换为受支持的模型:

// Before
String model = MistralAiApi.ChatModel.MAGISTRAL_MEDIUM.getValue();

// After
String model = MistralAiApi.ChatModel.MISTRAL_MEDIUM.getValue();

如果你依赖于 Magistral 的推理(“thinking”)输出,请改用 MistralAiApi.ChatCompletionRequest.ReasoningEffort 配合 MISTRAL_SMALL 或 MISTRAL_MEDIUM 使用。

MCP 工具异常处理​

变更:@McpTool 异常处理行为与 @Tool 保持一致​

@McpTool 注解的服务方法所遵循的异常处理契约已与 @Tool 保持一致。此前,@McpTool 方法抛出的所有异常(包括声明的受检异常、Error 子类型以及协议级别的 McpError`s)都会被捕获,并静默地转换为错误类型的 `CallToolResult 传递给模型。从 2.0.1 版本开始,异常的调度将遵循与 @Tool 相同的基于类型的规则:

异常类型行为
RuntimeException(非 McpError)转换为错误 CallToolResult 并传递给模型
声明的受检异常向上抛出为 UndeclaredThrowableException — 硬性失败,永远不会到达模型
Error 子类原样向上抛出 — 硬性失败
McpError原样向上抛出 — 硬性失败(协议级信号,例如 URL 提示)
影响​

故意抛出受检异常或 Error 以指示问题、并期望该异常作为错误消息传递给模型的 @McpTool 方法,现在将直接传播该异常。

迁移​

如果你的 @McpTool 方法抛出受检异常或 Error,并且你希望模型看到错误消息,请在抛出前在方法体中将其转换为 RuntimeException(或其子类):

// Before — checked exception was silently converted to an error result
@McpTool(description = "Look up an order")
public String lookupOrder(String orderId) throws NotFoundException {
throw new NotFoundException("Order not found: " + orderId);
}

// After — wrap in RuntimeException to convey error to model,
// or remove the checked-exception declaration and let it propagate
@McpTool(description = "Look up an order")
public String lookupOrder(String orderId) {
throw new RuntimeException("Order not found: " + orderId); // reaches model as error result
}

如果你希望受检异常被视为硬性失败,则无需任何更改——默认情况下,它会以 UndeclaredThrowableException 的形式向上抛出。

已弃用:toolCallExceptionClass 构造参数​

以下类中的 toolCallExceptionClass 参数已弃用,并将在 2.1.0 中移除。该参数在运行时会被忽略——异常分发现在基于类型,而非基于类。

  • SyncMcpToolMethodCallback(ReturnMode, Method, Object, Class<? extends Throwable>)

  • AsyncMcpToolMethodCallback(ReturnMode, Method, Object, Class<? extends Throwable>)

  • SyncStatelessMcpToolMethodCallback(ReturnMode, Method, Object, Class<? extends Throwable>)

  • AsyncStatelessMcpToolMethodCallback(ReturnMode, Method, Object, Class<? extends Throwable>)

  • AbstractMcpToolProvider.doGetToolCallException()

迁移​

请使用三参数构造函数。toolCallExceptionClass 参数虽然会被接受,但不再产生任何效果:

// Before
new SyncMcpToolMethodCallback(ReturnMode.TEXT, method, provider, Exception.class);

// After
new SyncMcpToolMethodCallback(ReturnMode.TEXT, method, provider);

工具调用​

新增:工具调用限制​

DefaultToolCallingManager 现在会对每轮的 tool calls 进行限制——每个 tool 最多 DefaultToolCallingManager.DEFAULT_MAX_CALLS_PER_TOOL(40)次,总体最多 DEFAULT_MAX_TOTAL_TOOL_CALLS(150)次——而之前完全没有此限制。

大多数应用不会注意到这一影响,因为默认值设置较为宽松。如果合法的工作负载超出了这些限制,请通过 ToolCallingManager.builder().maxCallsPerTool(…​) / .unlimitedCallsPerTool()(或 spring.ai.tools.limits.* 属性)来调高或禁用该限制。参见 Tool Call Limits。

变更:ToolCallingAdvisor 的使用情况现在会在循环中累积​

ToolCallingAdvisor 现在会在工具调用循环中的每次内部模型调用中累加 token 使用量,而不仅仅是在最终的 ChatClientResponse 中暴露最后一次调用的 Usage。在工具调用交互后,断言精确 Usage/token 数量的代码或测试将观察到更高的、如今为累计值的数值。无需进行 API 更改。

OpenAI​

变更:工具调用严格模式(Tool Calling Strict Mode)现在默认值为 false​

OpenAiChatModel 不再默认将工具 schema 设置为 strict(true)。由于 JsonSchemaGenerator 在生成 required 字段时会省略可选参数,而不是采用 OpenAI 严格模式所需的可空类型(nullable-type)模式,因此在旧的默认设置下,任何包含可选参数的工具都会被 OpenAI 以 400 错误拒绝。

影响​

依赖隐式 strict(true) 默认值的行为现在会被发送为非严格模式,除非明确请求严格模式。此变更仅影响 OpenAI 自身的 schema 符合性检查;工具执行及其结果保持不变。

迁移​

通过 OpenAiChatOptions#strict(true) 重新开启。启用后,可选参数会被自动放宽为可空类型,并填充至 required 字段,以确保 schema 仍满足 OpenAI 的严格模式契约:

OpenAiChatOptions options = OpenAiChatOptions.builder()
.strict(true)
.build();

变更:OpenAiAudioSpeechModel 流式传输现在输出真实的音频块​

OpenAiAudioSpeechModel.stream(TextToSpeechPrompt) 之前会缓冲整个响应并将其作为单个 Flux 元素发出。现在它请求 OpenAI 设置 stream_format=audio,并在块到达时立即发出这些块。

影响​

仅消费 Flux 第一个元素(例如通过 blockFirst())的代码,此前假设该元素包含完整音频,现在将只获取到第一个数据块。

迁移​

将生成的每个 chunk 进行拼接,而不是仅取第一个元素。完整的示例请参见桥接流式响应。

TranscriptionModel 现在继承自 StreamingTranscriptionModel​

TranscriptionModel 现在继承自 StreamingTranscriptionModel,这使得流式转录成为所有转录模型的一等公民能力。

StreamingTranscriptionModel 提供了一个默认的 stream(AudioTranscriptionPrompt) 实现,该方法返回 Flux.error(new UnsupportedOperationException(…​)),因此现有的 TranscriptionModel 自定义实现无需修改即可继续编译。

影响​

在自定义实现上调用 stream(),如果该实现未重写此方法,则会返回一个发出 UnsupportedOperationException 的 Flux。

Migration​

如果自定义的 TranscriptionModel 需要支持流式转写,请重写 stream(AudioTranscriptionPrompt) 方法。您可以提供原生的流式实现,或者将同步的 call() 结果包装为单元素的 Flux:

public class CustomTranscriptionModel implements TranscriptionModel {

@Override
public AudioTranscriptionResponse call(AudioTranscriptionPrompt prompt) {
// ...
}

@Override
public Flux<AudioTranscriptionResponse> stream(AudioTranscriptionPrompt prompt) {
// Wrap the synchronous call result as a single-element Flux
return Flux.just(call(prompt));
}
}

如果不需要流式传输,则无需执行任何操作——会自动继承默认实现。

媒体构建器:类型化的 data() 重载替代 data(Object)​

Media.Builder.data(Object) 已被类型化重载方法取代:data(byte[])、data(String)、data(URI)、data(URL) 和 data(Resource)。

影响​

使用静态类型为 Object 的参数调用 .data(…​) 的代码将无法再编译——不存在匹配的重载。

迁移​

在调用 .data(…​) 之前,先将类型收窄为具体类型:

// Before
Object data = getMediaData();
Media.builder().mimeType(mimeType).data(data).build();

// After
Object data = getMediaData();
if (data instanceof byte[] bytes) {
Media.builder().mimeType(mimeType).data(bytes).build();
}
else if (data instanceof String s) {
Media.builder().mimeType(mimeType).data(s).build();
}

工具解析回退默认禁用​

默认情况下,已禁用用于解析并执行那些已注册为 Bean 但未附加到请求的工具的回退机制。此前,当模型返回了一个未附加到请求的工具调用时,DefaultToolCallingManager 会回退到应用范围的 ToolCallbackResolver(其背后由应用程序上下文中的所有 ToolCallback Bean 提供支持)并执行解析出的工具。从 2.0.1 版本开始,通过 .tools(…​)、.defaultTools(…​) 或 ToolCallingChatOptions.toolCallbacks(…​) 附加到请求的工具,是唯一可针对该请求执行的工具。

要恢复先前的行为,请重新启用解析回退:

spring.ai.tools.resolution.fallback.enabled=true

直接在构造 ToolCallingManager 时,请改用 builder 开关:

ToolCallingManager toolCallingManager = ToolCallingManager.builder()
.toolCallbackResolver(toolCallbackResolver)
.resolutionFallbackEnabled(true) // default is false
.build();

有关详细信息,请参阅工具解析。

升级到 2.0.0​

本章节涵盖从 Spring AI 1.1.x 升级至 2.0.0 时所有破坏性变更及迁移步骤。

Advisors​

spring-ai-advisors-vector-store 更名为 spring-ai-vector-store-advisor

QWen 3.8 中英对照 Upgrade Notes spring-ai-advisors-vector-store renamed to spring-ai-vector-store-advisor

spring-ai-advisors-vector-store 模块已重命名为 spring-ai-vector-store-advisor,以更好地对齐其他 Spring AI 模块的命名规范。

新增:ToolSearchToolCallingAdvisor 自动配置与 Starter​

现在已提供 Spring Boot 自动配置(spring-ai-autoconfigure-tool-search-advisor)和对应的 starter(spring-ai-starter-tool-search-advisor)。启用后,ToolSearchToolCallingAdvisor 将替换自动配置的 ChatClient 中默认的 ToolCallingAdvisor,限制每次调用发送给 LLM 的工具定义仅为最相关的部分(通过关键词或语义搜索实现)。

通过添加 starter 并设置该属性来启用:

<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-tool-search-advisor</artifactId>
</dependency>
spring.ai.chat.client.tool-search-advisor.enabled=true

# Choose the index type: regex (default), lucene, or vector
spring.ai.chat.client.tool-search-advisor.tool-index-type=regex

regex 索引无需额外的依赖。lucene 索引需要 classpath 中包含 org.apache.lucene:lucene-core。vector 索引需要一个 VectorStore bean(即 classpath 中包含 spring-ai-vector-store)。

变更:Advisor.DEFAULT_CHAT_MEMORY_PRECEDENCE_ORDER 默认值​

Advisor.DEFAULT_CHAT_MEMORY_PRECEDENCE_ORDER 从 Ordered.HIGHEST_PRECEDENCE + 1000 更改为 Ordered.HIGHEST_PRECEDENCE + 200,使得记忆 Advisor 的默认顺序位于 ToolCallingAdvisor(HIGHEST_PRECEDENCE + 300)之外。

ToolCallingAdvisor 现在默认会在工具调用迭代过程中内部管理对话历史。记忆顾问(memory advisor)仅存储最终的用户/助手交互,而不会将工具调用消息写入 ChatMemoryRepository。这是正确的默认行为,因为大多数仓库实现(repository implementations)不支持这些消息类型。

如果你需要在循环内部使用内存(例如使用 InMemoryChatMemoryRepository),请显式将顾问顺序设置为高于 ToolCallingAdvisor.DEFAULT_ORDER,并调用 .disableInternalConversationHistory():

var toolCallingAdvisor = ToolCallingAdvisor.builder()
.disableInternalConversationHistory()
.build();
var chatMemoryAdvisor = MessageChatMemoryAdvisor.builder(chatMemory)
.advisorOrder(Ordered.HIGHEST_PRECEDENCE + 400)
.build();
提示

spring-ai-session 社区项目提供了一种支持会话感知(session-aware)的记忆实现,完全支持工具调用消息(tool-call messages),并且可以在任何后端的工具调用循环中安全使用。计划在 Spring AI 2.1 中替换 ChatMemory。详见 spring-ai-session 文档。

工具调用​

移除:从 ToolCallingChatOptions 中移除 internalToolExecutionEnabled​

internalToolExecutionEnabled 选项已从 ToolCallingChatOptions 以及所有特定提供商的 ChatOptions 类(例如 OpenAiChatOptions、AnthropicChatOptions)中移除。相应的 Spring Boot 配置属性 spring.ai.<provider>.chat.internal-tool-execution-enabled 也已移除。

影响​

调用 .internalToolExecutionEnabled(false) 以启用由用户控制的工具执行的代码将无法再编译。调用 .internalToolExecutionEnabled(true)(显式启用内部循环)的代码同样将无法再编译,且其所暗示的行为已不复存在——基于模型的内部工具执行已从所有 ChatModel 实现中被移除。

迁移​

删除对 .internalToolExecutionEnabled(…​) 的所有调用。推荐的做法是:

  • 通过 ChatClient 使用 ToolCallingAdvisor(推荐)——当存在工具时自动注册,无需额外配置标志。

  • 通过 ChatModel 直接控制用户循环 —— 直接调用 ChatModel 而不使用 ToolCallingAdvisor。工具调用将不会自动执行;您需要自行检查 chatResponse.hasToolCalls(),并使用 ToolCallingManager 驱动循环。

// Before
ChatOptions options = ToolCallingChatOptions.builder()
.toolCallbacks(ToolCallbacks.from(new MyTools()))
.internalToolExecutionEnabled(false) // <-- remove this line
.build();

// After
ChatOptions options = ToolCallingChatOptions.builder()
.toolCallbacks(ToolCallbacks.from(new MyTools()))
.build();

已移除:ToolExecutionEligibilityPredicate 和 DefaultToolExecutionEligibilityPredicate​

ToolExecutionEligibilityPredicate(自 2.0.0 起已被弃用)及其默认实现 DefaultToolExecutionEligibilityPredicate 已被移除。这些接口将基于选项的策略检查(internalToolExecutionEnabled)与响应检查(hasToolCalls())结合在了一起。由于基于选项的标志已被移除,因此在 ChatModel 层面没有替代方案。

Migration​

如果你实现了 ToolExecutionEligibilityPredicate 来自定义工具执行的触发时机,请迁移到 ToolExecutionEligibilityChecker(见下文),并将其提供给 ToolCallingAdvisor。

新增:ToolCallingAdvisor 中的 ToolExecutionEligibilityChecker​

ToolExecutionEligibilityChecker (Function<ChatResponse, Boolean>) 现在可以在 ToolCallingAdvisor.Builder 上设置,以自定义何时迭代工具调用循环。默认值为 chatResponse → chatResponse != null && chatResponse.hasToolCalls()。

这是用于提供商特定停止原因逻辑的扩展点(例如,在检查工具调用存在性的同时,还检查完成原因):

ToolCallingAdvisor advisor = ToolCallingAdvisor.builder()
.toolExecutionEligibilityChecker(response ->
response != null && response.hasToolCalls()
&& !"stop".equals(response.getResult().getMetadata().getFinishReason()))
.build();

Spring Boot 用户可以提供 ToolExecutionEligibilityChecker Bean;它会被自动配置的 ToolCallingAdvisor.Builder 自动拾取:

@Bean
ToolExecutionEligibilityChecker myChecker() {
return response -> response != null && response.hasToolCalls();
}

新增:spring.ai.chat.client.tool-calling.enabled 属性​

新增的 spring.ai.chat.client.tool-calling.enabled 属性(默认值为 true)用于控制由自动配置的 ChatClient 是否自动注册 ToolCallingAdvisor。将其设置为 false 可禁用所有调用中的自动工具执行——工具定义仍会发送给 AI 模型,但工具调用响应将不会被自动执行。

spring.ai.chat.client.tool-calling.enabled=false

这是在使用每次单独调用时都指定 AdvisorParams.toolCallingAdvisorAutoRegister(false) 的一种全局替代方案。

已移除:从 Advisor Builders 和自动配置中移除 streamToolCallResponses​

streamToolCallResponses 选项已从 ToolCallingAdvisor.Builder、ToolCallAdvisor.Builder 和 ToolSearchToolCallingAdvisor.Builder 中移除,同时也被移除了相应的 Spring Boot 自动配置属性:

  • spring.ai.chat.client.tool-calling.stream-tool-call-responses

  • spring.ai.chat.client.tool-search-advisor.stream-tool-call-responses

Why​

当 streamToolCallResponses=true 时,中间的工具调用请求块会被流式传输到下游,但配对返回给 LLM 的 ToolResponseMessage 却未被传输。任何记录了这些块的下游 memory advisor 都会收到一个缺少对应工具响应的工具调用请求,从而产生损坏的对话历史。由于该设计缺陷若不引入对 ChatClientResponse 的破坏性变更就无法修复,因此该选项已被完全移除。

影响​
  • 任何在顾问构建器(advisor builder)上调用 .streamToolCallResponses(true) 或 .streamToolCallResponses(false) 的代码都将无法编译。

  • 任何针对已移除属性的 application.properties 或 application.yml 配置项都会被静默忽略。

迁移​

移除构建器链中所有对 .streamToolCallResponses(…​) 的调用:

// Before
var advisor = ToolCallingAdvisor.builder()
.streamToolCallResponses(true) // <-- remove this line
.build();

// After
var advisor = ToolCallingAdvisor.builder().build();

要能够观察到工具调用循环中的每次迭代——即 streamToolCallResponses=true 旨在解决的用例——可以选择退出自动注册的 advisor,并使用 AdvisorParams.toolCallingAdvisorAutoRegister(false) 手动驱动循环:

ToolCallingManager toolCallingManager = ToolCallingManager.builder().build();
ToolCallback[] tools = ToolCallbacks.from(new WeatherTools());
ChatOptions chatOptions = ToolCallingChatOptions.builder()
.toolCallbacks(tools)
.build();

String question = "What is the weather in Amsterdam and Paris?";
Prompt prompt = new Prompt(List.of(new UserMessage(question)), chatOptions);

ChatClientResponse response = chatClient.prompt()
.user(question)
.options(chatOptions)
.advisors(AdvisorParams.toolCallingAdvisorAutoRegister(false))
.call()
.chatClientResponse();

while (response.chatResponse() != null && response.chatResponse().hasToolCalls()) {
// inspect or forward the tool-call chunk here before executing
ToolExecutionResult result = toolCallingManager.executeToolCalls(prompt, response.chatResponse());
prompt = new Prompt(result.conversationHistory(), chatOptions);
response = chatClient.prompt()
.messages(result.conversationHistory())
.options(chatOptions)
.advisors(AdvisorParams.toolCallingAdvisorAutoRegister(false))
.call()
.chatClientResponse();
}
// forward or process the final answer here

对于包含流式路径的完整示例,参见 用户控制工具执行 — 使用 ChatClient。

Removed: ChatModel 中的内部工具执行循环​

在 Spring AI 1.x 中,每个 ChatModel 实现都包含自己的内部工具执行循环:在使用工具调用 chatModel.call(prompt) 时,会自动执行响应中的任何工具调用并重新调用模型,循环直到模型生成非工具调用的响应为止。

在 2.0 中,所有 ChatModel 实现(OpenAI、Anthropic、Ollama、DeepSeek、Bedrock、MiniMax、Mistral、Google GenAI)的内部循环已被移除。ChatModel.call(prompt) 和 ChatModel.stream(prompt) 现在返回模型的原始响应——工具调用不会被自动执行。

影响​

直接调用 ChatModel 并提供工具且依赖自动执行的代码,现在将在响应中收到模型的工具调用请求,但该请求不会被自动执行。

迁移​

对于大多数应用,请切换到 ChatClient。自动注册的 ToolCallingAdvisor 会为您执行循环:

ChatClient.create(chatModel)
.prompt(question)
.tools(new MyTools())
.call()
.content();

当你确实需要直接使用 ChatModel(例如自定义编排器或基础设施代码)时,可以使用 ToolCallingManager 手动驱动循环。请参阅 ChatModel Tool Calling: Driving the Loop Manually。

已移除:SpringBeanToolCallbackResolver 和 toolNames()​

SpringBeanToolCallbackResolver 和 toolNames() API——它们通过名称从原始的 Function/Supplier/Consumer Bean 中解析工具——已被移除。现在,工具必须注册为显式的 ToolCallback 实例或带有 @Tool 注解的对象。

影响​

声明了 Function Bean 并通过 toolNames(…​) 按名称引用它们的代码将不再能编译或解析。

迁移​

直接声明一个 ToolCallback Bean(对于函数式工具,使用 FunctionToolCallback.builder()):

// Before (1.x) — bare Function bean resolved by name
@Bean
@Description("Get the weather in location")
Function<WeatherRequest, WeatherResponse> currentWeather() {
return weatherService::getWeather;
}
chatClient.prompt().toolNames("currentWeather"); // no longer exists

// After (2.0) — explicit ToolCallback bean
@Bean
ToolCallback currentWeather() {
return FunctionToolCallback.builder("currentWeather", weatherService::getWeather)
.description("Get the weather in location")
.inputType(WeatherRequest.class)
.build();
}

@Autowired ToolCallback currentWeather;

chatClient.prompt()
.user("What's the weather in Copenhagen?")
.tools(currentWeather)
.call()
.content();

基于方法的工具也可以通过 @Tool 声明:

class WeatherTools {
@Tool(description = "Get the weather in location")
WeatherResponse currentWeather(WeatherRequest request) {
return weatherService.getWeather(request);
}
}

chatClient.prompt().tools(new WeatherTools()).call().content();

重命名:ToolCallAdvisor → ToolCallingAdvisor​

用于递归工具调用的顾问类已重命名以提高精确度。如果您直接引用了 ToolCallAdvisor(例如,通过注册自定义实例或继承该类),请将该引用更新为 ToolCallingAdvisor。

// Before (1.x)
var advisor = ToolCallAdvisor.builder()...;

// After (2.0)
var advisor = ToolCallingAdvisor.builder()...;

重命名:FunctionCallback API → ToolCallback API​

Spring AI 1.0 引入了 ToolCallback 作为旧版 FunctionCallback API 的替代方案;2.0 彻底移除了已弃用的 FunctionCallback 类型和方法。术语现在已保持一致——到处都是“tools”,再也没有“functions”。

如果您正在从仍使用旧版 FunctionCallback API 的版本进行升级:

之前(旧版)之后(2.0)
FunctionCallbackToolCallback
FunctionCallback.builder().function(name, fn)FunctionToolCallback.builder(name, fn)
FunctionCallback.builder().method(…​)MethodToolCallback.builder() with ToolDefinition
FunctionCallingOptionsToolCallingChatOptions
FunctionCallingOptions.builder().functionCallbacks(…​)ToolCallingChatOptions.builder().toolCallbacks(…​)
ChatClient.Builder#defaultFunctions(…​)ChatClient.Builder#defaultTools(…​)
ChatClient.prompt().functions(…​)ChatClient.prompt().tools(…​)

示例:

// Before — function-style callback
FunctionCallback.builder()
.function("getCurrentWeather", new MockWeatherService())
.description("Get the weather in location")
.inputType(MockWeatherService.Request.class)
.build();

// After — explicit ToolCallback via FunctionToolCallback
FunctionToolCallback.builder("getCurrentWeather", new MockWeatherService())
.description("Get the weather in location")
.inputType(MockWeatherService.Request.class)
.build();
// Before — defaultFunctions in builder
ChatClient.builder(chatModel)
.defaultFunctions(
FunctionCallback.builder()
.function("WeatherInfo", new MockWeatherService())
.description("Get the current weather")
.inputType(MockWeatherService.Request.class)
.build())
.build();

// After — defaultTools in builder
ChatClient.builder(chatModel)
.defaultTools(
FunctionToolCallback.builder("WeatherInfo", new MockWeatherService())
.description("Get the current weather")
.inputType(MockWeatherService.Request.class)
.build())
.build();
// Before — per-call functions()
chatClient.prompt()
.user("...")
.functions(callback)
.call();

// After — per-call tools()
chatClient.prompt()
.user("...")
.tools(callback)
.call();

对于新代码,请优先使用声明式的 @Tool 注解 —— 请参阅 定义工具。

JDBC 聊天记忆 sequence_id 列​

JdbcChatMemoryRepository 模式新增了一个 sequence_id BIGINT 列,用于确定会话中消息的顺序。此前,排序依赖于 timestamp 列,但 TIMESTAMP 的精度在不同数据库之间存在差异——在 MySQL 和 MariaDB 中,默认精度为一秒,因此在同一秒内保存的消息会以非确定性顺序返回。专用的整数序列可确保在所有支持的数据库中获得一致排序。

timestamp 列被保留。现在它存储消息创建时间,并通过 JdbcChatMemoryRepository.CONVERSATION_TS 键(类型为 java.time.Instant)暴露在消息元数据中,以便应用程序可以显示消息的创建时间。该时间戳在保存过程中保持不变:重新保存对话时,每条已有消息的原始创建时间均会被保留。

影响​

  • SPRING_AI_CHAT_MEMORY 表新增了一个 sequence_id 列(类型为 BIGINT,在 Oracle 上为 NUMBER(19),在 SQLite 上为 INTEGER)以及一个 SPRING_AI_CHAT_MEMORY_CONVERSATION_ID_SEQUENCE_ID_IDX 索引。timestamp 列及其索引保持不变。

  • 由 Spring AI 1.x 创建现有的表需要先添加新列才能正常工作,因为消息现在根据 sequence_id 进行排序。

  • 从存储库读取的消息现在会在元数据(metadata)中携带其创建时间戳。由于元数据存在差异,检索到的消息不再与代码中构造的其他完全相同的消息相等(Message.equals)。依赖消息值进行比较,或依赖集合或映射中消息身份的代码,应考虑此变化。

Migration​

此变更是增量的:添加新列,并从现有的按会话顺序中回填数据。不会丢失任何数据,且 timestamp 列保持不变。对于 PostgreSQL:

ALTER TABLE SPRING_AI_CHAT_MEMORY ADD COLUMN sequence_id BIGINT;

WITH ordered AS (
SELECT ctid, ROW_NUMBER() OVER (PARTITION BY conversation_id ORDER BY "timestamp") - 1 AS seq
FROM SPRING_AI_CHAT_MEMORY
)
UPDATE SPRING_AI_CHAT_MEMORY t
SET sequence_id = o.seq
FROM ordered o
WHERE t.ctid = o.ctid;

ALTER TABLE SPRING_AI_CHAT_MEMORY ALTER COLUMN sequence_id SET NOT NULL;

CREATE INDEX SPRING_AI_CHAT_MEMORY_CONVERSATION_ID_SEQUENCE_ID_IDX
ON SPRING_AI_CHAT_MEMORY(conversation_id, sequence_id);

将标识符引用方式和行身份表达式(如上文中的 ctid)适配到您的数据库。ROW_NUMBER() OVER (PARTITION BY conversation_id ORDER BY <timestamp>) 模式可在所有支持的引擎上重现现有的按对话排序的顺序。或者,由于聊天记忆存储的是最近的对话上下文而非永久历史记录,您可以从更新后的 schema-<platform>.sql 脚本中删除并重新创建该表。

选项的不可变性与默认值​

选项的严格不可变性​

选项类(如 ChatOptions、EmbeddingOptions 等)现在严格不可变。选项中的集合(如 toolCallbacks、stopSequences、customHeaders)现在以不可修改的集合形式存储。此外,现在使用可空集合来代替空集合,以更好地表示值的缺失。

影响​
  • ChatOptions#copy() 和 *Options#fromOptions(*Options) 方法已移除,因为选项现在是严格不可变的。

  • 修改选项获取器返回的集合将抛出 UnsupportedOperationException。

迁移​

若要创建 options 实例的修改副本,请使用方法 mutate(),而非 copy() 或 fromOptions():

// Before
OllamaChatOptions options = originalOptions.copy();
options.setFoo("...");

// After
OllamaChatOptions options = originalOptions.mutate()
.foo("...")
.build();

默认值移至选项构造函数​

选项的默认值(如默认模型名称、温度等)已从 Model 实现类和 *Properties 配置类移至选项构造器本身。*Properties 类中的默认配置属性已被移除,因为不再需要它们,且应与选项级别的默认值保持一致。

影响​
  • ChatModel#getDefaultOptions() 已被弃用,建议使用 ChatModel#getOptions()。

  • *Properties 类中不再重复定义默认值。

迁移​

检索模型的默认选项时,请使用 getOptions() 代替 getDefaultOptions():

// Before
ChatOptions options = chatModel.getDefaultOptions();

// After
ChatOptions options = chatModel.getOptions();

配置属性扁平化​

基于上述描述的聊天配置变更,其他所有模型(Embedding、Image、Audio、Moderation、OCR 等)的配置属性不再使用 .options 前缀。例如,原有的 spring.ai.openai.embedding.options.model 现在变为 spring.ai.openai.embedding.model。为确保更平滑的迁移体验,已提供针对 .options 变体的废弃配置属性。

影响​
  • *Properties 类中的 getOptions() 方法已弃用。

  • *Properties 中的嵌套 Options 类已弃用。

  • toOptions() 方法已从嵌套的 Options 类移至根 *Properties 类。

迁移​

更新您的 application.properties 或 application.yml,从属性键中移除 .options 段。

# Before
spring.ai.openai.embedding.options.model=text-embedding-3-small

# After
spring.ai.openai.embedding.model=text-embedding-3-small

在 Java 代码中,直接使用根属性类来访问选项,或调用 toOptions():

// Before
String model = properties.getOptions().getModel();
OpenAiEmbeddingOptions options = properties.getOptions().toOptions();

// After
String model = properties.getModel();
OpenAiEmbeddingOptions options = properties.toOptions();

在选项构建器中将 N() 重命名为 n()​

*Options 和各种配置属性类中的 N() 构建方法已重命名为 n(),以符合 Java 命名规范。

影响​
  • 调用这些构建器上的 .N(value) 方法的任何 Java 代码都将无法编译。
Migration​

请将您的代码更新为调用 .n(value)。

// Before
OpenAiChatOptions.builder().N(1).build();

// After
OpenAiChatOptions.builder().n(1).build();

Ollama​

重命名:spring.ai.ollama.chat.think-option 更名为 spring.ai.ollama.chat.think​

spring.ai.ollama.chat.think-option 配置属性已重命名为 spring.ai.ollama.chat.think。

相应地更新你的 application.properties 或 application.yml:

# Before
spring.ai.ollama.chat.think-option=true

# After
spring.ai.ollama.chat.think=true

Minimax 专用支持已由 Anthropic 支持取代​

Minimax 专属支持已被移除,改为推荐使用 Anthropic 支持,这也是 Minimax 官方建议的方式。请改用 Spring AI 的 Anthropic 支持,配置基础 URL 为 https://api.minimax.io/anthropic,并使用 MiniMax 模型。不再支持嵌入(Embeddings)。

JSON 工具重构​

新增:JsonHelper 以及更新后的 JacksonUtils​

spring-ai-commons 中引入了一个新的 JsonHelper 类,作为执行 JSON 序列化和反序列化的标准方式。该类可实例化,并支持接受自定义的 JsonMapper,从而能够根据具体使用场景轻松定制 JSON 行为。JacksonUtils 新增了一个静态方法 getDefaultJsonMapper(),用于返回一个共享的、预配置好的 JsonMapper 实例。

JsonHelper 集中了之前分散在 JsonParser、ModelOptionsUtils 和 McpJsonParser 中的 JSON 操作。默认构造函数使用 JacksonUtils.getDefaultJsonMapper() 中的共享 mapper。如果需要不同的序列化设置,请注入自定义的 JsonMapper:

// Default — uses the shared JsonMapper from JacksonUtils
JsonHelper jsonHelper = new JsonHelper();

// Custom — supply your own JsonMapper
JsonMapper myMapper = JsonMapper.builder()
.addModule(new JavaTimeModule())
.build();
JsonHelper customHelper = new JsonHelper(myMapper);

已弃用:JsonParser​

JsonParser(位于 org.springframework.ai.util.json 中)已弃用并计划移除。现在所有方法都委托给 JsonHelper 处理。

影响​

调用 JsonParser 方法的代码在编译时会看到弃用警告。

Migration​
变更前变更后
JsonParser.getJsonMapper()JacksonUtils.getDefaultJsonMapper()
JsonParser.fromJson(json, MyType.class)jsonHelper.fromJson(json, MyType.class)
JsonParser.fromJson(json, type)jsonHelper.fromJson(json, type)
JsonParser.toJson(object)jsonHelper.toJson(object)
JsonParser.toTypedObject(value, type)jsonHelper.convertToTypedObject(value, type)

移除:来自 ModelOptionsUtils 的 JSON 方法​

ModelOptionsUtils 的以下成员已被移除,因为模型选项不再直接依赖 Jackson。

已移除的成员替代方案
ModelOptionsUtils.JSON_MAPPERJacksonUtils.getDefaultJsonMapper()
ModelOptionsUtils.jsonToMap(String)jsonHelper.fromJsonToMap(json)
ModelOptionsUtils.jsonToObject(String, Class<T>)jsonHelper.fromJson(json, type)
ModelOptionsUtils.toJsonString(Object)jsonHelper.toJson(object)
ModelOptionsUtils.toJsonStringPrettyPrinter(Object)JacksonUtils.getDefaultJsonMapper().writerWithDefaultPrettyPrinter().writeValueAsString(object)
ModelOptionsUtils.getJsonSchema(Type, boolean)JsonSchemaUtils.getJsonSchema(type, toUpperCase)
ModelOptionsUtils.getJsonSchema(Type)JsonSchemaUtils.getJsonSchema(type)
ModelOptionsUtils.toUpperCaseTypeValues(ObjectNode)JsonSchemaUtils.toUpperCaseTypeValues(node)
影响​

引用已移除字段或方法的代码将无法编译。

迁移​
// Before
import org.springframework.ai.model.ModelOptionsUtils;

Map<String, Object> map = ModelOptionsUtils.jsonToMap(jsonString);
String json = ModelOptionsUtils.toJsonString(myObject);
JsonMapper mapper = ModelOptionsUtils.JSON_MAPPER;

// After
import org.springframework.ai.util.JsonHelper;
import org.springframework.ai.util.JacksonUtils;

private static final JsonHelper jsonHelper = new JsonHelper();

Map<String, Object> map = jsonHelper.fromJsonToMap(jsonString);
String json = jsonHelper.toJson(myObject);
JsonMapper mapper = JacksonUtils.getDefaultJsonMapper();

已移除:McpJsonParser​

McpJsonParser(位于 org.springframework.ai.mcp.annotation.method.tool.utils)已被删除。其功能现在由 JsonHelper 提供。

迁移​
迁移前迁移后
McpJsonParser.toMap(object)jsonHelper.convertToMap(object)
McpJsonParser.fromMap(map, MyType.class)jsonHelper.convertFromMap(map, MyType.class)
McpJsonParser.fromMap(map, typeReference)jsonHelper.convertFromMap(map, parameterizedTypeReference)

MCP 征询 API:TypeReference 被 ParameterizedTypeReference 替换​

之前接受 tools.jackson.core.type.TypeReference<T> 的 elicit(…​) 重载方法,在 McpAsyncRequestContext 和 McpSyncRequestContext 中,现在改为接受 org.springframework.core.ParameterizedTypeReference<T>。

影响​

调用这些方法时使用 Jackson TypeReference 的任何代码都将无法编译。

受影响的方法签名:

  • McpAsyncRequestContext.elicit(TypeReference<T>)

  • McpAsyncRequestContext.elicit(Consumer<ElicitationSpec>, TypeReference<T>)

  • McpSyncRequestContext.elicit(TypeReference<T>)

  • McpSyncRequestContext.elicit(Consumer<ElicitationSpec>, TypeReference<T>)

Migration​

将 Jackson 的 TypeReference 匿名类替换为 Spring 的 ParameterizedTypeReference 匿名类:

// Before
import tools.jackson.core.type.TypeReference;

Mono<StructuredElicitResult<Map<String, Object>>> result =
context.elicit(e -> e.message("Please fill in the form"),
new TypeReference<Map<String, Object>>() {});

// After
import org.springframework.core.ParameterizedTypeReference;

Mono<StructuredElicitResult<Map<String, Object>>> result =
context.elicit(e -> e.message("Please fill in the form"),
new ParameterizedTypeReference<Map<String, Object>>() {});

同样的更改也适用于 McpSyncRequestContext:

// Before
StructuredElicitResult<Person> result =
context.elicit(e -> e.message("Provide your details"),
new TypeReference<Person>() {});

// After
StructuredElicitResult<Person> result =
context.elicit(e -> e.message("Provide your details"),
new ParameterizedTypeReference<Person>() {});

Google GenAI 嵌入:GoogleGenAiEmbeddingConnectionDetails 包变更​

GoogleGenAiEmbeddingConnectionDetails 已从 org.springframework.ai.google.genai 移至 org.springframework.ai.google.genai.embedding。

影响​

直接导入 GoogleGenAiEmbeddingConnectionDetails 的任何代码都将无法编译。

迁移​

更新导入语句:

// Before
import org.springframework.ai.google.genai.GoogleGenAiEmbeddingConnectionDetails;

// After
import org.springframework.ai.google.genai.embedding.GoogleGenAiEmbeddingConnectionDetails;

ChatClient 工具调用​

自动 ToolCallingAdvisor 注册​

ChatClient 现在始终会自动在 advisor 链中注册 ToolCallingAdvisor(除非明确禁用),因此无论工具是静态配置的还是由其他 advisor 在运行时注入的,模型请求的工具调用都会被自动处理。

Impact​

已经显式添加了 ToolCallingAdvisor 的现有代码会导致该 Advisor 在链中出现两次——一次来自显式添加,一次来自自动注册。

迁移​

移除链中显式的 ToolCallingAdvisor,让自动注册机制来处理。如果你需要自定义配置,可以在构建 ChatClient 时提供一个预配置的 ToolCallingAdvisor.Builder(参见 自定义默认 ToolCallingAdvisor 部分),或者禁用自动注册并手动注册该 advisor:

// Before — manual registration
chatClient.prompt("What's the weather?")
.tools(weatherTool)
.advisors(ToolCallingAdvisor.builder().build())
.call().content();

// After — auto-registration handles it; no explicit advisor needed
chatClient.prompt("What's the weather?")
.tools(weatherTool)
.call().content();

// Or, to keep full control, disable auto-registration explicitly
chatClient.prompt("What's the weather?")
.tools(weatherTool)
.advisors(
AdvisorParams.toolCallingAdvisorAutoRegister(false),
ToolCallingAdvisor.builder().build()
)
.call().content();

新增:ToolAdvisor 标记接口​

已添加 ToolAdvisor 标记接口,ToolCallingAdvisor 实现了该接口。DefaultChatClient 会检查该标记以决定是否自动注册 ToolCallingAdvisor——如果责任链中已有任意一个 Advisor 实现了 ToolAdvisor,则跳过自动注册。

拥有工具调用生命周期的自定义 Advisor 应实现 ToolAdvisor,以防止自动添加重复的 ToolCallingAdvisor。

新增:MemoryAdvisor 标记接口​

已添加一个 MemoryAdvisor 标记接口。BaseChatMemoryAdvisor 现在继承自该接口。DefaultChatClient 使用此标记来检测下游的内存顾问,并在存在内存顾问时禁用 ToolCallingAdvisor 的内部对话历史。

未继承 BaseChatMemoryAdvisor 但需要与工具调用自动注册逻辑集成的自定义内存顾问应实现 MemoryAdvisor 接口。

新特性:用于自定义 ToolCallingAdvisor 配置的 ChatClient.builder() 重载方法​

新增的具有 5 个参数的 ChatClient.builder() 静态方法以及与之匹配的 DefaultChatClientBuilder 构造函数接受一个 ToolCallingAdvisor.Builder<?>,用于配置在自动注册过程中使用的 advisor:

ChatClient chatClient = ChatClient
.builder(chatModel, observationRegistry, null, null,
ToolCallingAdvisor.builder().toolCallingManager(myToolCallingManager))
.build();

Spring Boot 用户应优先考虑使用以下选项之一:

  • 设置 spring.ai.chat.client.tool-calling.advisor-order 以控制 advisor 在链中的位置。

  • 声明一个 ToolCallingAdvisor.Builder<?> bean 以完全替换自动配置的 builder(通过 @ConditionalOnMissingBean 进行抑制)。

已移除:ChatClient 上的 ToolSpec 消费者 API​

tools(Consumer<ToolSpec>) / defaultTools(Consumer<ToolSpec>) API 和 ChatClient.ToolSpec 接口已被移除。tools(Object…​) / defaultTools(Object…​) 方法现在直接接受 ToolCallback、ToolCallbackProvider、带有 @Tool 注解的 POJO 实例,以及这些类型的集合或数组。上下文通过专用的 toolContext() / defaultToolContext() 方法单独设置。

迁移​
// Before
chatClient.prompt()
.tools(t -> t.callbacks(myCallback).context("tenantId", "acme"))
.call().content();

// After
chatClient.prompt()
.tools(myCallback)
.toolContext(Map.of("tenantId", "acme"))
.call().content();

ChatClientRequestSpec 上的各个 toolCallbacks() 方法以及 ChatClient.Builder 上的 defaultToolCallbacks() 方法已被弃用,建议使用 tools(Object…​) / defaultTools(Object…​) 替代。

变更:MethodToolCallbackProvider 现在抛出 IllegalArgumentException 而不是 IllegalStateException​

MethodToolCallbackProvider 在以下两种情况下现在会抛出 IllegalArgumentException(而非 IllegalStateException):

  • 当工具对象没有使用 @Tool 注释的方法时。

  • 当多个工具对象产生具有重复名称的回调时。

影响​

捕获 MethodToolCallbackProvider(直接或通过 ToolCallbacks.from())抛出的 IllegalStateException 的代码需要更新。

// Before
try {
ToolCallbacks.from(myObject);
}
catch (IllegalStateException e) { ... }

// After
try {
ToolCallbacks.from(myObject);
}
catch (IllegalArgumentException e) { ... }

移除:Spring Bean 工具解析(SpringBeanToolCallbackResolver)​

SpringBeanToolCallbackResolver 以及声明裸 Function / Supplier / Consumer bean 并通过 toolNames() 按名称引用的模式已被移除。toolNames() 方法已从所有聊天选项类以及 ChatClient 中移除。

迁移​

直接声明 ToolCallback Bean,而不是原始的功能性 Bean:

// Before — bare Function bean resolved by name at runtime
@Bean
@Description("Get the weather in location")
Function<WeatherRequest, WeatherResponse> currentWeather() {
return weatherService::getWeather;
}

// After — explicit ToolCallback bean
@Bean
ToolCallback currentWeather() {
return FunctionToolCallback.builder("currentWeather", weatherService::getWeather)
.description("Get the weather in location")
.inputType(WeatherRequest.class)
.build();
}

然后使用 tools() 直接注册该 bean:

chatClient.prompt("What's the weather like in Copenhagen?")
.tools(currentWeather)
.call().content();

或者,使用带有 @Tool 注解的方法以实现声明式方法(请参阅 Tools API)。

云绑定​

提供与 github.com/spring-cloud/spring-cloud-bindings 集成的 spring-ai-spring-cloud-bindings 模块已被移除。

BeanOutputConverter JSON Schema 生成​

BeanOutputConverter 现在将 JSON Schema 生成委托给 JsonSchemaGenerator,使结构化输出转换与工具调用中使用的 JSON Schema 行为保持一致。

影响​

  • Kotlin 主构造函数中可选的属性(可空或声明了默认值)不再包含在 JSON Schema 的 required 数组中。

  • 标注了 @JsonProperty(required = false) 的属性,包括未指定 required 的 @JsonProperty 声明,不再被视为必需。

  • 生成的 schema 现在包含面向原始类型的 OpenAPI 风格 format 提示(例如 int 对应 int32,long 对应 int64,LocalDateTime 对应 date-time),与工具调用中使用的格式约定保持一致。

  • BeanOutputConverter.postProcessSchema(JsonNode) 扩展点已被移除。重写此方法的自定义子类将无法编译。

迁移​

若要自定义 JSON Schema 生成,请改为重写 BeanOutputConverter.generateSchema()。子类可以通过委托给 super.generateSchema() 对默认 Schema 进行后处理。

// Before
class CustomConverter extends BeanOutputConverter<MyType> {

CustomConverter() {
super(MyType.class);
}

@Override
protected void postProcessSchema(JsonNode schema) {
// mutate schema
}
}

// After
class CustomConverter extends BeanOutputConverter<MyType> {

CustomConverter() {
super(MyType.class);
}

@Override
protected String generateSchema() {
String schema = super.generateSchema();
// post-process schema
return schema;
}
}

对 Azure Cosmos DB 的支持​

Azure Cosmos DB 向量存储(spring-ai-azure-cosmos-db-store)和聊天记忆仓库(spring-ai-model-chat-memory-repository-cosmos-db)模块,以及它们对应的自动配置和 Starter,已从 Spring AI 项目中移除。

Azure Cosmos DB 的支持现已作为由 Azure Cosmos DB 团队维护的外部模块提供。有关文档和依赖项坐标,请参阅 azurecosmosdb.github.io/spring-ai/docs/index.html。

MCP SDK 破坏性更改:必需字段​

MCP SDK 通过紧凑记录构造函数中的 Assert.notNull(),在构造时将先前可选的字段强制为必填字段。

破坏性变更:CreateMessageResult — model 现在为必填项​

// Before
CreateMessageResult.builder()
.content(TextContent.builder(response).build())
.build();

// After
CreateMessageResult.builder(Role.ASSISTANT, response, modelHint)
.build();

破坏性变更:CreateMessageRequest — maxTokens 现在为必填项​

// Before
CreateMessageRequest.builder()
.messages(messages)
.build();

// After
CreateMessageRequest.builder(messages, 500)
.build();

已弃用的 Builder API​

以下无需参数的构造函数和 builder() 方法已被弃用,转而采用需要预先提供必填参数的工厂方法:

已弃用替代方案
new TextContent(text)TextContent.builder(text).build()
new ReadResourceResult(contents)ReadResourceResult.builder(contents).build()
new GetPromptResult(description, messages)GetPromptResult.builder(messages).description(description).build()
new ProgressNotification(token, progress, total, message)ProgressNotification.builder(token, progress).total(total).message(message).build()
LoggingMessageNotification.builder()LoggingMessageNotification.builder(level, data)
ElicitRequest.builder()ElicitRequest.builder(message, requestedSchema)
CallToolRequest.builder()CallToolRequest.builder(name)

可观测性​

工具调用​

用于工具调用操作的观测数据变更如下:

  • 跨度名称为 execute_tool <tool-name>,而不是 tool_call <tool-name>。

  • 指标/跨度属性 gen_ai.operation.name 的值为 execute_tool,而不是 framework。

  • 新增 spring.ai.tool.type 指标/跨度属性,用于捕获工具类型(例如 function)。

  • 新增 spring.ai.tool.call.id 跨度属性,用于捕获由聊天模型识别的工具调用 ID。

已移除的模块​

spring-ai-hanadb-store 模块移除​

sring-ai-hanadb-store 模块已从 Spring AI 中移除。

聊天记忆顾问:现在需要会话 ID​

对于内置的记忆顾问(MessageChatMemoryAdvisor 和 VectorStoreChatMemoryAdvisor),会话 ID 不再是可选的。通过这些顾问进行的每次调用都必须通过顾问上下文提供 ChatMemory.CONVERSATION_ID。如果该值缺失或为 null,顾问会立即抛出 IllegalArgumentException。

移除:ChatMemory.DEFAULT_CONVERSATION_ID​

常量 ChatMemory.DEFAULT_CONVERSATION_ID(值为 "default")已从 ChatMemory 接口中移除。

影响​

引用此常量的代码将无法编译。

迁移​

将任何对 ChatMemory.DEFAULT_CONVERSATION_ID 的引用替换为显式对话 ID 字符串,或从您的会话/用户上下文中派生的值。

// Before
String conversationId = ChatMemory.DEFAULT_CONVERSATION_ID;

// After
String conversationId = "my-conversation-id";

移除:内存顾问中的 .conversationId() 构建器方法​

.conversationId(String) 构建器方法已从 MessageChatMemoryAdvisor.Builder 和 VectorStoreChatMemoryAdvisor.Builder 中移除。不再支持在构造时设置默认的 conversation ID。

影响​

调用这些构建器中任意一个的 .conversationId() 方法的代码将无法编译。

迁移​

移除 .conversationId() 构建器调用,并始终在调用时通过顾问上下文使用 ChatMemory.CONVERSATION_ID 来提供会话 ID:

// Before
ChatClient chatClient = ChatClient.builder(chatModel)
.defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory)
.conversationId("my-session")
.build())
.build();

chatClient.prompt()
.user("Hello!")
.call()
.content();

// After
ChatClient chatClient = ChatClient.builder(chatModel)
.defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build())
.build();

chatClient.prompt()
.user("Hello!")
.advisors(a -> a.param(ChatMemory.CONVERSATION_ID, "my-session"))
.call()
.content();

变更:BaseChatMemoryAdvisor.getConversationId() 方法签名​

默认方法 BaseChatMemoryAdvisor.getConversationId(Map, String) 已被 getConversationId(Map) 替代。

影响​

如果自定义的 advisor 实现重写或调用了双参数形式,将会导致编译失败。

迁移​

更新覆盖项和调用点,使其使用单参数形式。在调用该方法之前,确保上下文中始终包含 ChatMemory.CONVERSATION_ID。

// Before
String conversationId = getConversationId(context, this.defaultConversationId);

// After
String conversationId = getConversationId(context); // throws if CONVERSATION_ID is absent

已移除:PromptChatMemoryAdvisor​

PromptChatMemoryAdvisor 已被移除。请使用 MessageChatMemoryAdvisor 作为替代。

影响​

导入或引用 PromptChatMemoryAdvisor 的代码将无法编译。

迁移​

使用 MessageChatMemoryAdvisor 替换 PromptChatMemoryAdvisor。Builder API 完全相同。与将记忆作为纯文本注入系统提示不同,MessageChatMemoryAdvisor 会直接在提示中将对话历史作为聊天消息包含进来。

// Before
ChatClient chatClient = ChatClient.builder(chatModel)
.defaultAdvisors(PromptChatMemoryAdvisor.builder(chatMemory).build())
.build();

// After
ChatClient chatClient = ChatClient.builder(chatModel)
.defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build())
.build();

ChatClient 选项现需使用构建器​

使用 ChatClient 时,.options() / .defaultOptions() 方法现在接受 ChatOptions.Builder(或任何特定提供商的 builder 子类型),而不是完全构建好的 ChatOptions 实例。此更改通过方法的泛型类型约束 <B extends ChatOptions.Builder<?>> 在编译时强制执行。

选项构建器在与第一个顾问调用前与模型的默认选项合并,因此只有您显式设置的字段会覆盖默认值。

// Before — passing a built ChatOptions instance (no longer compiles with ChatClient)
ChatOptions opts = AnthropicChatOptions.builder()
.maxTokens(100)
.temperature(0.7)
.build();
String response = chatClient.prompt("Tell me a joke")
.options(opts)
.call().content();

// After — pass the builder directly
String response = chatClient.prompt("Tell me a joke")
.options(AnthropicChatOptions.builder()
.maxTokens(100)
.temperature(0.7))
.call().content();
备注

此限制仅适用于 ChatClient。直接调用 ChatModel.call(Prompt) 时,Prompt 必须携带一个完全构建的、具体类型所期望的 ChatOptions 实例(例如,对于 AnthropicChatModel 应为 AnthropicChatOptions)。ChatModel 不会合并选项:如果 Prompt.getOptions() 非 null,则将直接使用;如果为 null,则使用模型自身的默认选项。在 ChatModel 层面不会发生部分合并。

buildRequestPrompt 已从公共 API 中移除​

buildRequestPrompt 方法不再属于公共 API。它此前被错误地暴露为公共方法,现已恢复为其私有的或包级别的可见性。

OpenAI Java SDK 迁移​

Spring AI 现在在 spring-ai-openai 模块中为所有 OpenAI 模型(Chat、Embeddings、Image、Audio Speech、Audio Transcription 和 Moderation)使用官方 openai-java SDK 作为底层实现。

过渡应当无缝衔接,对于 spring-ai-openai 模块的现有用户来说,预计不会出现重大破坏性变更。所有属性(以 spring.ai.openai.* 为前缀)、构建器(builders)以及选项均保持完整不变。现有的 extraBody 配置参数会透明地映射到 openai-java SDK 中的 additionalBodyProperties。

移除 spring-ai-azure-openai 模块​

spring-ai-azure-openai 模块(及其关联的 Spring Boot starter spring-ai-starter-model-azure-openai 和自动配置 spring-ai-autoconfigure-model-azure-openai)已从 Spring AI 中移除。

现有用户应改用 spring-ai-openai 模块(及相关 starter 和自动配置),并相应地调整类名(例如移除 Azure 前缀)和配置属性。

spring-ai-openai-sdk 模块移除​

spring-ai-openai-sdk 模块(及其相关的 Spring Boot starter spring-ai-starter-model-openai-sdk 和自动配置 spring-ai-autoconfigure-model-openai-sdk)已从 Spring AI 中移除。

现有用户应改用 spring-ai-openai 模块(以及相关的 starter 和自动配置),并相应调整类名(例如移除 Sdk 后缀)和配置属性。

移除 spring-ai-oci-genai 模块​

MCP Java SDK 升级至 2.0.0​

Spring AI 2.0.0 将 MCP Java SDK 从 1.1.x 升级至 2.0.0。此次发布在 SDK 层面引入了多项破坏性变更,可能会影响那些直接操作 MCP 类型的应用程序。

默认启用服务端工具输入验证​

MCP 服务器现在会在调用工具处理器之前,根据工具的 JSON schema 对传入的工具参数进行验证。如果验证失败,将生成一个 CallToolResult,其中 isError=true,并附带描述性的错误信息。

影响​

先前接受松散类型或缺失工具参数的现有 MCP 服务器,现在可能会向发送不符合规范的参数的客户端返回验证错误。

迁移​

确保您的工具定义包含准确的 JSON schema,且所有客户端均发送符合要求的参数。若要禁用验证并恢复 2.0 之前的行为,请在服务器构建器上设置 validateToolInputs(false):

McpServer.sync(transportProvider)
.validateToolInputs(false)
.tool(myTool, handler)
.build();
备注

在使用 @McpTool 注解时,Spring AI 会根据方法参数自动生成 JSON 模式(schema)。这些模式与内置验证器兼容,无需额外操作。

Tool.inputSchema 从 JsonSchema 变更为 Map<String, Object>​

McpSchema.Tool.inputSchema()(以及 outputSchema())现在返回 Map<String, Object>,而不是之前的 JsonSchema 记录。这允许任意 JSON Schema 方言关键字(如 $ref、unevaluatedProperties、供应商扩展)在不被裁剪的情况下往返处理。

影响​

使用 tool.inputSchema() 作为 JsonSchema 对象的代码将无法编译。

迁移​

切换为 Map<String, Object>:

// Before
McpSchema.JsonSchema schema = tool.inputSchema();

// After
Map<String, Object> schema = tool.inputSchema();

在通过 McpSchema.Tool.Builder 构建工具时,出于向后兼容性的考虑,已弃用的 inputSchema(JsonSchema) 辅助方法仍然可用,但建议优先使用 inputSchema(Map) 或 inputSchema(McpJsonMapper, String)。

备注

使用 @McpTool 注解或 Spring AI 的 SyncMcpToolProvider / AsyncMcpToolProvider 的应用不受影响 — Spring AI 在内部处理 schema 生成。

Builder.customizeRequest() 从 HTTP 客户端传输中移除​

已弃用的 Builder.customizeRequest() 方法已从 HttpClientSseClientTransport.Builder 和 HttpClientStreamableHttpTransport.Builder 中移除。

影响​

直接在这些 builder 类型上调用 .customizeRequest() 的任何代码都将无法编译。

迁移​

使用 httpRequestCustomizer()(同步)或 asyncHttpRequestCustomizer()(异步)替换 customizeRequest():

// Before
HttpClientSseClientTransport.builder(baseUrl)
.customizeRequest(req -> req.header("Authorization", "Bearer token"))
.build();

// After
HttpClientSseClientTransport.builder(baseUrl)
.httpRequestCustomizer(req -> req.header("Authorization", "Bearer token"))
.build();
备注

如果您已经迁移到 McpClientCustomizer<B> API,则无需进一步操作。

已移除的 Sealed MCP Schema 接口​

以下接口不再为 sealed:McpSchema.JSONRPCMessage、McpSchema.Request、McpSchema.Result、McpSchema.Notification、McpSchema.ResourceContents、McpSchema.CompleteReference 和 McpSchema.Content。

影响​

依赖 sealed 层级关系来保证完整性的穷举 switch 表达式,在没有 default 分支的情况下将不再编译通过。

迁移​

为这些类型的任何穷举 switch 添加一个 default 分支:

// Before (no default needed when McpSchema.Content was sealed)
String text = switch (content) {
case McpSchema.TextContent tc -> tc.text();
case McpSchema.ImageContent ic -> "[image]";
case McpSchema.EmbeddedResource er -> "[resource]";
};

// After
String text = switch (content) {
case McpSchema.TextContent tc -> tc.text();
case McpSchema.ImageContent ic -> "[image]";
case McpSchema.EmbeddedResource er -> "[resource]";
default -> throw new IllegalArgumentException("Unknown content type: " + content);
};
备注

这种更改不太可能影响大多数通过注解或 Spring AI 更高层抽象与 MCP 交互的 Spring AI 用户。

Usage 上的统一缓存使用指标​

org.springframework.ai.chat.metadata.Usage 接口新增两个默认方法:getCacheReadInputTokens() 和 getCacheWriteInputTokens()。当提供商未报告相应值时,这两个方法均返回 null。

Anthropic、Bedrock Converse、OpenAI 和 Google GenAI 会填充它们:Anthropic 和 Bedrock 支持双向操作,OpenAI 和 Google 仅支持缓存读取。

将代码从原生类型转换或读取这些数字的特定提供者元数据键,可以切换到接口方法。示例请参考 Prompt Cache Usage Metrics。

Anthropic 模块​

spring-ai-anthropic 现在基于 com.anthropic:anthropic-java 构建,取代了之前手动实现的 RestClient / WebClient 实现。

对于大多数应用程序而言,此更改是透明的。Maven 制品、spring.ai.anthropic.* 配置,以及 AnthropicChatModel / AnthropicChatOptions / ChatClient API 均保持不变,通过 ChatClient 或 ChatModel.call(Prompt) 调用的代码无需更新。

从 org.springframework.ai.anthropic.api 导入的代码、使用 AnthropicApi 参数构建的 AnthropicChatModel,或依赖于旧版 maxTokens 默认值的代码,需要注意。

影响​

  • org.springframework.ai.anthropic.api.AnthropicApi 及其所有嵌套记录类型(ChatCompletionRequest、ContentBlock、Tool、ToolChoice*、流式事件记录)已被移除。引用这些类的代码将无法编译。

  • 公开的 AnthropicChatModel(AnthropicApi, AnthropicChatOptions, …​) 构造函数已被移除。请使用 AnthropicChatModel.builder()。

  • AnthropicChatOptions#maxTokens 的默认值已从 500 更改为 4096。之前达到旧上限的响应现在将持续更长时间,相应地,token 使用量也会更高。

  • AnthropicCacheOptions、AnthropicCacheStrategy、AnthropicCacheTtl、CacheBreakpointTracker 和 CacheEligibilityResolver 已从 api(以及 api.utils)包移动到根包 org.springframework.ai.anthropic 中。

  • AnthropicCacheType、StreamHelper 和 metadata.AnthropicRateLimit 已被移除;现在直接使用等效的 SDK 类型(CacheControlEphemeral、AsyncStreamResponse<RawMessageStreamEvent>、RateLimitException)。

  • CitationDocument 已重命名为 AnthropicCitationDocument。

  • com.anthropic:anthropic-java 会间接将 com.squareup.okhttp3:okhttp 引入类路径。

Migration​

更新已移动的缓存和引用类的导入:

BeforeAfter
org.springframework.ai.anthropic.api.AnthropicCacheOptionsorg.springframework.ai.anthropic.AnthropicCacheOptions
org.springframework.ai.anthropic.api.AnthropicCacheStrategyorg.springframework.ai.anthropic.AnthropicCacheStrategy
org.springframework.ai.anthropic.api.AnthropicCacheTtlorg.springframework.ai.anthropic.AnthropicCacheTtl
org.springframework.ai.anthropic.api.utils.CacheBreakpointTrackerorg.springframework.ai.anthropic.CacheBreakpointTracker
org.springframework.ai.anthropic.api.utils.CacheEligibilityResolverorg.springframework.ai.anthropic.CacheEligibilityResolver
org.springframework.ai.anthropic.api.CitationDocumentorg.springframework.ai.anthropic.AnthropicCitationDocument

AnthropicCacheStrategy(NONE、TOOLS_ONLY、SYSTEM_ONLY、SYSTEM_AND_TOOLS、CONVERSATION_HISTORY)和 AnthropicCacheTtl(FIVE_MINUTES、ONE_HOUR)保持相同的枚举值。

将直接构造函数的使用替换为构建器:

// Before
AnthropicApi anthropicApi = new AnthropicApi(apiKey);
AnthropicChatModel chatModel = new AnthropicChatModel(anthropicApi, options);

// After
AnthropicChatModel chatModel = AnthropicChatModel.builder()
.apiKey(apiKey)
.defaultOptions(options)
.build();

如果你之前依赖 500 token 的默认值来限制成本,请显式地设置它:

AnthropicChatOptions.builder()
.maxTokens(500)
// ...
.build();

将 Anthropic 模块迁移至官方 Java SDK 涵盖了其余内容:直接 SDK 访问、流式处理行为、提示缓存、引用以及已移除的类型。

新建聊天选项​

spring-ai-anthropic 还新增了四个聊天选项。各项的完整参考请参见 Anthropic Chat;重点如下:

选项所添加的内容
思考显示Display.SUMMARIZED 和 Display.OMITTED 位于 thinkingEnabled / thinkingAdaptive 构建器中,允许 Claude 使用思考预算而无需展示完整的推理过程。
服务层级AnthropicServiceTier.AUTO / STANDARD_ONLY 用于 Anthropic 的优先级容量层级。属性 spring.ai.anthropic.chat.service-tier。
内置网页搜索AnthropicWebSearchTool 允许 Claude 在请求过程中进行网页搜索。属性位于 spring.ai.anthropic.chat.web-search-tool.* 下。
推理地理位置inferenceGeo("us") 或 inferenceGeo("eu") 用于数据驻留路由。属性 spring.ai.anthropic.chat.inference-geo。
备注

如果您是从 1.1.x(或 1.0.x)版本进行升级,请参阅 Migrating the Anthropic Module to the Official Java SDK 了解 RestClient 迁移至官方 SDK 的完整指南。

MCP 注解迁移至 Spring AI​

外部库 org.springaicommunity:mcp-annotations 已不再作为 mcp-annotations 模块的依赖。其类现已作为 Spring AI 的一部分,位于新的包结构下。

影响​

  • 所有 MCP 注解和 Provider 类都有了新的全限定名(fully-qualified names)。
  • org.springaicommunity:mcp-annotations 构件不再由 Spring AI 传递依赖提供。
  • 任何导入 org.springaicommunity.mcp.* 的代码都将编译失败。

包重命名​

旧包新包
org.springaicommunity.mcp.annotation.*org.springframework.ai.mcp.annotation.*
org.springaicommunity.mcp.method.*org.springframework.ai.mcp.annotation.method.*
org.springaicommunity.mcp.provider.*org.springframework.ai.mcp.annotation.provider.*

迁移​

更新您应用程序代码中的所有导入:

// Before
import org.springaicommunity.mcp.annotation.McpTool;
import org.springaicommunity.mcp.annotation.McpPrompt;
import org.springaicommunity.mcp.annotation.McpResource;
import org.springaicommunity.mcp.annotation.McpSampling;
import org.springaicommunity.mcp.provider.tool.SyncMcpToolProvider;
import org.springaicommunity.mcp.provider.prompt.AsyncMcpPromptProvider;

// After
import org.springframework.ai.mcp.annotation.McpTool;
import org.springframework.ai.mcp.annotation.McpPrompt;
import org.springframework.ai.mcp.annotation.McpResource;
import org.springframework.ai.mcp.annotation.McpSampling;
import org.springframework.ai.mcp.annotation.provider.tool.SyncMcpToolProvider;
import org.springframework.ai.mcp.annotation.provider.prompt.AsyncMcpPromptProvider;

如果您将 org.springaicommunity:mcp-annotations 声明为 Maven 或 Gradle 的直接依赖项,请将其移除——这些类现在由 Spring AI 的 spring-ai-mcp-annotations 模块提供。

使用 OpenRewrite 进行自动迁移​

你可以使用提供的 OpenRewrite recipe 来自动完成所有导入和依赖项的更改。

从命令行应用 migrate-to-2-0-0-M3.yaml recipe:

mvn org.openrewrite.maven:rewrite-maven-plugin:6.32.0:run \
-Drewrite.configLocation=https://raw.githubusercontent.com/spring-projects/spring-ai/refs/heads/main/src/rewrite/migrate-to-2-0-0-M3.yaml \
-Drewrite.activeRecipes=org.springframework.ai.migration.M3MigrateMcpAnnotations \
-Dmaven.compiler.failOnError=false

该配方会自动执行以下两项更改:

  1. 移除 org.springaicommunity:mcp-annotations Maven 依赖。

  2. 重写 所有 .java 文件中的 import 语句,使其指向新的 org.springframework.ai.mcp.annotation.* 包。

若要一次性运行所有 M3 迁移,请使用 umbrella recipe —— 参见 [run-all-m3-migrations]。

MCP Spring 传输模块已迁移至 Spring AI​

mcp-spring-webflux 和 mcp-spring-webmvc 传输模块不再由 MCP Java SDK 提供。从 Spring AI 2.0 开始,它们已成为 Spring AI 项目的一部分。

影响​

  • 两个构件的 Maven 组 ID 已更改。

  • 所有 Spring 特定的传输类的 Java 包名已更改。

  • MCP Java SDK 的版本要求已从 0.18.x 提升至 1.0.x。

Maven 依赖 Group ID 变更​

<dependency>
<groupId>io.modelcontextprotocol.sdk</groupId>
<artifactId>mcp-spring-webflux</artifactId>
</dependency>

<dependency>
<groupId>io.modelcontextprotocol.sdk</groupId>
<artifactId>mcp-spring-webmvc</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>mcp-spring-webflux</artifactId>
</dependency>

<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>mcp-spring-webmvc</artifactId>
</dependency>
备注

在使用 spring-ai-bom 或 Spring AI MCP starter(spring-ai-starter-mcp-server-webflux、spring-ai-starter-mcp-server-webmvc、spring-ai-starter-mcp-client-webflux)时,无需显式指定版本——BOM 会自动进行管理。

Java 包重定位​

所有 Spring 特有的传输类已迁移至 org.springframework.ai 包。

表 1. 服务器传输

类旧包新包
WebFluxSseServerTransportProviderio.modelcontextprotocol.server.transportorg.springframework.ai.mcp.server.webflux.transport
WebFluxStreamableServerTransportProviderio.modelcontextprotocol.server.transportorg.springframework.ai.mcp.server.webflux.transport
WebFluxStatelessServerTransportio.modelcontextprotocol.server.transportorg.springframework.ai.mcp.server.webflux.transport
WebMvcSseServerTransportProviderio.modelcontextprotocol.server.transportorg.springframework.ai.mcp.server.webmvc.transport
WebMvcStreamableServerTransportProviderio.modelcontextprotocol.server.transportorg.springframework.ai.mcp.server.webmvc.transport
WebMvcStatelessServerTransportio.modelcontextprotocol.server.transportorg.springframework.ai.mcp.server.webmvc.transport

表 2. 客户端传输

类旧包新包
WebFluxSseClientTransportio.modelcontextprotocol.client.transportorg.springframework.ai.mcp.client.webflux.transport
WebClientStreamableHttpTransportio.modelcontextprotocol.client.transportorg.springframework.ai.mcp.client.webflux.transport

Migration​

更新你的 Java 导入:

// Before
import io.modelcontextprotocol.server.transport.WebFluxSseServerTransportProvider;
import io.modelcontextprotocol.server.transport.WebMvcSseServerTransportProvider;
import io.modelcontextprotocol.client.transport.WebFluxSseClientTransport;
import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;

// After
import org.springframework.ai.mcp.server.webflux.transport.WebFluxSseServerTransportProvider;
import org.springframework.ai.mcp.server.webmvc.transport.WebMvcSseServerTransportProvider;
import org.springframework.ai.mcp.client.webflux.transport.WebFluxSseClientTransport;
import org.springframework.ai.mcp.client.webflux.transport.WebClientStreamableHttpTransport;
备注

如果您仅依赖 Spring AI 启动器提供的 Spring Boot 自动配置,则无需对 Java 代码进行任何修改。只需按照上述说明更新 pom.xml/build.gradle 中的依赖坐标即可。

有关完整的 MCP 传输迁移参考,请参阅 升级至 Spring AI 2.0。

使用 OpenRewrite 进行自动化迁移​

您可以使用提供的 OpenRewrite 配方自动执行所有 Maven 依赖项和 Java 导入的更改:

mvn org.openrewrite.maven:rewrite-maven-plugin:6.32.0:run \
-Drewrite.configLocation=https://raw.githubusercontent.com/spring-projects/spring-ai/refs/heads/main/src/rewrite/migrate-to-2-0-0-M3.yaml \
-Drewrite.activeRecipes=org.springframework.ai.migration.M3MigrateMcpSpringTransports \
-Dmaven.compiler.failOnError=false
important

如果你的项目声明了 io.modelcontextprotocol.sdk:mcp-spring-webflux 或 mcp-spring-webmvc 且没有显式指定 <version>(即版本通过 BOM 管理),Maven 将拒绝解析 pom.xml,并且 recipe 永远不会执行。请首先对这些文件进行预补丁处理,然后再运行 OpenRewrite:

# Step 1 – patch the groupIds directly so Maven can load the modules
find . -name "pom.xml" -print0 \
| xargs -0 perl -i -0pe \
's{<groupId>io\.modelcontextprotocol\.sdk</groupId>(\s+)<artifactId>mcp-spring-webflux</artifactId>}{<groupId>org.springframework.ai</groupId>$1<artifactId>mcp-spring-webflux</artifactId>}g;
s{<groupId>io\.modelcontextprotocol\.sdk</groupId>(\s+)<artifactId>mcp-spring-webmvc</artifactId>}{<groupId>org.springframework.ai</groupId>$1<artifactId>mcp-spring-webmvc</artifactId>}g'

# Step 2 – run OpenRewrite to migrate Java imports and remaining POM changes
mvn org.openrewrite.maven:rewrite-maven-plugin:6.32.0:run \
-Drewrite.configLocation=https://raw.githubusercontent.com/spring-projects/spring-ai/refs/heads/main/src/rewrite/migrate-to-2-0-0-M3.yaml \
-Drewrite.activeRecipes=org.springframework.ai.migration.M3MigrateMcpSpringTransports \
-Dmaven.compiler.failOnError=false

要一次性运行所有 M3 迁移,请使用伞式配方(umbrella recipe) — 参见 [run-all-m3-migrations]。

MCP Client 自定义器 API 整合​

McpAsyncClientCustomizer 和 McpSyncClientCustomizer 已被移除,并由单一的通用接口 McpClientCustomizer<B> 替代。

影响​

  • McpAsyncClientCustomizer 已不再存在——任何实现该接口的 Bean 都会导致编译错误。

  • McpSyncClientCustomizer 已不再存在——任何实现该接口的 Bean 都会导致编译错误。

  • McpSyncClientConfigurer 和 McpAsyncClientConfigurer 的构造函数现在接受 List<McpClientCustomizer<…​>>,而非旧的类型特定列表。

  • 在基于 HttpClient 的传输自动配置中(SseHttpClientTransportAutoConfiguration、StreamableHttpHttpClientTransportAutoConfiguration),SDK 级别的 McpSyncHttpClientRequestCustomizer 和 McpAsyncHttpClientRequestCustomizer Bean 不再被应用。传输级别的定制现在分别通过 McpClientCustomizer<HttpClientSseClientTransport.Builder> 和 McpClientCustomizer<HttpClientStreamableHttpTransport.Builder> 实现。

迁移​

用新的通用接口替换你的定制器 bean,该接口由你所需的 spec 或 builder 类型参数化:

// Before
@Bean
public McpSyncClientCustomizer mySyncCustomizer() {
return (name, spec) -> spec.requestTimeout(Duration.ofSeconds(30));
}

@Bean
public McpAsyncClientCustomizer myAsyncCustomizer() {
return (name, spec) -> spec.requestTimeout(Duration.ofSeconds(30));
}

// After
@Bean
public McpClientCustomizer<McpClient.SyncSpec> mySyncCustomizer() {
return (name, spec) -> spec.requestTimeout(Duration.ofSeconds(30));
}

@Bean
public McpClientCustomizer<McpClient.AsyncSpec> myAsyncCustomizer() {
return (name, spec) -> spec.requestTimeout(Duration.ofSeconds(30));
}

针对 HttpClient 传输层的自定义(此前通过 McpSyncHttpClientRequestCustomizer / McpAsyncHttpClientRequestCustomizer 实现):

// Before
@Bean
public McpSyncHttpClientRequestCustomizer myRequestCustomizer() {
return requestBuilder -> requestBuilder.header("Authorization", "Bearer token");
}

// After
@Bean
public McpClientCustomizer<HttpClientSseClientTransport.Builder> mySseTransportCustomizer() {
return (name, builder) -> builder.httpRequestCustomizer(
req -> req.header("Authorization", "Bearer token")
);
}

使用 OpenRewrite 进行自动化迁移​

您可以使用提供的 OpenRewrite recipe 来自动化导入和类型变更:

mvn org.openrewrite.maven:rewrite-maven-plugin:6.32.0:run \
-Drewrite.configLocation=https://raw.githubusercontent.com/spring-projects/spring-ai/refs/heads/main/src/rewrite/migrate-to-2-0-0-M3.yaml \
-Drewrite.activeRecipes=org.springframework.ai.migration.M3MigrateMcpClientCustomizer \
-Dmaven.compiler.failOnError=false

该配方会自动执行以下更改:

  1. 替换了 McpAsyncClientCustomizer 和 McpSyncClientCustomizer 的导入为 McpClientCustomizer,并添加了所需的 import io.modelcontextprotocol.client.McpClient;。

  2. 重写 implements McpAsyncClientCustomizer 为 implements McpClientCustomizer<McpClient.AsyncSpec>。

  3. 重写 implements McpSyncClientCustomizer 为 implements McpClientCustomizer<McpClient.SyncSpec>。

  4. 重写所有其余的使用场景(返回类型、变量声明、参数类型)。

备注

McpSyncHttpClientRequestCustomizer 和 McpAsyncHttpClientRequestCustomizer Bean 不再被传输层自动配置应用。将其迁移到 McpClientCustomizer<TransportBuilder> 需要一个手动步骤——目标构建器类型取决于您正在配置的传输方式(SSE 或 Streamable HTTP)。

若要一次性运行所有 M3 迁移,请使用 umbrella recipe — 详见 [run-all-m3-migrations]。

MCP WebMvc 传输层请求头被规范化为小写​

在 WebMvcSseServerTransportProvider、WebMvcStatelessServerTransport 和 WebMvcStreamableServerTransportProvider 中,传递给 securityValidator.validateHeaders(headers) 的 Map<String, List<String>> 现在已将所有头名称规范为小写。

此前,头部名称(header name)按其原始 HTTP 大小写传递(例如 "Authorization"、"Content-Type")。现在,它们始终为小写(例如 "authorization"、"content-type")。

影响​

自定义的 ServerTransportSecurityValidator 实现如果通过大小写混合的名称查找请求头,将会静默地查找失败。

迁移​

更新 ServerTransportSecurityValidator 中所有标头名称查询,使用小写键:

// Before
public void validateHeaders(Map<String, List<String>> headers) {
List<String> authHeader = headers.get("Authorization");
// ...
}

// After
public void validateHeaders(Map<String, List<String>> headers) {
List<String> authHeader = headers.get("authorization");
// ...
}

从 ToolContext 中移除了对话历史​

对话历史不再自动添加到 ToolContext。ToolContext 类中的 TOOL_CALL_HISTORY 常量和 getToolCallHistory() 方法已被移除。

影响​

  • ToolContext.TOOL_CALL_HISTORY 常量不再存在

  • ToolContext.getToolCallHistory() 方法不再存在

  • 对话历史不再自动填充到 ToolContext 中

为什么做出此更改?​

  1. 内存效率:防止在长对话中内存无限制增长

  2. 关注点分离:工具应只操作其参数,而非管理对话状态

  3. 架构对齐:对话上下文应归属于 advisor 层,而非工具执行层

迁移​

如果您的应用程序需要会话历史管理,请使用 ToolCallingAdvisor:

ChatClient chatClient = ChatClient.builder()
.defaultAdvisors(
ToolCallingAdvisor.builder()
.conversationHistoryEnabled(true) // Full history (default)
.build()
)
.build();

ToolCallingAdvisor 的工作原理:

ToolCallingAdvisor 在 advisor 层面管理对话历史:

  • conversationHistoryEnabled=true(默认值):在整个工具调用迭代过程中,会完整维护对话历史并将其发送至 LLM,从而使 LLM 能够基于完整上下文来综合处理结果

  • conversationHistoryEnabled=false:仅向 LLM 发送最近一次的 工具响应(当 ChatMemory 顾问单独管理历史时非常有用)

关键点: 对话历史由 LLM 用于理解上下文并生成回复,而非由 tools 本身使用。工具仅接收其输入参数以及您明确提供的任何自定义上下文。

工具中的自定义上下文:

ToolContext 仍然可用于向工具传递自定义的应用特定数据:

ChatResponse response = chatClient.prompt()
.user("What's the weather in SF?")
.toolContext(Map.of("userId", "user123", "apiKey", "secret"))
.call()
.chatResponse();

示例流程:

  1. 用户提问:“旧金山和洛杉矶的天气如何?”

  2. LLM 请求工具调用:getWeather(SF) 和 getWeather(LA)

  3. 工具仅基于其参数执行(不包含对话历史)

  4. ToolCallingAdvisor 收集工具结果和对话历史

  5. LLM 从 advisor 接收对话上下文并合成回答:“旧金山的天气是 72°F,洛杉矶是 85°F”

LLM 通过 Advisor 链查看完整的对话,而不是通过 ToolContext。

模型内部方法的访问级别已更改为私有 {#_the_access_level_of_model_internal_methods_changed_to_private}

QWen 3.8 中英对照 Upgrade Notes The access level of model internal methods changed to private

  • 模型类中所有的 internalCall 和 internalStream 方法均已更改为 private。
Impact​
  • 直接调用 xxxModel.internalCall 或 xxxModel.internalStream 方法,将导致编译失败。
迁移​
  • 将所有对 xxxModel.internalCall 的调用替换为 xxxModel.call。

  • 将所有对 xxxModel.internalStream 的调用替换为 xxxModel.stream。

    // Before
    ChatResponse response = model.internalCall(prompt, previousChatResponse);
    Flux<ChatResponse> responseFlux = model.internalStream(prompt, previousChatResponse);

    // After
    ChatResponse response = model.call(prompt);
    Flux<ChatResponse> responseFlux = model.stream(prompt);

OpenSearch 依赖项已升级​

OpenSearch 向量存储依赖项已升级到新版本:

  • OpenSearch Java Client: 2.23.0 → 3.6.0

  • OpenSearch Testcontainers: 2.0.1 → 4.1.0

背景​

此次升级是为了兼容 Spring Boot 4.1.x,该版本使用 HttpClient5 (org.apache.httpcomponents.client5:httpclient5) 5.6 版本。该版本的 HttpClient 存在一项 gzip content formatter 的破坏性变更,因此需要对 OpenSearch Java Client 进行升级。详细信息请参见 OpenSearch Java PR #1851。

影响​

OpenSearch Java Client 3.x 引入了破坏性的 API 变更,这会影响直接与原生 OpenSearch 客户端交互的自定义代码。

迁移​

如果你通过 Spring AI 的 VectorStore 接口使用 OpenSearch 向量存储,则无需任何操作。此次升级是透明的。

Testcontainers 类名已重命名:OpensearchContainer → OpenSearchContainer(正确的驼峰命名法)

Spring AI 的内部实现已更新,以自动处理这些更改。

AbstractFilterExpressionConverter:doSingleValue 现在为抽象方法​

在 AbstractFilterExpressionConverter(被向量存储过滤表达式转换器使用)中,方法 doSingleValue(Object value, StringBuilder context) 已从具体方法变更为抽象方法。扩展 AbstractFilterExpressionConverter 的自定义向量存储实现现在必须显式实现该方法。

影响​

  • 任何扩展了 AbstractFilterExpressionConverter 且未重写 doSingleValue() 的自定义 FilterExpressionConverter 都将无法编译。

  • 实现类必须将单个过滤值(String、Number、Boolean、Date 等)转换为目标格式,并将其追加到提供的 StringBuilder 上下文中。

迁移​

在自定义转换器中实现 doSingleValue(Object value, StringBuilder context)。你可以使用提供的静态辅助方法:

  • 基于 JSON 的过滤器(例如 PostgreSQL JSONPath、Neo4j Cypher、Weaviate):使用 emitJsonValue(Object value, StringBuilder context) 来序列化值,并确保正确的引号使用和转义。

  • 基于 Lucene 的过滤器(例如 Elasticsearch、OpenSearch、GemFire):对于字符串值,使用 emitLuceneString(String value, StringBuilder context),并针对其他类型(数字、布尔值、日期)按照存储引擎的查询语法进行处理。

  • 其他格式:实现自定义逻辑,并将结果追加到 context 中。

备注

框架会在调用 doSingleValue 之前对值进行标准化处理(例如,将 ISO 日期字符串转换为 Date),因此你的实现接收到的已是标准化后的值。如果你需要在标准流程之外构建表达式时进行相同的标准化处理,可以使用静态辅助方法 normalizeDateString(Object)。

修复 MongoDB 聊天记忆中的消息排序​

MongoChatMemoryRepository 已修复为按消息发送顺序(从旧到新)返回消息,以匹配其他所有聊天内存仓库实现。此前,它错误地以相反顺序(从新到旧)返回消息,这破坏了 LLM 的对话流程。

影响​

如果您的应用程序之前使用 MongoChatMemoryRepository 并通过变通方法处理了不正确的排序(例如,在检索后反转消息顺序),您需要移除该变通方法。

迁移​

删除在从 MongoDB 聊天记忆检索消息后反转消息顺序的代码:

// BEFORE (with workaround for bug):
List<Message> messages = chatMemoryRepository.findByConversationId(conversationId);
Collections.reverse(messages); // Remove this workaround

// AFTER (correct ordering):
List<Message> messages = chatMemoryRepository.findByConversationId(conversationId);
// Messages are now correctly ordered chronologically

所有聊天记忆仓库现在均一致地按消息发送顺序(从旧到新)返回消息,这是大型语言模型(LLM)对话历史的预期格式。

开发时服务​

  • Docker Compose 和 Testcontainers 对 MongoDB Atlas 的支持现在由 Spring Boot MongoDB 模块原生提供。迁移过程应当是透明的,无需进行任何代码更改。在依赖项方面,您不再需要导入 org.springframework.ai:spring-ai-spring-boot-testcontainers。仅需依赖 org.springframework.boot:spring-boot-testcontainers 即可。

移除默认温度配置​

Spring AI 不再为聊天模型的自动配置属性提供默认的 temperature 值。此前,Spring AI 为大多数聊天模型设置了默认的 temperature 为 0.7。该默认值已被移除,以允许使用每个 AI 提供商原生的默认 temperature。

影响​

如果你的应用没有显式配置温度值,而是依赖 Spring AI 的默认值 0.7,在升级后你可能会注意到行为有所不同。实际的默认值现在将由各 AI 提供商的 API 决定,具体可能有所不同:

  • 某些提供方默认值为 1.0
  • 某些提供方默认值为 0.7
  • 某些提供方具有特定于模型的默认值

迁移​

如果你想保持之前的行为,请在配置中显式设置 temperature:

# Example for OpenAI
spring.ai.openai.chat.temperature=0.7

# Example for Anthropic
spring.ai.anthropic.chat.temperature=0.7

# Example for Azure OpenAI
spring.ai.azure.openai.chat.temperature=0.7

或在构建请求时通过编程方式:

ChatResponse response = chatModel.call(
new Prompt("Your prompt here",
OpenAiChatOptions.builder()
.temperature(0.7)
.build()));

升级到 1.1.0-RC1​

破坏性变更​

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

OpenAI 文本转语音(Text-to-Speech)的实现已从特定提供商的类迁移到共享接口。这使得可以编写可移植的代码,从而在多个 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)

此外,为了使所有 OpenAI TTS 组件与其他 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 版本包含对 artifact ID、包名和模块结构的重大更改。本节提供有关使用 SNAPSHOT 版本的具体指导。

添加快照存储库​

若要使用 1.0.0-SNAPSHOT 版本,你需要在构建文件中添加快照仓库。有关详细说明,请参阅“入门指南”中的 Snapshots - Add Snapshot Repositories 部分。

更新依赖管理​

请在构建配置中将 Spring AI BOM 版本更新为 1.0.0-SNAPSHOT。有关依赖管理的详细配置说明,请参阅入门指南中的 Dependency Management 部分。

Artifact ID、包和模块变更​

1.0.0-SNAPSHOT 版本包含了对 artifact ID、包名和模块结构的更改。

升级到 1.0.0-RC1​

你可以使用 OpenRewrite 配方自动化升级到 1.0.0-RC1 的过程。该配方有助于应用此版本所需的许多代码更改。配方的详细内容及使用说明请参见 Arconia Spring AI Migrations。

破坏性变更​

聊天客户端和顾问​

影响最终用户代码的主要变更是:

  • 在 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 占位符,用于接收检索到的上下文。

  • VectorStoreChatMemoryAdvisor 期望使用包含以下占位符的模板(更多详情请参阅 更多详细信息):

    • instructions 占位符,用于接收原始的 system message。

    • long_term_memory 占位符,用于接收检索到的对话记忆。

可观测性​

  • 重构了内容观测(content observation),以使用日志(logging)替代追踪(tracing)(ca843e8)

    • 用日志处理器(logging handlers)替换了内容观测过滤器(content observation filters)

    • 重命名配置属性以更准确地反映其用途:

      • include-prompt → log-prompt

      • include-completion → log-completion

      • include-query-response → log-query-response

    • 新增 TracingAwareLoggingObservationHandler 以实现具备追踪感知能力的日志记录

    • 用 micrometer-tracing 替换了 micrometer-tracing-bridge-otel

    • 移除基于事件的追踪(event-based tracing),改为直接日志记录

    • 移除对 OTel SDK 的直接依赖

    • 在观测属性中将 includePrompt 重命名为 logPrompt(涉及 ChatClientBuilderProperties、ChatObservationProperties 和 ImageObservationProperties)

Chat Memory Repository 模块和自动配置重命名​

我们通过在代码库中统一添加“repository”后缀,标准化了聊天内存组件的命名模式。此变更影响了 Cassandra、JDBC 和 Neo4j 的实现,并为了清晰起见,更新了相关的 artifact IDs、Java 包名和类名。

工件 ID​

所有与内存相关的产物现在都遵循一致的规范:

  • 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 IDs。 - 更新任何使用了旧包名或类名的导入、类引用或配置。

消息聚合器重构​

更改​
  • 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 Community 仓库。

移除 Vector Store​

  • 移除了 HanaDB vector store 的自动配置 (f3b4624)

内存管理​

  • 移除 CassandraChatMemory 实现 (11e3c8f)

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

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

  • 重构聊天记忆存储库构件以提升清晰度 (2d517ee)

  • 重构聊天记忆存储库自动配置及 Spring Boot Starter 以提升清晰度 (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 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)

  • 简化了 chat memory advisor 层次结构并移除了已弃用的 API (848a3fd)

  • 移除了 JdbcChatMemory 中的弃用项 (356a68f)

  • 重构了 chat memory repository 构件以提升清晰度 (2d517ee)

  • 重构了 chat memory repository 自动配置和 Spring Boot starters 以提升清晰度 (f6dba1b)

客户端 API​

  • 移除了 ChatClient 和 Advisors 中的弃用内容(4fe74d8)

  • chatclient 工具调用的破坏性变更(5b7849d)

  • 移除了 OllamaApi 和 AnthropicApi 中的弃用内容(46be898)

消息和模板 APIs​

  • 移除了已弃用的 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 替换了 micrometer-tracing-bridge-otel

    • 移除了基于事件的追踪,转而采用直接日志记录

    • 移除了对 OTel SDK 的直接依赖

    • 在观测属性中(在 ChatClientBuilderProperties、ChatObservationProperties 和 ImageObservationProperties 中)将 includePrompt 重命名为 logPrompt

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 IDs、包名和模块结构的重要变更,这些变更将在最终版本中保留。

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 实现客户端交互​

之前可在服务器端使用的方法,现在通过 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 将会分析你的项目并进行必要的更改

备注

自动升级提示目前处理构件 ID 变更、包路径迁移和模块结构变更,但尚未包含针对升级到 MCP 0.9.0 的自动变更。如果您正在使用 MCP,则需要按照 MCP Java SDK 升级 章节中的指引手动更新您的代码。

各版本的常见变更​

制品 ID 变更​

Spring AI 启动器工件的命名规则已变更。您需要根据以下模式更新依赖项:

  • 模型启动器: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 自动配置工件的变更​

Spring AI 的自动配置(autoconfiguration)已从单一的大型构件(artifact)拆分为针对每个模型、向量存储(vector store)及其他组件的独立自动配置构件。此变更旨在最小化不同版本的依赖库之间发生冲突的影响,例如 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>
备注

在大多数情况下,你不需要显式添加这些自动配置依赖项。当使用对应的 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 之类的接口
  • 消息类型与提示模板
  • Function-calling 框架(ToolDefinition、ToolCallback)
  • 内容过滤与观察支持

spring-ai-vector-store​

统一向量数据库抽象:

  • VectorStore 接口,用于相似性搜索
  • 支持类 SQL 表达式的高级过滤
  • SimpleVectorStore,用于内存中的使用
  • 支持对嵌入(Embeddings)进行批处理

spring-ai-client-chat​

高级对话式 AI API:- ChatClient 接口 - 通过 ChatMemory 实现会话持久化 - 使用 OutputConverter 进行响应转换 - 基于 Advisor 的拦截 - 同步和响应式流支持

spring-ai-vector-store-advisor​

Bridges 与向量存储交互以实现 RAG: - QuestionAnswerAdvisor:将上下文注入提示词 - VectorStoreChatMemoryAdvisor:存储/检索对话历史

spring-ai-model-chat-memory-cassandra {#_spring_ai_model_chat_memory_cassandra}

QWen 3.8 中英对照 Upgrade Notes 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-vector-store-advisor 和 spring-ai-rag(依赖 client-chat 和 vector-store)

  • spring-ai-model-chat-memory-* 模块(依赖 client-chat)

ToolContext 更改​

ToolContext 类已增强,以支持显式和隐式工具解析。现在工具可以:

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

  2. 隐式可用:可用于运行时动态解析,除非明确请求,否则不会包含在任何模型调用中的工具。

从 1.0.0-M7 开始,仅当在提示词中明确请求或在调用中明确包含时,工具才会被纳入对模型的调用。

此外,ToolContext 类现已标记为 final,因此不再可以被继承。该类原本就不应被用作子类。在实例化 ToolContext 时,你可以以 Map<String, Object> 的形式添加所需的所有上下文数据。更多信息,请查看 [documentation](docs.spring.io/spring-ai/reference/api/tools.html#_tool_context)。

升级到 1.0.0-M6​

Usage 接口与 DefaultUsage 实现的变更​

Usage 接口及其默认实现 DefaultUsage 经历了以下变更:

  1. 方法重命名:

    • getGenerationTokens() 现更名为 getCompletionTokens()
  2. 类型变更:

    • DefaultUsage 中所有 token 计数字段从 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 起:

  • 任何通过 functions() 方法或默认 FunctionCallingOptions 实例的 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 中所有的 Chat 对话。除 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 Builders 进行重构,以保持一致性。
  • 当前 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。

  • 对于支持初始化模式(schema)的向量存储,initialize-schema 属性的默认值现已设置为 false。这意味着,如果期望在应用程序启动时创建模式,应用程序现在需要显式选择启用受支持向量存储的模式初始化。并非所有向量存储都支持此属性。有关更多详细信息,请参阅相应的向量存储文档。以下是当前不支持 initialize-schema 属性的向量存储:

    1. Pinecone

    2. 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,正确的引用文档即将发布。

我们将“旧的” ModelClient 重命名为 Model,并相应地重命名了实现类,例如,ImageClient 被重命名为 ImageModel。Model 实现层是一个可移植层,负责在 Spring AI API 与底层 AI Model API 之间进行转换。

包含接口和基类的新包 model,用于支持创建针对任意输入/输出数据类型组合的 AI 模型客户端。目前,聊天模型包和图像模型包已实现此功能。我们将很快将嵌入包更新为此新模型。

一种新的“可移植选项”设计模式。我们希望尽可能提高 ModelCall 在不同基于聊天的 AI 模型之间的可移植性。这里有一组通用的生成选项,还有一些特定于模型提供商的选项。采用了一种类似“鸭子类型”的方法。模型包中的 ModelOptions 是一个标记接口,表明该类的实现将提供模型选项。参见 ImageOptions,它是一个子接口,定义了所有从文本到图像的 ImageModel 实现之间通用的可移植选项。然后,StabilityAiImageOptions 和 OpenAiImageOptions 提供了特定于每个模型提供商的选项。所有选项类都通过流式 API 构建器创建,并且都可以传递给可移植的 ImageModel API。这些选项数据类型用于 ImageModel 实现的自动配置/配置属性中。

制品名称变更​

重命名的 POM 工件名称:

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

To

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

以及相关 Palm2 模型的 Boot starter 已从

<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-01-03)

    • 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 Model Client 的接口和基类。目前,chat 和 image model 包已实现该接口。我们将很快更新 embedding 包以适配此新模型。

  • 新增“可移植选项”设计模式。我们希望尽可能提高 ModelCall 在不同基于聊天的 AI Model 之间的可移植性。这里有一组通用的生成选项,以及特定于模型提供商的选项。采用了一种类似“鸭子类型”的方法。model 包中的 ModelOptions 是一个标记接口,表明该类的实现将提供模型的选项。参见 ImageOptions,它是一个子接口,定义了所有文本→图像 ImageModel 实现共用的可移植选项。随后,StabilityAiImageOptions 和 OpenAiImageOptions 分别提供特定于每个模型提供商的选项。所有选项类都通过流式 API 构建器创建,且都可以传入可移植的 ImageModel API。这些选项数据类型用于 ImageModel 实现的自动配置/配置属性中。

2024 年 1 月 13 日更新​

以下 OpenAi 自动配置聊天属性已更改

  • 从 spring.ai.openai.model 改为 spring.ai.openai.chat.model。

  • 从 spring.ai.openai.temperature 改为 spring.ai.openai.chat.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.OllamaModelCall 替换 org.springframework.ai.ollama.client.OllamaClient。

  • 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

重命名工件 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>

章节摘要​