升级说明
升级至 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
QWen 3.8 中英对照 Upgrade Notesspring-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) |
|---|---|
FunctionCallback | ToolCallback |
FunctionCallback.builder().function(name, fn) | FunctionToolCallback.builder(name, fn) |
FunctionCallback.builder().method(…) | MethodToolCallback.builder() with ToolDefinition |
FunctionCallingOptions | ToolCallingChatOptions |
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_MAPPER | JacksonUtils.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
更新已移动的缓存和引用类的导入:
| Before | After |
|---|---|
org.springframework.ai.anthropic.api.AnthropicCacheOptions | org.springframework.ai.anthropic.AnthropicCacheOptions |
org.springframework.ai.anthropic.api.AnthropicCacheStrategy | org.springframework.ai.anthropic.AnthropicCacheStrategy |
org.springframework.ai.anthropic.api.AnthropicCacheTtl | org.springframework.ai.anthropic.AnthropicCacheTtl |
org.springframework.ai.anthropic.api.utils.CacheBreakpointTracker | org.springframework.ai.anthropic.CacheBreakpointTracker |
org.springframework.ai.anthropic.api.utils.CacheEligibilityResolver | org.springframework.ai.anthropic.CacheEligibilityResolver |
org.springframework.ai.anthropic.api.CitationDocument | org.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
该配方会自动执行以下两项更改:
-
移除
org.springaicommunity:mcp-annotationsMaven 依赖。 -
重写 所有
.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. 服务器传输
| 类 | 旧包 | 新包 |
|---|---|---|
WebFluxSseServerTransportProvider | io.modelcontextprotocol.server.transport | org.springframework.ai.mcp.server.webflux.transport |
WebFluxStreamableServerTransportProvider | io.modelcontextprotocol.server.transport | org.springframework.ai.mcp.server.webflux.transport |
WebFluxStatelessServerTransport | io.modelcontextprotocol.server.transport | org.springframework.ai.mcp.server.webflux.transport |
WebMvcSseServerTransportProvider | io.modelcontextprotocol.server.transport | org.springframework.ai.mcp.server.webmvc.transport |
WebMvcStreamableServerTransportProvider | io.modelcontextprotocol.server.transport | org.springframework.ai.mcp.server.webmvc.transport |
WebMvcStatelessServerTransport | io.modelcontextprotocol.server.transport | org.springframework.ai.mcp.server.webmvc.transport |
表 2. 客户端传输
| 类 | 旧包 | 新包 |
|---|---|---|
WebFluxSseClientTransport | io.modelcontextprotocol.client.transport | org.springframework.ai.mcp.client.webflux.transport |
WebClientStreamableHttpTransport | io.modelcontextprotocol.client.transport | org.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
如果你的项目声明了 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和McpAsyncHttpClientRequestCustomizerBean 不再被应用。传输级别的定制现在分别通过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
该配方会自动执行以下更改:
-
替换了
McpAsyncClientCustomizer和McpSyncClientCustomizer的导入为McpClientCustomizer,并添加了所需的import io.modelcontextprotocol.client.McpClient;。 -
重写
implements McpAsyncClientCustomizer为implements McpClientCustomizer<McpClient.AsyncSpec>。 -
重写
implements McpSyncClientCustomizer为implements McpClientCustomizer<McpClient.SyncSpec>。 -
重写所有其余的使用场景(返回类型、变量声明、参数类型)。
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中
为什么做出此更改?
-
内存效率:防止在长对话中内存无限制增长
-
关注点分离:工具应只操作其参数,而非管理对话状态
-
架构对齐:对话上下文应归属于 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();
示例流程:
-
用户提问:“旧金山和洛杉矶的天气如何?”
-
LLM 请求工具调用:
getWeather(SF)和getWeather(LA) -
工具仅基于其参数执行(不包含对话历史)
-
ToolCallingAdvisor 收集工具结果和对话历史
-
LLM 从 advisor 接收对话上下文并合成回答:“旧金山的天气是 72°F,洛杉矶是 85°F”
LLM 通过 Advisor 链查看完整的对话,而不是通过 ToolContext。
模型内部方法的访问级别已更改为私有 {#_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。
迁移步骤
-
更新导入:将所有来自
org.springframework.ai.openai.audio.speech.的导入 替换为org.springframework.ai.audio.tts. -
更新类型引用:将所有旧类名的出现替换为新类名:
查找: SpeechModel
替换: TextToSpeechModel
查找: StreamingSpeechModel
替换: StreamingTextToSpeechModel
查找: SpeechPrompt
替换: TextToSpeechPrompt
查找: SpeechResponse
替换: TextToSpeechResponse
查找: SpeechMessage
替换: TextToSpeechMessage -
更新速度参数:将
Float更改为Double:查找: .speed(1.0f)
替换: .speed(1.0)
查找: Float speed
替换: Double speed -
更新依赖注入:如果你注入了
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、包名和模块结构的更改。
详情请参考:- 常见制品 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。
顾问中的自包含模板
执行提示增强的内置顾问已更新为使用自包含模板。其目标是让每个顾问都能独立执行模板操作,既不受其他顾问的模板和提示决策影响,也不影响其他顾问。
如果您为以下顾问提供了自定义模板,您需要更新它们,以确保包含所有预期的占位符。
可观测性
-
重构了内容观测(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)
内存管理
消息与模板 API
客户端 API 的其他变更
包结构变更
依赖项
- 移除了 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
内存管理
客户端 API
消息和模板 APIs
模型实现
包结构变更
依赖项
- 移除了 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-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 的过程:
-
从 update-to-m7.txt 文件中复制提示词
-
将提示词粘贴到 Claude Code CLI 中
-
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}
示例
- Maven
- Gradle
<!-- BEFORE -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>
<!-- AFTER -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>
// BEFORE
implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter'
implementation 'org.springframework.ai:spring-ai-redis-store-spring-boot-starter'
// AFTER
implementation 'org.springframework.ai:spring-ai-starter-model-openai'
implementation 'org.springframework.ai:spring-ai-starter-vector-store-redis'
Spring AI 自动配置工件的变更
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}
新增自动配置工件示例
- Models
- Vector Stores
- MCP
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-autoconfigure-model-openai</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-autoconfigure-model-anthropic</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-autoconfigure-vector-store-redis</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-autoconfigure-vector-store-pgvector</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-autoconfigure-vector-store-chroma</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-autoconfigure-mcp-client</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-autoconfigure-mcp-server</artifactId>
</dependency>
在大多数情况下,你不需要显式添加这些自动配置依赖项。当使用对应的 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-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-cassandraApache 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.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 经历了以下变更:
-
方法重命名:
getGenerationTokens()现更名为getCompletionTokens()
-
类型变更:
-
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属性的向量存储:-
Pinecone
-
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 构建器创建,且都可以传入可移植的ImageModelAPI。这些选项数据类型用于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>
章节摘要
将 Anthropic 模块迁移至官方 Java SDK
在 2.0.0-M3 中,spring-ai-anthropic 基于官方 com.anthropic:anthropic-java SDK 进行了重写,取代了原先手工编写的 RestClient / WebClient 实现。之前的 AnthropicApi 类是一个包含 47 个嵌套 DTO record 的 2,300 行文件。