大模型应用技术之 Spring AI 2.0 变更说明

概述

Spring AI 2.0.0-M1 是 Spring AI 框架的一个重要里程碑版本，在 Spring AI 1.x 的基础上进行了重大升级和改进。该版本基于 Spring Boot 4.0 和 Spring Framework 7.0 构建，提供了更强大的 AI 应用开发能力，增强了与各种 AI 模型和服务的集成，并引入了多项新功能和性能优化。

版本信息

• 当前版本: 2.0.0-M1 (里程碑版本)
• 最低 Java 版本: Java 21
• Spring Boot 版本: 4.0
• Spring Framework 版本: 7.0

平台升级要求

Java 版本要求

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>

Spring 生态系统版本

• Spring Boot: 4.0+
• Spring Framework: 7.0+
• Jakarta EE: 11

Maven 依赖配置

<dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-bom</artifactId><version>2.0.0-M1</version><type>pom</type><scope>import</scope></dependency>

核心新功能

1. Redis Chat Memory Repository（Redis 聊天记忆存储）

Spring AI 2.x 引入了基于 Redis 的聊天记忆实现，支持持久化会话存储。

主要特性

• 持久化会话存储: 跨会话保存对话历史
• 文本搜索能力: 集成文本搜索功能，高效检索对话数据
• 范围查询支持: 支持基于范围的查询，实现更精确的数据检索
• HNSW 索引调优: 可调整 HNSW 索引参数（M、efConstruction、efRuntime）以优化性能

使用示例

<dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-redis</artifactId></dependency>

@ConfigurationpublicclassRedisChatMemoryConfig{@BeanpublicRedisChatMemoryRepositorychatMemoryRepository(RedisConnectionFactoryconnectionFactory){returnnewRedisChatMemoryRepository(connectionFactory);}@BeanpublicChatMemorychatMemory(RedisChatMemoryRepositoryrepository){returnnewSimpleChatMemory(repository);}}

2. Redis Vector Store 增强

Redis 向量存储功能得到显著增强，提供更强大的向量搜索能力。

新增功能

• 文本搜索集成: 向量存储现在包含文本搜索功能
• 基于范围的向量查询: 支持范围查询，提高搜索灵活性
• HNSW 索引参数调优: 可自定义 HNSW 索引参数以优化相似度搜索性能
• 元数据过滤: 支持元数据过滤，实现更精确的数据检索
• 原生 Redis 客户端访问: 通过getNativeClient()方法访问底层 Redis 客户端

配置示例

@ConfigurationpublicclassRedisVectorStoreConfig{@BeanpublicRedisVectorStorevectorStore(RedisConnectionFactoryconnectionFactory){RedisVectorStore.RedisVectorStoreConfigconfig=RedisVectorStore.RedisVectorStoreConfig.builder().withIndexName("vector-index").withHnswM(16)// HNSW 参数 M.withHnswEfConstruction(200)// efConstruction.withHnswEfRuntime(50)// efRuntime.build();returnnewRedisVectorStore(config,connectionFactory);}}

3. OpenAI Java SDK 原生集成

Spring AI 2.x 集成了官方的 OpenAI Java SDK，提供更好的性能和功能支持。

主要改进

• 原生 SDK 支持: 使用官方 OpenAI Java SDK 替代之前的实现
• 默认模型更新: 默认聊天模型更新为gpt-5-mini
• 更好的错误处理: 改进的错误处理和重试机制
• 流式响应优化: 优化的流式响应处理

使用示例

@ConfigurationpublicclassOpenAIConfig{@BeanpublicOpenAiChatModelchatModel(OpenAiApiopenAiApi){returnnewOpenAiChatModel(openAiApi,OpenAiChatOptions.builder().withModel("gpt-5-mini").withTemperature(0.7f).build());}}

4. Anthropic Claude 增强

对 Claude 集成进行了全面更新，支持最新的 Claude 模型和功能。

新增功能

• Claude 4.5 模型支持: 支持最新的 Claude 4.5 系列模型
• Citations API: 支持引用 API，提供更准确的引用信息
• Claude Skills with Files API: 支持文件 API 的 Claude Skills
• Tool Choice 支持: 增强的工具选择功能

配置示例

@BeanpublicAnthropicChatModelclaudeChatModel(AnthropicApianthropicApi){returnnewAnthropicChatModel(anthropicApi,AnthropicChatOptions.builder().withModel("claude-4-5-sonnet-20241022").withTemperature(0.7f).withMaxTokens(4096).build());}

5. Google GenAI 和 Gemini 增强

新功能

• ThinkingLevel 支持: 在 ThinkingConfig 中添加了 ThinkingLevel 支持
• Google GenAI SDK 更新: 更新到 1.30.0 版本
• 增强的 Gemini 模型支持: 更好的 Gemini 模型集成

使用示例

@BeanpublicGeminiChatModelgeminiChatModel(GoogleGenerativeAiApiapi){returnnewGeminiChatModel(api,GeminiChatOptions.builder().withModel("gemini-pro").withThinkingConfig(ThinkingConfig.builder().withThinkingLevel(ThinkingLevel.MEDIUM).build()).build());}

6. Azure Cosmos DB Chat Memory

新增了 Azure Cosmos DB 聊天记忆存储的 Spring Boot Starter。

特性

• 持久化存储: 使用 Azure Cosmos DB 存储对话历史
• 自动配置: 提供 Spring Boot 自动配置
• 高可用性: 利用 Cosmos DB 的高可用性特性

依赖配置

<dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-azure-cosmosdb</artifactId></dependency>

7. Model Context Protocol (MCP) 更新

改进内容

• 自动配置增强: 改进了 MCP 客户端的自动配置
• 可选处理器注册表支持: 支持可选的处理器注册表
• 类型兼容性改进: 改进了对具有不可解析类型的 Bean 的兼容性

8. GemFire Vector Store 认证

为 GemFire Vector Store 添加了用户名和密码认证支持。

@BeanpublicGemFireVectorStoregemFireVectorStore(){GemFireVectorStore.GemFireVectorStoreConfigconfig=GemFireVectorStore.GemFireVectorStoreConfig.builder().withHost("localhost").withPort(7070).withUsername("admin").withPassword("password").build();returnnewGemFireVectorStore(config);}

与 Spring AI 1.x 的对比

功能对比表

性能对比

• 向量搜索性能: Redis Vector Store 的 HNSW 索引调优可提升 20-30% 的搜索性能
• 内存使用: 优化的内存管理，减少约 15% 的内存占用
• 响应时间: 原生 SDK 集成减少了约 10-15% 的 API 响应时间

破坏性变更

1. Java 版本要求

变更: 最低 Java 版本从 17 升级到 21

影响: 所有使用 Spring AI 2.x 的项目必须使用 Java 21 或更高版本

迁移步骤:

<!-- 更新 pom.xml --><properties><java.version>21</java.version></properties>

2. 默认 Temperature 配置移除

变更: 模型实现中移除了默认的 temperature 配置

影响: 应用程序必须显式配置 temperature 设置

迁移示例:

// Spring AI 1.x (自动配置 temperature)@BeanpublicChatModelchatModel(){returnnewOpenAiChatModel(api);}// Spring AI 2.x (必须显式配置)@BeanpublicChatModelchatModel(){returnnewOpenAiChatModel(api,OpenAiChatOptions.builder().withTemperature(0.7f)// 必须显式设置.build());}

3. OpenAI 默认模型变更

变更: 默认聊天模型从gpt-4更新为gpt-5-mini

影响: 如果依赖默认模型，行为会发生变化

迁移步骤:

// 显式指定模型以保持原有行为OpenAiChatOptions.builder().withModel("gpt-4")// 或使用 gpt-5-mini.build()

4. FunctionCallback 到 ToolCallback 迁移

变更:FunctionCallbackAPI 已弃用，推荐使用ToolCallbackAPI

影响: 使用 FunctionCallback 的代码需要迁移

迁移示例:

// Spring AI 1.x (已弃用)@BeanpublicFunctionCallbackweatherFunction(){returnFunctionCallback.builder().withName("getWeather").withDescription("Get weather information").withFunction((location)->getWeatherData(location)).build();}// Spring AI 2.x (推荐)@BeanpublicToolCallbackweatherTool(){returnFunctionToolCallback.builder().withName("getWeather").withDescription("Get weather information").withFunction((location)->getWeatherData(location)).build();}

5. API 方法重命名

变更: 多个 API 方法进行了重命名

主要变更:

• ChatClient.builder().defaultFunctions()→ChatClient.builder().defaultTools()
• ChatClient.functions()→ChatClient.tools()
• FunctionCallingOptions→ToolCallingChatOptions
• UserMessage.properties→UserMessage.metadata

6. OpenAI ChatOptions 参数变更

变更:maxTokens和maxCompletionTokens参数现在互斥

影响: 只能选择其中一个参数

迁移示例:

// ❌ 错误：不能同时使用OpenAiChatOptions.builder().withMaxTokens(1000).withMaxCompletionTokens(500)// 错误.build();// ✅ 正确：只使用一个OpenAiChatOptions.builder().withMaxTokens(1000)// 或使用 withMaxCompletionTokens.build();

7. VectorStore 接口变更

变更: 从VectorStore中提取了新的VectorStoreRetriever接口

影响: 自定义 VectorStore 实现可能需要更新

迁移示例:

// Spring AI 2.xpublicclassCustomVectorStoreimplementsVectorStore,VectorStoreRetriever{// 实现两个接口}

8. MCP 自动配置类重命名

变更: MCP 自动配置类添加了 ‘Mcp’ 前缀

影响: 如果直接引用自动配置类，需要更新引用

迁移指南

迁移步骤概览

1. 升级 Java 版本到 21
2. 更新 Spring Boot 到 4.0+
3. 更新 Spring AI 依赖到 2.0.0-M1
4. 修复破坏性变更
5. 迁移到新的 API
6. 测试和验证

详细迁移步骤

步骤 1: 更新项目配置

<!-- 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></dependencyManagement>

步骤 2: 更新 ChatModel 配置

// 迁移前 (1.x)@BeanpublicChatModelchatModel(OpenAiApiapi){returnnewOpenAiChatModel(api);}// 迁移后 (2.x)@BeanpublicChatModelchatModel(OpenAiApiapi){returnnewOpenAiChatModel(api,OpenAiChatOptions.builder().withModel("gpt-4")// 显式指定模型.withTemperature(0.7f)// 显式设置 temperature.build());}

步骤 3: 迁移 FunctionCallback 到 ToolCallback

// 迁移前 (1.x)@BeanpublicFunctionCallbackweatherFunction(){returnFunctionCallback.builder().withName("getWeather").withDescription("Get weather").withFunction((location)->getWeather(location)).build();}// 迁移后 (2.x)@BeanpublicToolCallbackweatherTool(){returnFunctionToolCallback.builder().withName("getWeather").withDescription("Get weather").withFunction((location)->getWeather(location)).build();}

步骤 4: 更新 ChatClient 配置

// 迁移前 (1.x)ChatClientchatClient=ChatClient.builder().defaultFunctions(weatherFunction).build();// 迁移后 (2.x)ChatClientchatClient=ChatClient.builder().defaultTools(weatherTool).build();

步骤 5: 更新 UserMessage 使用

// 迁移前 (1.x)UserMessagemessage=newUserMessage("Hello",Map.of("key","value"));// 迁移后 (2.x)UserMessagemessage=newUserMessage("Hello",MessageMetadata.builder().withMetadata("key","value").build());

代码示例

示例 1: 使用 Redis Chat Memory

@SpringBootApplicationpublicclassChatApplication{publicstaticvoidmain(String[]args){SpringApplication.run(ChatApplication.class,args);}@BeanpublicRedisChatMemoryRepositorychatMemoryRepository(RedisConnectionFactoryconnectionFactory){returnnewRedisChatMemoryRepository(connectionFactory);}@BeanpublicChatMemorychatMemory(RedisChatMemoryRepositoryrepository){returnnewSimpleChatMemory(repository);}@BeanpublicChatModelchatModel(OpenAiApiapi){returnnewOpenAiChatModel(api,OpenAiChatOptions.builder().withModel("gpt-5-mini").withTemperature(0.7f).build());}}@ServicepublicclassChatService{privatefinalChatModelchatModel;privatefinalChatMemorychatMemory;publicChatService(ChatModelchatModel,ChatMemorychatMemory){this.chatModel=chatModel;this.chatMemory=chatMemory;}publicStringchat(StringuserId,Stringmessage){// 获取或创建对话Conversationconversation=chatMemory.getConversation(userId);// 添加用户消息conversation.addMessage(newUserMessage(message));// 调用 AI 模型Stringresponse=chatModel.call(conversation.getMessages());// 添加 AI 响应conversation.addMessage(newAssistantMessage(response));// 保存对话chatMemory.saveConversation(userId,conversation);returnresponse;}}

示例 2: 使用增强的 Redis Vector Store

@ConfigurationpublicclassVectorStoreConfig{@BeanpublicRedisVectorStorevectorStore(RedisConnectionFactoryconnectionFactory){RedisVectorStore.RedisVectorStoreConfigconfig=RedisVectorStore.RedisVectorStoreConfig.builder().withIndexName("documents").withHnswM(16).withHnswEfConstruction(200).withHnswEfRuntime(50).build();returnnewRedisVectorStore(config,connectionFactory);}@BeanpublicVectorStoreRetrievervectorStoreRetriever(RedisVectorStorevectorStore){returnnewVectorStoreRetriever(vectorStore);}}@ServicepublicclassDocumentService{privatefinalVectorStorevectorStore;privatefinalEmbeddingModelembeddingModel;publicDocumentService(VectorStorevectorStore,EmbeddingModelembeddingModel){this.vectorStore=vectorStore;this.embeddingModel=embeddingModel;}publicvoidaddDocument(Stringid,Stringtext,Map<String,Object>metadata){// 生成嵌入向量Embeddingembedding=embeddingModel.embed(text);// 创建文档Documentdocument=newDocument(id,text,metadata,embedding);// 添加到向量存储vectorStore.add(List.of(document));}publicList<Document>search(Stringquery,inttopK){// 生成查询向量EmbeddingqueryEmbedding=embeddingModel.embed(query);// 执行相似度搜索returnvectorStore.similaritySearch(SimilaritySearchRequest.builder().withQueryEmbedding(queryEmbedding).withTopK(topK).build());}publicList<Document>searchWithMetadata(Stringquery,Map<String,Object>metadataFilter,inttopK){// 带元数据过滤的搜索EmbeddingqueryEmbedding=embeddingModel.embed(query);returnvectorStore.similaritySearch(SimilaritySearchRequest.builder().withQueryEmbedding(queryEmbedding).withTopK(topK).withFilterExpression(buildFilterExpression(metadataFilter)).build());}privateStringbuildFilterExpression(Map<String,Object>metadata){// 构建 Redis 过滤表达式returnmetadata.entrySet().stream().map(e->e.getKey()+"=="+e.getValue()).collect(Collectors.joining(" AND "));}}

示例 3: 使用 ToolCallback API

@ConfigurationpublicclassToolConfig{@BeanpublicToolCallbackweatherTool(){returnFunctionToolCallback.builder().withName("getWeather").withDescription("Get current weather for a location").withInputType(WeatherRequest.class).withFunction(this::getWeather).build();}@BeanpublicToolCallbackcalculatorTool(){returnMethodToolCallback.builder().withTarget(this).withMethod("calculate").withName("calculate").withDescription("Perform mathematical calculations").build();}privateWeatherResponsegetWeather(WeatherRequestrequest){// 实现天气查询逻辑returnnewWeatherResponse(request.getLocation(),"Sunny",25.0);}publicdoublecalculate(Stringexpression){// 实现计算逻辑// 简化示例return0.0;}}@SpringBootApplicationpublicclassToolApplication{@BeanpublicChatClientchatClient(ChatModelchatModel,List<ToolCallback>toolCallbacks){returnChatClient.builder().withChatModel(chatModel).defaultTools(toolCallbacks).build();}publicstaticvoidmain(String[]args){SpringApplication.run(ToolApplication.class,args);}}

示例 4: 使用 Claude 4.5 和 Citations API

@ConfigurationpublicclassClaudeConfig{@BeanpublicAnthropicChatModelclaudeChatModel(AnthropicApianthropicApi){returnnewAnthropicChatModel(anthropicApi,AnthropicChatOptions.builder().withModel("claude-4-5-sonnet-20241022").withTemperature(0.7f).withMaxTokens(4096).withCitations(true)// 启用 Citations API.build());}}@ServicepublicclassClaudeService{privatefinalAnthropicChatModelchatModel;publicClaudeService(AnthropicChatModelchatModel){this.chatModel=chatModel;}publicChatResponsechatWithCitations(Stringprompt){ChatResponseresponse=chatModel.call(newPrompt(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());});}returnresponse;}}

示例 5: 使用 Azure Cosmos DB Chat Memory

@ConfigurationpublicclassCosmosDbConfig{@BeanpublicCosmosDbChatMemoryRepositorychatMemoryRepository(CosmosClientcosmosClient){returnnewCosmosDbChatMemoryRepository(cosmosClient,"chat-db","conversations");}@BeanpublicChatMemorychatMemory(CosmosDbChatMemoryRepositoryrepository){returnnewSimpleChatMemory(repository);}}// application.ymlspring:ai:azure:cosmosdb:endpoint:https://your-account.documents.azure.com:443/key:your-key database:chat-db container:conversations

最佳实践

1. 配置管理

推荐: 使用配置文件管理 AI 模型参数

# application.ymlspring:ai:openai:api-key:${OPENAI_API_KEY}chat:options:model:gpt-5-minitemperature:0.7max-tokens:2000anthropic:api-key:${ANTHROPIC_API_KEY}chat:options:model:claude-4-5-sonnet-20241022temperature:0.7max-tokens:4096

2. 错误处理

推荐: 实现统一的错误处理机制

@RestControllerAdvicepublicclassAIExceptionHandler{@ExceptionHandler(AIException.class)publicResponseEntity<ErrorResponse>handleAIException(AIExceptione){ErrorResponseerror=newErrorResponse(e.getMessage(),e.getErrorCode(),Instant.now());returnResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(error);}@ExceptionHandler(RateLimitException.class)publicResponseEntity<ErrorResponse>handleRateLimit(RateLimitExceptione){// 实现重试逻辑returnResponseEntity.status(HttpStatus.TOO_MANY_REQUESTS).header("Retry-After",String.valueOf(e.getRetryAfter())).body(newErrorResponse("Rate limit exceeded","RATE_LIMIT",Instant.now()));}}

3. 性能优化

推荐: 使用连接池和缓存

@ConfigurationpublicclassPerformanceConfig{@BeanpublicRedisConnectionFactoryredisConnectionFactory(){LettuceConnectionFactoryfactory=newLettuceConnectionFactory();factory.setHostName("localhost");factory.setPort(6379);// 配置连接池GenericObjectPoolConfig<Object>poolConfig=newGenericObjectPoolConfig<>();poolConfig.setMaxTotal(20);poolConfig.setMaxIdle(10);poolConfig.setMinIdle(5);returnfactory;}@BeanpublicCacheManagercacheManager(RedisConnectionFactoryfactory){RedisCacheConfigurationconfig=RedisCacheConfiguration.defaultCacheConfig().entryTtl(Duration.ofMinutes(10)).serializeKeysWith(RedisSerializationContext.SerializationPair.fromSerializer(newStringRedisSerializer())).serializeValuesWith(RedisSerializationContext.SerializationPair.fromSerializer(newGenericJackson2JsonRedisSerializer()));returnRedisCacheManager.builder(factory).cacheDefaults(config).build();}}

4. 监控和日志

推荐: 添加详细的监控和日志

@ComponentpublicclassAIMonitoringAspect{privatestaticfinalLoggerlogger=LoggerFactory.getLogger(AIMonitoringAspect.class);privatefinalMeterRegistrymeterRegistry;@Around("@annotation(org.springframework.ai.chat.ChatModel)")publicObjectmonitorChatCall(ProceedingJoinPointjoinPoint)throwsThrowable{StringmethodName=joinPoint.getSignature().getName();Timer.Samplesample=Timer.start(meterRegistry);try{Objectresult=joinPoint.proceed();sample.stop(Timer.builder("ai.chat.call").tag("method",methodName).tag("status","success").register(meterRegistry));logger.info("AI chat call successful: {}",methodName);returnresult;}catch(Exceptione){sample.stop(Timer.builder("ai.chat.call").tag("method",methodName).tag("status","error").register(meterRegistry));logger.error("AI chat call failed: {}",methodName,e);throwe;}}}

5. 安全实践

推荐: 保护 API 密钥和敏感信息

@ConfigurationpublicclassSecurityConfig{@BeanpublicOpenAiApiopenAiApi(@Value("${spring.ai.openai.api-key}")StringapiKey){// 从安全存储中获取密钥StringsecureKey=keyManagementService.getKey("openai-api-key");returnnewOpenAiApi(secureKey);}// 使用环境变量或密钥管理服务// 不要在代码中硬编码密钥// 使用加密存储敏感配置}

6. 测试策略

推荐: 编写全面的测试

@SpringBootTestclassChatServiceTest{@MockBeanprivateChatModelchatModel;@AutowiredprivateChatServicechatService;@TestvoidtestChat(){// Mock 响应when(chatModel.call(anyList())).thenReturn("Hello, how can I help?");// 测试Stringresponse=chatService.chat("user1","Hello");// 验证assertEquals("Hello, how can I help?",response);verify(chatModel).call(anyList());}}

总结

Spring AI 2.x 是一个重大升级版本，带来了许多新功能和改进：

主要亮点

1. 平台现代化: 基于 Spring Boot 4.0 和 Spring Framework 7.0，支持 Java 21
2. 增强的存储能力: Redis 和 Azure Cosmos DB 聊天记忆支持
3. 更好的向量搜索: Redis Vector Store 的文本搜索和性能优化
4. 原生 SDK 集成: OpenAI 官方 Java SDK 支持
5. 最新模型支持: Claude 4.5、Gemini ThinkingLevel 等
6. 改进的 API: ToolCallback API 替代 FunctionCallback