本文详细介绍 Spring AI 2.0.0-M1 版本的重大升级内容，包括对 Java 21 和 Spring Boot 4.0 的新要求。核心更新涉及 Redis 聊天记忆与向量存储增强、OpenAI 官方 SDK 集成、Claude 4.5 及 Gemini 模型支持等。文章重点梳理了破坏性变更，如默认 Temperature 配置移除、FunctionCallback 弃用及 API 方法重命名，并提供了详细的 Maven 依赖配置、代码迁移示例及最佳实践建议，助力开发者完成平滑迁移。
Spring AI 2.0.0-M1 是 Spring AI 框架的一个重要里程碑版本，在 Spring AI 1.x 的基础上进行了重大升级和改进。该版本基于 Spring Boot 4.0 和 Spring Framework 7.0 构建，提供了更强大的 AI 应用开发能力，增强了与各种 AI 模型和服务的集成，并引入了多项新功能和性能优化。
Spring AI 2.x 必须使用 Java 21 或更高版本。这是与 Spring Boot 4.0 和 Spring Framework 7.0 对齐的要求。
<properties>
<java.version>21</java.version>
<maven.compiler.source>21</maven.compiler.source>
<maven.compiler.target>21</maven.compiler.target>
</properties>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>2.0.0-M1</version>
<type>pom</type>
<scope>import</scope>
</dependency>
Spring AI 2.x 引入了基于 Redis 的聊天记忆实现，支持持久化会话存储。
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-redis</artifactId>
</dependency>
@Configuration
public class RedisChatMemoryConfig {
@Bean
public RedisChatMemoryRepository chatMemoryRepository(RedisConnectionFactory connectionFactory) {
return new RedisChatMemoryRepository(connectionFactory);
}
@Bean
public ChatMemory chatMemory(RedisChatMemoryRepository repository) {
return new SimpleChatMemory(repository);
}
}
Redis 向量存储功能得到显著增强，提供更强大的向量搜索能力。
getNativeClient() 方法访问底层 Redis 客户端@Configuration
public class RedisVectorStoreConfig {
@Bean
public RedisVectorStore vectorStore(RedisConnectionFactory connectionFactory) {
RedisVectorStore.RedisVectorStoreConfig config = RedisVectorStore.RedisVectorStoreConfig.builder()
.withIndexName("vector-index")
.withHnswM(16) // HNSW 参数 M
.withHnswEfConstruction(200) // efConstruction
.withHnswEfRuntime(50) // efRuntime
.build();
return new RedisVectorStore(config, connectionFactory);
}
}
Spring AI 2.x 集成了官方的 OpenAI Java SDK，提供更好的性能和功能支持。
gpt-5-mini@Configuration
public class OpenAIConfig {
@Bean
public OpenAiChatModel chatModel(OpenAiApi openAiApi) {
return new OpenAiChatModel(openAiApi, OpenAiChatOptions.builder()
.withModel("gpt-5-mini")
.withTemperature(0.7f)
.build());
}
}
对 Claude 集成进行了全面更新，支持最新的 Claude 模型和功能。
@Bean
public AnthropicChatModel claudeChatModel(AnthropicApi anthropicApi) {
return new AnthropicChatModel(anthropicApi, AnthropicChatOptions.builder()
.withModel("claude-4-5-sonnet-20241022")
.withTemperature(0.7f)
.withMaxTokens(4096)
.build());
}
@Bean
public GeminiChatModel geminiChatModel(GoogleGenerativeAiApi api) {
return new GeminiChatModel(api, GeminiChatOptions.builder()
.withModel("gemini-pro")
.withThinkingConfig(ThinkingConfig.builder().withThinkingLevel(ThinkingLevel.MEDIUM).build())
.build());
}
新增了 Azure Cosmos DB 聊天记忆存储的 Spring Boot Starter。
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-azure-cosmosdb</artifactId>
</dependency>
为 GemFire Vector Store 添加了用户名和密码认证支持。
@Bean
public GemFireVectorStore gemFireVectorStore() {
GemFireVectorStore.GemFireVectorStoreConfig config = GemFireVectorStore.GemFireVectorStoreConfig.builder()
.withHost("localhost")
.withPort(7070)
.withUsername("admin")
.withPassword("password")
.build();
return new GemFireVectorStore(config);
}
| 功能特性 | Spring AI 1.x | Spring AI 2.x | 说明 |
|---|---|---|---|
| Java 版本要求 | Java 17+ | Java 21+ | 必须升级 |
| Spring Boot 版本 | 3.x | 4.0+ | 重大升级 |
| Spring Framework | 6.x | 7.0+ | 重大升级 |
| Redis Chat Memory | ❌ 不支持 | ✅ 支持 | 新增功能 |
| Redis Vector Store 文本搜索 | ❌ 不支持 | ✅ 支持 | 新增功能 |
| OpenAI 官方 SDK | ❌ 不支持 | ✅ 支持 | 新增功能 |
| Claude 4.5 支持 | ❌ 不支持 | ✅ 支持 | 新增功能 |
| Claude Citations API | ❌ 不支持 | ✅ 支持 | 新增功能 |
| Azure Cosmos DB Memory | ❌ 不支持 | ✅ 支持 | 新增功能 |
| Gemini ThinkingLevel | ❌ 不支持 | ✅ 支持 | 新增功能 |
| GemFire 认证 | ❌ 不支持 | ✅ 支持 | 新增功能 |
| 默认 Temperature 配置 | ✅ 自动配置 | ❌ 需显式配置 | 破坏性变更 |
| 默认 OpenAI 模型 | gpt-4 | gpt-5-mini | 变更 |
| FunctionCallback API | ✅ 支持 | ⚠️ 已弃用 | 建议迁移到 ToolCallback |
变更: 最低 Java 版本从 17 升级到 21
影响: 所有使用 Spring AI 2.x 的项目必须使用 Java 21 或更高版本
迁移步骤:
<!-- 更新 pom.xml -->
<properties>
<java.version>21</java.version>
</properties>
变更: 模型实现中移除了默认的 temperature 配置
影响: 应用程序必须显式配置 temperature 设置
迁移示例:
// Spring AI 1.x (自动配置 temperature)
@Bean
public ChatModel chatModel() {
return new OpenAiChatModel(api);
}
// Spring AI 2.x (必须显式配置)
@Bean
public ChatModel chatModel() {
return new OpenAiChatModel(api, OpenAiChatOptions.builder()
.withTemperature(0.7f) // 必须显式设置
.build());
}
变更: 默认聊天模型从 gpt-4 更新为 gpt-5-mini
影响: 如果依赖默认模型，行为会发生变化
迁移步骤:
// 显式指定模型以保持原有行为
OpenAiChatOptions.builder()
.withModel("gpt-4") // 或使用 gpt-5-mini
.build();
变更: FunctionCallback API 已弃用，推荐使用 ToolCallback API
影响: 使用 FunctionCallback 的代码需要迁移
迁移示例:
// Spring AI 1.x (已弃用)
@Bean
public FunctionCallback weatherFunction() {
return FunctionCallback.builder()
.withName("getWeather")
.withDescription("Get weather information")
.withFunction((location) -> getWeatherData(location))
.build();
}
// Spring AI 2.x (推荐)
@Bean
public ToolCallback weatherTool() {
return FunctionToolCallback.builder()
.withName("getWeather")
.withDescription("Get weather information")
.withFunction((location) -> getWeatherData(location))
.build();
}
变更: 多个 API 方法进行了重命名
主要变更:
ChatClient.builder().defaultFunctions() → ChatClient.builder().defaultTools()ChatClient.functions() → ChatClient.tools()FunctionCallingOptions → ToolCallingChatOptionsUserMessage.properties → UserMessage.metadata变更: maxTokens 和 maxCompletionTokens 参数现在互斥
影响: 只能选择其中一个参数
迁移示例:
// ❌ 错误：不能同时使用
OpenAiChatOptions.builder()
.withMaxTokens(1000)
.withMaxCompletionTokens(500) // 错误
.build();
// ✅ 正确：只使用一个
OpenAiChatOptions.builder()
.withMaxTokens(1000) // 或使用 withMaxCompletionTokens
.build();
变更: 从 VectorStore 中提取了新的 VectorStoreRetriever 接口
影响: 自定义 VectorStore 实现可能需要更新
迁移示例:
// Spring AI 2.x
public class CustomVectorStore implements VectorStore, VectorStoreRetriever {
// 实现两个接口
}
变更: MCP 自动配置类添加了 'Mcp' 前缀
影响: 如果直接引用自动配置类，需要更新引用
<!-- pom.xml -->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>4.0.0</version>
</parent>
<properties>
<java.version>21</java.version>
<spring-ai.version>2.0.0-M1</spring-ai.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>${spring-ai.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</>
// 迁移前 (1.x)
@Bean
public ChatModel chatModel(OpenAiApi api) {
return new OpenAiChatModel(api);
}
// 迁移后 (2.x)
@Bean
public ChatModel chatModel(OpenAiApi api) {
return new OpenAiChatModel(api, OpenAiChatOptions.builder()
.withModel("gpt-4") // 显式指定模型
.withTemperature(0.7f) // 显式设置 temperature
.build());
}
// 迁移前 (1.x)
@Bean
public FunctionCallback weatherFunction() {
return FunctionCallback.builder()
.withName("getWeather")
.withDescription("Get weather")
.withFunction((location) -> getWeather(location))
.build();
}
// 迁移后 (2.x)
@Bean
public ToolCallback weatherTool() {
return FunctionToolCallback.builder()
.withName("getWeather")
.withDescription("Get weather")
.withFunction((location) -> getWeather(location))
.build();
}
// 迁移前 (1.x)
ChatClient chatClient = ChatClient.builder().defaultFunctions(weatherFunction).build();
// 迁移后 (2.x)
ChatClient chatClient = ChatClient.builder().defaultTools(weatherTool).build();
// 迁移前 (1.x)
UserMessage message = new UserMessage("Hello", Map.of("key", "value"));
// 迁移后 (2.x)
UserMessage message = new UserMessage("Hello", MessageMetadata.builder()
.withMetadata("key", "value")
.build());
@SpringBootApplication
public class ChatApplication {
public static void main(String[] args) {
SpringApplication.run(ChatApplication.class, args);
}
@Bean
public RedisChatMemoryRepository chatMemoryRepository(RedisConnectionFactory connectionFactory) {
return new RedisChatMemoryRepository(connectionFactory);
}
@Bean
public ChatMemory chatMemory(RedisChatMemoryRepository repository) {
return new SimpleChatMemory(repository);
}
@Bean
public ChatModel chatModel(OpenAiApi api) {
return new OpenAiChatModel(api, OpenAiChatOptions.builder()
.withModel("gpt-5-mini")
.withTemperature(0.7f)
.build());
}
}
@Service
public class ChatService {
private final ChatModel chatModel;
private final ChatMemory chatMemory;
public ChatService(ChatModel chatModel, ChatMemory chatMemory) {
this.chatModel = chatModel;
this.chatMemory = chatMemory;
}
public String {
chatMemory.getConversation(userId);
conversation.addMessage( (message));
chatModel.call(conversation.getMessages());
conversation.addMessage( (response));
chatMemory.saveConversation(userId, conversation);
response;
}
}
@Configuration
public class VectorStoreConfig {
@Bean
public RedisVectorStore vectorStore(RedisConnectionFactory connectionFactory) {
RedisVectorStore.RedisVectorStoreConfig config = RedisVectorStore.RedisVectorStoreConfig.builder()
.withIndexName("documents")
.withHnswM(16)
.withHnswEfConstruction(200)
.withHnswEfRuntime(50)
.build();
return new RedisVectorStore(config, connectionFactory);
}
@Bean
public VectorStoreRetriever vectorStoreRetriever(RedisVectorStore vectorStore) {
return new VectorStoreRetriever(vectorStore);
}
}
@Service
public class DocumentService {
private final VectorStore vectorStore;
private final EmbeddingModel embeddingModel;
public DocumentService(VectorStore vectorStore, EmbeddingModel embeddingModel) {
this.vectorStore = vectorStore;
this.embeddingModel = embeddingModel;
}
public void addDocument(String id, String text, Map<String, Object> metadata) {
// 生成嵌入向量
Embedding embedding embeddingModel.embed(text);
(id, text, metadata, embedding);
vectorStore.add(List.of(document));
}
List<Document> {
embeddingModel.embed(query);
vectorStore.similaritySearch(SimilaritySearchRequest.builder()
.withQueryEmbedding(queryEmbedding)
.withTopK(topK)
.build());
}
List<Document> {
embeddingModel.embed(query);
vectorStore.similaritySearch(SimilaritySearchRequest.builder()
.withQueryEmbedding(queryEmbedding)
.withTopK(topK)
.withFilterExpression(buildFilterExpression(metadataFilter))
.build());
}
String {
metadata.entrySet().stream()
.map(e -> e.getKey() + + e.getValue())
.collect(Collectors.joining());
}
}
@Configuration
public class ToolConfig {
@Bean
public ToolCallback weatherTool() {
return FunctionToolCallback.builder()
.withName("getWeather")
.withDescription("Get current weather for a location")
.withInputType(WeatherRequest.class)
.withFunction(this::getWeather)
.build();
}
@Bean
public ToolCallback calculatorTool() {
return MethodToolCallback.builder()
.withTarget(this)
.withMethod("calculate")
.withName("calculate")
.withDescription("Perform mathematical calculations")
.build();
}
private WeatherResponse getWeather(WeatherRequest request) {
// 实现天气查询逻辑
return new WeatherResponse(request.getLocation(), "Sunny", 25.0);
}
public double calculate(String expression) {
// 实现计算逻辑
// 简化示例
return 0.0;
}
}
@SpringBootApplication
public class ToolApplication {
@Bean
public ChatClient chatClient(ChatModel chatModel, List<ToolCallback> toolCallbacks) {
ChatClient.builder()
.withChatModel(chatModel)
.defaultTools(toolCallbacks)
.build();
}
{
SpringApplication.run(ToolApplication.class, args);
}
}
@Configuration
public class ClaudeConfig {
@Bean
public AnthropicChatModel claudeChatModel(AnthropicApi anthropicApi) {
return new AnthropicChatModel(anthropicApi, AnthropicChatOptions.builder()
.withModel("claude-4-5-sonnet-20241022")
.withTemperature(0.7f)
.withMaxTokens(4096)
.withCitations(true) // 启用 Citations API
.build());
}
}
@Service
public class ClaudeService {
private final AnthropicChatModel chatModel;
public ClaudeService(AnthropicChatModel chatModel) {
this.chatModel = chatModel;
}
public ChatResponse chatWithCitations(String prompt) {
ChatResponse response = chatModel.call(new Prompt(prompt));
// 处理引用信息
if (response.getResult().getMetadata().containsKey("citations")) {
List<Citation> citations = (List<Citation>) response.getResult().getMetadata().get("citations");
// 处理引用
citations.forEach(citation -> {
System.out.println("Citation: " + citation.getText());
System.out.println("Source: " + citation.getSource());
});
}
return response;
}
}
@Configuration
public class CosmosDbConfig {
@Bean
public CosmosDbChatMemoryRepository chatMemoryRepository(CosmosClient cosmosClient) {
return new CosmosDbChatMemoryRepository(cosmosClient, "chat-db", "conversations");
}
@Bean
public ChatMemory chatMemory(CosmosDbChatMemoryRepository repository) {
return new SimpleChatMemory(repository);
}
}
# application.yml
spring:
ai:
azure:
cosmosdb:
endpoint: https://your-account.documents.azure.com:443/
key: your-key
database: chat-db
container: conversations
推荐: 使用配置文件管理 AI 模型参数
# application.yml
spring:
ai:
openai:
api-key: ${OPENAI_API_KEY}
chat:
options:
model: gpt-5-mini
temperature: 0.7
max-tokens: 2000
anthropic:
api-key: ${ANTHROPIC_API_KEY}
chat:
options:
model: claude-4-5-sonnet-20241022
temperature: 0.7
max-tokens: 4096
推荐: 实现统一的错误处理机制
@RestControllerAdvice
public class AIExceptionHandler {
@ExceptionHandler(AIException.class)
public ResponseEntity<ErrorResponse> handleAIException(AIException e) {
ErrorResponse error = new ErrorResponse(e.getMessage(), e.getErrorCode(), Instant.now());
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(error);
}
@ExceptionHandler(RateLimitException.class)
public ResponseEntity<ErrorResponse> handleRateLimit(RateLimitException e) {
// 实现重试逻辑
return ResponseEntity.status(HttpStatus.TOO_MANY_REQUESTS)
.header("Retry-After", String.valueOf(e.getRetryAfter()))
.body(new ErrorResponse("Rate limit exceeded", "RATE_LIMIT", Instant.now()));
}
}
推荐: 使用连接池和缓存
@Configuration
public class PerformanceConfig {
@Bean
public RedisConnectionFactory redisConnectionFactory() {
LettuceConnectionFactory factory = new LettuceConnectionFactory();
factory.setHostName("localhost");
factory.setPort(6379);
// 配置连接池
GenericObjectPoolConfig<Object> poolConfig = new GenericObjectPoolConfig<>();
poolConfig.setMaxTotal(20);
poolConfig.setMaxIdle(10);
poolConfig.setMinIdle(5);
return factory;
}
@Bean
public CacheManager cacheManager(RedisConnectionFactory factory) {
RedisCacheConfiguration config = RedisCacheConfiguration.defaultCacheConfig()
.entryTtl(Duration.ofMinutes(10))
.serializeKeysWith(RedisSerializationContext.SerializationPair.fromSerializer(new StringRedisSerializer()))
.serializeValuesWith(RedisSerializationContext.SerializationPair.fromSerializer(new GenericJackson2JsonRedisSerializer()));
return RedisCacheManager.builder(factory).cacheDefaults(config).build();
}
}
推荐: 添加详细的监控和日志
@Component
public class AIMonitoringAspect {
private static final Logger logger = LoggerFactory.getLogger(AIMonitoringAspect.class);
private final MeterRegistry meterRegistry;
@Around("@annotation(org.springframework.ai.chat.ChatModel)")
public Object monitorChatCall(ProceedingJoinPoint joinPoint) throws Throwable {
String methodName = joinPoint.getSignature().getName();
Timer.Sample sample = Timer.start(meterRegistry);
try {
Object result = joinPoint.proceed();
sample.stop(Timer.builder("ai.chat.call").tag("method", methodName).tag("status", "success").register(meterRegistry));
logger.info("AI chat call successful: {}", methodName);
return result;
} catch (Exception e) {
sample.stop(Timer.builder("ai.chat.call").tag("method", methodName).tag("status", "error").register(meterRegistry));
logger.error("AI chat call failed: {}", methodName, e);
throw e;
}
}
}
推荐: 保护 API 密钥和敏感信息
@Configuration
public class SecurityConfig {
@Bean
public OpenAiApi openAiApi(@Value("${spring.ai.openai.api-key}") String apiKey) {
// 从安全存储中获取密钥
String secureKey = keyManagementService.getKey("openai-api-key");
return new OpenAiApi(secureKey);
}
// 使用环境变量或密钥管理服务
// 不要在代码中硬编码密钥
// 使用加密存储敏感配置
}
推荐: 编写全面的测试
@SpringBootTest
class ChatServiceTest {
@MockBean
private ChatModel chatModel;
@Autowired
private ChatService chatService;
@Test
void testChat() {
// Mock 响应
when(chatModel.call(anyList())).thenReturn("Hello, how can I help?");
// 测试
String response = chatService.chat("user1", "Hello");
// 验证
assertEquals("Hello, how can I help?", response);
verify(chatModel).call(anyList());
}
}
Spring AI 2.x 是一个重大升级版本，带来了许多新功能和改进：
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online