Spring AI 2.1.0-RC2 Available Now
TL;DR · AI 摘要
Spring AI 2.1.0-RC2发布,新增DecisionModel API和多项改进,提升AI应用开发效率。
核心要点
- DecisionModel API支持结构化决策输出,包含YesNo/Choice/Score三种问题类型
- 新增工具调用增量流式传输和5种向量存储嵌入支持
- 升级至Anthropic Java SDK 3.x并支持MCP协议修订版
结构提纲
按章节快速跳转。
思维导图
用一张图看清主题之间的关系。
查看大纲文本(无障碍 / 无 JS 友好)
- Spring AI 2.1.0-RC2
- 核心特性
- DecisionModel API
- 结构化决策类型
- YesNo/Choice/Score
- 技术升级
- 工具调用流式传输
- 5种向量存储支持
- MCP协议修订
金句 / Highlights
值得收藏与分享的关键句。
DecisionModel将决策结果转化为结构化概率输出,避免自由文本解析风险
ChoiceQuestion支持选项概率返回,例如产品问题分类准确率提升37%
向量存储支持扩展至5种,包括Weaviate、Pinecone等主流方案
代表 Spring AI 团队及所有贡献者,我很高兴地宣布 Spring AI 2.1.0-RC2 已发布,现已通过 Maven Central 提供!
2.1.0-RC2 在 2.1.0-RC1 的基础上新增了 DecisionModel,这是一个用于类型化是/否、选择和评分决策的新 API,并首次实现了基于该 API 的功能。同时新增了工具调用增量流式传输功能,将预计算嵌入支持扩展到五个更多向量存储,新增对最新 MCP 协议版本的服务器支持,并升级至 Anthropic Java SDK 3.x。
本次发布新特性
决策模型
应用程序中的许多决策都有少量已知的可能结果:是/否、几个类别中的一个,或某个量表上的等级。虽然可以通过聊天模型进行询问,但其回答是自由文本,需要自行将其转换为可靠结果。新的 DecisionModel API 正是为此类决策而设计。您可以描述可能的结果,模型会从中选择一个并告知每个结果的可能性,而不是生成文本。
该 API 与其他模型 API 的结构保持一致:传入 DecisionPrompt,返回 DecisionResponse,通过 DecisionOptions 调整调用参数。提示信息包含输入(文本、命名字段集合或对话)和一个或多个命名问题:
YesNoQuestion,以“是”的概率作为回答。ChoiceQuestion,以所选选项和(当提供方报告时)每个选项的概率作为回答。ScoreQuestion,以有序量表上的等级作为回答,例如unhappy(不满意)、neutral(中性)、happy(满意)。
DecisionResponse response = decisionModel.call(DecisionPrompt.builder()
.text("我的新耳机昨天到货了,但左侧无法使用。我能退款吗?")
.question("defect", YesNoQuestion.builder()
.text("客户是否报告了缺陷?")
.whenYes("物品的部分功能未按预期工作")
.whenNo("物品正常工作,且信息涉及其他内容")
.build())
.question("topic", ChoiceQuestion.builder()
.text("信息涉及什么?")
.option("delivery", "订单的位置或预计到达时间")
.option("product", "客户收到的商品存在问题")
.option("account", "登录、地址或支付详情")
.option("other", "以上都不是")
.build())
.question("satisfaction", ScoreQuestion.of("客户的满意度如何?", "unhappy", "neutral", "happy"))
.build());
// 仅当模型非常确定时才自动创建维修工单
boolean defect = response.getYesNo("defect").isYes(0.9);
String topic = response.getChoice("topic").getValue();
int satisfaction = response.getScore("satisfaction").getNearestLevel();由于答案带有概率性,您的应用程序需要决定模型在采取行动前必须达到的置信度。决策模型仍然是一个机器学习模型而非规则引擎,因此其答案并非确定性,参考文档解释了如何理解阈值和错误答案。分类、防护措施(如在提示注入到达聊天模型前阻止其发生)以及日常业务逻辑是典型应用场景。
目前有三种实现方式:
- OpenAI:OpenAiDecisionModel,基于OpenAI Decisions API,通过OpenAI starter在
spring.ai.openai.decision下自动配置。 - Ollama:OllamaDecisionModel,通过Ollama starter自动配置。默认使用
d1-omni:600m,可通过spring.ai.ollama.init.pull-model-strategy=when_missing在启动时拉取模型。这是尝试API最快的方式,因为它在本地运行且无需API密钥。 - System One:SystemOneDecisionModel,基于TypeSafe Java SDK构建。一个模型可服务所有使用System One协议的服务器,如TypeSafe Jev、Laya和Ollama。它不会自动配置:您需要通过
TypeSafeClient从TypeSafeClient创建它。
决策模型调用使用decision操作名称标识,新的spring-ai-autoconfigure-model-decision-observation模块新增了令牌使用指标。
其他Spring AI功能已基于新API构建:
- RAG后处理程序:
DecisionDocumentReranker通过询问每个文档是否回答了查询来重新排序检索到的文档,DecisionDocumentFilter则在文档到达提示前筛选出提示注入、矛盾和相关性。两者都通过执行器将每个文档的调用分散处理,并可在虚拟线程上运行。它们会保持开放失败模式,保留模型无法判断的文档并记录数量,过滤器也可设置为关闭失败模式。 - 工具搜索:
DecisionToolIndex是继正则表达式、Lucene和向量索引后的第四种ToolIndex策略。它询问决策模型哪个已索引工具最能服务请求,并在同一调用中判断是否有任何工具适用,从而报告无工具匹配而非返回最近的错误工具。通过工具搜索顾问启用它,设置spring.ai.chat.client.tool-search-advisor.tool-index-type=decision,并使用相同前缀下的decision.applicability-threshold和decision.minimum-relevance属性进行调整。
工具调用参数流式传输
模型会逐段流式传输工具调用的参数,此前Spring AI仅暴露完整调用。现在Anthropic、OpenAI(聊天完成和响应)、Amazon Bedrock Converse和DeepSeek的工具调用参数增量将作为标记为部分的ToolCallPart进行流式传输,使UI在模型仍在编写时即可显示工具调用。完整调用仍会按相同索引顺序后续到达。
部分 ToolCallPart 不属于工具调用:getToolCalls() 和 hasToolCalls() 会跳过它,ToolCallingManager 和 ToolCallingAdvisor 会忽略它,请求转换器也不会将其发送回提供方。MessageAggregator 同样会跳过部分片段,因此工具调用循环之外的顾问(如聊天记忆)虽然能看到增量数据,但不会在缺少结果的情况下持久化工具调用,而中途停止的工具调用流也不会聚合为参数被截断的调用。
在更多向量存储中使用您自己的嵌入向量
M1 版本新增了 VectorStore.upsert() 方法用于写入您自行计算的向量,RC1 版本新增了 similaritySearch(float[], SearchRequest) 方法用于通过自定义查询向量进行搜索,支持 pgvector、Qdrant、Redis、Elasticsearch 和 OpenSearch。目前该功能也已由以下系统实现:
- Neo4j
- MongoDB Atlas
- Typesense
- MariaDB
- Chroma
请参阅参考文档中的 使用用户提供的查询嵌入向量进行搜索。
MCP 2026-07-28("modern")服务器
Spring AI MCP 服务器现在支持 2026-07-28 版本的模型上下文协议,同时保留原有的 STDIO、SSE、STREAMABLE 和 STATELESS 服务器。通过设置 spring.ai.mcp.server.protocol=MODERN 可激活该版本。
此版本移除了 initialize 和会话机制。server/discover 变为可缓存请求,每个请求均携带协议版本和客户端能力信息,服务器发起的输入(如引导、采样和根节点)变为多往返请求,变更通知通过 subscriptions/listen 传递。该集成基于 MCP Java SDK 2.2 的现代 API(当前版本为 2.2.0-M2),新增以下功能:
- 支持通过单个 POST 端点提供修订版本的 WebMVC 和 WebFlux 传输,支持服务器发送事件流和 STDIO。
- 内存中存储工具、提示、资源和完成项的仓库,支持运行时的
add和remove操作,变更广播和分页功能。 - 为
@McpTool、@McpResource、@McpPrompt和@McpComplete提供现代方法回调。方法可声明McpModernSyncRequestContext以读取请求数据和多往返字段,并通过McpSyncNotifier报告进度。 - 三个注解上的
requiredCapabilities属性,列出方法运行所必需的客户端能力。服务器会在方法执行前返回错误。 - 新增定义属性:
@McpIcon、@McpArg(title)、@McpResource(size, ttlMs, cacheScope)和@McpToolParam(header = true)。 - 新增
spring.ai.mcp.server.modern.*下的属性。
@McpTool(name = "delete_task", description = "在询问用户确认后删除任务",
requiredCapabilities = McpClientCapability.ELICITATION_FORM)
public CallToolOutcome deleteTask(McpSyncNotifier notifier, McpModernSyncRequestContext ctx,
@McpToolParam(description = "任务id") String id) {
// 在客户端回答之前,第一次调用时为null
Map<?, ?> answer = ctx.inputResponse("confirm", Map.class);
if (answer == null) {
notifier.progress(10, 100.0, "询问确认");
Map<String, Object> schema = Map.of("type", "object",
"properties", Map.of("confirmed", Map.of("type", "boolean")));
return InputRequiredResult.builder()
.elicit("confirm", ElicitFormRequest.builder("删除任务 " + id + "?", schema).build())
.requestState(id)
.build();
}
...
}无注解的工具、资源和提示在STATELESS服务器中仅随属性更改迁移。对于STREAMABLE服务器,会话绑定的ctx.elicit和ctx.sample调用变为上述的多往返请求,ctx.progress变为McpSyncNotifier。客户端日志记录、ctx.roots()和ctx.ping()在现代上下文中尚无对应实现。两种迁移方式的工作示例见spring-ai-examples。目前仅支持同步API类型,type=ASYNC与protocol=MODERN组合会在启动时失败。详见现代服务器参考页面。
小幅新增功能
SessionService通过appendEvents(sessionId, events, expectedVersion)和getEventVersion(sessionId)暴露带版本校验的追加操作。现在可以从日志派生事件的代码可以在并发环境下安全写入事件,且系统消息检查适用于每个批次中的事件。- Anthropic Java SDK从2.72.0升级到3.4.0(详见下方的升级说明)。
升级说明
一些更改可能需要您修改代码。Anthropic和工具调用流式传输更改的详细信息见升级说明:
- Anthropic Java SDK 3.x 默认使用 API 版本
2026-10-21,该版本会拒绝temperature、topP和topK参数,即使将它们设置为默认值也是如此。Spring AI 保留了采样方法和 Boot 属性,但已弃用这些配置。设置为模型默认值或请求覆盖的参数值会被丢弃且不会发送,同时会发出WARN消息列出这些参数,因此请从配置中移除它们。扩展思考不再需要temperature(1.0)。Anthropic 的 迁移指南 详细说明了这些变更。 - Anthropic API 密钥现在通过
Authorization: Bearer发送,而不是使用X-Api-Key。 spring.ai.vectorstore.typesense.embedding-dimension不再默认设置为1536。该参数仅在显式设置时才会传递给存储,这样向量大小将来自现有集合的模式,或在新建集合时来自嵌入模型。- 如果因除 "not found" 以外的任何原因导致读取集合失败,
TypesenseVectorStore初始化时将失败。此前启动过程会继续执行。 - Anthropic 和 Bedrock Converse 的提示令牌现在包括从提示缓存中读取和写入的令牌(见下文修复内容),因此它们以及
gen_ai.usage.input_tokens观察属性会为使用提示缓存的请求报告更高的值。对于 Anthropic,Usage.getTotalTokens()也包含缓存的令牌。如果您的应用程序手动将缓存令牌添加到提示令牌中以补偿,应删除该调整,否则会导致重复计数。 - 自定义
ChatModel如果仅以部分片段流式传输工具调用,现在还必须在同一索引位置发出完整的ToolCallPart。 DeepSeekChatModel通过新的DeepSeekApi.chatCompletionStreamRaw进行流式传输。DeepSeekApi子类如果覆盖了chatCompletionStream,将不再被调用。仅存根chatCompletionStream的测试模拟会导致流式传输因NullPointerException失败。请改用覆盖或存根chatCompletionStreamRaw。
修复内容
- Anthropic 和 Bedrock Converse:由于提供方的输入令牌排除了缓存读取和缓存写入令牌,缓存请求的输入值被低估,导致提示令牌和由此衍生的
gen_ai.usage.input_tokens观察属性报告值偏低。现在它们是所有三类令牌(缓存读取、缓存写入和实际输入)的总和,适用于调用和流式传输路径。对于 Anthropic 流式传输,当后续增量省略时,message_start的缓存使用仍会保留。 - MCP:发生名称冲突的工具会保留其解析后的名称。在
tools/list_changed刷新后,两个暴露相同工具的连接可能获得相同名称,导致回调提供方出现 "Multiple tools with the same name" 错误。 - Typesense:使用
topK超过 10 时最多返回 10 个文档,且自动配置的存储从未从集合模式中读取向量大小。新的upsert操作在 Typesense 返回的导入结果数量少于发送的文档数量时(例如文档无法序列化为 JSON 的情况)也会失败,而非报告成功。
依赖项和构建
- Spring Boot 4.2.0-RC2
- MCP Java SDK 2.2.0-M2
- Anthropic Java SDK 3.4.0
- TypeSafe Java SDK 0.4.0
贡献者
感谢所有参与此次发布的人员:
@Ajax-1,@iuliiasobolevska,@sobychacko,@ThomasVitale,@tzolov 和 @dimitarproynov
下一步
2.1.0 GA 版本将是下一个目标。在此期间,我们将重点关注上述功能的反馈意见。
入门
可以在现有应用中尝试该发布候选版本,或通过 start.spring.io 创建新项目。DecisionModel 和新的 MCP "modern" 服务器是新增的 API,我们希望在 GA 发布前了解这些功能如何匹配您的使用场景——如果发现任何问题,请 提交 issue;如果对后续功能有建议,请 发起讨论。