Spring AI 1.0.0 M7 发布

发布 | Mark Pollack | 2025年4月10日 | ...

我们很高兴地宣布 Spring AI 1.0.0 Milestone 7 的发布。这将是最后一个里程碑版本。下个月将发布 RC1 版本，紧接着在 Spring IO 巴塞罗那会议之前发布 GA 版本。

为了庆祝这次发布，我们在 AI 生成音乐播放列表中添加了一首新歌，歌词由 Josh Long 和 Claude 创作！快来收听最新曲目，为您的博客阅读和编码体验增添乐趣。

以下是本次发布的主要变更。请注意，存在破坏性变更！

破坏性变更

Spring AI 1.0.0-M7 引入了多项重要变更，这些变更与早期 SNAPSHOT 版本中引入的结构性改进保持一致。这些变更旨在打造一个更模块化、更易于维护的代码库，同时减少应用程序中的不必要依赖。

Artifact ID 变更

最显著的变更是 Spring AI 启动器 artifact 的命名模式

模型启动器：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}

包变更

一些类已移动到新的包中，以更好地反映其领域职责。

KeywordMetadataEnricher 和 SummaryMetadataEnricher 从 org.springframework.ai.transformer 移动到 org.springframework.ai.chat.transformer
Content、MediaContent 和 Media 从 org.springframework.ai.model 移动到 org.springframework.ai.content

您的 IDE 应该能轻松处理这些重构。

新模块结构

如上方“核心架构改进”部分所述，项目已从单体核心重构为专门的领域模块。

这种模块化方法允许您仅包含所需的功能，从而实现更小的部署和更清晰的组件边界。

重要的是，如果您使用 Spring AI starter，此更改不应构成破坏性更改，因为它们现在会自动导入新的模块化依赖项。只有直接引用先前单体 artifact 的应用程序才需要更新其依赖项。

ToolContext 变更

ToolContext 类已得到增强，以支持显式和隐式工具解析，并且仅在显式请求时才将工具包含在模型调用中。

其他资源

有关这些变更的更多详细信息，请参阅

Spring AI 更新到快照版本 - 结构性变更的初步公告
Spring AI 使用快照版本第二部分 - 模块重构的详细说明
参考指南中的升级说明

有两种方法可以将您的项目更新到 Spring AI 1.0.0-M7

使用 Claude Code CLI 工具和此提示。您也可以使用其他 AI 助手工具，但我们仅测试了 Claude Code。请注意，此自动化方法处理了 artifact ID 更改、包重定位和模块结构更改，但尚未自动处理升级到 MCP 0.9.0 的更改。
有关详细说明，包括关于手动更新 MCP 相关代码的指导，请参阅升级说明。

核心架构改进

全面的模块化架构
- 项目已完全从单体核心重构为专门的领域模块，提供了
  - 减少的依赖占用空间：应用程序只需包含实际使用的模块
  - 最小化的传递依赖：与第三方库的冲突更少
  - 更清晰的关注点分离：每个模块都有明确的职责
- spring-ai-commons：基础模块，不依赖于其他 Spring AI 模块
  - 核心领域模型（Document、TextSplitter 等）
  - JSON 工具和资源处理
  - 结构化日志记录和可观察性支持
- spring-ai-model：基于 commons 提供 AI 功能抽象
  - 接口，如 ChatModel、EmbeddingModel 和 ImageModel
  - 消息类型和提示模板
  - 函数调用框架（ToolDefinition、ToolCallback）
  - 内容过滤和观察支持
- spring-ai-vector-store：统一的向量数据库抽象
  - 用于相似性搜索的 VectorStore 接口
  - 支持 SQL 风格表达式的高级过滤
  - SimpleVectorStore 用于内存使用
  - Embedding 的批量处理支持
- spring-ai-client-chat：高级对话式 AI API
  - ChatClient 接口
  - 通过 ChatMemory 进行对话持久化
  - 使用 OutputConverter 进行响应转换
  - 基于 Advisor 的拦截
  - 同步和响应式流支持
- spring-ai-advisors-vector-store：连接聊天和向量存储以实现 RAG
  - QuestionAnswerAdvisor：将上下文注入提示
  - VectorStoreChatMemoryAdvisor：存储/检索对话历史记录
- spring-ai-model-chat-memory-*：专用持久化实现
  - Cassandra、Neo4j 和 JDBC 实现
- spring-ai-rag：用于检索增强生成的全面框架
  - RAG 管道的模块化架构
  - RetrievalAugmentationAdvisor 作为主要入口点
  - 函数式编程原则与可组合组件
模块化自动配置
- 将单个单体自动配置 artifact 替换为每个组件的独立自动配置 artifact
  - 模型自动配置：spring-ai-autoconfigure-model-{model}
  - 向量存储自动配置：spring-ai-autoconfigure-vector-store-{store}
  - MCP 自动配置：spring-ai-autoconfigure-mcp-{type}
- 此更改最大限度地减少了与 Google Protocol Buffers 和 gRPC 等库的依赖冲突
- 应用程序现在只包含实际使用的组件的自动配置
- 使用相应的 starter 依赖项时，这些自动配置 artifact 会被传递性地包含
包重组
- 类的战略性迁移，以更好地反映其领域职责
  - KeywordMetadataEnricher 和 SummaryMetadataEnricher 从 org.springframework.ai.transformer 移动到 org.springframework.ai.chat.transformer
  - Content、MediaContent 和 Media 从 org.springframework.ai.model 移动到 org.springframework.ai.content
- 改进的包命名约定，以提高可发现性和组织性
框架增强
- 为 MethodToolCallbackProvider 添加了 AOP 代理支持，以实现更灵活的集成
- 增强了 JSON 序列化的运行时提示配置，以改进原生镜像支持
- 通过标准化配置改进了 Spring Boot 集成
- 增强了所有模块的可观察性和指标收集

升级到 MCP 0.9.0

Spring AI 1.0.0-M7 集成了最新的 MCP 参考实现 Java SDK 版本 0.9.0，带来了重大的架构改进

基于会话的架构：改进了对多个并发客户端连接的处理，并增强了会话之间的隔离性
基于交换的交互：新的交换对象提供了客户端和服务器之间的上下文感知交互
增强的传输提供程序抽象：实现了更清晰的连接管理和通信处理之间的分离
改进的工具管理：通过名称改进了工具的去重，以避免在复杂场景中发生冲突
简化的服务器配置：为配置和管理 MCP 服务器提供了简化的 API
全面的 WebFlux 和 WebMvc 支持：为响应式和 Servlet 应用程序增强了传输提供程序

这些改进带来了更健壮、更具扩展性的 MCP 实现，能更好地符合 MCP 规范。有关详细迁移指南，请参阅 MCP Java SDK 变更的升级说明部分。

Spring AI Examples 存储库中的所有示例均已更新，以兼容最新的 MCP 实现：Spring AI Examples repository。

新增和增强的模型集成

Anthropic Claude 更新
- 添加了对 Claude 3.7 Sonnet 模型支持，并将其设为默认
- 增强了“思考”能力（THINKING 和 REDACTED_THINKING 块）
- 重命名了与函数相关的 API 为与工具相关的 API，以保持一致性
- 添加了对 Anthropic API 请求中自定义 HTTP 标头的支持
- 改进了选项，增加了 equals、hashCode 和 deep copy 支持
Mistral AI 增强
- 添加了审核模型支持，用于检测潜在的有害内容
- 实现了具有 JSON schema 功能的自定义结构化输出
- 增强了安全功能和内容过滤
Ollama 改进
- 添加了 min_p 参数以改进采样控制
- 添加了对 qwq 模型支持
- 添加了对 LLAMA3_2_3B 模型支持
Azure OpenAI 更新
- 增强了 AzureOpenAiChatOptions
- 修复了自动配置的 opt-in 行为
- 改进了与 Azure 服务的集成
OpenAI 增强
- 更改了 OpenAI Audio Speech API 中的 voice 参数为 string 类型
- 为 OpenAI Audio API 添加了缺失的音频格式
- 使用 equals、hashCode 和 deep copy 功能增强了 OpenAiChatOptions

Docker Model Runner 支持

Spring AI 1.0.0-M7 增加了对 Docker Desktop 4.40 的 Model Runner 的支持，实现了与本地运行的 AI 模型的无缝集成

OpenAI 兼容 API：Docker Model Runner 提供了一个本地推理 API，设计上兼容 OpenAI API，从而可以轻松地与 Spring AI 集成
标准 OCI Artifacts：模型以标准 OCI artifact 的形式分布在 Docker Hub 的 ai 命名空间下
多种配置选项:
- 直接 TCP 连接到 Model Runner
- 通过 Testcontainers 集成，用于开发和测试

简单配置：只需使用自定义基本 URL 配置 OpenAI 客户端

spring.ai.openai.api-key=ignored
spring.ai.openai.base-url=https://:12434/engines
spring.ai.openai.chat.options.model=ai/gemma3

完整功能支持：所有 Spring AI 功能，包括函数调用、流式传输等，均可与 Docker Model Runner 配合使用
本地模型执行：在 Apple Silicon 上本地运行模型，无需将数据发送到外部服务

有关详细信息，请查阅 Spring AI Docker Model Runner 文档以及我们配套的博客文章 Spring AI with Docker Model Runner，该文章深入探讨了此集成。

特别感谢 Eddú Meléndez 对此功能做出的重要贡献。

工具和多模态能力

工具执行框架
- 引入了 ToolExecutionEligibilityPredicate 接口
- 通过 MCP 服务器按名称改进了工具去重
- 增强了 MCP 工具回调中的错误处理
- 标准化了 MCP 工具名称格式
多模态支持
- 支持工具调用结果中的 base64 编码图像
- 处理 JSON 响应中的 base64 编码图像
- 增强了图像转换能力
- 支持工具响应中的自定义 MIME 类型
文档处理
- 添加了 JSoup HTML 文档读取器，用于解析网页内容
- 增强了文档格式化能力
- 向 ContextualQueryAugmenter 添加了 documentFormatter 参数

内存和存储

聊天内存实现
- 添加了 ChatMemory 的 JDBC 实现
- 将 Cassandra 聊天内存实现迁移到其自己的模块
- 添加了 Neo4j 聊天内存实现
向量存储增强
- 添加了 Couchbase 向量存储支持
- 移除了 CosmosDBVectorStore 中对分区键路径的断言
- 使用原生表达式增强了 Milvus 向量存储
- 添加了 Milvus 中数据库集合的配置选项
- 条件性启用单个向量存储实现
- 增强了 PgVectorStore，使其支持基于 PgIdType 的 schema 生成

查询处理

检索增强
- 向 RetrievalAugmentationAdvisor 中的 Query 添加了 Context 支持
- 移除了所有 QueryTransformer 实现中的默认 temperature
- 增强了上下文处理，以提高相关性

开发者体验

Spring Boot 集成
- 更新了支持的 Spring Boot 版本
- 改进了自动配置模式
- 向 MCP 自动配置添加了 boot 配置处理器
AOT 和原生镜像支持
- 改进了提前编译支持
- 增强了原生镜像兼容性的运行时提示
- 对 JsonInclude 注释进行了全面扫描
文档
- 添加了迁移到 M7 的升级说明
- 使用架构图改进了模块文档
- 为新功能增强了 API 文档

贡献者

还有许多其他重构、错误修复、文档增强等工作由众多贡献者完成。如果您的 PR 尚未被处理，我们会尽快处理，请耐心等待。感谢

Spring 博客