Spring AI 2.1.0 已发布,现已可从 Maven Central 获取。此次版本新增对 Mistral AI 消息部分的原生支持,并大幅升级 AI Agent 能力。该版本基于 Spring Boot 4.2 构建,包含来自 86 位贡献者的 430 多次提交。它在 Spring AI 2.0.0 GA 发布五个月后推出,从根本上扩展了开发者构建 AI 应用的方式,支持推理、工具调用和会话管理。
Mistral AI 与 OpenAI(Chat Completions 和 Responses)、Anthropic、Google GenAI、Amazon Bedrock Converse、Ollama 和 DeepSeek 一样,成为能够原生生成和使用消息部分的核心项目聊天模型。这意味着 Spring AI 2.1 现在可以直接处理 Mistral AI 模型返回的复杂消息结构,包括与工具调用交错的推理、图像间的文本,以及特定于提供商的区块,无需手动适配。
Spring AI 2.1 的基础性变化是重新设计消息的结构。在 2.0 版本之前,Spring AI 消息由文本以及单独存放的工具调用和媒体列表组成。这种结构无法表示当前模型返回的内容:与工具调用交错的推理、图像间的文本,或必须在下一轮原样传回的特定于提供商的区块。
从 2.1 开始,AssistantMessage、UserMessage 和 ToolResponseMessage 现在将内容保存为有序的 MessagePart 条目列表:TextPart、ReasoningPart、ToolCallPart、ToolResultPart、MediaPart 和 UnknownPart。各部分会保留提供商生成时的顺序。ReasoningPart 或 ToolCallPart 可以携带 OpaquePayload,例如 Anthropic thinking signature 或 Gemini thought signature,并在重放时保持原样。UnknownPart 会保留适配器尚未建模的区块的原始 JSON,因此不会静默丢弃任何内容。
核心项目的所有聊天模型——包括 Mistral AI——都能原生生成和使用这些部分。常用访问器(getText()、getMedia()、getToolCalls(),以及新增的 getReasoning())都是对这些部分的视图,因此现有代码无需修改即可继续运行。
应用中的许多决策只有少量已知结果:是或否、若干类别之一,或某个等级。聊天模型会用自由文本作答,必须手动将其转换为可靠结果。新的 DecisionModel API 专为这类决策而设计。你可以描述可能的结果,模型会选出其中一个,并告知每个结果的可能性。
该 API 提供三种实现,每种都由一个 Boot starter 自动配置:OpenAiDecisionModel,由 OpenAI Decisions API 提供支持,并通过 spring.ai.openai.decision 配置;OllamaDecisionModel,默认模型为 d1-omni:600m,可在本机运行且无需 API 密钥;以及 SystemOneDecisionModel,适用于所有支持 System One 协议的服务器,例如 TypeSafe、Laya、llmman 和 Ollama。
Spring AI 的其他功能也基于 Decision Model API 构建:DecisionDocumentReranker 会询问每份检索到的文档是否回答了查询,并据此重新排序;DecisionDocumentFilter 会在文档进入提示词之前,筛查提示词注入、矛盾和相关性;DecisionToolIndex 则会询问决策模型,哪个已索引工具最适合处理请求,以及是否有任何工具适用。
ChatMemory 会为每个对话 ID 保存一份扁平的消息列表。长对话和 Agent 需要的不止于此,因此 Spring AI 2.1 现在引入了从社区项目 Spring AI Session 移植而来的 Session API。会话会将对话保存为只追加的事件日志。会话记忆是其首个用途,它根据该日志的视图构建提示词。
SessionEvent 会连同其所有消息部分一起保存;你自己的事件类型也可以记录同一日志中发生的其他事情。SessionService.searchEvents 可通过关键词搜索事件,SessionRecallTools 则向模型提供名为 conversation_search 的工具所具有的搜索功能。JdbcSessionRepository 支持 PostgreSQL、MySQL、MariaDB、Microsoft SQL Server 和 H2,并支持幂等且经过版本检查的追加操作。
Advisor 本身不保存状态,因此任何应用实例都可以处理会话中的任意一轮。这里有意不提供默认会话,因为共享会话会在不知不觉中合并不同用户的历史记录。**注意:**ChatMemory、其 Advisor 和 Repository 已弃用,并计划在 3.0.0 中移除。每项弃用声明都注明了替代方案,Chat Memory to Session Memory 指南则说明了如何将一个 API 映射到另一个 API。
预订航班、删除文件或发送邮件等操作,用户可能希望先审批。现在,工具可以声明 requiresConfirmation = true。当模型调用此类工具时,工具调用循环会在执行回复中的任何调用之前暂停,并将包含待决策调用的回复返回给你的应用。应用会为每次调用收集一个 ToolCallDecision,使用 ToolCallingManager.executeToolCalls(prompt, reply, decisions) 执行它们,并在下一次请求中发送结果。
永不结束的循环会造成高昂的故障成本。现在,工具调用循环会限制每个工具的调用次数和每轮的总调用次数,默认分别为 40 和 150,可通过 spring.ai.tools.limits.* 配置。达到限制后,循环要么以 ToolCallLimitExceededException 结束,要么告知模型已达到限制并让它继续运行。
模型会逐段流式输出工具调用的参数。Anthropic、OpenAI(两种 API)、Bedrock Converse 和 DeepSeek 现在会将这些增量作为标记为 partial 的 ToolCallParts 流式传输,因此 UI 可以在模型仍在生成工具调用时显示它。完整调用仍会随后以相同索引发送。部分内容并不算工具调用:getToolCalls() 和工具调用循环会跳过它,而且它绝不会存入记忆。
2026-07-28 版本是对 Model Context Protocol 的重新设计。它采用无状态架构:没有初始化握手,也没有会话;每个请求都携带协议版本和客户端能力,而引导服务器端输入的操作(例如 elicitation 和 sampling)则变成多次往返请求。Spring AI 2.1 基于 MCP Java SDK 2.2.0,在现有的 STDIO、SSE、Streamable HTTP 和无状态服务器与客户端之外,支持双方使用这一现代协议。
对于服务器,将 spring.ai.mcp.server.protocol 设置为 MODERN。你在其他协议中使用的相同 @McpTool、@McpResource、@McpPrompt 和 @McpComplete bean 及 ToolCallbacks,无需改动即可通过 WebMVC、WebFlux 或 STDIO 提供服务。两种 API 类型均受支持。使用 spring.ai.mcp.server.type=ASYNC 时,方法会返回 Mono,并通过 McpAsyncNotifier 报告进度。
对于客户端,当 Streamable HTTP 连接的 protocol 属性设置为现代协议时,该连接便会使用现代协议。旧版和现代连接可以并行工作,一个工具回调提供器会同时返回两者的工具。现代客户端不持有会话,创建成本低,因此一个客户端可以对应单个调用方。默认情况下,连接的客户端作用域为 PER_REQUEST,因此每个 ChatClient 请求都会获得自己的客户端。SHARED 会为以单一身份调用服务器的应用保留一个客户端,而 CUSTOM 则允许你通过自己的 bean 选择客户端。
新增的 OpenAiResponsesChatModel 会调用 OpenAI 的 /v1/responses 端点,与基于 Chat Completions 的 OpenAiChatModel 并存。从 GPT-5.4 开始,Chat Completions 不支持将工具调用与非 none 的推理强度结合使用,而 Responses 支持。Responses 回复中的每个条目都会按顺序变成一个部分,加密的推理内容会在工具调用期间原样传回。该模型是无状态的:每次调用都会发送完整的 Prompt,因此记忆、Advisor 和 RAG 的工作方式与 OpenAiChatModel 相同。HostedTool 可启用由 OpenAI 运行的工具:网页搜索、文件搜索、代码解释器、远程 MCP 和图像生成。只需设置一个属性即可切换:spring.ai.openai.chat.api=responses。
VectorStore.add() 总是使用存储自身的 embedding 模型计算 embedding。有时你已经有了向量:批处理 API 已在夜间计算好它们、另一团队负责 embedding 流程,或者多模态模型已为图像生成 embedding。VectorStore.upsert() 会按给定内容存储向量,而 similaritySearch(float[], SearchRequest) 则使用你自行计算的查询向量进行搜索。
再次写入相同 ID 会替换现有行,因此使用稳定 ID 的摄取任务可以安全地重新运行。写入任何内容之前,系统都会检查每个向量的维度是否与索引一致,而且存储自身的 embedding 模型不会执行任何 embedding 计算。pgvector、Qdrant、Redis、Elasticsearch、OpenSearch、Neo4j、MongoDB Atlas、Typesense、MariaDB、Chroma 和 Couchbase 均已实现这两项操作。
当防护机制拦截请求时,会用拒绝回复替代模型的回答。此类回复现在会标记为 GuardrailRefusal,Advisor 链中的其他部分也会据此处理:StructuredOutputValidationAdvisor 不会再次询问模型,SemanticCacheAdvisor 不会缓存该回复,而 ChatClient.entity(...) 会抛出 GuardrailRefusalException。该异常继承自新增的 ContentFilteredException;如果提供商的安全过滤器拦截了响应,导致响应无法转换,entity(...) 就会抛出该异常。
不同提供商对模型停止原因的命名各不相同:stop、end_turn、STOP、content_filter、SAFETY 等。除了原始结束原因外,现在每个 Generation 还会报告一个 FinishReasonCategory,该类别在所有提供商之间保持一致:COMPLETED、TRUNCATED、TOOL_CALL、FILTERED、OTHER 或 UNSPECIFIED。
TokenTextSplitter 支持区块重叠,且默认不启用;不启用时,生成的区块与之前相同。PagePdfDocumentReader 接受页面范围,Tika 文档读取器则升级到 Tika 4.0.0。PgVectorStore 可以使用列名不同的现有表。MongoDBAtlasVectorStore 可以通过 bulkUpsertBatchSize 批量写入 upsert。MilvusVectorStore 可以限定到特定分区。OpenAiChatModel 会填充速率限制元数据,并传递每次调用的请求头。OpenAiConnectionDetails bean 允许 Testcontainers 或 Docker Compose 在开发和测试中提供到 OpenAI 兼容服务器的连接。
Spring AI 2.1 的核心项目聊天模型都能原生生成和使用消息部分:OpenAI(Chat Completions 和 Responses API)、Anthropic、Google GenAI、Amazon Bedrock Converse、Ollama、Mistral AI 和 DeepSeek。消息部分包括 TextPart、ReasoningPart、ToolCallPart、ToolResultPart、MediaPart 和 UnknownPart。使用 getText()、getMedia()、getToolCalls() 等常用访问器以及新增的 getReasoning() 的现有代码无需修改即可继续运行。
DecisionModel API 通过让模型从已知结果集合中选出一个结果,并报告每个结果的可能性,来处理结构化决策,例如是或否、类别或等级。该 API 提供三种实现:OpenAiDecisionModel(通过 spring.ai.openai.decision 配置)、OllamaDecisionModel(默认使用 d1-omni:600m,无需 API 密钥)和 SystemOneDecisionModel(适用于支持 System One 协议的服务器,例如 TypeSafe、Laya、llmman 和 Ollama)。该 API 支持防护机制、文档重排和工具索引,应用也可以在单个聊天流程中组合多个决策模型。
从社区项目 Spring AI Session 移植而来的 Session API,取代了已弃用的 ChatMemory,用于管理长期运行的 Agent 对话。会话会将对话保存为只追加的事件日志,其中 SessionEvent 包含所有消息部分。SessionService.searchEvents 可通过关键词搜索检索事件,而 SessionRecallTools 会为模型提供 conversation_search 工具。JdbcSessionRepository 支持 PostgreSQL、MySQL、MariaDB、Microsoft SQL Server 和 H2,并支持幂等且经过版本检查的追加操作。Advisor 不保存状态,因此任何应用实例都可以处理会话中的任意一轮。ChatMemory、其 Advisor 和 Repository 已弃用,并计划在 3.0.0 中移除;同时提供了专门的升级指南。
相关快讯