Spring AI 2.0.0-M5 发布：全面转向 OpenAI Java SDK

2025年5月，Spring AI 正式发布了 2.0.0-M5 版本。这是 2.x 里程碑版本的第五个预发布版，带来了大量重要的架构变更——最核心的变化是全面拥抱 OpenAI 官方 Java SDK，同时清理了多个长期积累的技术债务。

---

一、本次发布概览

类别	数量
新功能	13
Bug 修复	36
文档改进	14
其他改进	41

---

二、最重要的变化：OpenAI Java SDK 集成

这是 M5 最大的亮点。spring-ai-openai 模块已完全迁移到官方 openai-java SDK，原来的 spring-ai-openai-sdk 模块被合并移除。

影响范围：

• Chat、Embedding、Image、Audio、Moderation 全部模型都已迁移
• 现有配置兼容 — spring.ai.openai.* 属性和 Builder 模式完全不变，大多数用户无需修改代码
• extraBody 配置被透明映射到 additionalBodyProperties

# 配置方式完全不变
spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.openai.chat.options.model=gpt-4o

对于仍在使用 spring-ai-openai-sdk 的项目，直接移除该依赖即可，功能已全部合并到 spring-ai-openai。

---

三、架构清理：多个模块被移除

M5 进行了大规模的模块清理：

3.1 Azure OpenAI 独立模块移除

spring-ai-azure-openai 已移除，功能合并到 spring-ai-openai。

迁移方式：

// 旧依赖（需移除）
// implementation 'org.springframework.ai:spring-ai-azure-openai'

// 新依赖
implementation 'org.springframework.ai:spring-ai-openai'

# 配置方式不变，只是前缀从 azure-openai 变为 openai
spring.ai.openai.azure.api-key=${AZURE_OPENAI_API_KEY}
spring.ai.openai.azure.endpoint=${AZURE_OPENAI_ENDPOINT}
spring.ai.openai.chat.options.deployment-name=${DEPLOYMENT_NAME}

3.2 Vertex AI 非嵌入模块移除

spring-ai-vertex-ai-gemini 等非 embedding 模块全部移除，仅保留 spring-ai-vertex-ai-embedding。

3.3 ZhipuAI 和 OCI GenAI 移除

这两个国产/云厂商集成被移除，官方建议迁移到其他支持的模型提供商。

---

四、新功能详解

4.1 AudioTranscription — 音频转文本

新增基于 OpenAI SDK 的音频转写模型支持：

@RestController
public class TranscriptionController {
    
    private final AudioTranscriptionModel transcriptionModel;
    
    public TranscriptionController(AudioTranscriptionModel model) {
        this.transcriptionModel = model;
    }
    
    public String transcribe(byte[] audioData) {
        AudioTranscriptionOptions options = AudioTranscriptionOptions.builder()
            .withLanguage("zh")
            .build();
        
        AudioTranscriptionPrompt prompt = new AudioTranscriptionPrompt(
            new ByteArrayResource(audioData), options);
        
        return transcriptionModel.call(prompt).getResult().getOutput();
    }
}

4.2 Moderation Model — 内容审核

新增内容审核模型，统一接入 Spring AI 的模型抽象：

@RestController
public class ContentModerationController {
    
    private final ModerationModel moderationModel;
    
    public String moderate(String userContent) {
        ModerationOptions options = ModerationOptions.builder()
            .withInput(userContent)
            .build();
        
        ModerationPrompt prompt = new ModerationPrompt(options);
        ModerationResult result = moderationModel.call(prompt);
        
        // 检查 flagged 状态
        if (result.getResult().isFlagged()) {
            return "内容需要审核";
        }
        return "内容正常";
    }
}

4.3 Anthropic Web Search

Anthropic 集成现在支持网页搜索工具，模型可以主动搜索网络来回答问题：

spring.ai.anthropic.api-key=${ANTHROPIC_API_KEY}
spring.ai.anthropic.chat.options.tools=web-search

4.4 Anthropic 地理配置和服务级别

新增两个高级配置选项：

# 地理数据主权配置
spring.ai.anthropic.inference.geo.area=us-east-1

# 服务级别（专用容量）
spring.ai.anthropic.chat.options.service-tier=extended

4.5 MCP 工具过滤

MCP Server 新增工具暴露过滤配置：

# 只暴露特定工具给 MCP Client
spring.ai.mcp.server.expose-mcp-client-tools=false
spring.ai.mcp.server.tools=calculator,weather

4.6 统一缓存指标

Usage 接口新增统一的缓存命中/未命中统计：

Usage usage = response.getResult().getUsage();
long cacheHits = usage.getCacheHitTokens();
long cacheMisses = usage.getCacheMissTokens();

---

五、ChatClient 选项合并重构

ModelOptionsUtils.merge() 从模型层面移除，改由 ChatClient 通过 combineWith() 方法统一处理：

// 旧方式（已移除）
// ChatModel chatModel = ...
// ChatOptions options = ChatOptionsBuilder.builder()
//     .withTemperature(0.8)
//     .build();
// chatModel.call(prompt, options); // merge 在底层发生

// 新方式（显式合并）
ChatClient chatClient = ChatClient.create(chatModel);

String result = chatClient.prompt()
    .options(ChatOptionsBuilder.builder()
        .withTemperature(0.8)
        .build())
    .combineWith(userOptions)  // 显式合并
    .user("Hello")
    .call()
    .content();

---

六、安全修复

本次发布包含三个安全相关的修复：

修复	说明
Transformer 缓存目录权限	缓存文件现在使用受限权限，防止未授权访问
恶意 PDF 防御	处理畸形 PDF 时限制内存分配，防御 DoS
CosmosDB 参数化查询	delete() 方法改用参数化查询，防注入

---

七、依赖版本升级

依赖	旧版本	新版本
Spring Boot	4.1.0-M4	4.1.0-RC1
Spring Framework	—	7.0.7
Kotlin	2.3.x	2.3.20
Anthropic SDK	—	2.24.0
MCP Java SDK	—	2.0.0-M2
Apache Tika	3.x	3.3.0
PDFBox	3.x	3.0.7
jsoup	1.x	1.22.1

---

八、升级建议

注意：2.0.0-M5 是 Milestone 版本，生产环境建议等待 GA。

必须检查的事项

1. 使用了 spring-ai-azure-openai → 迁移到 spring-ai-openai，配置前缀从 spring.ai.azure-openai 改为 spring.ai.openai
2. 使用了 spring-ai-openai-sdk → 直接移除依赖
3. 调用了 ModelOptionsUtils.merge() → 改用 ChatClient.combineWith()
4. 使用了 Vertex AI Chat/非嵌入功能 → 迁移到其他模型提供商
5. 使用了 MCP → 检查 MCP Java SDK 2.0.0-M2 的破坏性变更

Maven 依赖示例

// Spring AI BOM
dependencyManagement {
    imports {
        mavenBom 'org.springframework.ai:spring-ai-bom:2.0.0-M5'
    }
}

dependencies {
    // OpenAI（包含 Azure 支持）
    implementation 'org.springframework.ai:spring-ai-openai'
    
    // MCP
    implementation 'org.springframework.ai:spring-ai-mcp'
    
    // 向量存储（根据需要）
    implementation 'org.springframework.ai:spring-ai-pgvector'
}

---

九、参考链接

• GitHub Release Notes
• Spring AI 官方文档
• OpenAI Java SDK Migration Guide

---

本文原创，首发于 CSDN博客。配图来源：Spring 官方。