Spring AI Chat Client API 实战：从配置到流式响应

1. 环境准备与基础配置第一次接触Spring AI Chat Client时最让人头疼的就是环境搭建。记得去年我在一个智能客服项目中集成ChatGPT时光是依赖冲突就折腾了大半天。现在有了Spring AI这个一站式工具箱整个过程变得异常简单。先说说依赖配置。现代Java项目通常采用Maven或Gradle管理依赖这里以Maven为例。打开你的pom.xml文件除了基础的Spring Boot Starter外关键要添加这两个依赖dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-core/artifactId version1.0.0/version /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId version1.0.0/version /dependency这里有个实战小技巧如果你同时连接多个AI平台比如既要OpenAI又要Azure OpenAI建议使用spring-ai-core配合具体平台的starter而不是直接引入多个starter这样可以避免自动配置冲突。配置文件是另一个容易踩坑的地方。在application.yml中最基本的OpenAI配置长这样spring: ai: openai: api-key: sk-your-key-here model: gpt-3.5-turbo但实际项目中我建议增加这些优化配置设置合理的超时时间特别是流式响应时根据业务场景调整temperature等模型参数配置重试策略应对API限流2. ChatClient核心玩法解析配置好环境后我们来玩转ChatClient的核心功能。Spring AI最让我欣赏的就是它的Fluent API设计用起来就像在搭积木。基础用法很简单String response chatClient.prompt() .user(用中文解释量子计算) .call() .content();但实际开发中系统消息system message的设置往往决定对话质量。我在电商客服机器人项目中就深有体会String response chatClient.prompt() .system(你是一个专业的电商客服回答要简短友好不超过3句话) .user(我买的衣服尺码不对怎么办) .call() .content();链式调用的威力在于可以构建多轮对话上下文。比如实现一个编程助手ChatResponse response chatClient.prompt() .system(你是一个Java专家用中文回答技术问题) .user(怎么用Stream API过滤列表) .user(能给个具体例子吗) .call();这里有个容易忽略的点每次user()调用都是追加而不是覆盖这在实现聊天历史功能时特别有用。3. 流式响应的实战技巧流式响应(Streaming Response)是处理长文本的神器。去年开发智能写作助手时如果不使用流式传输用户要等10多秒才能看到完整结果体验极差。基础流式调用示例FluxChatResponse stream chatClient.prompt() .user(生成一篇关于Spring AI的技术博客) .stream(); stream.subscribe( chunk - System.out.print(chunk.content()), error - System.err.println(出错啦: error), () - System.out.println(\n生成完成) );实战中的三个优化点背压处理用limitRate()控制接收速率防止客户端过载错误处理添加retry逻辑应对网络波动结果拼接使用StringBuilder累积分块结果更专业的做法是结合WebFlux实现服务端推送GetMapping(/stream-chat) public FluxString streamChat(RequestParam String question) { return chatClient.prompt() .user(question) .stream() .map(ChatResponse::content); }4. 高级特性与性能优化当项目规模变大后一些高级功能就派上用场了。提示模板是我最常用的功能之一比如多语言翻译场景String template 把以下{text}从{source}翻译到{target}; MapString, Object vars Map.of( text, Hello World, source, 英语, target, 法语 ); String response chatClient.promptTemplate(template) .fill(vars) .call() .content();性能调优方面有几点经验值得分享使用连接池配置HTTP客户端连接池建议最大连接数设置在20-50之间超时设置流式请求的超时要足够长建议30-60秒缓存策略对常见问答进行本地缓存自定义Advisor可以实现各种骚操作。比如我实现的这个耗时统计Advisorpublic class TimingAdvisor implements Advisor { Override public MonoVoid beforeRequest(Object request) { System.out.println(请求开始: System.currentTimeMillis()); return Mono.empty(); } Override public MonoVoid afterResponse(Object response) { System.out.println(请求结束: System.currentTimeMillis()); return Mono.empty(); } }在配置类中注册即可生效Bean public ChatClient chatClient(ChatClient.Builder builder) { return builder.advisor(new TimingAdvisor()).build(); }5. 常见问题排查指南在真实项目中这些问题我几乎都遇到过问题1调用时报错Model not found检查application.yml中的model名称确认你的API Key有访问该模型的权限问题2流式响应中途断开检查网络稳定性适当增大超时时间添加重试机制问题3中文回复质量差在system message中明确要求使用中文调整temperature参数0.3-0.7适合中文场景添加示例对话few-shot日志排查是个好习惯建议开启DEBUG日志logging: level: org.springframework.ai: DEBUG6. 真实项目架构建议经过多个项目实践我总结出一个稳健的AI聊天服务架构服务层封装不要直接暴露ChatClient给ControllerService public class ChatService { private final ChatClient chatClient; public FluxString streamChat(String message, String systemRole) { return chatClient.prompt() .system(systemRole) .user(message) .stream() .map(ChatResponse::content); } }限流防护使用Resilience4j或Sentinel实现API限流监控指标暴露关键指标到Prometheus请求耗时错误率流式响应块数量对话上下文管理对于多轮对话建议这样设计public class Conversation { private ListMessage history; public void addUserMessage(String content) { history.add(new Message(user, content)); } public FluxString continueChat(ChatClient client) { var prompt client.prompt(); history.forEach(msg - { if (user.equals(msg.role())) { prompt.user(msg.content()); } else { prompt.system(msg.content()); } }); return prompt.stream().map(ChatResponse::content); } }7. 未来兼容性设计AI领域迭代极快好的架构要预留扩展空间。我通常这样做抽象接口定义ChatService接口隔离具体实现public interface AIChatService { FluxString streamChat(String message); }多模型支持通过配置切换不同AI提供商spring: ai: provider: openai # 可切换为azure或anthropic版本隔离API路径带版本号如/v1/chat特性开关用FeatureToggle控制新功能灰度发布在Spring AI的版本升级方面建议定期查看官方Release Notes先在测试环境验证新版本使用兼容性包装层处理Breaking Changes