1. 从一次全绿的发布事故说起先说那个让我至今记忆犹新的坑。项目上线前的回归测试单元测试全绿CI 流水线一路畅通我甚至已经在心里盘算着晚上吃什么庆祝了。结果灰度发布不到半小时客服群里开始炸锅——用户发消息给 AI 助手要么半天没反应要么回复到一半突然断掉前端界面卡在正在输入的状态转圈圈。最诡异的是本地跑得好好的测试环境也跑得好好的偏偏生产环境出问题。我第一反应是网络抖动第二反应是模型服务限流排查了两个小时才发现问题出在一个我压根没写测试的地方——流式响应的超时配置。单元测试里我用的是 Mock 的流式响应数据瞬间返回永远不会触发超时。但生产环境里大模型生成一段长文本要十几秒甚至几十秒中间还有思考停顿SSE 连接就这么被网关掐断了。测试全绿产品是坏的说的就是这种场景。这篇文章我把过去大半年在 Spring AI 项目里踩过的 14 个坑整理出来涵盖依赖选型、流式接口、超时控制、单元测试、模型对接、Agent 编排等环节。每个坑我都会说清楚为什么会踩、怎么发现的、怎么修的、以后怎么防。如果你正在用 Spring Boot 做 AI 应用集成或者准备把大模型能力接进现有系统这些经验应该能帮你省下不少通宵的时间。需要说明的是下面涉及具体版本和配置的地方我会标注清楚适用的大致范围因为 Spring AI 这个生态迭代很快1.0 之前和之后 API 变化不小Spring Boot 2.3.x、2.6.x 到 3.x 的差异也要留意。你照着做的时候先确认自己的版本基线。2. 依赖与版本第一个坑就劝退了一半人2.1 Spring AI 的版本命名是个迷宫刚开始接触 Spring AI 的时候我按照习惯去 Maven 中央仓库搜spring-ai结果看到一堆spring-ai-core、spring-ai-openai-spring-boot-starter、spring-ai-alibaba-spring-boot-starter之类的坐标版本号还有1.0.0-M1、1.0.0-M6、1.0.0-SNAPSHOT各种形态。当时我就懵了——到底该用哪个这里有个关键认知Spring AI 在 1.0.0 正式版之前里程碑版本M 系列之间的 API 是不保证兼容的。我一开始用了 M1写了几天代码看到 M6 出来了想升级结果发现ChatClient的构建方式、Prompt的封装类全变了改了一下午。我的建议是新项目直接锁定一个稳定的里程碑版本或者正式版在pom.xml里用dependencyManagement统一管理版本别让各个 starter 各自为政。下面是一个我实际在用的依赖管理片段properties spring-ai.version1.0.0/spring-ai.version /properties dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version${spring-ai.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement用 BOM 的好处是你引入spring-ai-openai-spring-boot-starter或者spring-ai-alibaba-spring-boot-starter的时候不用再写版本号避免版本冲突。这个坑本身不复杂但如果你不知道 BOM 的存在就会像我一样手动对齐版本浪费时间。2.2 Spring Boot 版本和 Spring AI 的兼容矩阵第二个相关的坑是 Spring Boot 版本。我有个老项目是 Spring Boot 2.6.x 的想直接引入 Spring AI结果发现根本跑不起来。原因是 Spring AI 的自动配置大量使用了 Spring Boot 3.x 才有的新特性比如AutoConfiguration注解、新的ConfigData加载机制等。实测下来Spring AI 1.0.x 基本要求 Spring Boot 3.2 及以上。如果你手上是 2.3.x 或 2.6.x 的老系统有两条路一是升级 Spring Boot工作量大风险高二是把 AI 能力做成独立的微服务老系统通过 HTTP 调用。我选了第二条因为那个老系统还跑着不少业务动不得。这里给个兼容性对照方便你快速判断Spring AI 版本建议 Spring Boot 版本JDK 要求1.0.0-M1 ~ M33.2.x171.0.0-M4 ~ M63.3.x171.0.0 正式版3.3.x / 3.4.x17注意这个表是基于我实际测试的经验总结不是官方硬性规定。如果你的项目卡在某个版本上最稳妥的办法是拉一个最小 Demo 先跑通再往主项目里搬。2.3 starter 选错白写一天代码第三个坑更隐蔽。我一开始用的是通用的spring-ai-openai-spring-boot-starter对接的是国内的通义千问。通义千问提供了兼容 OpenAI 协议的接口所以理论上能通。但实际用下来发现一些特有的参数比如enable_search、incremental_output传不过去因为 OpenAI 的 starter 不认识这些字段。后来换成spring-ai-alibaba-spring-boot-starter这些参数就能正常配置了。所以选 starter 的原则是优先用模型厂商官方或社区维护的专用 starter通用 starter 只适合标准协议对接。通义千问、智谱、百川这些国内模型基本都有对应的 Spring AI 适配。3. SSE 流式接口坑最密集的区域3.1 为什么 AI 场景非要用 SSE先解释一下为什么流式这么重要。大模型生成文本是逐 token 输出的如果等全部生成完再一次性返回用户要盯着空白屏幕等十几秒体验极差。SSEServer-Sent Events就是解决这个问题的——服务端一边生成一边推前端一边接收一边渲染用户能看到文字像打字机一样冒出来。Spring AI 的ChatClient提供了stream()方法返回FluxString配合 Spring WebFlux 或者 Spring MVC 的SseEmitter就能实现流式输出。听起来简单但坑全在细节里。3.2 那个让测试全绿的超时配置回到开头那个事故。我的 Controller 大概长这样GetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString streamChat(RequestParam String message) { return chatClient.prompt() .user(message) .stream() .content(); }单元测试里我 Mock 了ChatClient让它返回Flux.just(Hello, , World)测试通过。但生产环境里模型生成一段 500 字的回答要 20 秒中间还有停顿。问题出在网关和容器的空闲超时上。具体来说有三个地方会掐断 SSE 连接Nginx 的proxy_read_timeout默认 60 秒但有些配置是 30 秒甚至更短。Tomcat 的connectionTimeout默认 20 秒指的是连接建立后等待请求的超时对流式响应有影响。Spring MVC 的async请求超时默认 30 秒通过spring.mvc.async.request-timeout配置。我的问题出在 Tomcat 的connectionTimeout上。因为 SSE 连接建立后服务端在等模型返回第一个 token 之前可能有好几秒没有数据写出Tomcat 认为这个连接空闲了就给关了。前端收到的是stream disconnected before completion: idle timeout waiting for SSE这样的错误。修复方案是分层配置server: tomcat: connection-timeout: 120000 keep-alive-timeout: 120000 spring: mvc: async: request-timeout: 300000Nginx 那边也要同步调整location /chat/stream { proxy_pass http://backend; proxy_read_timeout 300s; proxy_send_timeout 300s; proxy_buffering off; proxy_cache off; chunked_transfer_encoding on; }proxy_buffering off这个特别关键。如果开着缓冲Nginx 会攒一批数据再发给客户端流式效果就没了用户看到的是一段一段蹦出来而不是平滑输出。3.3 单元测试为什么测不出这个问题这是最值得反思的地方。我的单元测试用的是 Mock 的Flux数据瞬间返回永远不会触发超时。要测出这个问题需要的是集成测试而且是带真实网络延迟的集成测试。后来我加了一个测试策略用WebTestClient配合一个故意延迟的 Mock 服务模拟模型生成慢的场景。大概长这样Test void shouldNotTimeoutWhenModelIsSlow() { // 模拟模型每 5 秒返回一个 token总共返回 3 个 FluxString slowFlux Flux.just(A, B, C) .delayElements(Duration.ofSeconds(5)); // 用 WebTestClient 发起请求验证 20 秒内能收到完整响应 webTestClient.get() .uri(/chat/stream?messagetest) .accept(MediaType.TEXT_EVENT_STREAM) .exchange() .expectStatus().isOk() .returnResult(String.class) .getResponseBody() .collectList() .block(Duration.ofSeconds(30)); }这个测试跑起来要 15 秒CI 里会拖慢流水线所以我把它放在单独的integration-testprofile 里只在发布前跑。但就是它帮我提前发现了超时配置的问题。经验凡是涉及时间、网络、并发的逻辑单元测试的 Mock 都是理想世界必须有集成测试兜底。AI 流式场景尤其如此。3.4 前端接收 SSE 的常见断连后端配好了前端也可能出问题。我用 Vue 做前端的时候一开始用EventSource接收发现连接经常莫名其妙断开。排查后发现两个原因一是EventSource默认会在连接断开后自动重连但如果服务端已经发完了数据并关闭连接重连就会导致重复请求。解决办法是服务端在发送完最后一个事件后显式发送一个event: done事件前端收到后主动close()。二是浏览器对同一域名的 SSE 连接数有限制HTTP/1.1 下是 6 个如果页面同时开了多个流会互相阻塞。这个在 HTTP/2 下会好很多所以生产环境尽量上 HTTP/2。4. 模型对接通义千问的实战细节4.1 配置项别写错尤其是 base-url对接通义千问的时候我踩过一个低级但浪费时间的坑base-url写错了。通义千问的兼容模式接口地址和原生接口地址不一样我一开始填的是原生地址结果一直报 404。正确的配置大概是这样spring: ai: dashscope: api-key: ${DASHSCOPE_API_KEY} chat: options: model: qwen-plus temperature: 0.7如果你用的是 OpenAI 兼容模式那base-url要指向兼容端点。这里我不写具体地址了因为各家云厂商的端点可能会调整你以官方文档为准。核心原则是先确认你用的是原生 SDK 还是兼容协议两者的地址和参数名都不一样。4.2 流式输出里的增量字段通义千问在流式模式下返回的每个 chunk 里有一个incremental_output参数。如果这个参数没设对你可能会收到重复的完整文本而不是增量片段。我一开始没注意前端渲染出来就是你好你好你好这样重复。Spring AI 的 alibaba starter 已经帮你处理了大部分情况但如果你自己封装 SSE 接口调用逻辑就要特别注意解析响应时取的是delta还是full content。这个细节在官方文档里藏得比较深我是看源码才搞明白的。4.3 模型超时和重试的平衡大模型接口偶尔会超时尤其是高峰期。我一开始设置了 3 次重试结果发现有些请求重试后返回了两次结果因为第一次其实成功了只是响应慢客户端等不及就重试了。这里的经验是对于流式请求不要盲目重试。因为流式请求一旦开始返回数据就说明服务端已经处理了重试会导致重复。正确的做法是设置一个合理的首字节超时比如 30 秒超过这个时间还没收到第一个 token 才重试而且重试要幂等。// 伪代码示意实际用 Resilience4j 或 Spring Retry RetryConfig config RetryConfig.custom() .maxAttempts(2) .waitDuration(Duration.ofSeconds(1)) .retryOnException(e - e instanceof TimeoutException) .build();5. 单元测试与集成测试的边界5.1 Mock 掉的东西恰恰是最容易坏的前面说了超时的坑这里再展开讲讲测试策略。用 Spring AI 的时候我习惯把ChatClientMock 掉因为真实调用要花钱、要网络、还不稳定。但 Mock 带来一个问题你测的是你的代码逻辑不是集成逻辑。我后来把测试分成三层纯单元测试Mock 掉ChatClient测 Prompt 组装、结果解析、异常处理。跑得快每次提交都跑。集成测试用WebTestClient或TestRestTemplate打真实接口但模型用本地 Mock 服务替代。测流式、超时、错误码。发布前跑。端到端测试真实调用模型测完整链路。每天定时跑一次或者手动触发。这个分层帮我抓住了好几个只在集成层才暴露的问题比如 SSE 的Content-Type不对、网关截断、序列化异常等。5.2 流式响应的断言怎么写流式响应的测试和普通接口不一样你不能简单地断言返回体等于某个字符串。我的做法是把流收集成列表再断言StepVerifier.create(chatService.streamResponse(你好)) .expectNextMatches(chunk - chunk.contains(你)) .expectNextMatches(chunk - chunk.contains(好)) .verifyComplete();用 Reactor 的StepVerifier可以精确控制每个元素的断言还能验证完成信号。如果是 Spring MVC 的SseEmitter就用MockMvc配合asyncDispatch。注意StepVerifier默认有超时如果流一直不结束测试会挂起。记得设置.verify(Duration.ofSeconds(10))这样的超时保护。5.3 别让测试依赖真实 API Key我见过有同事把 API Key 硬编码在测试类里结果 Key 泄露了还产生了不少费用。正确做法是用环境变量或者测试专用的配置文件CI 里通过 Secret 注入。如果 CI 环境没有 Key就用Disabled或者条件注解跳过真实调用测试。6. Agent 编排与工具调用6.1 Spring AI 还是 LangGraph4j这是最近被问得最多的问题。我的看法是如果你的 Agent 逻辑是线性的、步骤固定的用 Spring AI 就够了如果涉及复杂的状态机、循环、条件分支LangGraph4j 更合适。Spring AI 的ChatClient加上Tool注解能实现简单的工具调用。比如让模型查天气、查数据库定义好工具方法模型会自动决定调哪个。但如果你要做多轮推理、根据中间结果决定下一步Spring AI 的抽象就不太够用了。我有个项目是做智能客服的需要根据用户问题先分类再走不同的处理流程中间还可能回退。这种场景我用 LangGraph4j 画了个状态图每个节点是一个处理步骤边是条件跳转。代码结构清晰很多。6.2 工具调用的参数校验用Tool定义工具的时候参数校验很容易被忽略。模型生成的参数不一定符合你的预期比如它可能传一个字符串给你期望是数字的参数。如果不校验直接抛异常用户体验很差。我的做法是在工具方法里做防御性校验并且把校验失败的提示返回给模型让它重新生成参数Tool(description 查询订单状态) public String queryOrder(ToolParam(description 订单号必须是数字) String orderId) { if (!orderId.matches(\\d)) { return 订单号格式错误请提供纯数字订单号; } // 实际查询逻辑 return orderService.getStatus(orderId); }这样模型收到错误提示后会尝试修正参数再调用一次。6.3 循环调用的终止条件Agent 调用工具可能陷入循环——模型调工具工具返回结果模型又调同一个工具。我遇到过模型反复查同一个订单的情况。解决办法是设置最大调用轮数超过就强制返回ChatOptions options ChatOptions.builder() .maxToolCallRounds(5) .build();同时在 Prompt 里明确告诉模型如果已经获取到足够信息请直接回答不要重复调用工具。7. 生产环境的监控与降级7.1 流式接口的监控指标普通接口看 QPS、响应时间、错误率就够了流式接口还要看几个特有指标首字节时间TTFB从请求发出到收到第一个 token 的时间反映模型响应速度。流持续时间整个流从开始到结束的时间太长可能是模型卡住了。中断率流没有正常结束就断开的比例这个指标直接反映用户体验。我用 Micrometer 埋了这些点配合 Prometheus 和 Grafana 做看板。中断率超过 5% 就告警通常意味着网关或模型服务有问题。7.2 模型服务不可用时的降级大模型服务不是 100% 可用的高峰期可能限流或者超时。我的降级策略是首先重试一次针对非流式请求。重试失败后返回一个预设的兜底回复比如当前咨询人数较多请稍后再试。同时记录日志触发告警。对于流式请求如果第一个 token 迟迟不来就切换到非流式接口等完整结果返回后一次性展示。虽然体验差一点但至少不会让用户干等。7.3 成本控制的一个小技巧大模型调用是按 token 计费的流式输出如果用户中途关闭页面已经生成的 token 照样计费。我加了一个逻辑前端关闭连接时后端通过doOnCancel钩子感知到主动取消模型调用减少不必要的生成。return chatClient.prompt() .user(message) .stream() .content() .doOnCancel(() - log.info(客户端取消停止生成));这个技巧帮我省了大概 10% 到 15% 的 token 消耗尤其是长文本生成场景。8. 那些零碎但致命的配置细节8.1 Bean 注入的顺序问题Spring AI 的自动配置会创建ChatClient.Builder但如果你自己定义了同类型的 Bean可能会冲突。我遇到过一次启动报错说ChatClient有多个候选 Bean。原因是既用了 starter 的自动配置又在配置类里手动new了一个。解决办法是要么完全用自动配置通过ChatClient.Builder注入后构建要么完全手动配置排除自动配置类。别混着用。8.2 序列化与字符编码SSE 返回中文的时候如果编码没设对前端会收到乱码。确保produces里指定了charsetUTF-8GetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE ;charsetUTF-8)另外如果你用 Jackson 序列化对象再推给前端注意ObjectMapper的配置要和前端约定一致比如日期格式、空值处理等。8.3 日志打印的坑调试流式接口的时候我习惯把每个 chunk 都打日志。结果发现日志量巨大而且因为日志是同步写的反而拖慢了流式输出。后来改成只打首字节、尾字节和异常中间的不打。或者用异步日志框架避免阻塞主流程。8.4 线程池配置Spring AI 的流式调用底层用的是 Reactor 的线程池如果并发量大默认的线程数可能不够。可以通过reactor.netty.ioWorkerCount或者自定义Scheduler来调整。但别调太大线程多了上下文切换开销也大。我一般从默认值开始压测后根据实际情况微调。9. 我总结的排查清单踩了这么多坑我整理了一个排查清单遇到流式接口问题的时候按顺序过一遍能覆盖 80% 的情况排查项检查内容常见问题网关配置proxy_read_timeout、proxy_buffering超时截断、缓冲导致非流式容器配置TomcatconnectionTimeout空闲连接被关闭Spring MVCasync.request-timeout异步请求超时模型配置base-url、api-key、模型名404、401、模型不存在前端EventSource重连、连接数限制重复请求、阻塞编码charsetUTF-8中文乱码测试是否有集成测试覆盖慢响应单元测试全绿但生产坏这个清单我贴在工位上每次上线前对着过一遍心里踏实很多。10. 最后聊几句掏心窝的话做 AI 应用集成这大半年最大的感受是传统 Web 开发的经验在这里只对了一半。接口设计、异常处理、测试策略这些基本功依然重要但 AI 场景引入了新的不确定性——模型响应时间不可控、输出内容不可控、成本不可控。我踩过的这些坑本质上都是用传统思维做 AI 集成导致的。比如用 Mock 测流式、用固定超时等模型、用同步思维处理异步流。后来我慢慢调整了心态把模型当成一个慢且不稳定但很聪明的外部服务来对待所有的设计都围绕这个前提展开很多问题就迎刃而解了。如果你刚开始做 Spring AI 集成我的建议是先把一个最小的流式 Demo 跑通然后立刻加上超时配置和集成测试别等到上线才发现问题。那个让我测试全绿但产品坏掉的坑希望你不要再踩一遍。还有一个实用的小习惯每次遇到新坑修完之后花五分钟写个测试用例把它固化下来。我现在项目里有一批回归测试专门覆盖这些历史坑每次重构或者升级版本都跑一遍能挡住不少回归问题。这个习惯看起来费时间但长期算下来省下的排查时间远超投入。
1. 从一次全绿的发布事故说起先说那个让我至今记忆犹新的坑。项目上线前的回归测试单元测试全绿CI 流水线一路畅通我甚至已经在心里盘算着晚上吃什么庆祝了。结果灰度发布不到半小时客服群里开始炸锅——用户发消息给 AI 助手要么半天没反应要么回复到一半突然断掉前端界面卡在正在输入的状态转圈圈。最诡异的是本地跑得好好的测试环境也跑得好好的偏偏生产环境出问题。我第一反应是网络抖动第二反应是模型服务限流排查了两个小时才发现问题出在一个我压根没写测试的地方——流式响应的超时配置。单元测试里我用的是 Mock 的流式响应数据瞬间返回永远不会触发超时。但生产环境里大模型生成一段长文本要十几秒甚至几十秒中间还有思考停顿SSE 连接就这么被网关掐断了。测试全绿产品是坏的说的就是这种场景。这篇文章我把过去大半年在 Spring AI 项目里踩过的 14 个坑整理出来涵盖依赖选型、流式接口、超时控制、单元测试、模型对接、Agent 编排等环节。每个坑我都会说清楚为什么会踩、怎么发现的、怎么修的、以后怎么防。如果你正在用 Spring Boot 做 AI 应用集成或者准备把大模型能力接进现有系统这些经验应该能帮你省下不少通宵的时间。需要说明的是下面涉及具体版本和配置的地方我会标注清楚适用的大致范围因为 Spring AI 这个生态迭代很快1.0 之前和之后 API 变化不小Spring Boot 2.3.x、2.6.x 到 3.x 的差异也要留意。你照着做的时候先确认自己的版本基线。2. 依赖与版本第一个坑就劝退了一半人2.1 Spring AI 的版本命名是个迷宫刚开始接触 Spring AI 的时候我按照习惯去 Maven 中央仓库搜spring-ai结果看到一堆spring-ai-core、spring-ai-openai-spring-boot-starter、spring-ai-alibaba-spring-boot-starter之类的坐标版本号还有1.0.0-M1、1.0.0-M6、1.0.0-SNAPSHOT各种形态。当时我就懵了——到底该用哪个这里有个关键认知Spring AI 在 1.0.0 正式版之前里程碑版本M 系列之间的 API 是不保证兼容的。我一开始用了 M1写了几天代码看到 M6 出来了想升级结果发现ChatClient的构建方式、Prompt的封装类全变了改了一下午。我的建议是新项目直接锁定一个稳定的里程碑版本或者正式版在pom.xml里用dependencyManagement统一管理版本别让各个 starter 各自为政。下面是一个我实际在用的依赖管理片段properties spring-ai.version1.0.0/spring-ai.version /properties dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version${spring-ai.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement用 BOM 的好处是你引入spring-ai-openai-spring-boot-starter或者spring-ai-alibaba-spring-boot-starter的时候不用再写版本号避免版本冲突。这个坑本身不复杂但如果你不知道 BOM 的存在就会像我一样手动对齐版本浪费时间。2.2 Spring Boot 版本和 Spring AI 的兼容矩阵第二个相关的坑是 Spring Boot 版本。我有个老项目是 Spring Boot 2.6.x 的想直接引入 Spring AI结果发现根本跑不起来。原因是 Spring AI 的自动配置大量使用了 Spring Boot 3.x 才有的新特性比如AutoConfiguration注解、新的ConfigData加载机制等。实测下来Spring AI 1.0.x 基本要求 Spring Boot 3.2 及以上。如果你手上是 2.3.x 或 2.6.x 的老系统有两条路一是升级 Spring Boot工作量大风险高二是把 AI 能力做成独立的微服务老系统通过 HTTP 调用。我选了第二条因为那个老系统还跑着不少业务动不得。这里给个兼容性对照方便你快速判断Spring AI 版本建议 Spring Boot 版本JDK 要求1.0.0-M1 ~ M33.2.x171.0.0-M4 ~ M63.3.x171.0.0 正式版3.3.x / 3.4.x17注意这个表是基于我实际测试的经验总结不是官方硬性规定。如果你的项目卡在某个版本上最稳妥的办法是拉一个最小 Demo 先跑通再往主项目里搬。2.3 starter 选错白写一天代码第三个坑更隐蔽。我一开始用的是通用的spring-ai-openai-spring-boot-starter对接的是国内的通义千问。通义千问提供了兼容 OpenAI 协议的接口所以理论上能通。但实际用下来发现一些特有的参数比如enable_search、incremental_output传不过去因为 OpenAI 的 starter 不认识这些字段。后来换成spring-ai-alibaba-spring-boot-starter这些参数就能正常配置了。所以选 starter 的原则是优先用模型厂商官方或社区维护的专用 starter通用 starter 只适合标准协议对接。通义千问、智谱、百川这些国内模型基本都有对应的 Spring AI 适配。3. SSE 流式接口坑最密集的区域3.1 为什么 AI 场景非要用 SSE先解释一下为什么流式这么重要。大模型生成文本是逐 token 输出的如果等全部生成完再一次性返回用户要盯着空白屏幕等十几秒体验极差。SSEServer-Sent Events就是解决这个问题的——服务端一边生成一边推前端一边接收一边渲染用户能看到文字像打字机一样冒出来。Spring AI 的ChatClient提供了stream()方法返回FluxString配合 Spring WebFlux 或者 Spring MVC 的SseEmitter就能实现流式输出。听起来简单但坑全在细节里。3.2 那个让测试全绿的超时配置回到开头那个事故。我的 Controller 大概长这样GetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString streamChat(RequestParam String message) { return chatClient.prompt() .user(message) .stream() .content(); }单元测试里我 Mock 了ChatClient让它返回Flux.just(Hello, , World)测试通过。但生产环境里模型生成一段 500 字的回答要 20 秒中间还有停顿。问题出在网关和容器的空闲超时上。具体来说有三个地方会掐断 SSE 连接Nginx 的proxy_read_timeout默认 60 秒但有些配置是 30 秒甚至更短。Tomcat 的connectionTimeout默认 20 秒指的是连接建立后等待请求的超时对流式响应有影响。Spring MVC 的async请求超时默认 30 秒通过spring.mvc.async.request-timeout配置。我的问题出在 Tomcat 的connectionTimeout上。因为 SSE 连接建立后服务端在等模型返回第一个 token 之前可能有好几秒没有数据写出Tomcat 认为这个连接空闲了就给关了。前端收到的是stream disconnected before completion: idle timeout waiting for SSE这样的错误。修复方案是分层配置server: tomcat: connection-timeout: 120000 keep-alive-timeout: 120000 spring: mvc: async: request-timeout: 300000Nginx 那边也要同步调整location /chat/stream { proxy_pass http://backend; proxy_read_timeout 300s; proxy_send_timeout 300s; proxy_buffering off; proxy_cache off; chunked_transfer_encoding on; }proxy_buffering off这个特别关键。如果开着缓冲Nginx 会攒一批数据再发给客户端流式效果就没了用户看到的是一段一段蹦出来而不是平滑输出。3.3 单元测试为什么测不出这个问题这是最值得反思的地方。我的单元测试用的是 Mock 的Flux数据瞬间返回永远不会触发超时。要测出这个问题需要的是集成测试而且是带真实网络延迟的集成测试。后来我加了一个测试策略用WebTestClient配合一个故意延迟的 Mock 服务模拟模型生成慢的场景。大概长这样Test void shouldNotTimeoutWhenModelIsSlow() { // 模拟模型每 5 秒返回一个 token总共返回 3 个 FluxString slowFlux Flux.just(A, B, C) .delayElements(Duration.ofSeconds(5)); // 用 WebTestClient 发起请求验证 20 秒内能收到完整响应 webTestClient.get() .uri(/chat/stream?messagetest) .accept(MediaType.TEXT_EVENT_STREAM) .exchange() .expectStatus().isOk() .returnResult(String.class) .getResponseBody() .collectList() .block(Duration.ofSeconds(30)); }这个测试跑起来要 15 秒CI 里会拖慢流水线所以我把它放在单独的integration-testprofile 里只在发布前跑。但就是它帮我提前发现了超时配置的问题。经验凡是涉及时间、网络、并发的逻辑单元测试的 Mock 都是理想世界必须有集成测试兜底。AI 流式场景尤其如此。3.4 前端接收 SSE 的常见断连后端配好了前端也可能出问题。我用 Vue 做前端的时候一开始用EventSource接收发现连接经常莫名其妙断开。排查后发现两个原因一是EventSource默认会在连接断开后自动重连但如果服务端已经发完了数据并关闭连接重连就会导致重复请求。解决办法是服务端在发送完最后一个事件后显式发送一个event: done事件前端收到后主动close()。二是浏览器对同一域名的 SSE 连接数有限制HTTP/1.1 下是 6 个如果页面同时开了多个流会互相阻塞。这个在 HTTP/2 下会好很多所以生产环境尽量上 HTTP/2。4. 模型对接通义千问的实战细节4.1 配置项别写错尤其是 base-url对接通义千问的时候我踩过一个低级但浪费时间的坑base-url写错了。通义千问的兼容模式接口地址和原生接口地址不一样我一开始填的是原生地址结果一直报 404。正确的配置大概是这样spring: ai: dashscope: api-key: ${DASHSCOPE_API_KEY} chat: options: model: qwen-plus temperature: 0.7如果你用的是 OpenAI 兼容模式那base-url要指向兼容端点。这里我不写具体地址了因为各家云厂商的端点可能会调整你以官方文档为准。核心原则是先确认你用的是原生 SDK 还是兼容协议两者的地址和参数名都不一样。4.2 流式输出里的增量字段通义千问在流式模式下返回的每个 chunk 里有一个incremental_output参数。如果这个参数没设对你可能会收到重复的完整文本而不是增量片段。我一开始没注意前端渲染出来就是你好你好你好这样重复。Spring AI 的 alibaba starter 已经帮你处理了大部分情况但如果你自己封装 SSE 接口调用逻辑就要特别注意解析响应时取的是delta还是full content。这个细节在官方文档里藏得比较深我是看源码才搞明白的。4.3 模型超时和重试的平衡大模型接口偶尔会超时尤其是高峰期。我一开始设置了 3 次重试结果发现有些请求重试后返回了两次结果因为第一次其实成功了只是响应慢客户端等不及就重试了。这里的经验是对于流式请求不要盲目重试。因为流式请求一旦开始返回数据就说明服务端已经处理了重试会导致重复。正确的做法是设置一个合理的首字节超时比如 30 秒超过这个时间还没收到第一个 token 才重试而且重试要幂等。// 伪代码示意实际用 Resilience4j 或 Spring Retry RetryConfig config RetryConfig.custom() .maxAttempts(2) .waitDuration(Duration.ofSeconds(1)) .retryOnException(e - e instanceof TimeoutException) .build();5. 单元测试与集成测试的边界5.1 Mock 掉的东西恰恰是最容易坏的前面说了超时的坑这里再展开讲讲测试策略。用 Spring AI 的时候我习惯把ChatClientMock 掉因为真实调用要花钱、要网络、还不稳定。但 Mock 带来一个问题你测的是你的代码逻辑不是集成逻辑。我后来把测试分成三层纯单元测试Mock 掉ChatClient测 Prompt 组装、结果解析、异常处理。跑得快每次提交都跑。集成测试用WebTestClient或TestRestTemplate打真实接口但模型用本地 Mock 服务替代。测流式、超时、错误码。发布前跑。端到端测试真实调用模型测完整链路。每天定时跑一次或者手动触发。这个分层帮我抓住了好几个只在集成层才暴露的问题比如 SSE 的Content-Type不对、网关截断、序列化异常等。5.2 流式响应的断言怎么写流式响应的测试和普通接口不一样你不能简单地断言返回体等于某个字符串。我的做法是把流收集成列表再断言StepVerifier.create(chatService.streamResponse(你好)) .expectNextMatches(chunk - chunk.contains(你)) .expectNextMatches(chunk - chunk.contains(好)) .verifyComplete();用 Reactor 的StepVerifier可以精确控制每个元素的断言还能验证完成信号。如果是 Spring MVC 的SseEmitter就用MockMvc配合asyncDispatch。注意StepVerifier默认有超时如果流一直不结束测试会挂起。记得设置.verify(Duration.ofSeconds(10))这样的超时保护。5.3 别让测试依赖真实 API Key我见过有同事把 API Key 硬编码在测试类里结果 Key 泄露了还产生了不少费用。正确做法是用环境变量或者测试专用的配置文件CI 里通过 Secret 注入。如果 CI 环境没有 Key就用Disabled或者条件注解跳过真实调用测试。6. Agent 编排与工具调用6.1 Spring AI 还是 LangGraph4j这是最近被问得最多的问题。我的看法是如果你的 Agent 逻辑是线性的、步骤固定的用 Spring AI 就够了如果涉及复杂的状态机、循环、条件分支LangGraph4j 更合适。Spring AI 的ChatClient加上Tool注解能实现简单的工具调用。比如让模型查天气、查数据库定义好工具方法模型会自动决定调哪个。但如果你要做多轮推理、根据中间结果决定下一步Spring AI 的抽象就不太够用了。我有个项目是做智能客服的需要根据用户问题先分类再走不同的处理流程中间还可能回退。这种场景我用 LangGraph4j 画了个状态图每个节点是一个处理步骤边是条件跳转。代码结构清晰很多。6.2 工具调用的参数校验用Tool定义工具的时候参数校验很容易被忽略。模型生成的参数不一定符合你的预期比如它可能传一个字符串给你期望是数字的参数。如果不校验直接抛异常用户体验很差。我的做法是在工具方法里做防御性校验并且把校验失败的提示返回给模型让它重新生成参数Tool(description 查询订单状态) public String queryOrder(ToolParam(description 订单号必须是数字) String orderId) { if (!orderId.matches(\\d)) { return 订单号格式错误请提供纯数字订单号; } // 实际查询逻辑 return orderService.getStatus(orderId); }这样模型收到错误提示后会尝试修正参数再调用一次。6.3 循环调用的终止条件Agent 调用工具可能陷入循环——模型调工具工具返回结果模型又调同一个工具。我遇到过模型反复查同一个订单的情况。解决办法是设置最大调用轮数超过就强制返回ChatOptions options ChatOptions.builder() .maxToolCallRounds(5) .build();同时在 Prompt 里明确告诉模型如果已经获取到足够信息请直接回答不要重复调用工具。7. 生产环境的监控与降级7.1 流式接口的监控指标普通接口看 QPS、响应时间、错误率就够了流式接口还要看几个特有指标首字节时间TTFB从请求发出到收到第一个 token 的时间反映模型响应速度。流持续时间整个流从开始到结束的时间太长可能是模型卡住了。中断率流没有正常结束就断开的比例这个指标直接反映用户体验。我用 Micrometer 埋了这些点配合 Prometheus 和 Grafana 做看板。中断率超过 5% 就告警通常意味着网关或模型服务有问题。7.2 模型服务不可用时的降级大模型服务不是 100% 可用的高峰期可能限流或者超时。我的降级策略是首先重试一次针对非流式请求。重试失败后返回一个预设的兜底回复比如当前咨询人数较多请稍后再试。同时记录日志触发告警。对于流式请求如果第一个 token 迟迟不来就切换到非流式接口等完整结果返回后一次性展示。虽然体验差一点但至少不会让用户干等。7.3 成本控制的一个小技巧大模型调用是按 token 计费的流式输出如果用户中途关闭页面已经生成的 token 照样计费。我加了一个逻辑前端关闭连接时后端通过doOnCancel钩子感知到主动取消模型调用减少不必要的生成。return chatClient.prompt() .user(message) .stream() .content() .doOnCancel(() - log.info(客户端取消停止生成));这个技巧帮我省了大概 10% 到 15% 的 token 消耗尤其是长文本生成场景。8. 那些零碎但致命的配置细节8.1 Bean 注入的顺序问题Spring AI 的自动配置会创建ChatClient.Builder但如果你自己定义了同类型的 Bean可能会冲突。我遇到过一次启动报错说ChatClient有多个候选 Bean。原因是既用了 starter 的自动配置又在配置类里手动new了一个。解决办法是要么完全用自动配置通过ChatClient.Builder注入后构建要么完全手动配置排除自动配置类。别混着用。8.2 序列化与字符编码SSE 返回中文的时候如果编码没设对前端会收到乱码。确保produces里指定了charsetUTF-8GetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE ;charsetUTF-8)另外如果你用 Jackson 序列化对象再推给前端注意ObjectMapper的配置要和前端约定一致比如日期格式、空值处理等。8.3 日志打印的坑调试流式接口的时候我习惯把每个 chunk 都打日志。结果发现日志量巨大而且因为日志是同步写的反而拖慢了流式输出。后来改成只打首字节、尾字节和异常中间的不打。或者用异步日志框架避免阻塞主流程。8.4 线程池配置Spring AI 的流式调用底层用的是 Reactor 的线程池如果并发量大默认的线程数可能不够。可以通过reactor.netty.ioWorkerCount或者自定义Scheduler来调整。但别调太大线程多了上下文切换开销也大。我一般从默认值开始压测后根据实际情况微调。9. 我总结的排查清单踩了这么多坑我整理了一个排查清单遇到流式接口问题的时候按顺序过一遍能覆盖 80% 的情况排查项检查内容常见问题网关配置proxy_read_timeout、proxy_buffering超时截断、缓冲导致非流式容器配置TomcatconnectionTimeout空闲连接被关闭Spring MVCasync.request-timeout异步请求超时模型配置base-url、api-key、模型名404、401、模型不存在前端EventSource重连、连接数限制重复请求、阻塞编码charsetUTF-8中文乱码测试是否有集成测试覆盖慢响应单元测试全绿但生产坏这个清单我贴在工位上每次上线前对着过一遍心里踏实很多。10. 最后聊几句掏心窝的话做 AI 应用集成这大半年最大的感受是传统 Web 开发的经验在这里只对了一半。接口设计、异常处理、测试策略这些基本功依然重要但 AI 场景引入了新的不确定性——模型响应时间不可控、输出内容不可控、成本不可控。我踩过的这些坑本质上都是用传统思维做 AI 集成导致的。比如用 Mock 测流式、用固定超时等模型、用同步思维处理异步流。后来我慢慢调整了心态把模型当成一个慢且不稳定但很聪明的外部服务来对待所有的设计都围绕这个前提展开很多问题就迎刃而解了。如果你刚开始做 Spring AI 集成我的建议是先把一个最小的流式 Demo 跑通然后立刻加上超时配置和集成测试别等到上线才发现问题。那个让我测试全绿但产品坏掉的坑希望你不要再踩一遍。还有一个实用的小习惯每次遇到新坑修完之后花五分钟写个测试用例把它固化下来。我现在项目里有一批回归测试专门覆盖这些历史坑每次重构或者升级版本都跑一遍能挡住不少回归问题。这个习惯看起来费时间但长期算下来省下的排查时间远超投入。
