Spring Blog

Spring AI 2.1.0-RC2 Available Now

8.5内容质量

TL;DR · AI 摘要

Spring AI 2.1.0-RC2发布,新增DecisionModel API和多项改进,提升AI应用开发效率。

核心要点

  • DecisionModel API支持结构化决策输出,包含YesNo/Choice/Score三种问题类型
  • 新增工具调用增量流式传输和5种向量存储嵌入支持
  • 升级至Anthropic Java SDK 3.x并支持MCP协议修订版

结构提纲

按章节快速跳转。

  1. 宣布Spring AI 2.1.0-RC2正式发布并提供下载渠道

  2. 介绍DecisionModel API的结构化决策能力及其三种问题类型

  3. 展示DecisionPrompt/DecisionResponse/DecisionOptions的交互流程

  4. 包含工具调用流式传输和向量存储扩展等五项关键升级

  5. 新增MCP协议修订版服务器端实现

  6. 提供升级说明和参考文档的访问链接

思维导图

用一张图看清主题之间的关系。

查看大纲文本(无障碍 / 无 JS 友好)
  • Spring AI 2.1.0-RC2
    • 核心特性
      • DecisionModel API
      • 结构化决策类型
      • YesNo/Choice/Score
    • 技术升级
      • 工具调用流式传输
      • 5种向量存储支持
      • MCP协议修订

金句 / Highlights

值得收藏与分享的关键句。

#Spring AI#Java#AI框架#机器学习
打开原文

代表 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(满意)。
code
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.* 下的属性。
code
@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;如果对后续功能有建议,请 发起讨论。

资源

项目页面 | GitHub | 问题跟踪 | 参考文档