1. 项目概述最近在技术社区看到不少关于Spring AI的讨论作为一个长期使用Spring生态的开发者我决定亲自尝试一下这个新兴框架。Spring AI是Spring官方推出的AI集成方案它让开发者能够以熟悉的Spring方式调用各类AI能力。本文将记录我从零开始搭建环境到实现多轮对话的全过程环境基于JDK 17和Spring Boot 3.5。这个项目特别适合已经熟悉Spring Boot但想快速接入AI能力的开发者。相比直接调用AI厂商的APISpring AI提供了更符合Spring习惯的抽象层能显著降低学习成本。我将在后文详细展示如何用最少的代码实现对话式AI功能。2. 环境准备与项目初始化2.1 基础环境配置首先需要确认开发环境满足以下要求JDK 17推荐使用Amazon Corretto或OpenJDKMaven 3.6或Gradle 7.xIDEIntelliJ IDEA或VS Code验证JDK版本java -version如果版本不符可以通过SDKMAN!快速切换sdk install java 17.0.8-amzn sdk use java 17.0.8-amzn2.2 创建Spring Boot项目使用Spring Initializr创建项目时需要注意几个关键配置选择Spring Boot 3.1.0或更高版本添加Spring Web和Spring AI依赖打包方式建议选JarJava版本选择17对于已经存在的项目可以手动添加Spring AI依赖Maven示例dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId version0.8.0/version /dependency注意Spring AI目前还在快速迭代中建议锁定具体版本号以避免兼容性问题。3. API密钥配置与基础测试3.1 获取AI服务凭证目前Spring AI主要支持OpenAI、Azure OpenAI等主流服务。以OpenAI为例登录OpenAI平台进入API Keys页面创建新的API密钥3.2 安全配置密钥千万不要将密钥硬编码在代码中推荐做法在application.properties中配置spring.ai.openai.api-key${OPENAI_API_KEY}通过环境变量传入密钥export OPENAI_API_KEYyour_key_here对于生产环境建议使用Vault或KMS等专业密钥管理服务。3.3 基础对话测试创建一个简单的REST控制器RestController public class AIController { private final OpenAiChatClient chatClient; public AIController(OpenAiChatClient chatClient) { this.chatClient chatClient; } GetMapping(/ai/chat) public String chat(RequestParam String message) { return chatClient.call(message); } }启动应用后访问http://localhost:8080/ai/chat?message你好你应该能收到AI的回复。这个简单的端点验证了基础集成是成功的。4. 实现多轮对话功能4.1 对话上下文管理单次问答无法维持对话上下文我们需要改进实现PostMapping(/ai/conversation) public String conversation(RequestBody ListChatMessage messages) { return chatClient.call(messages); }请求示例[ {role: user, content: 推荐一本编程书}, {role: assistant, content: 《Clean Code》很不错}, {role: user, content: 中文版有吗} ]4.2 持久化对话记录实际应用中需要持久化对话历史简单的实现方案Service public class ConversationService { private final MapString, ListChatMessage conversations new ConcurrentHashMap(); public String handleMessage(String conversationId, String userMessage) { ListChatMessage messages conversations.computeIfAbsent( conversationId, k - new ArrayList()); messages.add(new ChatMessage(user, userMessage)); String response chatClient.call(messages); messages.add(new ChatMessage(assistant, response)); return response; } }4.3 高级对话参数配置可以通过ChatOptions定制对话行为Bean public OpenAiChatClient openAiChatClient(OpenAiApi openAiApi) { OpenAiChatOptions options OpenAiChatOptions.builder() .withModel(gpt-4) .withTemperature(0.7f) .withMaxTokens(500) .build(); return new OpenAiChatClient(openAiApi, options); }关键参数说明model指定使用的模型版本temperature控制回答的随机性0-1maxTokens限制响应长度5. 生产环境注意事项5.1 性能优化建议实现响应缓存Cacheable(value aiResponses, key #message) public String getCachedResponse(String message) { return chatClient.call(message); }设置合理的超时spring.ai.openai.api-timeout30s5.2 异常处理必须处理API可能抛出的异常ExceptionHandler(OpenAiApiException.class) public ResponseEntityString handleAiException(OpenAiApiException ex) { if (ex.getStatusCode().is4xxClientError()) { return ResponseEntity.badRequest().body(请求参数错误); } return ResponseEntity.internalServerError() .body(AI服务暂时不可用); }5.3 安全防护措施实现速率限制RateLimiter(name aiApiLimiter) public String rateLimitedCall(String message) { return chatClient.call(message); }敏感内容过滤public String safeCall(String message) { if (containsSensitiveContent(message)) { throw new ContentPolicyException(); } return chatClient.call(message); }6. 扩展应用场景6.1 结构化数据提取Spring AI支持将响应自动转换为对象public class BookRecommendation { private String title; private String author; private String reason; // getters/setters } GetMapping(/ai/recommend) public BookRecommendation getRecommendation(RequestParam String topic) { PromptTemplate promptTemplate new PromptTemplate(请推荐一本关于{topi}的书); Prompt prompt promptTemplate.create(Map.of(topic, topic)); return chatClient.call(prompt) .getOutput() .getContentAs(BookRecommendation.class); }6.2 流式响应处理对于长内容可以使用流式响应GetMapping(value /ai/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString streamResponse(RequestParam String message) { return chatClient.stream(message) .map(ChatResponse::getOutput) .map(AssistantMessage::getContent); }前端可以通过EventSource接收实时数据。7. 常见问题排查7.1 连接问题如果遇到连接失败检查网络是否能访问api.openai.com是否配置了正确的代理如有需要API密钥是否正确且未过期7.2 性能问题响应缓慢的可能原因模型选择gpt-4比gpt-3.5慢maxTokens设置过大网络延迟7.3 内容质量问题如果回答不符合预期调整temperature参数提供更明确的提示词在消息中包含示例回答8. 项目优化与进阶8.1 自定义Prompt工程创建提示词模板库public class PromptTemplates { public static final String CODE_REVIEW_TEMPLATE 请以专业开发者的身份审查以下代码 {code} 重点检查 - 代码风格 - 潜在bug - 性能问题 请用Markdown格式回复; }8.2 多模型切换策略通过配置实现模型动态切换Bean ConditionalOnProperty(name ai.provider, havingValue openai) public ChatClient openAiClient() { return new OpenAiChatClient(...); } Bean ConditionalOnProperty(name ai.provider, havingValue azure) public ChatClient azureClient() { return new AzureOpenAiChatClient(...); }8.3 监控与指标收集集成Micrometer收集AI调用指标Bean public MeterBinder aiMetrics(ChatClient chatClient) { return registry - Timer.builder(ai.calls) .description(AI API调用耗时) .tag(model, chatClient.getModel()) .register(registry); }在实际项目中我发现Spring AI最大的优势是让AI集成变得像使用其他Spring组件一样自然。特别是在已有Spring Boot项目中几乎不需要改变编程模式就能添加AI能力。不过要注意的是生产环境中一定要做好限流和降级处理因为AI API的响应时间和可用性不如本地服务稳定。
1. 项目概述最近在技术社区看到不少关于Spring AI的讨论作为一个长期使用Spring生态的开发者我决定亲自尝试一下这个新兴框架。Spring AI是Spring官方推出的AI集成方案它让开发者能够以熟悉的Spring方式调用各类AI能力。本文将记录我从零开始搭建环境到实现多轮对话的全过程环境基于JDK 17和Spring Boot 3.5。这个项目特别适合已经熟悉Spring Boot但想快速接入AI能力的开发者。相比直接调用AI厂商的APISpring AI提供了更符合Spring习惯的抽象层能显著降低学习成本。我将在后文详细展示如何用最少的代码实现对话式AI功能。2. 环境准备与项目初始化2.1 基础环境配置首先需要确认开发环境满足以下要求JDK 17推荐使用Amazon Corretto或OpenJDKMaven 3.6或Gradle 7.xIDEIntelliJ IDEA或VS Code验证JDK版本java -version如果版本不符可以通过SDKMAN!快速切换sdk install java 17.0.8-amzn sdk use java 17.0.8-amzn2.2 创建Spring Boot项目使用Spring Initializr创建项目时需要注意几个关键配置选择Spring Boot 3.1.0或更高版本添加Spring Web和Spring AI依赖打包方式建议选JarJava版本选择17对于已经存在的项目可以手动添加Spring AI依赖Maven示例dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId version0.8.0/version /dependency注意Spring AI目前还在快速迭代中建议锁定具体版本号以避免兼容性问题。3. API密钥配置与基础测试3.1 获取AI服务凭证目前Spring AI主要支持OpenAI、Azure OpenAI等主流服务。以OpenAI为例登录OpenAI平台进入API Keys页面创建新的API密钥3.2 安全配置密钥千万不要将密钥硬编码在代码中推荐做法在application.properties中配置spring.ai.openai.api-key${OPENAI_API_KEY}通过环境变量传入密钥export OPENAI_API_KEYyour_key_here对于生产环境建议使用Vault或KMS等专业密钥管理服务。3.3 基础对话测试创建一个简单的REST控制器RestController public class AIController { private final OpenAiChatClient chatClient; public AIController(OpenAiChatClient chatClient) { this.chatClient chatClient; } GetMapping(/ai/chat) public String chat(RequestParam String message) { return chatClient.call(message); } }启动应用后访问http://localhost:8080/ai/chat?message你好你应该能收到AI的回复。这个简单的端点验证了基础集成是成功的。4. 实现多轮对话功能4.1 对话上下文管理单次问答无法维持对话上下文我们需要改进实现PostMapping(/ai/conversation) public String conversation(RequestBody ListChatMessage messages) { return chatClient.call(messages); }请求示例[ {role: user, content: 推荐一本编程书}, {role: assistant, content: 《Clean Code》很不错}, {role: user, content: 中文版有吗} ]4.2 持久化对话记录实际应用中需要持久化对话历史简单的实现方案Service public class ConversationService { private final MapString, ListChatMessage conversations new ConcurrentHashMap(); public String handleMessage(String conversationId, String userMessage) { ListChatMessage messages conversations.computeIfAbsent( conversationId, k - new ArrayList()); messages.add(new ChatMessage(user, userMessage)); String response chatClient.call(messages); messages.add(new ChatMessage(assistant, response)); return response; } }4.3 高级对话参数配置可以通过ChatOptions定制对话行为Bean public OpenAiChatClient openAiChatClient(OpenAiApi openAiApi) { OpenAiChatOptions options OpenAiChatOptions.builder() .withModel(gpt-4) .withTemperature(0.7f) .withMaxTokens(500) .build(); return new OpenAiChatClient(openAiApi, options); }关键参数说明model指定使用的模型版本temperature控制回答的随机性0-1maxTokens限制响应长度5. 生产环境注意事项5.1 性能优化建议实现响应缓存Cacheable(value aiResponses, key #message) public String getCachedResponse(String message) { return chatClient.call(message); }设置合理的超时spring.ai.openai.api-timeout30s5.2 异常处理必须处理API可能抛出的异常ExceptionHandler(OpenAiApiException.class) public ResponseEntityString handleAiException(OpenAiApiException ex) { if (ex.getStatusCode().is4xxClientError()) { return ResponseEntity.badRequest().body(请求参数错误); } return ResponseEntity.internalServerError() .body(AI服务暂时不可用); }5.3 安全防护措施实现速率限制RateLimiter(name aiApiLimiter) public String rateLimitedCall(String message) { return chatClient.call(message); }敏感内容过滤public String safeCall(String message) { if (containsSensitiveContent(message)) { throw new ContentPolicyException(); } return chatClient.call(message); }6. 扩展应用场景6.1 结构化数据提取Spring AI支持将响应自动转换为对象public class BookRecommendation { private String title; private String author; private String reason; // getters/setters } GetMapping(/ai/recommend) public BookRecommendation getRecommendation(RequestParam String topic) { PromptTemplate promptTemplate new PromptTemplate(请推荐一本关于{topi}的书); Prompt prompt promptTemplate.create(Map.of(topic, topic)); return chatClient.call(prompt) .getOutput() .getContentAs(BookRecommendation.class); }6.2 流式响应处理对于长内容可以使用流式响应GetMapping(value /ai/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString streamResponse(RequestParam String message) { return chatClient.stream(message) .map(ChatResponse::getOutput) .map(AssistantMessage::getContent); }前端可以通过EventSource接收实时数据。7. 常见问题排查7.1 连接问题如果遇到连接失败检查网络是否能访问api.openai.com是否配置了正确的代理如有需要API密钥是否正确且未过期7.2 性能问题响应缓慢的可能原因模型选择gpt-4比gpt-3.5慢maxTokens设置过大网络延迟7.3 内容质量问题如果回答不符合预期调整temperature参数提供更明确的提示词在消息中包含示例回答8. 项目优化与进阶8.1 自定义Prompt工程创建提示词模板库public class PromptTemplates { public static final String CODE_REVIEW_TEMPLATE 请以专业开发者的身份审查以下代码 {code} 重点检查 - 代码风格 - 潜在bug - 性能问题 请用Markdown格式回复; }8.2 多模型切换策略通过配置实现模型动态切换Bean ConditionalOnProperty(name ai.provider, havingValue openai) public ChatClient openAiClient() { return new OpenAiChatClient(...); } Bean ConditionalOnProperty(name ai.provider, havingValue azure) public ChatClient azureClient() { return new AzureOpenAiChatClient(...); }8.3 监控与指标收集集成Micrometer收集AI调用指标Bean public MeterBinder aiMetrics(ChatClient chatClient) { return registry - Timer.builder(ai.calls) .description(AI API调用耗时) .tag(model, chatClient.getModel()) .register(registry); }在实际项目中我发现Spring AI最大的优势是让AI集成变得像使用其他Spring组件一样自然。特别是在已有Spring Boot项目中几乎不需要改变编程模式就能添加AI能力。不过要注意的是生产环境中一定要做好限流和降级处理因为AI API的响应时间和可用性不如本地服务稳定。
