1. 为什么要在 Spring Boot 里集成 AI 对话能力1.1 从业务需求到技术选型的思考过程做过企业级开发的人都有一个共识需求从来不会等你准备好才来。前阵子我手上有个内部知识库项目产品那边突然提了个需求说希望能在系统里直接跟文档对话用户提问后由 AI 基于已有资料给出回答。这个需求听起来不复杂但落到技术层面就涉及几个关键决策AI 能力从哪来、怎么跟现有的 Spring Boot 服务整合、对话上下文怎么维护、流式输出怎么处理。市面上做 AI 对话服务的方案大致分三类。第一类是直接调大模型厂商的 API比如 OpenAI 提供的接口优点是接入快、效果稳定、不用自己维护模型第二类是用 Spring AI 这类框架做一层抽象好处是切换模型供应商时改动小代价是多一层学习成本第三类是自己部署开源模型适合对数据隐私要求极高的场景但硬件成本和运维复杂度都不低。我这个项目最终选了第一条路——Spring Boot 直接集成 OpenAI API原因很实际项目周期紧团队对 Spring 生态熟没必要为了“架构优雅”去引入额外的抽象层。这里要澄清一个常见误区。很多人一听到“集成 OpenAI API”就觉得必须用 Spring AI其实不是。Spring AI 确实提供了统一的 ChatClient 抽象、自动配置、对话记忆管理等能力但如果你只是要做一个简单的对话接口直接用 RestTemplate 或 WebClient 调 HTTP 接口反而更透明、更好排查问题。我的建议是先用原生 HTTP 客户端把链路跑通理解每一步在做什么等业务复杂到需要多模型切换、需要 RAG 检索增强的时候再考虑引入 Spring AI。这个顺序反过来很容易在框架的黑盒里迷失方向。1.2 这个服务能做什么适合谁来参考先把边界说清楚。这篇文章要搭建的是一个基于 Spring Boot 的 AI 对话服务核心能力包括接收用户消息、调用 OpenAI 的对话补全接口、返回 AI 回复、支持多轮对话上下文、支持流式输出。它不是一个完整的生产级产品但是一个可以直接跑起来、可以继续往上叠功能的最小可用骨架。适合的读者有三类。第一类是 Java 后端开发者想在自己的项目里加一个 AI 对话入口但不确定从哪下手第二类是做企业信息化的同学手上有 Spring Boot 的老系统想低成本试水 AI 能力第三类是想理解大模型 API 调用原理的学习者通过一个真实的 Spring Boot 项目把 HTTP 调用、流式响应、上下文管理这些概念串起来。如果你完全没接触过 Spring Boot建议先把 Controller、Service、RestTemplate 这些基础过一遍再来看不然会有点吃力。提示本文所有代码基于 Spring Boot 3.x 和 Java 17 编写。如果你还在用 Spring Boot 2.x大部分逻辑通用但要注意 WebClient 的依赖坐标和部分 API 有差异。2. 环境准备与项目骨架搭建2.1 依赖选型为什么是 WebClient 而不是 RestTemplate创建 Spring Boot 项目时依赖选择直接决定了后面的开发体验。我用的核心依赖有这么几个spring-boot-starter-web 提供 Web 能力spring-boot-starter-webflux 提供 WebClient 用于发起 HTTP 请求lombok 简化实体类代码jackson 处理 JSON 序列化Spring Boot 默认已包含。这里重点说一下为什么选 WebClient 而不是 RestTemplate。RestTemplate 是同步阻塞的调用 AI 接口时线程会一直等着响应返回在高并发场景下线程池很容易被打满。WebClient 是响应式的支持非阻塞调用而且它原生支持流式响应——这一点对 AI 对话特别重要因为大模型的回复是逐字生成的用流式输出能让用户感觉响应更快。虽然 WebClient 的学习曲线比 RestTemplate 陡一点但为了流式能力这个投入值得。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-webflux/artifactId /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency有个坑要提前说同时引入 starter-web 和 starter-webflux 时Spring Boot 默认启动的是 Servlet 容器TomcatWebFlux 的响应式能力不会自动生效但 WebClient 可以正常使用。这个组合是安全的不用担心冲突。如果你想要全响应式栈那就只引 webflux但那样 Controller 的写法要改成返回 Mono 或 Flux对团队来说学习成本更高我一般不建议在传统业务系统里这么干。2.2 API Key 的获取与安全配置调用 OpenAI 接口需要一个 API Key。获取流程是登录 OpenAI 平台进入 API Keys 页面创建一个新的密钥复制保存。这里有个血泪教训——密钥只在创建时显示一次关掉页面就再也看不到了所以一定要当场保存到安全的地方。如果丢了只能删掉重新创建。密钥的管理方式直接关系到系统安全。我见过太多项目把密钥硬编码在代码里然后提交到代码仓库这是大忌。正确的做法是通过环境变量或配置中心注入。在 Spring Boot 里我通常这样配置openai: api-key: ${OPENAI_API_KEY:} base-url: https://api.openai.com/v1 model: gpt-4o-mini timeout: 60000然后在启动时通过环境变量传入OPENAI_API_KEY。这样代码仓库里只有占位符密钥不会泄露。如果你用 Docker 部署就在 docker run 时用-e OPENAI_API_KEYxxx传入如果用 K8s就放到 Secret 里挂载。本地开发时可以在 IDE 的运行配置里设置环境变量或者用.env文件配合插件加载。注意千万不要把真实密钥写进 application.yml 然后提交。哪怕后来删掉了Git 历史里依然能翻出来。一旦泄露别人可以用你的额度账单会很难看。2.3 配置类的设计思路配置类的作用是把散落在 yml 里的参数绑定成一个强类型的对象方便在代码里注入使用。我定义了一个OpenAiProperties类用ConfigurationProperties注解绑定前缀为openai的配置项。这样做的好处是参数集中管理、IDE 有自动补全、类型安全、改配置不用改代码。Data Component ConfigurationProperties(prefix openai) public class OpenAiProperties { private String apiKey; private String baseUrl https://api.openai.com/v1; private String model gpt-4o-mini; private Integer timeout 60000; }同时我还会配一个 WebClient 的 Bean把 baseUrl 和超时时间预设好后面调用时就不用重复设置。超时时间设 60 秒是有讲究的大模型生成一段较长的回复可能需要几十秒设太短会频繁超时设太长又会占用连接资源。60 秒是个比较平衡的值实测下来大部分对话都能在这个时间内完成。3. 核心对话链路的实现细节3.1 请求与响应模型的设计跟 OpenAI 接口打交道本质上是构造一个 JSON 请求体发过去再解析返回的 JSON。请求体的核心字段有四个model 指定用哪个模型messages 是对话消息数组temperature 控制回复的随机性stream 决定是否流式返回。messages 数组的结构值得展开说。每条消息有 role 和 content 两个字段role 有三种取值system 用于设定 AI 的角色和行为准则user 是用户说的话assistant 是 AI 之前的回复。多轮对话的关键就在于每次请求都要把历史消息按顺序带上AI 才能“记得”之前聊了什么。这一点跟人类的对话逻辑一样你不提之前说过的话对方自然不知道上下文。Data Builder public class ChatMessage { private String role; private String content; } Data public class ChatRequest { private String model; private ListChatMessage messages; private Double temperature; private Boolean stream; }响应模型相对简单主要取 choices 数组里第一条的 message.content。但要注意OpenAI 的响应结构里 choices 是个数组虽然对话场景下通常只有一条但代码里还是要做空判断不然遇到异常响应会直接 NPE。3.2 对话服务的核心逻辑服务层的职责很清晰接收用户消息组装请求调用接口解析响应返回结果。但真正写好这段逻辑有几个细节必须处理到位。第一个细节是 system 消息的注入。每次请求我都建议带上一条 system 消息用来约束 AI 的行为。比如“你是一个专业的技术助手回答要简洁准确不确定的内容要明确说明”。这条消息不占多少 token但能显著提升回复质量避免 AI 胡编乱造。第二个细节是历史消息的截断。多轮对话不能无限往 messages 里塞历史因为模型的上下文窗口是有限的而且 token 越多费用越高。我的做法是保留最近 N 轮对话N 一般取 10 到 20。如果对话特别长还可以考虑对早期消息做摘要压缩但这个复杂度较高初期可以先不做。Service RequiredArgsConstructor public class ChatService { private final WebClient webClient; private final OpenAiProperties properties; private final ConversationStore conversationStore; public String chat(String sessionId, String userMessage) { ListChatMessage messages new ArrayList(); messages.add(ChatMessage.builder() .role(system) .content(你是一个专业的技术助手回答简洁准确。) .build()); messages.addAll(conversationStore.getHistory(sessionId)); messages.add(ChatMessage.builder() .role(user) .content(userMessage) .build()); ChatRequest request new ChatRequest(); request.setModel(properties.getModel()); request.setMessages(messages); request.setTemperature(0.7); request.setStream(false); ChatResponse response webClient.post() .uri(/chat/completions) .header(Authorization, Bearer properties.getApiKey()) .bodyValue(request) .retrieve() .bodyToMono(ChatResponse.class) .block(Duration.ofMillis(properties.getTimeout())); String reply extractReply(response); conversationStore.append(sessionId, userMessage, reply); return reply; } }第三个细节是会话存储。我用一个ConversationStore来管理每个会话的历史消息底层可以用 ConcurrentHashMap 做内存存储生产环境建议换成 Redis。key 用 sessionIdvalue 是消息列表。每次对话结束后把用户消息和 AI 回复都追加进去下次请求时取出来。这里要注意线程安全同一个 session 的并发请求要加锁或者用原子操作不然历史消息可能错乱。3.3 流式输出的实现要点流式输出是提升用户体验的关键。传统模式下用户要等十几秒才能看到完整回复流式模式下文字是一个一个蹦出来的感觉上快很多。实现流式的核心是把 stream 参数设为 true然后服务端返回的是 SSEServer-Sent Events格式的数据流每行以data:开头最后以data: [DONE]结束。用 WebClient 接收流式响应要用bodyToFlux(String.class)而不是bodyToMono。拿到每一行后去掉data:前缀判断是不是[DONE]不是的话就解析 JSON 取出增量内容。Controller 层要返回FluxServerSentEventString或者用SseEmitter把每个增量推给前端。public FluxString chatStream(String sessionId, String userMessage) { ChatRequest request buildRequest(sessionId, userMessage, true); return webClient.post() .uri(/chat/completions) .header(Authorization, Bearer properties.getApiKey()) .bodyValue(request) .retrieve() .bodyToFlux(String.class) .filter(line - line.startsWith(data: )) .map(line - line.substring(6)) .takeUntil([DONE]::equals) .filter(chunk - ![DONE].equals(chunk)) .map(this::extractDeltaContent); }这里有个容易踩的坑流式响应里每个 chunk 的 JSON 结构跟非流式不一样增量内容在choices[0].delta.content里而不是choices[0].message.content。而且有些 chunk 的 delta 是空的比如第一个 chunk 只带 role 信息解析时要判空不然会抛异常。4. 常见问题排查与实战避坑4.1 接口调用失败的典型场景实际开发中接口调用失败的原因五花八门我整理了一张速查表覆盖了最常遇到的几种情况。现象可能原因排查方向401 UnauthorizedAPI Key 无效或未传检查环境变量是否注入成功Header 格式是否为 Bearer xxx429 Too Many Requests请求频率超限或额度不足查看账户余额降低并发加重试退避400 Bad Request请求体格式错误检查 messages 结构model 名称是否正确超时无响应网络问题或模型生成慢增大超时时间检查网络连通性返回内容为空解析字段取错确认取的是 message.content 还是 delta.content429 这个错误特别常见尤其是测试阶段频繁调用时。我的处理方式是加一个简单的重试机制用指数退避第一次等 1 秒第二次等 2 秒第三次等 4 秒。Spring 的 Retry 或者 Resilience4j 都能做手写一个循环也不复杂。但要注意重试次数不能太多否则用户等待时间会很长一般 3 次就够了。4.2 上下文管理的那些坑多轮对话最容易出问题的地方就是上下文管理。我踩过的坑有这么几个。第一个坑是 sessionId 的生成和传递。前端每次请求都要带上同一个 sessionId服务端才能找到对应的历史。如果前端每次生成新的 sessionId那 AI 就永远“失忆”。我的做法是前端在会话开始时生成一个 UUID存在内存或 localStorage 里后续所有请求都带上。第二个坑是历史消息无限增长。前面提过要截断但截断策略有讲究。不能简单地从头部删因为 system 消息必须保留。我的做法是system 消息永远保留然后从 user 和 assistant 的消息里保留最近 N 轮。如果单条消息特别长比如用户粘贴了一大段代码还要考虑按 token 数截断而不是按条数。第三个坑是并发写入。同一个用户快速发两条消息两个请求同时读写历史列表可能导致消息顺序错乱或者丢失。解决办法是给每个 session 加一把锁或者用 Redis 的 List 结构配合原子操作。内存存储的话用Collections.synchronizedList或者CopyOnWriteArrayList能缓解但高并发下还是建议上 Redis。4.3 成本控制的实操经验用 API 是要花钱的按 token 计费。如果不加控制一个测试跑下来可能就烧掉不少额度。我总结了几个控制成本的技巧。首先是选对模型。gpt-4o-mini 比 gpt-4o 便宜很多对于大部分对话场景mini 的效果已经够用。开发测试阶段一律用 mini上线后根据实际效果再决定要不要升级。其次是控制 max_tokens。请求里可以设置 max_tokens 限制回复长度避免 AI 长篇大论。一般对话场景设 500 到 1000 就够了除非你需要它写长文。第三是缓存高频问题。如果某些问题被反复问到可以把问题和答案缓存起来命中缓存就直接返回不调接口。用 Redis 做缓存设置合理的过期时间。这个优化在客服类场景里效果特别明显。第四是监控用量。OpenAI 平台有用量统计页面但最好在系统里也记录每次调用的 token 消耗方便做成本分析和告警。我在服务里加了一个拦截器每次调用后记录 prompt_tokens 和 completion_tokens定期汇总。提示开发阶段建议单独建一个 API Key 用于测试和生产环境的 Key 分开这样即使测试 Key 泄露或者超额也不影响生产。5. 从能跑到好用进阶优化方向5.1 引入 Spring AI 的时机判断前面我说先用原生 HTTP 客户端跑通那什么时候该引入 Spring AI 呢我的判断标准是当你需要频繁切换模型供应商或者需要 RAG、Function Calling、多模态这些高级能力时Spring AI 的价值就体现出来了。Spring AI 的核心优势是抽象。它定义了 ChatClient、EmbeddingClient、VectorStore 等统一接口底层可以接 OpenAI、Azure OpenAI、通义千问等多种实现。切换供应商时业务代码基本不用改只改配置。它还内置了对话记忆管理、提示词模板、输出解析等功能省去不少重复代码。但 Spring AI 也有代价。它是一层封装出问题时排查链路更长版本迭代较快API 可能变化某些新特性支持会滞后于原生接口。所以我的建议是简单场景用原生复杂场景用框架不要为了用框架而用框架。5.2 生产环境必须考虑的几个问题从 demo 到生产中间隔着不少工程问题。我列几个必须处理的。限流和熔断。AI 接口是外部依赖可能因为网络或对方服务问题而变慢或不可用。要用 Resilience4j 或 Sentinel 做限流和熔断避免一个慢接口拖垮整个系统。熔断后可以返回兜底话术比如“当前服务繁忙请稍后再试”。异步化。如果对话不需要实时返回可以改成异步任务用户提交后先返回一个任务 ID后台处理完再通知。这样能避免长连接占用提升系统吞吐。日志和审计。每次对话的输入输出都要记日志一方面便于排查问题另一方面很多行业有合规要求。但要注意脱敏用户可能输入敏感信息日志里不能明文存储。多实例部署时的会话共享。如果服务部署了多个实例内存存储的会话历史就不通了用户请求打到不同实例会“失忆”。这时候必须把会话存到 Redis 等共享存储里。5.3 一个容易被忽视的细节提示词工程很多人把精力都花在代码上却忽视了提示词的质量。实际上同样的模型提示词写得好不好效果差距巨大。我在项目里总结了几条经验。system 消息要具体。不要写“你是一个助手”而要写“你是一个 Java 技术专家回答要给出可运行的代码示例不确定的内容要明确说不知道”。越具体AI 的表现越符合预期。给例子比讲道理有效。如果希望 AI 按特定格式输出与其描述格式不如直接给一个输入输出的例子。这叫 few-shot实测效果比纯文字描述好很多。temperature 要按场景调。需要准确答案的场景比如查资料调低0.2 左右需要创意的场景比如写文案调高0.8 左右。默认的 0.7 是个折中值但未必适合你的场景。控制输出长度。在提示词里明确说“回答控制在 200 字以内”比在参数里设 max_tokens 更自然AI 会更合理地组织内容而不是被硬截断。我在实际项目里把这些经验固化成了几个提示词模板不同场景用不同模板效果比一句通用的 system 消息稳定得多。这个投入不大但回报很明显值得每个做 AI 应用的团队认真对待。