橙心橙怡1. Spring AI项目概述
Spring AI是Spring生态系统中最新加入的成员，专门为Java开发者提供了一套简化AI功能集成的解决方案。作为一名长期使用Spring框架的后端开发者，我第一次接触Spring AI时就被它的设计理念所吸引——它不像其他AI框架那样要求开发者具备深厚的机器学习背景，而是将AI能力封装成Spring开发者熟悉的接口和模式。
这个框架的核心价值在于：让Java开发者能够用自己熟悉的Spring方式（如依赖注入、自动配置）来调用各类AI模型的功能。无论是聊天对话、文本生成还是图像处理，Spring AI都提供了统一的API抽象。这意味着我们不需要为了使用不同厂商的AI服务而学习多种SDK，也不需要在切换AI供应商时重写大量代码。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与项目搭建
2.1 基础环境配置
在开始之前，我们需要确保开发环境满足以下要求：
- JDK 17或更高版本（Spring AI充分利用了Java的新特性）
- Maven 3.6+或Gradle 7.x（本文以Maven为例）
- Spring Boot 3.2.x或3.3.x
注意：Spring AI目前仍处于快速迭代阶段，建议使用最新的Spring Boot版本以获得最佳兼容性。我在实际项目中曾遇到过Spring Boot 3.1.x与Spring AI的兼容性问题，升级到3.2.x后问题解决。
2.2 Maven仓库配置
由于Spring AI目前还是快照版本，我们需要在pom.xml中添加Spring的Snapshot仓库：
xml复制<repositories>
<repository>
<id>spring-snapshots</id>
<name>Spring Snapshots</name>
<url>https://repo.spring.io/snapshot</url>
<releases>
<enabled>false</enabled>
</releases>
</repository>
</repositories>
2.3 核心依赖引入
Spring AI采用了模块化设计，我们可以按需引入特定AI供应商的starter。以下是最基础的OpenAI模块配置：
xml复制<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>1.0.0-SNAPSHOT</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>
</dependencies>
3. 基础功能实现
3.1 配置文件设置
在application.properties或application.yml中配置AI服务参数：
yaml复制spring:
ai:
openai:
api-key: ${OPENAI_API_KEY}
base-url: https://api.openai.com/v1
实践经验：建议将api-key放在环境变量中而非直接写在配置文件里，这既能提高安全性，也方便在不同环境间切换。我在团队项目中曾因为将key硬编码在配置文件中导致安全审计不通过。
3.2 ChatClient配置
Spring AI的核心接口是ChatClient，它的配置异常简单：
java复制@Configuration
public class AiConfig {
@Bean
public ChatClient chatClient(ChatClient.Builder builder) {
return builder.build();
}
}
这种设计体现了Spring的"约定优于配置"理念。如果需要定制化，可以通过Builder模式添加各种参数：
java复制@Bean
public ChatClient customChatClient(ChatClient.Builder builder) {
return builder
.defaultSystem("你是一个专业的Java技术专家")
.defaultOptions(ChatOptions.builder()
.withTemperature(0.5f)
.build())
.build();
}
3.3 控制器实现
下面是一个完整的REST控制器示例，展示了同步和流式两种响应方式：
java复制@RestController
@RequestMapping("/api/ai")
public class AiController {
private final ChatClient chatClient;
public AiController(ChatClient chatClient) {
this.chatClient = chatClient;
}
@GetMapping("/chat")
public String chat(@RequestParam String message) {
return chatClient.prompt()
.user(message)
.call()
.content();
}
@GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> streamChat(@RequestParam String message) {
return chatClient.prompt()
.user(message)
.stream()
.content();
}
}
4. 高级功能探索
4.1 结构化输出
Spring AI的一个强大功能是将AI输出自动映射为POJO：
java复制public record ProgrammingQuestion(String language, String question, String answer) {}
public ProgrammingQuestion askProgrammingQuestion(String question) {
return chatClient.prompt()
.user("""
请回答以下编程问题，并按照指定JSON格式返回：
语言：{language}
问题：{question}
答案：{answer}
问题：{question}
""".replace("{question}", question))
.call()
.entity(ProgrammingQuestion.class);
}
4.2 函数调用(Function Calling)
Spring AI支持OpenAI的函数调用功能，可以实现更复杂的交互：
java复制@Bean
@Description("根据城市名称获取当前天气")
public Function<WeatherRequest, WeatherResponse> weatherFunction() {
return request -> {
// 实际调用天气API的逻辑
return new WeatherResponse("sunny", 25);
};
}
public String getWeather(String location) {
return chatClient.prompt()
.user("当前" + location + "的天气如何？")
.call()
.content();
}
5. 性能优化与最佳实践
5.1 超时配置
在application.yml中添加合理的超时设置：
yaml复制spring:
ai:
openai:
client:
connect-timeout: 10s
read-timeout: 30s
5.2 缓存策略
对于频繁查询的相似问题，可以添加缓存层：
java复制@Cacheable("aiResponses")
public String getCachedResponse(String prompt) {
return chatClient.prompt()
.user(prompt)
.call()
.content();
}
5.3 异常处理
java复制@RestControllerAdvice
public class AiExceptionHandler {
@ExceptionHandler(AiClientException.class)
public ResponseEntity<String> handleAiException(AiClientException ex) {
return ResponseEntity.status(502)
.body("AI服务暂时不可用: " + ex.getMessage());
}
}
6. 实际应用案例
6.1 代码生成
java复制public String generateCode(String requirement) {
return chatClient.prompt()
.system("你是一个经验丰富的Java开发者")
.user("""
请根据以下需求生成Java代码：
{requirement}
要求：
1. 使用Java 17语法
2. 包含适当的注释
3. 遵循Google Java代码风格
""".replace("{requirement}", requirement))
.call()
.content();
}
6.2 文档摘要
java复制public String summarizeDocument(String text) {
return chatClient.prompt()
.user("""
请为以下技术文档生成摘要：
{text}
摘要要求：
1. 不超过100字
2. 包含关键术语
3. 使用中文输出
""".replace("{text}", text))
.call()
.content();
}
7. 常见问题排查
7.1 连接问题
症状：请求长时间无响应或报连接超时
解决方案：
- 检查网络连接是否正常
- 验证base-url配置是否正确
- 尝试调整超时时间
7.2 认证失败
症状：返回401或403状态码
解决方案：
- 确认api-key是否正确
- 检查key是否有使用权限
- 验证key是否已过期
7.3 速率限制
症状：返回429状态码
解决方案：
- 降低请求频率
- 实现请求队列或限流机制
- 考虑升级API套餐
8. 扩展与集成
8.1 与其他Spring项目集成
Spring AI可以无缝与其他Spring项目集成，比如：
java复制@Service
@Transactional
public class AiEnhancedService {
private final ChatClient chatClient;
private final UserRepository userRepository;
public AiEnhancedService(ChatClient chatClient, UserRepository userRepository) {
this.chatClient = chatClient;
this.userRepository = userRepository;
}
public String generatePersonalizedGreeting(Long userId) {
User user = userRepository.findById(userId).orElseThrow();
return chatClient.prompt()
.user("为{name}生成个性化的欢迎语，他是一名{role}"
.replace("{name}", user.getName())
.replace("{role}", user.getRole()))
.call()
.content();
}
}
8.2 自定义模型接入
如果需要接入非官方支持的模型，可以实现自定义适配器：
java复制public class CustomAiAdapter implements ChatClient {
@Override
public ChatResponse call(Prompt prompt) {
// 实现自定义模型的调用逻辑
}
}
@Bean
public ChatClient customAiClient() {
return new CustomAiAdapter();
}
经过多个项目的实践验证，Spring AI确实大幅降低了Java项目集成AI功能的门槛。它的设计既保留了Spring框架的优雅特性，又提供了足够的灵活性来应对不同的AI场景。对于已经熟悉Spring生态的团队来说，这无疑是快速拥抱AI时代的最佳选择之一。