使用 Spring AI 1.0.0 M7 已发布

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

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

为了庆祝这个版本，我们在我们的 AI 生成的音乐播放列表中添加了一首新歌，由 Josh Long 和 Claude 作词！查看最新曲目以增强您的博客阅读和编码体验。

以下是此版本的关键变化。请注意，存在破坏性变更！

破坏性变更

Spring AI 1.0.0-M7 引入了几项重要变更，这些变更与之前在 SNAPSHOT 版本中引入的结构改进一致。这些变更创建了一个更模块化和更易于维护的代码库，同时减少了应用程序中不必要的依赖项。

Artifact ID 变更

最重要的变化是 Spring AI starter artifact 的命名模式

Model starters: spring-ai-{model}-spring-boot-starter → spring-ai-starter-model-{model}
Vector Store starters: spring-ai-{store}-store-spring-boot-starter → spring-ai-starter-vector-store-{store}
MCP starters: 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 Snapshots 更新 - 结构变更的初步公告
Spring AI 使用 Snapshots 第二部分 - 模块重组的详细解释
参考指南中的升级说明

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

使用 Claude Code CLI tool 工具并使用此 prompt。您也可以使用其他 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
  - 消息类型和 prompt 模板
  - 函数调用框架（ToolDefinition、ToolCallback）
  - 内容过滤和观察支持
- spring-ai-vector-store：统一的向量数据库抽象
  - 用于相似性搜索的 VectorStore 接口
  - 使用类似 SQL 的表达式进行高级过滤
  - 用于内存使用的 SimpleVectorStore
  - embeddings 的批量处理支持
- spring-ai-client-chat：高级会话 AI API
  - ChatClient 接口
  - 通过 ChatMemory 进行会话持久化
  - 使用 OutputConverter 进行响应转换
  - 基于 Advisor 的拦截
  - 同步和响应式流支持
- spring-ai-advisors-vector-store：桥接聊天与向量存储以实现 RAG
  - QuestionAnswerAdvisor：将上下文注入到 prompts 中
  - VectorStoreChatMemoryAdvisor：存储/检索会话历史记录
- spring-ai-model-chat-memory-*：专业的持久化实现
  - Cassandra、Neo4j 和 JDBC 实现
- spring-ai-rag：用于检索增强生成 (Retrieval Augmented Generation) 的综合框架
  - RAG pipelines 的模块化架构
  - 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 序列化的运行时提示配置，以改善 native image 支持
- 通过标准化配置改进了 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 repository 中的所有示例已更新，以与最新的 MCP 实现协同工作。

新增和增强的模型集成

Anthropic Claude 更新
- 添加了对 Claude 3.7 Sonnet 模型的支持并将其设置为默认
- 增强了“思考”能力（THINKING 和 REDACTED_THINKING 块）
- 将函数相关的 API 重命名为工具相关的 API 以保持一致性
- 在 Anthropic API 请求中添加了对自定义 HTTP header 的支持
- 改进了 options，支持 equals、hashCode 和深度复制
Mistral AI 增强
- 添加了 moderation 模型支持，用于检测潜在的有害内容
- 实现了带有 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 添加了缺失的音频格式
- 增强了 OpenAiChatOptions，新增了 equals、hashCode 和深度复制功能

Docker Model Runner 支持

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

OpenAI 兼容 API：Docker Model Runner 提供了一个设计上与 OpenAI API 兼容的本地推理 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=http://localhost: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 server 中按名称进行的工具去重
- 增强了 MCP 工具回调中的错误处理
- 标准化了 MCP 工具名称格式
多模态支持
- 支持工具调用结果中的 base64 编码图像
- 处理 JSON 响应中的 base64 编码图像
- 增强了图像转换能力
- 支持工具响应中的自定义 MIME 类型
文档处理
- 添加了 JSoup HTML 文档读取器用于解析网页内容
- 增强了文档格式化能力
- 为 ContextualQueryAugmenter 添加了 documentFormatter 参数

内存和存储

聊天内存实现
- 添加了 JDBC 实现的 ChatMemory
- 将 Cassandra 聊天内存实现迁移到其自己的模块中
- 添加了 Neo4j 聊天内存实现
向量存储增强
- 添加了 Couchbase 向量存储支持
- 移除了 CosmosDBVectorStore 中对 partition key path 的断言
- 通过 native expressions 增强了 Milvus 向量存储
- 为 Milvus 中的数据库集合添加了配置选项
- 对单个向量存储实现进行条件启用
- 使用基于 PgIdType 的 schema 生成增强了 PgVectorStore

查询处理

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

开发者体验

Spring Boot 集成
- 更新了支持的 Spring Boot 版本
- 改进了自动配置模式
- 为 MCP 自动配置添加了 boot configuration processor
AOT 和 Native Image 支持
- 改进了 ahead-of-time 编译支持
- 增强了 native image 兼容性的运行时提示
- 全面扫描 JsonInclude 注解
文档
- 添加了迁移到 M7 的升级说明
- 改进了带有架构图的模块文档
- 增强了新功能的 API 文档

贡献者

还有许多其他 refactoring、bug fixing、文档增强，由广泛的贡献者完成。如果您的 PR 还没有被处理，请耐心等待，我们会处理的。感谢以下贡献者：

Spring 博客