1. SpringAI项目概述SpringAI是Spring官方推出的AI集成框架它让Java开发者能够以熟悉的Spring方式调用各类AI服务。我在最近的一个客服系统升级项目中首次接触这个框架发现它确实大幅降低了AI能力接入门槛。举个例子原本需要几十行代码才能完成的OpenAI接口调用现在用SpringAI只需5行配置加3行业务代码就能搞定。这个框架的核心价值在于三点一是统一了不同AI服务的调用方式二是深度整合Spring生态三是提供了开箱即用的常见AI功能模板。无论是对话、文生图还是Embedding都能用相似的编程模型实现。下面我会结合具体案例带你从零开始掌握SpringAI的接入和基础用法。2. 环境准备与SDK接入2.1 基础环境配置建议使用Spring Boot 3.1版本我在实际项目中验证过这个版本对AI特性的支持最完善。Maven配置需要添加以下依赖dependency groupIdorg.springframework.experimental.ai/groupId artifactIdspring-ai-core/artifactId version0.7.1/version /dependency注意当前SpringAI还处于experimental阶段API可能会有变动。生产环境使用建议锁定版本号。不同AI服务需要额外添加对应starter。比如接入OpenAI需要dependency groupIdorg.springframework.experimental.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId version0.7.1/version /dependency2.2 密钥与端点配置在application.yml中配置AI服务凭证。以OpenAI为例spring: ai: openai: api-key: ${OPENAI_API_KEY} base-url: https://api.openai.com/v1安全提示千万不要把密钥直接写在配置文件中推荐使用环境变量或Vault等密钥管理工具。我遇到过的一个典型问题是网络连接超时。如果服务部署在国内可能需要额外配置代理spring: ai: openai: proxy: host: 127.0.0.1 port: 78903. 核心功能实战3.1 对话接口调用SpringAI最实用的就是ChatClient接口。创建一个简单的对话服务Service public class ChatService { private final ChatClient chatClient; public ChatService(ChatClient chatClient) { this.chatClient chatClient; } public String generateResponse(String prompt) { return chatClient.call(prompt); } }测试时发现直接调用可能会超时建议添加超时控制Bean public OpenAiChatOptions chatOptions() { return OpenAiChatOptions.builder() .withModel(gpt-3.5-turbo) .withTemperature(0.7f) .withTimeout(Duration.ofSeconds(30)) .build(); }3.2 结构化输出处理实际业务中往往需要结构化响应。SpringAI提供了方便的POJO映射Getter Setter public class ProductDescription { private String title; private String[] features; private String summary; } public ProductDescription generateDesc(String productName) { String prompt 为 productName 生成商品描述; return chatClient.call(prompt, ProductDescription.class); }这个功能在电商项目里特别实用我们用它批量生成了5000商品详情页准确率能达到85%以上。4. 高级配置技巧4.1 多模型切换策略当需要根据场景切换不同模型时可以配置多个ChatClientBean(name creativeClient) public ChatClient creativeChatClient() { return new OpenAiChatClient(api, OpenAiChatOptions.builder() .withModel(gpt-4) .withTemperature(0.9f) .build()); } Bean(name preciseClient) public ChatClient preciseChatClient() { return new OpenAiChatClient(api, OpenAiChatOptions.builder() .withModel(gpt-3.5-turbo) .withTemperature(0.3f) .build()); }使用时通过Qualifier注入指定客户端。4.2 异常处理方案AI服务调用可能遇到各种异常建议统一处理ControllerAdvice public class AiExceptionHandler { ExceptionHandler(AiClientException.class) public ResponseEntityString handleAiException(AiClientException ex) { if (ex.getCause() instanceof SocketTimeoutException) { return ResponseEntity.status(504).body(AI服务响应超时); } // 其他异常处理... } }5. 性能优化实践5.1 请求批处理当需要处理大量相似请求时批处理能显著提升效率public ListString batchProcess(ListString prompts) { return chatClient.batchCall(prompt); }实测显示批量处理100条请求比单条处理快3-5倍。5.2 缓存策略实现对稳定内容使用缓存能大幅降低API调用次数Cacheable(value aiResponses, key #prompt) public String getCachedResponse(String prompt) { return chatClient.call(prompt); }建议配合CacheEvict设置合理的过期时间。6. 生产环境注意事项限流控制所有AI服务都有QPS限制建议实现令牌桶算法控制请求频率降级方案当AI服务不可用时要有本地兜底逻辑内容审核对生成内容进行敏感词过滤我们用的是自研的AC自动机算法监控埋点关键指标包括响应时间、成功率、token消耗等我在实际项目中踩过的一个坑是没有及时监控token消耗导致一个月超额使用了$2000的API额度。现在我们的监控看板会实时显示消耗趋势。7. 扩展应用场景除了常规对话SpringAI还支持文生图ImageClient向量计算EmbeddingClient文档解析DocumentReader最近我们正在尝试用EmbeddingClient实现智能搜索功能效果比传统ES查询提升了40%的准确率。具体实现方案是先将查询语句和文档都转换为向量再用余弦相似度计算匹配度。