本文是《Java 后端 + AI 落地(Spring AI 主线)》系列第 8 篇。第 7 篇刻意把流式全部关掉了------批处理没人看打字机效果。这一篇从批处理回到在线场景,讲清楚为什么对话链路必须开流式、SSE 与 WebFlux 在后端怎么落地、以及"首 token 延迟"这个第 2 篇埋下的指标到底该怎么测。 有意思的是,对流式来说最关键的一条纪律恰恰来自第 7 篇:已经流出去了的内容不能重试,因为用户已经看到了。 这一篇会把"不能重试"从一个口号变成一套可执行的三阶段状态机,并给出 Nginx、网关、取消传播、心跳保活这些"文档里不写但线上必然遇到"的细节。
📌 版本声明 :本文基于 Spring AI 2.0.1 (2.0.0 于 2026-06-12 GA)+ Spring Boot 4.1.x + Spring Framework 7 + JDK 21 编写,模型侧使用通义千问的 OpenAI 兼容端点 (qwen-plus 的流式接口),同时对照 Spring MVC + SseEmitter 与 WebFlux + Flux 两种后端形态。注意 Spring Boot 3.5 与 Spring Framework 6.2 已于 2026-06-30 EOL ;Spring AI 1.1.x 与 2.0.x 在流式 API 的返回类型与 Advisor 行为上存在差异(第 2 篇已详述),升级前请用官方 Release Notes 复核 。文中首 token 延迟、取消止损比例类数字均为特定环境下的量级参考,会随网络、模型与输入长度显著变化。
文章目录
-
- [1️⃣ 为什么流式不是"体验优化",而是可用性刚需](#1️⃣ 为什么流式不是"体验优化",而是可用性刚需)
-
- [1.1 感知延迟与实际延迟是两件事](#1.1 感知延迟与实际延迟是两件事)
- [1.2 为什么"等全部生成完再返回"在长回答上不可接受](#1.2 为什么"等全部生成完再返回"在长回答上不可接受)
- [1.3 流式不是免费的:三个真实代价](#1.3 流式不是免费的:三个真实代价)
- [2️⃣ 核心概念:SSE、Flux 与"不能重试"的边界](#2️⃣ 核心概念:SSE、Flux 与"不能重试"的边界)
-
- [2.1 SSE:为什么是它,而不是 WebSocket](#2.1 SSE:为什么是它,而不是 WebSocket)
- [2.2 Spring AI 的流式抽象:`Flux` 与背压](#2.2 Spring AI 的流式抽象:
Flux与背压) - [2.3 "不能重试"的准确边界:三阶段](#2.3 "不能重试"的准确边界:三阶段)
- [2.4 两个必须知道的限制](#2.4 两个必须知道的限制)
- [3️⃣ 环境准备](#3️⃣ 环境准备)
-
- [3.1 版本与依赖](#3.1 版本与依赖)
- [3.2 MVC 还是 WebFlux:一个必须显式做的决策](#3.2 MVC 还是 WebFlux:一个必须显式做的决策)
- [3.3 反向代理配置:流式失效的头号原因](#3.3 反向代理配置:流式失效的头号原因)
- [3.4 前端:为什么不用 EventSource](#3.4 前端:为什么不用 EventSource)
- [4️⃣ 核心实现](#4️⃣ 核心实现)
-
- [4.1 最简的流式接口:先跑通,再加固](#4.1 最简的流式接口:先跑通,再加固)
- [4.2 从模型流到 SSE:事件格式设计与心跳](#4.2 从模型流到 SSE:事件格式设计与心跳)
- [4.3 流中的错误处理:三阶段状态机的实现](#4.3 流中的错误处理:三阶段状态机的实现)
- [4.4 取消传播:把"停止生成"变成真的停止](#4.4 取消传播:把"停止生成"变成真的停止)
- [4.5 结构化尾巴:在流末尾附上元信息](#4.5 结构化尾巴:在流末尾附上元信息)
- [5️⃣ 进阶与优化](#5️⃣ 进阶与优化)
-
- [5.1 首 token 延迟的四个优化点(以及一个陷阱)](#5.1 首 token 延迟的四个优化点(以及一个陷阱))
- [5.2 取消止损与超时分层](#5.2 取消止损与超时分层)
- [5.3 可观测性:流式链路独有的四个指标](#5.3 可观测性:流式链路独有的四个指标)
- [5.4 同一服务里三种链路的共存](#5.4 同一服务里三种链路的共存)
- [6️⃣ 适用边界与风险提示](#6️⃣ 适用边界与风险提示)
-
- [6.1 适用场景](#6.1 适用场景)
- [6.2 不适用场景](#6.2 不适用场景)
- [6.3 版本兼容与升级注意](#6.3 版本兼容与升级注意)
- [6.4 生产建议清单](#6.4 生产建议清单)
- [7️⃣ 总结](#7️⃣ 总结)
-
- [7.1 关键决策点回顾](#7.1 关键决策点回顾)
- [7.2 回到开头](#7.2 回到开头)
- 参考资料

1️⃣ 为什么流式不是"体验优化",而是可用性刚需
1.1 感知延迟与实际延迟是两件事
先把一个容易混淆的概念分开:流式改变的不是"总耗时",而是"用户什么时候看到第一个字"。
我实测过同一份提示词、同一个模型、同一条问题,在开启与关闭流式两种情况下的时间线:
| 观测点 | 非流式(等全部生成完) | 流式(边生成边返回) |
|---|---|---|
| 用户看到第一个字 | 约 6.8 秒 | 约 0.9 秒 |
| 整段回答结束 | 约 7.1 秒 | 约 7.2 秒 |
| 总耗时 | 7.1 秒 | 7.2 秒(略增) |
注意第三行:流式的总耗时反而略长。 因为分帧、多次网络往返、以及前端逐字渲染都有开销。所以"流式能让回答更快"是错的------它让回答"更早开始"。
这个区别的工程含义是:优化的目标完全不同。
| 你想改善 | 应该优化的指标 | 手段 |
|---|---|---|
| "用户觉得卡" | 首 token 延迟(TTFT) | 缩短输入(prefill 时间与输入长度成正比)、换更快的模型、减少链路上的中间跳数 |
| "用户觉得慢/等太久" | 总耗时 | 缩短输出(要求更简洁、限制 maxTokens)、提高输出速度 |
| "用户觉得不稳定" | 首 token 延迟的 P95 | 连接预热、避免冷启动、错峰 |
第一行和第二行必须分开优化,否则会出现"优化了半年但用户还是说卡"的情况。 我见过一个团队反复压缩回答长度(优化总耗时),但用户抱怨的是"点了发送之后半天没反应"------那是首 token 延迟的问题,而压缩输出长度对首 token 延迟几乎毫无帮助(甚至因为提示词变短而略有改善,但幅度完全不足以解决"卡"的感知)。
为什么首 token 延迟主要由输入决定? 因为模型处理一次请求分两个阶段:prefill(把输入 prompt 全部编码进 KV Cache) 和 decode(逐 token 生成输出) 。prefill 的耗时与输入 token 数近似成正比,而 decode 的耗时与输出 token 数成正比。 所以:
- 要降首 token 延迟 → 砍输入(历史消息、检索片段、系统提示的瘦身);
- 要降总耗时 → 砍输出 (要求精简、限制
maxTokens)。
这条区分是整篇最重要的一个认知。 它解释了为什么第 2 篇强调"首 token 延迟与总耗时必须分开统计"------它们是两个指向完全不同优化方向的指标。
模型 后端 用户 模型 后端 用户 #mermaid-svg-yoD9lYFUB0RAz9yT{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-yoD9lYFUB0RAz9yT .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-yoD9lYFUB0RAz9yT .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-yoD9lYFUB0RAz9yT .error-icon{fill:#552222;}#mermaid-svg-yoD9lYFUB0RAz9yT .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-yoD9lYFUB0RAz9yT .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-yoD9lYFUB0RAz9yT .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-yoD9lYFUB0RAz9yT .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-yoD9lYFUB0RAz9yT .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-yoD9lYFUB0RAz9yT .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-yoD9lYFUB0RAz9yT .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-yoD9lYFUB0RAz9yT .marker{fill:#333333;stroke:#333333;}#mermaid-svg-yoD9lYFUB0RAz9yT .marker.cross{stroke:#333333;}#mermaid-svg-yoD9lYFUB0RAz9yT svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-yoD9lYFUB0RAz9yT p{margin:0;}#mermaid-svg-yoD9lYFUB0RAz9yT .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-yoD9lYFUB0RAz9yT text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-yoD9lYFUB0RAz9yT .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-yoD9lYFUB0RAz9yT .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-yoD9lYFUB0RAz9yT .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-yoD9lYFUB0RAz9yT .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-yoD9lYFUB0RAz9yT #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-yoD9lYFUB0RAz9yT .sequenceNumber{fill:white;}#mermaid-svg-yoD9lYFUB0RAz9yT #sequencenumber{fill:#333;}#mermaid-svg-yoD9lYFUB0RAz9yT #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-yoD9lYFUB0RAz9yT .messageText{fill:#333;stroke:none;}#mermaid-svg-yoD9lYFUB0RAz9yT .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-yoD9lYFUB0RAz9yT .labelText,#mermaid-svg-yoD9lYFUB0RAz9yT .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-yoD9lYFUB0RAz9yT .loopText,#mermaid-svg-yoD9lYFUB0RAz9yT .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-yoD9lYFUB0RAz9yT .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-yoD9lYFUB0RAz9yT .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-yoD9lYFUB0RAz9yT .noteText,#mermaid-svg-yoD9lYFUB0RAz9yT .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-yoD9lYFUB0RAz9yT .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-yoD9lYFUB0RAz9yT .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-yoD9lYFUB0RAz9yT .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-yoD9lYFUB0RAz9yT .actorPopupMenu{position:absolute;}#mermaid-svg-yoD9lYFUB0RAz9yT .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-yoD9lYFUB0RAz9yT .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-yoD9lYFUB0RAz9yT .actor-man circle,#mermaid-svg-yoD9lYFUB0RAz9yT line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-yoD9lYFUB0RAz9yT :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 非流式:全部生成完才返回 流式:边生成边返回(总耗时反而略增) loop 每个 chunk 发送问题(t=0) 1 请求(stream=false) 2 prefill 输入 + decode 全部输出 3 完整回答(t≈6.8s) 4 一次性展示(t≈6.8s) 5 发送问题(t=0) 6 请求(stream=true) 7 首个 chunk(t≈0.9s) 8 首字出现(t≈0.9s) 9 后续 chunk 10 逐字追加 11 结束 + usage(t≈7.2s) 12 done 帧 13
(图 1:流式与非流式的时间线对比------注意最后两行的总耗时几乎一样,唯一差别是"首字何时出现";这就是为什么"优化首 token 延迟"和"优化总耗时"是两件不同的事)
1.2 为什么"等全部生成完再返回"在长回答上不可接受
短回答无所谓,长回答会直接击穿可用性。 这不是主观判断,可以用一个简单的时间预算推算:
| 回答类型 | 输出 token | 非流式首次可见时间 | 用户的容忍度 |
|---|---|---|---|
| 一句话确认 | 30 | 约 1.5 秒 | 可接受 |
| 段落说明 | 200 | 约 4 秒 | 尚可 |
| 结构化长回答(报告、方案) | 1500 | 约 25~40 秒 | 不可接受 |
| 总结一份长文档 | 3000+ | 约 60 秒以上 | 必然被认为"卡死了" |
长回答的场景恰恰是最需要流式的场景。 讽刺的是,很多系统在"短问答"上开了流式(收益很小),在"长报告"上反而没开(收益最大)------因为长任务的链路往往更复杂,中途有检索、有工具调用、有后处理,开发者怕流式之后这些东西不好处理。
这个顾虑是合理的------流式确实会让链路复杂化。所以第 1.3 节先把代价说清楚。
1.3 流式不是免费的:三个真实代价
我不太喜欢"流式是体验优化,无脑开"这类说法,因为它掩盖了三处成本。 这三处成本在低并发时感觉不到,在复杂链路里会集中爆发:
代价一:一旦有内容流出,重试的语义就变了。 这是全篇反复强调的一条。非流式请求失败可以整体重试(用户什么都没看到);流式请求如果已经流出了 200 个字再失败,你既不能重试(会重复或跳变),也不能"假装没发生"(用户看到了半句话)。 这个问题在第 4.3 节会用一套三阶段状态机处理。
代价二:错误处理从"返回一个错误码"变成"错误可能发生在流的中间"。 非流式下一个 500 就结束了;流式下 HTTP 状态码在第 0 秒就已经是 200 了(因为第一个 data 帧通常会先发出来),之后的任何失败都无法用状态码表达 ,只能在事件流里发一个错误事件,然后寄希望于前端正确渲染它。这就是为什么流式接口的"前后端契约"比普通接口复杂得多。
代价三:观测变难。 非流式接口的耗时是一个数(请求到响应的墙钟时间);流式接口的时间被切成了至少三段(首 token、中间间隔、结束),而且流可能被客户端随时取消 ------取消后的请求在常规的"请求-响应"埋点里会记成"客户端主动断开",容易被误判为故障。
所以我的建议是有条件地开流式,而不是全开:
| 场景 | 是否开流式 | 理由 |
|---|---|---|
| 实时对话、长回答(报告/方案/总结) | 必须开 | 首 token 延迟是可用性底线 |
| 实时对话、短回答(确认、路由判断) | 可开可不开 | 收益有限;链路简单时可以省掉这部分复杂度 |
需要结构化输出的调用 (.entity()) |
不能开 | 见 2.4 节:增量 JSON 无法可靠映射成对象 |
| 后端之间的同步调用 | 一般不开 | 调用方需要完整结果 |
| 批处理(第 7 篇) | 必须关 | 没有人看,且流式会阻碍"整段解析 + 校验" |
2️⃣ 核心概念:SSE、Flux 与"不能重试"的边界
2.1 SSE:为什么是它,而不是 WebSocket
在"服务器持续向浏览器推送文本"这件事上,SSE(Server-Sent Events)几乎是唯一合理的选择。 三种主流方案对比:
| 方案 | 传输方向 | 协议开销 | 自动重连 | 浏览器原生支持 | 适用性 |
|---|---|---|---|---|---|
| SSE | 单向(服务器 → 浏览器) | 纯 HTTP,极低 | 有(EventSource 内置) |
是 | AI 流式输出的最佳匹配 |
| WebSocket | 双向 | 需要升级握手与独立协议 | 需自己实现 | 是 | 双向交互场景(如协作编辑);对单向文本流是过度设计 |
| 长轮询 | 伪推送 | 每次都新建 HTTP 请求 | 需自己实现 | 是 | 兼容性兜底方案,延迟与开销都差 |
为什么 SSE 是 AI 流式的最佳匹配? 因为AI 流式输出的数据流方向天然是单向的------用户发一次请求,服务器持续推送 token。双向通信(WebSocket)在这个场景下带来的复杂度(握手升级、心跳自管、代理兼容性、连接状态管理)换不来任何收益。
SSE 的协议本身简单得值得记住(第 4.2 节要用):
text
event: message ← 事件类型(可选,默认是 message)
data: {"content":"你"} ← 数据行,可以有多行(多行会被拼成一条)
data: {"content":"好"}
id: 42 ← 事件 ID,用于断线续传(Last-Event-ID)
retry: 3000 ← 建议客户端重连间隔(毫秒)
: ping ← 以冒号开头的行是注释,用于心跳保活
四个字段里最容易被忽略的是最后那个注释行。 它的作用在 4.4 节展开:当一个长回答在生成中途"想了 30 秒没出字"时,中间的网关和负载均衡会认为这条连接空闲并把它断掉------注释帧就是拿来喂这些中间设备的。
还有一个必须知道的现实:EventSource 有两个硬限制 ------只能发 GET 请求、不能自定义请求头。 这意味着你无法用 EventSource 携带 Authorization 头 。所以生产环境里主流做法是用 fetch + ReadableStream 手动解析 SSE 帧(浏览器端),或者把凭证放在 Cookie 里。这个限制是"为什么很多 AI 产品的前端不用 EventSource"的答案。
#mermaid-svg-6x9taCa1yfugamM1{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-6x9taCa1yfugamM1 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-6x9taCa1yfugamM1 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-6x9taCa1yfugamM1 .error-icon{fill:#552222;}#mermaid-svg-6x9taCa1yfugamM1 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-6x9taCa1yfugamM1 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-6x9taCa1yfugamM1 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-6x9taCa1yfugamM1 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-6x9taCa1yfugamM1 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-6x9taCa1yfugamM1 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-6x9taCa1yfugamM1 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-6x9taCa1yfugamM1 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-6x9taCa1yfugamM1 .marker.cross{stroke:#333333;}#mermaid-svg-6x9taCa1yfugamM1 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-6x9taCa1yfugamM1 p{margin:0;}#mermaid-svg-6x9taCa1yfugamM1 .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-6x9taCa1yfugamM1 .cluster-label text{fill:#333;}#mermaid-svg-6x9taCa1yfugamM1 .cluster-label span{color:#333;}#mermaid-svg-6x9taCa1yfugamM1 .cluster-label span p{background-color:transparent;}#mermaid-svg-6x9taCa1yfugamM1 .label text,#mermaid-svg-6x9taCa1yfugamM1 span{fill:#333;color:#333;}#mermaid-svg-6x9taCa1yfugamM1 .node rect,#mermaid-svg-6x9taCa1yfugamM1 .node circle,#mermaid-svg-6x9taCa1yfugamM1 .node ellipse,#mermaid-svg-6x9taCa1yfugamM1 .node polygon,#mermaid-svg-6x9taCa1yfugamM1 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-6x9taCa1yfugamM1 .rough-node .label text,#mermaid-svg-6x9taCa1yfugamM1 .node .label text,#mermaid-svg-6x9taCa1yfugamM1 .image-shape .label,#mermaid-svg-6x9taCa1yfugamM1 .icon-shape .label{text-anchor:middle;}#mermaid-svg-6x9taCa1yfugamM1 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-6x9taCa1yfugamM1 .rough-node .label,#mermaid-svg-6x9taCa1yfugamM1 .node .label,#mermaid-svg-6x9taCa1yfugamM1 .image-shape .label,#mermaid-svg-6x9taCa1yfugamM1 .icon-shape .label{text-align:center;}#mermaid-svg-6x9taCa1yfugamM1 .node.clickable{cursor:pointer;}#mermaid-svg-6x9taCa1yfugamM1 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-6x9taCa1yfugamM1 .arrowheadPath{fill:#333333;}#mermaid-svg-6x9taCa1yfugamM1 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-6x9taCa1yfugamM1 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-6x9taCa1yfugamM1 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-6x9taCa1yfugamM1 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-6x9taCa1yfugamM1 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-6x9taCa1yfugamM1 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-6x9taCa1yfugamM1 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-6x9taCa1yfugamM1 .cluster text{fill:#333;}#mermaid-svg-6x9taCa1yfugamM1 .cluster span{color:#333;}#mermaid-svg-6x9taCa1yfugamM1 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-6x9taCa1yfugamM1 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-6x9taCa1yfugamM1 rect.text{fill:none;stroke-width:0;}#mermaid-svg-6x9taCa1yfugamM1 .icon-shape,#mermaid-svg-6x9taCa1yfugamM1 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-6x9taCa1yfugamM1 .icon-shape p,#mermaid-svg-6x9taCa1yfugamM1 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-6x9taCa1yfugamM1 .icon-shape .label rect,#mermaid-svg-6x9taCa1yfugamM1 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-6x9taCa1yfugamM1 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-6x9taCa1yfugamM1 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-6x9taCa1yfugamM1 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 并行注入,客户端不当作事件
SSE 响应流(text/event-stream)
event: meta
requestId / model
event: delta
内容增量 × N
event: refs
引用编号(可选)
event: done
ttft / total / usage
event: error
code / retryable / 已输出长度
: ping 注释帧
每 15 秒
(图 2:SSE 的事件协议设计------五种事件各司其职;usage 必须在 done 帧,心跳必须用注释帧,这两条都源自"流是时间序列而非一个响应"这个本质)
2.2 Spring AI 的流式抽象:Flux 与背压
Spring AI 在 2.0 里的流式返回类型是 Flux(Reactor 的响应式流),这一点与 LangChain4j 的 TokenStream 不同(第 6 篇对比过)。
java
// 一次流式调用:返回 Flux<String>,每个元素是一个增量片段
Flux<String> stream = chatClient.prompt()
.user("请用 300 字介绍 Spring AI")
.stream()
.content(); // 注意:返回的是"增量片段",不是累积文本
这里有一个必须记住的语义差异,很多人第一次用会踩:Flux 里发出的是"增量片段",而不是"累积文本"。
text
flux: "你" "好" ",我" "是" "一个" ...
拼接后: "你好,我是一个..."
"你" 之后是 "好",而不是 "你好"。 所以如果你直接对 Flux 里的元素做处理(比如做敏感词检查、做格式化),必须在正确的层级做拼接,否则检查会失效(一个敏感词被拆成两个片段就检测不到了,见 4.3 节)。
Flux 带来的第二个东西是背压(backpressure)。 概念是:消费者可以告诉生产者"我处理不过来了,慢一点发" 。SSE 场景下这个能力很重要------如果前端浏览器渲染跟不上,或者某个中间代理的缓冲区满了,背压能让上游减速,而不是无限堆积在内存里。 非响应式方案(如 MVC 的 SseEmitter)没有这个能力,只能自己控速。
代价是:Flux 的错误处理模型与命令式代码完全不同。 try-catch 在这里不适用,要用 onErrorResume / onErrorMap / doOnError 这类操作符。我第一次从命令式切过来时最大的困扰就是"异常在哪一层被谁接走了"------这部分在 4.3 节会给出一份完整的错误处理链。
2.3 "不能重试"的准确边界:三阶段
"已经流出去了就不能重试"这句话是对的,但太粗糙,不足以指导实现。准确的表述是三阶段:
| 阶段 | 判定依据 | 能否重试 | 用户视角 |
|---|---|---|---|
| 阶段一:未开始输出 | 第一个 content 帧尚未发出 | 可以整体重试(用户什么都没看到) | 仍在等待 |
| 阶段二:已开始输出 | 已有 ≥1 个 content 帧发出 | 绝不重试。只能发错误事件 + 优雅收尾 | 看到了半句话 |
| 阶段三:工具已执行(若链路含工具) | 任一写操作型工具已执行 | 绝不重试(与第 5 篇、系列一第 11 篇同源纪律) | 可能已产生副作用 |
表格里第二行和第三行是两个独立的条件,必须都检查。 一个常见错误是只检查"有没有流出内容":如果某个工具在"还没有任何内容流出"之前就执行了(比如先查订单再生成回答),此时第一个条件不成立,但重试仍然会造成重复的写操作。 所以判定的正确写法是"两个条件任一成立即不可重试":
java
// 不可重试的判定:两个条件任一为真
boolean cannotRetry = contentStreamed || sideEffectExecuted;
阶段一和阶段二的分界线,也正是"限流重试"能生效的唯一窗口。 因为 429 通常在请求发出的极早期发生(还在 prefill 阶段),这时候还没有任何内容流出,退避重试是安全的 ------这是流式链路里仍能保留重试能力的那一小块区域,要珍惜它,不要因为"流式就不用管重试了"而放弃它。
#mermaid-svg-exv5HuEHawWlzRVT{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-exv5HuEHawWlzRVT .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-exv5HuEHawWlzRVT .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-exv5HuEHawWlzRVT .error-icon{fill:#552222;}#mermaid-svg-exv5HuEHawWlzRVT .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-exv5HuEHawWlzRVT .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-exv5HuEHawWlzRVT .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-exv5HuEHawWlzRVT .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-exv5HuEHawWlzRVT .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-exv5HuEHawWlzRVT .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-exv5HuEHawWlzRVT .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-exv5HuEHawWlzRVT .marker{fill:#333333;stroke:#333333;}#mermaid-svg-exv5HuEHawWlzRVT .marker.cross{stroke:#333333;}#mermaid-svg-exv5HuEHawWlzRVT svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-exv5HuEHawWlzRVT p{margin:0;}#mermaid-svg-exv5HuEHawWlzRVT defs #statediagram-barbEnd{fill:#333333;stroke:#333333;}#mermaid-svg-exv5HuEHawWlzRVT g.stateGroup text{fill:#9370DB;stroke:none;font-size:10px;}#mermaid-svg-exv5HuEHawWlzRVT g.stateGroup text{fill:#333;stroke:none;font-size:10px;}#mermaid-svg-exv5HuEHawWlzRVT g.stateGroup .state-title{font-weight:bolder;fill:#131300;}#mermaid-svg-exv5HuEHawWlzRVT g.stateGroup rect{fill:#ECECFF;stroke:#9370DB;}#mermaid-svg-exv5HuEHawWlzRVT g.stateGroup line{stroke:#333333;stroke-width:1;}#mermaid-svg-exv5HuEHawWlzRVT .transition{stroke:#333333;stroke-width:1;fill:none;}#mermaid-svg-exv5HuEHawWlzRVT .stateGroup .composit{fill:white;border-bottom:1px;}#mermaid-svg-exv5HuEHawWlzRVT .stateGroup .alt-composit{fill:#e0e0e0;border-bottom:1px;}#mermaid-svg-exv5HuEHawWlzRVT .state-note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-exv5HuEHawWlzRVT .state-note text{fill:black;stroke:none;font-size:10px;}#mermaid-svg-exv5HuEHawWlzRVT .stateLabel .box{stroke:none;stroke-width:0;fill:#ECECFF;opacity:0.5;}#mermaid-svg-exv5HuEHawWlzRVT .edgeLabel .label rect{fill:#ECECFF;opacity:0.5;}#mermaid-svg-exv5HuEHawWlzRVT .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-exv5HuEHawWlzRVT .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-exv5HuEHawWlzRVT .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-exv5HuEHawWlzRVT .edgeLabel .label text{fill:#333;}#mermaid-svg-exv5HuEHawWlzRVT .label div .edgeLabel{color:#333;}#mermaid-svg-exv5HuEHawWlzRVT .stateLabel text{fill:#131300;font-size:10px;font-weight:bold;}#mermaid-svg-exv5HuEHawWlzRVT .node circle.state-start{fill:#333333;stroke:#333333;}#mermaid-svg-exv5HuEHawWlzRVT .node .fork-join{fill:#333333;stroke:#333333;}#mermaid-svg-exv5HuEHawWlzRVT .node circle.state-end{fill:#9370DB;stroke:white;stroke-width:1.5;}#mermaid-svg-exv5HuEHawWlzRVT .end-state-inner{fill:white;stroke-width:1.5;}#mermaid-svg-exv5HuEHawWlzRVT .node rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-exv5HuEHawWlzRVT .node polygon{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-exv5HuEHawWlzRVT #statediagram-barbEnd{fill:#333333;}#mermaid-svg-exv5HuEHawWlzRVT .statediagram-cluster rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-exv5HuEHawWlzRVT .cluster-label,#mermaid-svg-exv5HuEHawWlzRVT .nodeLabel{color:#131300;}#mermaid-svg-exv5HuEHawWlzRVT .statediagram-cluster rect.outer{rx:5px;ry:5px;}#mermaid-svg-exv5HuEHawWlzRVT .statediagram-state .divider{stroke:#9370DB;}#mermaid-svg-exv5HuEHawWlzRVT .statediagram-state .title-state{rx:5px;ry:5px;}#mermaid-svg-exv5HuEHawWlzRVT .statediagram-cluster.statediagram-cluster .inner{fill:white;}#mermaid-svg-exv5HuEHawWlzRVT .statediagram-cluster.statediagram-cluster-alt .inner{fill:#f0f0f0;}#mermaid-svg-exv5HuEHawWlzRVT .statediagram-cluster .inner{rx:0;ry:0;}#mermaid-svg-exv5HuEHawWlzRVT .statediagram-state rect.basic{rx:5px;ry:5px;}#mermaid-svg-exv5HuEHawWlzRVT .statediagram-state rect.divider{stroke-dasharray:10,10;fill:#f0f0f0;}#mermaid-svg-exv5HuEHawWlzRVT .note-edge{stroke-dasharray:5;}#mermaid-svg-exv5HuEHawWlzRVT .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-exv5HuEHawWlzRVT .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-exv5HuEHawWlzRVT .statediagram-note text{fill:black;}#mermaid-svg-exv5HuEHawWlzRVT .statediagram-note .nodeLabel{color:black;}#mermaid-svg-exv5HuEHawWlzRVT .statediagram .edgeLabel{color:red;}#mermaid-svg-exv5HuEHawWlzRVT #dependencyStart,#mermaid-svg-exv5HuEHawWlzRVT #dependencyEnd{fill:#333333;stroke:#333333;stroke-width:1;}#mermaid-svg-exv5HuEHawWlzRVT .statediagramTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-exv5HuEHawWlzRVT :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 第一个 delta 帧发出
可重试错误(429 / 5xx / 超时)
不可重试(400 / 401)
退避后整体重试(唯一安全窗口)
正常结束并发 done 帧
出错或断开
只能发 error 帧优雅收尾
NotStreamed
Streaming
FailedRetryable
FailedFatal
Completed
BrokenNoRetry
两个条件任一成立即不可重试:已流出内容 或 已执行写操作
(图 3:三阶段状态机------中间那条"FailedRetryable → NotStreamed"是流式链路里唯一安全的重试窗口;一旦进入 Streaming,"能重试"这件事就永久消失了)
2.4 两个必须知道的限制
限制一:结构化输出(.entity())与流式无法同时使用。
因为 .entity() 的本质是"等完整 JSON 到达后反序列化成对象",而流式的每一帧只是 JSON 的一个碎片 ------{"categ、ory":"咨 这样的片段无法被可靠地映射成对象。理论上可以自己实现增量 JSON 解析(把碎片不断拼接、尝试解析、成功就发射),但这条路的收益(让用户更早看到结构化字段)通常不值这个复杂度。
所以这是一个二选一的决策:
| 你要的 | 选择 | 用在哪 |
|---|---|---|
| 流式(打字机效果) | .stream().content() → Flux<String> |
面向人的回答展示 |
| 结构化(下游程序消费) | .call().entity(Class) |
内部调用、批处理、路由判断 |
绝不试图用一个接口同时满足两者。 我见过一个"想在流式回答里同时返回结构化字段"的设计,最后变成了"在流的最后一帧塞一段 JSON 让前端解析"------这其实是本文 4.5 节要讲的"结构化尾巴"模式,它是可行的,但要点在于:结构化部分放在流的末尾单独一帧,而不是让它和内容混流。
限制二:Flux 的取消必须显式传播到模型侧,否则 token 会被白烧。
用户在生成中途关闭页面/点了"停止"时,如果取消没有传播到 HTTP 客户端,模型会继续把整个回答生成完------这一段 token 完全白花。 实测一次 1500 token 的长回答,在生成 20% 时被取消,能省下约 80% 的输出 token (maxTokens 按输出计费)。
Reactor 本身会处理取消(下游 cancel() 会向上游传播),但前提是链路上的每一环都正确实现了它。 三个容易断链的地方:① 自己写的阻塞式处理(比如在流里调用了外部系统)会忽略取消信号;② 某些 HTTP 客户端的连接没有随取消而关闭;③ 中间加了一层 Flux.create() 手工发射数据的桥接代码。 第 4.4 节会给出一份可验证的实现,并说明怎么验证"取消真的传播下去了"。

3️⃣ 环境准备
3.1 版本与依赖
| 组件 | 版本 | 说明 |
|---|---|---|
| Spring Boot | 4.1.x | 与系列二其他篇一致(第 6 篇的"版本锁链") |
| Spring AI | 2.0.1 | stream() 返回 Flux |
| JDK | 21 | Boot 4 硬要求 |
| 模型 | qwen-plus |
流式接口走 OpenAI 兼容端点的 stream: true |
| Web 栈 | WebFlux 或 MVC(见 3.2) | 这是一个必须做的决策 |
xml
<!-- WebFlux 路线:流式场景的默认选择 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webflux</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>
注意:不要同时引 spring-boot-starter-web 和 spring-boot-starter-webflux。 两者共存时 Spring Boot 默认启动 MVC (因为 MVC 的存在会让 WebFlux 自动配置退让),于是你写的 Flux 返回值会被 MVC 当成普通对象序列化 ------表现为"接口返回了完整结果,但没有流式效果,且没有报错"。这是流式链路里最典型的"静默失效" ,与第 2 篇的"配置静默失效"、第 3 篇的"Ollama 默认无鉴权"属于同一类问题:不报错,但行为完全不对。
3.2 MVC 还是 WebFlux:一个必须显式做的决策
这是流式落地时的第一个架构决策,而很多团队是"顺手选了"的------因为项目原本是 MVC,就直接用 SseEmitter 了。
| 维度 | Spring MVC + SseEmitter |
WebFlux + Flux |
|---|---|---|
| 线程模型 | 每个连接占一个线程(除非配置异步 Servlet 容器线程) | 不占业务线程(事件循环) |
| 单机可支撑的并发流连接 | 约 200~500(取决于线程池与容器配置) | 数千(取决于内存与 fd 上限) |
| 学习成本 | 低(命令式思维可延续) | 中高(响应式操作符、错误传播模型) |
| 与阻塞式代码共存 | 好(可以直接调阻塞的 JDBC 等) | 差 (阻塞调用会拖垮事件循环,必须切到 boundedElastic) |
| 背压支持 | 无 | 有 |
| 适合的场景 | 并发几百以内、团队没有响应式经验、链路里有大量阻塞调用 | 并发上千、链路以 IO 为主、团队熟悉 Reactor |
我的判断标准是一条简单的线:并发流连接数是否可能超过 500。 低于这条线,MVC + SseEmitter 是更务实的选择 ------不是因为它更好,而是因为响应式改造的隐性成本(团队技能、调试困难、与既有阻塞代码的摩擦)在低并发下换不来收益。
超过这条线,就必须考虑 WebFlux,而且要注意一个关键纪律:WebFlux 里绝不能直接调用阻塞接口。 因为事件循环线程数量很少(默认等于 CPU 核数),一个阻塞调用会卡住整个事件循环上的所有连接。所以:
java
// WebFlux 里调用任何阻塞式依赖(JDBC、同步 HTTP 客户端)都必须切换到弹性线程池
return Mono.fromCallable(() -> jdbcTemplate.queryForList(sql)) // 阻塞调用
.subscribeOn(Schedulers.boundedElastic()); // 关键:切到弹性线程池
漏掉 subscribeOn(Schedulers.boundedElastic()) 的后果是"平时看起来正常,压力上来后全站响应时间一起飙升" ------因为被卡住的不是那一个请求,而是共享事件循环的一批请求。这个故障形态非常像"数据库慢",排查方向容易跑偏。
#mermaid-svg-cH27rtSRsRflFWzK{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-cH27rtSRsRflFWzK .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-cH27rtSRsRflFWzK .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-cH27rtSRsRflFWzK .error-icon{fill:#552222;}#mermaid-svg-cH27rtSRsRflFWzK .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-cH27rtSRsRflFWzK .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-cH27rtSRsRflFWzK .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-cH27rtSRsRflFWzK .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-cH27rtSRsRflFWzK .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-cH27rtSRsRflFWzK .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-cH27rtSRsRflFWzK .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-cH27rtSRsRflFWzK .marker{fill:#333333;stroke:#333333;}#mermaid-svg-cH27rtSRsRflFWzK .marker.cross{stroke:#333333;}#mermaid-svg-cH27rtSRsRflFWzK svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-cH27rtSRsRflFWzK p{margin:0;}#mermaid-svg-cH27rtSRsRflFWzK .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-cH27rtSRsRflFWzK .cluster-label text{fill:#333;}#mermaid-svg-cH27rtSRsRflFWzK .cluster-label span{color:#333;}#mermaid-svg-cH27rtSRsRflFWzK .cluster-label span p{background-color:transparent;}#mermaid-svg-cH27rtSRsRflFWzK .label text,#mermaid-svg-cH27rtSRsRflFWzK span{fill:#333;color:#333;}#mermaid-svg-cH27rtSRsRflFWzK .node rect,#mermaid-svg-cH27rtSRsRflFWzK .node circle,#mermaid-svg-cH27rtSRsRflFWzK .node ellipse,#mermaid-svg-cH27rtSRsRflFWzK .node polygon,#mermaid-svg-cH27rtSRsRflFWzK .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-cH27rtSRsRflFWzK .rough-node .label text,#mermaid-svg-cH27rtSRsRflFWzK .node .label text,#mermaid-svg-cH27rtSRsRflFWzK .image-shape .label,#mermaid-svg-cH27rtSRsRflFWzK .icon-shape .label{text-anchor:middle;}#mermaid-svg-cH27rtSRsRflFWzK .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-cH27rtSRsRflFWzK .rough-node .label,#mermaid-svg-cH27rtSRsRflFWzK .node .label,#mermaid-svg-cH27rtSRsRflFWzK .image-shape .label,#mermaid-svg-cH27rtSRsRflFWzK .icon-shape .label{text-align:center;}#mermaid-svg-cH27rtSRsRflFWzK .node.clickable{cursor:pointer;}#mermaid-svg-cH27rtSRsRflFWzK .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-cH27rtSRsRflFWzK .arrowheadPath{fill:#333333;}#mermaid-svg-cH27rtSRsRflFWzK .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-cH27rtSRsRflFWzK .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-cH27rtSRsRflFWzK .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-cH27rtSRsRflFWzK .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-cH27rtSRsRflFWzK .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-cH27rtSRsRflFWzK .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-cH27rtSRsRflFWzK .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-cH27rtSRsRflFWzK .cluster text{fill:#333;}#mermaid-svg-cH27rtSRsRflFWzK .cluster span{color:#333;}#mermaid-svg-cH27rtSRsRflFWzK div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-cH27rtSRsRflFWzK .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-cH27rtSRsRflFWzK rect.text{fill:none;stroke-width:0;}#mermaid-svg-cH27rtSRsRflFWzK .icon-shape,#mermaid-svg-cH27rtSRsRflFWzK .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-cH27rtSRsRflFWzK .icon-shape p,#mermaid-svg-cH27rtSRsRflFWzK .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-cH27rtSRsRflFWzK .icon-shape .label rect,#mermaid-svg-cH27rtSRsRflFWzK .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-cH27rtSRsRflFWzK .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-cH27rtSRsRflFWzK .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-cH27rtSRsRflFWzK :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 小于 500
大于 500 或不确定
大量(JDBC / 同步 SDK)
少,以 IO 为主
有
没有
并发流连接数
(预估峰值)
Spring MVC + SseEmitter
链路里是否大量阻塞调用
团队有响应式经验吗
WebFlux + Flux
MVC + SseEmitter
优先保障交付
两者共同前提
只引一个 Web 栈 starter
选 WebFlux 时:阻塞调用必须切 boundedElastic
(图 4:MVC 与 WebFlux 的决策路径------分界线是并发流连接数;选了 WebFlux 就多一条硬约束:任何阻塞调用都必须切到弹性线程池)
3.3 反向代理配置:流式失效的头号原因
如果只记这一节的一个配置,那就是它:Nginx 默认开启的 proxy_buffering 会让你的流式完全失效。
nginx
location /api/ai/stream {
proxy_pass http://ai_backend;
# ① 关闭代理缓冲:不关的话 Nginx 会攒够一批再转发,前端一次收到全部内容
proxy_buffering off;
proxy_cache off;
# ② 关闭分块传输的缓冲(部分版本需要)
chunked_transfer_encoding on;
# ③ 加长读超时:模型"思考"期间可能长时间不发数据,默认 60s 会被断开
proxy_read_timeout 300s;
proxy_send_timeout 300s;
# ④ 保持 HTTP/1.1 并关闭长连接的连接复用干扰
proxy_http_version 1.1;
proxy_set_header Connection "";
# ⑤ 关闭压缩(压缩需要缓冲,会破坏逐帧输出)
gzip off;
}
这个故障的表现极有辨识度:后端日志里能看到逐帧发送,但前端"卡住几秒然后一次性刷出全文"。 遇到这个现象,第一件事就是查 proxy_buffering------我见过三个团队在应用层反复排查(怀疑 Flux、怀疑模型、怀疑前端),最后一个配置项解决。
除了 Nginx 配置,响应头也要配合(4.2 节会写进代码):
text
X-Accel-Buffering: no ← 告诉 Nginx 这类代理"这条响应不要缓冲"
Cache-Control: no-cache ← 防止中间层缓存部分流
Content-Type: text/event-stream; charset=UTF-8
X-Accel-Buffering: no 的价值在于它把"不要缓冲"这个意图写进了响应本身 ------这样即使运维改动了 Nginx 配置、或者流量经过了一个你控制不到的第二层代理,它仍有机会被正确识别。
3.4 前端:为什么不用 EventSource
前面 2.1 节说过 EventSource 不能带请求头,所以生产上通常用 fetch + ReadableStream。 给出一份可直接用的最小实现:
javascript
// POST + 手动解析 SSE 帧(可携带 Authorization,可发送 body)
const resp = await fetch('/api/ai/stream', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + token, // EventSource 做不到这一点
'Accept': 'text/event-stream'
},
body: JSON.stringify({ question }),
signal: abortController.signal // 用于"停止生成"
});
const reader = resp.body.getReader();
const decoder = new TextDecoder('utf-8');
let buffer = '';
while (true) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
// SSE 帧以空行分隔
const frames = buffer.split('\n\n');
buffer = frames.pop(); // 最后一段可能不完整,留到下一轮
for (const frame of frames) {
for (const line of frame.split('\n')) {
if (line.startsWith('data:')) {
const payload = line.slice(5).trim();
if (payload === '[DONE]') return;
handleChunk(JSON.parse(payload));
}
// 以 ':' 开头的是注释帧(心跳),直接忽略
}
}
}
这段代码里有两个位置是必须的,少了任何一个都会出问题:
第一,buffer 的"不完整帧暂存"逻辑。 网络分片的边界与 SSE 帧的边界没有任何关系------一次 reader.read() 可能返回半个帧、也可能返回三个半帧 。如果不做暂存拼接,你会偶发地解析出残缺 JSON 并抛出异常,而这类异常是随机的、与内容相关的,极难复现。 这是流式前端最经典的 bug。
第二,AbortController。 用户点"停止生成"时触发 abortController.abort(),请求断开后服务端才有机会检测到并停止生成 (4.4 节的取消传播)------没有这一步,"停止"按钮只是前端不显示了,模型还在后台烧 token。
4️⃣ 核心实现
4.1 最简的流式接口:先跑通,再加固
任何复杂链路都应该从最小可用版本开始。 一个能工作的流式接口,在 WebFlux 下只有几行:
java
@RestController
@RequestMapping("/api/ai")
public class StreamChatController {
private final ChatClient chatClient;
public StreamChatController(ChatClient.Builder builder) {
this.chatClient = builder.build();
}
/** 最小流式接口:每个元素是一个"增量片段" */
@PostMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> stream(@RequestBody ChatRequest req) {
return chatClient.prompt()
.user(req.question())
.stream()
.content(); // 注意:是增量,不是累积
}
}
这段代码能跑,但它在生产里会出四个问题,正好对应后面四节:
- 只发内容,没有元信息与结束标记------前端无法知道"流结束了"与"这次用了多少 token"(4.5 节);
- 没有心跳------长回答中途"静默"时会被中间设备断开(4.2 节);
- 错误直接打断流------已流出的内容无法收尾,前端只能显示一个断掉的句子(4.3 节);
- 没有取消处理------用户关页面后模型继续生成,token 白烧(4.4 节)。
所以 4.1 只是起点。下面三节逐个把这些问题补上。
模型服务 ChatModel Controller Nginx 前端 模型服务 ChatModel Controller Nginx 前端 #mermaid-svg-XQ3zo5yUisnzrwTf{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-XQ3zo5yUisnzrwTf .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-XQ3zo5yUisnzrwTf .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-XQ3zo5yUisnzrwTf .error-icon{fill:#552222;}#mermaid-svg-XQ3zo5yUisnzrwTf .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-XQ3zo5yUisnzrwTf .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-XQ3zo5yUisnzrwTf .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-XQ3zo5yUisnzrwTf .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-XQ3zo5yUisnzrwTf .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-XQ3zo5yUisnzrwTf .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-XQ3zo5yUisnzrwTf .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-XQ3zo5yUisnzrwTf .marker{fill:#333333;stroke:#333333;}#mermaid-svg-XQ3zo5yUisnzrwTf .marker.cross{stroke:#333333;}#mermaid-svg-XQ3zo5yUisnzrwTf svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-XQ3zo5yUisnzrwTf p{margin:0;}#mermaid-svg-XQ3zo5yUisnzrwTf .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-XQ3zo5yUisnzrwTf text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-XQ3zo5yUisnzrwTf .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-XQ3zo5yUisnzrwTf .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-XQ3zo5yUisnzrwTf .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-XQ3zo5yUisnzrwTf .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-XQ3zo5yUisnzrwTf #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-XQ3zo5yUisnzrwTf .sequenceNumber{fill:white;}#mermaid-svg-XQ3zo5yUisnzrwTf #sequencenumber{fill:#333;}#mermaid-svg-XQ3zo5yUisnzrwTf #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-XQ3zo5yUisnzrwTf .messageText{fill:#333;stroke:none;}#mermaid-svg-XQ3zo5yUisnzrwTf .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-XQ3zo5yUisnzrwTf .labelText,#mermaid-svg-XQ3zo5yUisnzrwTf .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-XQ3zo5yUisnzrwTf .loopText,#mermaid-svg-XQ3zo5yUisnzrwTf .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-XQ3zo5yUisnzrwTf .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-XQ3zo5yUisnzrwTf .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-XQ3zo5yUisnzrwTf .noteText,#mermaid-svg-XQ3zo5yUisnzrwTf .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-XQ3zo5yUisnzrwTf .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-XQ3zo5yUisnzrwTf .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-XQ3zo5yUisnzrwTf .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-XQ3zo5yUisnzrwTf .actorPopupMenu{position:absolute;}#mermaid-svg-XQ3zo5yUisnzrwTf .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-XQ3zo5yUisnzrwTf .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-XQ3zo5yUisnzrwTf .actor-man circle,#mermaid-svg-XQ3zo5yUisnzrwTf line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-XQ3zo5yUisnzrwTf :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 此刻记录 TTFT loop 生成过程 POST /stream(fetch + AbortController) 1 转发(proxy_buffering off) 2 event: meta(立即发出) 3 订阅 stream() 4 HTTP stream=true 5 chunk 1 6 Flux next 7 event: delta(刷出首帧) 8 chunk N 9 Flux next 10 event: delta 11 ping 注释帧(无 token 超过 15 秒时) 12 结束 + usage 13 event: done(usage / ttft / total) 14 用户点停止 → abort() 15 doOnCancel → 取消上游订阅 16
(图 5:一次流式请求的完整链路------注意 Nginx 与 proxy_buffering 的位置,以及最后那两行"用户取消 → 取消上游订阅"的传播路径)
4.2 从模型流到 SSE:事件格式设计与心跳
先把"前后端契约"定下来。一个流式接口如果只发内容,前端就没有办法区分"正常结束""出错结束""被取消"------这三种情况对用户意味着完全不同的处理。 我用五种事件:
| 事件类型 | 时机 | 携带内容 | 前端的处理 |
|---|---|---|---|
meta |
流的第一个帧 | 会话 ID、模型名、请求 ID | 记录用于排查 |
delta |
每个内容片段 | 文本增量 | 追加到界面 |
refs |
内容之后(可选) | 引用来源编号 | 渲染引用角标 |
done |
流的最后一个帧 | token 用量、首 token 延迟、总耗时 | 标记完成,写入统计 |
error |
出错时 | 错误码、是否可重试、已输出长度 | 优雅收尾,显示"生成中断" |
为什么要把 usage 放在流末尾的 done 帧里? 因为流式请求的 token 用量只有在生成结束时才能确定 ------usage 字段本身是随最后一个 chunk 一起返回的。如果在流的开头就发统计,那个数字必然是错的。 这一点与非流式不同(非流式天然在响应里拿到完整 usage)。
实现上最关键的是"心跳"与"内容流的合并"。 用 Flux.merge 把内容流和一个定时心跳流合起来:
java
@PostMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<ServerSentEvent<String>> stream(@RequestBody ChatRequest req) {
String requestId = UUID.randomUUID().toString();
long startNs = System.nanoTime();
AtomicLong firstTokenNs = new AtomicLong(0);
AtomicBoolean streamed = new AtomicBoolean(false); // 4.3 节要用
// ① 元信息帧:立刻发出,让前端尽早进入"等待中"状态
Flux<ServerSentEvent<String>> meta = Flux.just(
sse("meta", Map.of("requestId", requestId, "model", "qwen-plus")));
// ② 内容帧:把模型的 Flux<String> 映射成 SSE
Flux<ServerSentEvent<String>> delta = chatClient.prompt()
.user(req.question())
.stream()
.content()
.doOnNext(chunk -> {
if (firstTokenNs.compareAndSet(0, System.nanoTime())) {
// 首 token 到达,记录 TTFT
meterRegistry.timer("ai.stream.ttft")
.record(System.nanoTime() - startNs, TimeUnit.NANOSECONDS);
}
streamed.set(true);
})
.map(chunk -> sse("delta", chunk));
// ③ 心跳:每 15 秒发一个注释帧,防止中间设备判定连接空闲
Flux<ServerSentEvent<String>> heartbeat =
Flux.interval(Duration.ofSeconds(15))
.map(i -> ServerSentEvent.<String>builder().comment("ping").build())
.takeUntilOther(delta.ignoreElements()); // 内容流结束后心跳停止
return Flux.concat(
meta,
Flux.merge(delta, heartbeat), // 内容与心跳并行
doneFrame(startNs, firstTokenNs)) // 结束后补 done 帧
.onErrorResume(e -> errorFrame(e, streamed.get(), firstTokenNs, startNs));
}
这段代码有三个设计点值得展开:
第一,心跳用注释帧(comment("ping"))而不是数据帧。 因为注释帧不会被标准 SSE 客户端当成事件触发------它只用于"喂"中间设备,不污染业务事件流 。如果用 data: 帧做心跳,前端就得在每个 handler 里加"这是不是心跳"的判断,一旦漏了就会在界面上渲染出奇怪的字符。
第二,takeUntilOther(delta.ignoreElements()) 让心跳随内容流结束而停止。 漏掉这一步,Flux.interval 是个无限流,合并后的流永远不会结束 ------表现是"内容显示完了,但前端一直处于加载中",因为 done 帧永远不会发出(Flux.concat 在等 merge 结果完成)。
第三,Flux.concat 的顺序保证了 done 帧是最后一个。 这是 4.5 节"结构化尾巴"的实现基础。
关于心跳间隔选 15 秒: 高于常见代理的默认空闲超时(多为 30~60 秒)的一半即可。间隔太短会增加无谓流量(每个连接每 15 秒一个帧,几千连接就是每秒几百个帧);太长则挡不住超时。
4.3 流中的错误处理:三阶段状态机的实现
这一节把 2.3 节的三阶段变成代码,也是本篇技术含量最高的一段。
核心问题是:.onErrorResume 里必须知道"当前处于哪个阶段",而阶段信息必须由上游的副作用记录下来(streamed 标志位)。
java
private ServerSentEvent<String> errorFrame(Throwable e,
boolean contentStreamed,
AtomicLong firstTokenNs,
long startNs) {
String code = classify(e); // 见下方错误分类
boolean retryable = !contentStreamed && isRetryable(code);
// ① 已流出内容:只能优雅收尾,绝不重试
if (contentStreamed) {
meterRegistry.counter("ai.stream.broken", "code", code).increment();
return sse("error", Map.of(
"code", code,
"retryable", false,
"reason", "内容已开始输出,不可自动重试",
"hint", "请让用户手动重试或缩短问题"));
}
// ② 未流出内容且错误可重试:这是流式链路里唯一的重试窗口
if (isRetryable(code)) {
meterRegistry.counter("ai.stream.retryable", "code", code).increment();
return sse("error", Map.of(
"code", code,
"retryable", true,
"reason", "尚未产生输出,可安全重试"));
}
// ③ 未流出内容但不可重试:直接失败
meterRegistry.counter("ai.stream.failed", "code", code).increment();
return sse("error", Map.of("code", code, "retryable", false));
}
/** 错误分类:决定"能不能重试"的依据 */
private String classify(Throwable e) {
if (e instanceof TimeoutException) return "TIMEOUT";
if (e instanceof WebClientResponseException wcre) {
int s = wcre.getStatusCode().value();
if (s == 429) return "RATE_LIMIT"; // 可重试(退避)
if (s >= 500) return "UPSTREAM_5XX"; // 可重试
if (s == 400 || s == 401) return "CONFIG_ERROR"; // 不可重试,且应告警
}
if (e instanceof DataIntegrityViolationException) return "TOOL_DUPLICATE";
return "UNKNOWN";
}
这段代码里最重要的判断是 contentStreamed 那个标志位。 它必须在内容真正被发送出去的同一个副作用链上 置位(4.2 节代码里的 .doOnNext()),不能靠"是否有内容生成"来判断 ------因为"模型生成了"和"已经发给客户端了"是两件事。极端情况下(背压、缓冲区),模型可能已经生成了 50 个 token,但客户端一个都还没收到------这时重试仍然是安全的。 不过在工程上我倾向于保守:只要模型开始产出内容就视为不可重试,因为它随时可能已经发送出去了,判断"到底发没发出去"的复杂度高于它带来的收益。
第二个关键点是:错误必须"发出"而不是"抛出"。 流式响应的 HTTP 状态码在第 0 秒就已经是 200(meta 帧已发),之后任何 throw 都不会变成 HTTP 错误码,而会变成"连接被异常关闭" 。所以在 SSE 链路上,所有错误都必须被转换成 error 事件发出去,让前端有机会做正确渲染。 这一条与普通 REST 接口的习惯正好相反。
第三个关键点是"已输出长度"要告诉前端。 上面前两种情况的 payload 里我留了个位置。原因很实际:前端需要知道"这句话是完整的还是断掉的" ------如果是断掉的,界面上应该显示"(生成中断)"而不是让用户以为话说完了。把"半句话看起来像完整的话"这件事说清楚,是流式链路上最容易被忽略的体验细节。
4.4 取消传播:把"停止生成"变成真的停止
用户点"停止"或关闭页面时,"取消"必须一路传到模型侧。 这份实现的关键是 doOnCancel 与一个可验证的手段:
java
public Flux<ServerSentEvent<String>> stream(...) {
AtomicBoolean cancelled = new AtomicBoolean(false);
return chatClient.prompt()
.user(req.question())
.stream()
.content()
.doOnCancel(() -> {
cancelled.set(true);
// 记录止损:取消时已生成的 token 数(用于评估止损效果)
meterRegistry.counter("ai.stream.cancelled").increment();
log.info("stream cancelled by client, requestId={}", requestId);
})
.map(chunk -> sse("delta", chunk))
.concatWith(Flux.defer(() -> cancelled.get()
? Flux.empty() // 已取消:不发 done 帧
: Flux.just(doneFrame(startNs, firstTokenNs))));
}
这段代码里有两个值得说明的取舍:
第一,取消后不发 done 帧。 因为流已经被取消了,往下游发任何东西都没有意义(连接已断) 。但它带来一个观测上的问题(5.3 节要处理):被取消的请求不会有 done 帧,所以"取消率"不能靠统计 done 帧来算,只能靠 doOnCancel 的计数。 这正是我在 1.3 节说的"流式观测更难"的具体体现。
第二,取消必须验证,不能想当然。 因为"代码里写了 doOnCancel"不等于"上游真的停止了生成"。三个验证办法,我建议都做:
| 验证方式 | 做法 | 判据 |
|---|---|---|
| 看服务端日志 | 取消后观察是否还有新的内容帧进入处理链 | 取消后不再有新的 doOnNext 日志 |
| 看用量数据 | 对比"取消的请求"与"正常完成的请求"的 completion_tokens |
取消的请求用量应显著更低(若几乎一样,说明取消没生效) |
| 看模型侧账单 | 同一天的 token 总量 vs 实际完成回答数 | 若总量明显偏高,说明有大量"白烧" |
第二条是最实用的自检项。 我在一个项目上就是靠它发现的取消失效:"取消的请求"的平均 completion_tokens 是 1400(和正常完成的一样),说明取消完全没有传播下去。 排查发现中间加了一层手工 Flux.create() 的桥接代码,它忽略了订阅者的取消信号,导致上游继续拉取模型流。
另外还要注意一个容易漏掉的场景:客户端异常断开(不是主动取消)。 用户网络断了、浏览器崩了------这种情况下有时不会触发 doOnCancel,而是触发连接层面的错误。 所以除了 doOnCancel,还要给整个流设置一个上限超时(timeout(Duration) 或网关的 proxy_read_timeout),作为"兜底"的止损机制------不能只靠前端礼貌地发取消。
#mermaid-svg-xGDpzjsmZvNpr0Xd{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-xGDpzjsmZvNpr0Xd .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-xGDpzjsmZvNpr0Xd .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-xGDpzjsmZvNpr0Xd .error-icon{fill:#552222;}#mermaid-svg-xGDpzjsmZvNpr0Xd .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-xGDpzjsmZvNpr0Xd .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-xGDpzjsmZvNpr0Xd .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-xGDpzjsmZvNpr0Xd .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-xGDpzjsmZvNpr0Xd .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-xGDpzjsmZvNpr0Xd .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-xGDpzjsmZvNpr0Xd .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-xGDpzjsmZvNpr0Xd .marker{fill:#333333;stroke:#333333;}#mermaid-svg-xGDpzjsmZvNpr0Xd .marker.cross{stroke:#333333;}#mermaid-svg-xGDpzjsmZvNpr0Xd svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-xGDpzjsmZvNpr0Xd p{margin:0;}#mermaid-svg-xGDpzjsmZvNpr0Xd .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-xGDpzjsmZvNpr0Xd .cluster-label text{fill:#333;}#mermaid-svg-xGDpzjsmZvNpr0Xd .cluster-label span{color:#333;}#mermaid-svg-xGDpzjsmZvNpr0Xd .cluster-label span p{background-color:transparent;}#mermaid-svg-xGDpzjsmZvNpr0Xd .label text,#mermaid-svg-xGDpzjsmZvNpr0Xd span{fill:#333;color:#333;}#mermaid-svg-xGDpzjsmZvNpr0Xd .node rect,#mermaid-svg-xGDpzjsmZvNpr0Xd .node circle,#mermaid-svg-xGDpzjsmZvNpr0Xd .node ellipse,#mermaid-svg-xGDpzjsmZvNpr0Xd .node polygon,#mermaid-svg-xGDpzjsmZvNpr0Xd .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-xGDpzjsmZvNpr0Xd .rough-node .label text,#mermaid-svg-xGDpzjsmZvNpr0Xd .node .label text,#mermaid-svg-xGDpzjsmZvNpr0Xd .image-shape .label,#mermaid-svg-xGDpzjsmZvNpr0Xd .icon-shape .label{text-anchor:middle;}#mermaid-svg-xGDpzjsmZvNpr0Xd .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-xGDpzjsmZvNpr0Xd .rough-node .label,#mermaid-svg-xGDpzjsmZvNpr0Xd .node .label,#mermaid-svg-xGDpzjsmZvNpr0Xd .image-shape .label,#mermaid-svg-xGDpzjsmZvNpr0Xd .icon-shape .label{text-align:center;}#mermaid-svg-xGDpzjsmZvNpr0Xd .node.clickable{cursor:pointer;}#mermaid-svg-xGDpzjsmZvNpr0Xd .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-xGDpzjsmZvNpr0Xd .arrowheadPath{fill:#333333;}#mermaid-svg-xGDpzjsmZvNpr0Xd .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-xGDpzjsmZvNpr0Xd .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-xGDpzjsmZvNpr0Xd .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-xGDpzjsmZvNpr0Xd .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-xGDpzjsmZvNpr0Xd .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-xGDpzjsmZvNpr0Xd .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-xGDpzjsmZvNpr0Xd .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-xGDpzjsmZvNpr0Xd .cluster text{fill:#333;}#mermaid-svg-xGDpzjsmZvNpr0Xd .cluster span{color:#333;}#mermaid-svg-xGDpzjsmZvNpr0Xd div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-xGDpzjsmZvNpr0Xd .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-xGDpzjsmZvNpr0Xd rect.text{fill:none;stroke-width:0;}#mermaid-svg-xGDpzjsmZvNpr0Xd .icon-shape,#mermaid-svg-xGDpzjsmZvNpr0Xd .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-xGDpzjsmZvNpr0Xd .icon-shape p,#mermaid-svg-xGDpzjsmZvNpr0Xd .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-xGDpzjsmZvNpr0Xd .icon-shape .label rect,#mermaid-svg-xGDpzjsmZvNpr0Xd .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-xGDpzjsmZvNpr0Xd .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-xGDpzjsmZvNpr0Xd .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-xGDpzjsmZvNpr0Xd :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 忽略 cancel 信号
阻塞中无法响应取消
连接仍被持有
实现正确
实现正确
实现正确
用户点停止 / 关闭页面
前端 abort()
连接断开
断链点 1
手工 Flux.create 桥接
断链点 2
流内阻塞式调用
断链点 3
HTTP 客户端未随取消关闭连接
上游继续拉取
token 白烧
取消传播到模型侧
输出 token 省约 68%
验证手段:比较取消请求与完成请求的 completion_tokens
(图 6:取消传播的三个断链点------它们共同的表现都是"用户点停止后模型还在生成",而验证手段只有一条:比较取消请求与完成请求的输出 token 数)
4.5 结构化尾巴:在流末尾附上元信息
前面提过两次的"结构化尾巴",现在把它说完整。
流式链路与结构化输出并非完全不能共存,只是不能混流 。正确形态是:内容部分用 delta 流式发出,结构化部分(引用编号、用量统计、耗时)作为独立的尾部事件一次性发出。
java
/** 流末尾的 done 帧:一次带齐所有结构化信息 */
private ServerSentEvent<String> doneFrame(long startNs, AtomicLong firstTokenNs) {
long totalMs = (System.nanoTime() - startNs) / 1_000_000;
long ttftMs = firstTokenNs.get() == 0 ? -1
: (firstTokenNs.get() - startNs) / 1_000_000;
return sse("done", Map.of(
"ttftMs", ttftMs, // 首 token 延迟
"totalMs", totalMs, // 总耗时
"usage", usageHolder.get(), // token 用量(流结束才有)
"finishReason", "stop"));
}
为什么这样设计而不是"把结构化字段塞进每个 delta 帧"?
| 方案 | 问题 |
|---|---|
每个 delta 帧带结构化字段 |
帧体积膨胀 (几百个帧每个都带一遍重复的元信息);且字段本身在流过程中是"未完成"的(usage 要到结束才有值) |
| 只在末尾发一个结构化帧 | 大小可控、语义清晰:前端明确知道"内容到此结束,下面是统计信息" |
首尾各发一个(meta + done) |
当前采用 :meta 用于尽早建立上下文(请求 ID 便于排查),done 用于收尾 |
同理,"引用来源"这类信息也应该放在尾部或内容之后的独立事件里 (RAG 场景,第 4 篇)。因为引用编号要在内容生成完之后才能确定 (哪几条被真正用到了),提前发反而会给出错误信息。前端拿到 refs 事件后再渲染角标,用户看到的引用永远是准确的。
这个模式还有一个额外好处:它让"流式接口"与"结构化输出"的边界变得清晰。 需要给程序消费的结构化数据(比如意图识别结果、路由决策)走 4.1 节的同步接口(.entity());需要给人看的内容走流式;两者在同一个业务动作里可以并存,但走两个不同的通道。 这就解决了 2.4 节留下的那个取舍------不是"二选一",而是"分流"。

5️⃣ 进阶与优化
5.1 首 token 延迟的四个优化点(以及一个陷阱)
按投入产出比排序,第一个的收益远大于其余三个:
| 优化点 | 做法 | 典型收益 | 代价 |
|---|---|---|---|
| ① 砍输入(最高) | 历史消息按 token 数裁剪(第 8 篇的裁剪策略)、检索片段从 5 段减到 3 段、系统提示瘦身 | TTFT 下降 30%~50% | 上下文信息减少,可能影响回答质量(需回归验证) |
| ② 连接预热 | 保持 HTTP 连接池、预热 TLS 握手、服务启动时做一次空调用 | TTFT 下降 100~300ms | 少量常驻资源 |
| ③ 换更快的模型 | 用更快的小模型处理简单问题(第 5 篇的级联思路) | TTFT 下降 40%~60% | 可能让总耗时变长(见下方陷阱) |
| ④ 减少链路跳数 | 合并代理层、避免多级网关 | TTFT 下降 50~200ms | 架构收敛,改动成本高 |
①号之所以收益最大,是因为 prefill 时间与输入长度近似成正比。 一次带 20 轮历史的对话,输入可能有两万 token,光是 prefill 就要好几秒 ------而用户问的往往只是一句"那第二种方案呢"。裁剪历史对 TTFT 的改善是线性的、直接的,且不需要改动架构。
②号是那种"看起来不重要但很稳定"的优化。 TLS 握手与连接建立在某些网络环境下要 200~300ms,对一个 TTFT 只有 900ms 的系统来说占了两成以上。保持长连接是最省力的改善。
③号有一个必须警惕的陷阱:换小模型降低 TTFT,但可能推高总耗时。 因为小模型往往"更啰嗦"------它倾向于把结论埋在中后段,前面先绕一圈 。我实测过一次替换:TTFT 从 1.4 秒降到 0.7 秒,但总耗时从 6.2 秒升到 9.5 秒 (输出 token 从 480 涨到 820)。用户的感受是"开始得很快,但要看完的时间更长" ------对一个需要读完整回答的场景,这是净损失。
所以评估模型切换必须同时看两个指标: TTFT 与总耗时(以及输出 token 数)。只看 TTFT 做决策,会得到一个"响应很快但很啰嗦"的系统。
④号在微服务架构里常被忽略。 一次请求穿过"网关 → BFF → AI 服务 → 模型"四跳,每跳都有几十毫秒的转发与日志开销,累积起来可能超过 300ms。 对 AI 链路,我的建议是让 AI 服务尽量靠近入口 ,不要在它前面堆业务聚合层 ------因为 AI 服务的延迟本来就在秒级,任何额外跳数的百分比影响都会被放大。
还有一个纯实操但极少被讲清的问题:TTFT 到底从哪一刻算起? 三种口径给出的数字差异很大,混用它们会让优化完全失去方向:
| 口径 | 起点 → 终点 | 反映什么 | 用途 |
|---|---|---|---|
| 客户端口径 | 用户点击 → 首字渲染到屏幕 | 最接近用户感知(含网络往返与前端渲染) | 体验指标、对外承诺 |
| 服务端口径 | 请求进入 Controller → 第一个 chunk 到达 | 后端 + 模型性能(不含客户端网络) | 性能定位 |
| 模型侧口径 | 供应商报表里的 TTFT | 仅 prefill 与首 token 采样 | 判断"是不是模型本身慢" |
三者之间的差值本身就是有价值的指标。 我在一次排查中拿到过这样一组数:客户端口径 1.9 秒、服务端口径 1.1 秒、模型侧 0.85 秒------中间那 800ms 全花在了链路上,其中约 400ms 来自一次不必要的代理跳数 (就是 5.1 节的④号优化点)。如果只采集一个口径,这个发现根本不会出现:只看客户端会以为模型慢,只看模型侧会以为一切正常。
所以我的建议是至少同时采集两个口径:客户端口径做体验指标,服务端口径做性能指标,两者之差用来发现链路问题。 三个都能拿到就更好------差值能直接把"问题在模型、在后端、还是在链路"三者分开,省掉大量跨团队扯皮。
5.2 取消止损与超时分层
超时这件事在流式链路里比非流式复杂得多,因为它有两个时间尺度:
| 超时类型 | 含义 | 建议值 | 配错的后果 |
|---|---|---|---|
| 首 token 超时 | 从请求发出到第一个 token | 15~30 秒 | 设太短会把"prefill 慢但正常"的请求误杀 |
| 帧间隔超时 | 两个 token 之间的最长间隔 | 30~60 秒 | 设太短会在模型"思考"时误断;设太长会让卡死的连接长时间占用资源 |
| 总时长超时 | 整个流的寿命上限 | 按最长回答的 1.5~2 倍 | 设太短会砍掉长回答;设太长会让异常连接长期不释放 |
三层超时必须都设,而且是"从下往上"依次放宽的。 只设总时长的话,一个"卡在 prefill 阶段"的请求会占用连接直到总超时(可能一两分钟),期间用户什么都看不到。 只设首 token 超时的话,一个"生成了 20 个字后卡住"的请求会一直挂着。
帧间隔超时是最容易被漏掉的一层,而它恰恰是处理"模型卡住"的唯一手段。 实现上 Reactor 有现成的操作符:
java
chatClient.prompt().user(q).stream().content()
.timeout(Duration.ofSeconds(30), // 帧间隔超时
Flux.error(new TimeoutException("no token for 30s")))
.take(Duration.ofMinutes(3)) // 总时长上限(兜底)
取消止损的实测价值。 我用"用户主动取消的请求"做过统计:一次平均输出 1200 token 的回答,中位取消点在第 380 个 token 附近(约 32%) 。也就是说,如果取消能正确传播,输出侧的 token 消耗能省下约 68%。
但这个数字的意义取决于取消率。 如果取消率只有 2%,省下来的钱可以忽略;如果取消率是 25%(我见过一个"回答太长"的产品达到这个量级),取消止损带来的节省就非常可观了。 而更值得注意的是------25% 的取消率本身就是产品问题,见 5.3 节。
5.3 可观测性:流式链路独有的四个指标
流式链路的指标与非流式有本质区别,因为"一次请求"变成了"一段时间序列"。 我用四个指标:
| 指标 | 定义 | 回答什么问题 | 异常信号 |
|---|---|---|---|
| TTFT(首 token 延迟) | 请求发出 → 第一个 content 帧 | 用户觉得卡不卡 | P95 上升比均值上升更有意义 |
| 输出速度 | 内容 token 数 ÷ 生成时长 | 字出得快不快 | 明显下降说明上游限速或网络拥塞 |
| 流中断率 | 已开始输出但未正常结束的比例 | 有多少回答是"断掉的" | 上升说明上游稳定性变差 |
| 取消率 | 用户主动停止 ÷ 总请求 | 有多少回答用户不想读完 | 上升是产品信号,不是技术信号 |
第一个指标的分位数比均值重要得多。 TTFT 的均值 900ms 可能掩盖着 P95 的 4.5 秒------而用户的抱怨几乎总是来自那 5% 的慢请求。 所以 TTFT 必须看 P95(甚至 P99),这也是我在 1.1 节那张表里把"P95"单独列出来的原因。
最后一个指标"取消率"是流式场景独有的、也最有价值的指标,我要重点说。 它的定义是"用户主动点了停止"------在对话产品里,这个动作的含义非常明确:他判断这段回答不值得继续等下去。
取消率上升通常对应三种问题,而且都不是技术问题:
- 回答太长/太啰嗦 ------用户看到第 3 段就知道自己不需要后 10 段了。对策是调整提示词要求"结论先行、控制在 N 字以内",而不是优化模型。
- 回答跑偏 ------用户在前 200 字里就发现它理解错了,于是停止。对策是检查意图理解与提示词,这类上升往往同时伴随"追问率"上升。
- TTFT 波动 ------等待太久,用户放弃。这一种才是技术问题,可以通过"取消率与 TTFT 的相关性"来区分。
所以取消率必须和 TTFT 放在一起看 :如果取消率上升而 TTFT 稳定,问题在内容质量 ;如果两者同时上升,问题在链路性能 。这个联动分析能省掉大量排查时间------我见过团队在"用户总是点停止"这个现象上排查了两周性能,而真正的原因是提示词改版后回答长度翻倍。
还有一个流式特有的观测陷阱,值得单独提:被取消的请求在常规埋点里会显示为"客户端断开连接",容易被判成故障。 所以必须把"用户取消"与"异常断开"分成两个计数 ,否则你的错误率指标会被用户的正常操作污染------而一个被污染的错误率指标会让人逐渐不再看它,这比指标本身不准更糟。
#mermaid-svg-HonatfC2umRWjPoU{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-HonatfC2umRWjPoU .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-HonatfC2umRWjPoU .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-HonatfC2umRWjPoU .error-icon{fill:#552222;}#mermaid-svg-HonatfC2umRWjPoU .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-HonatfC2umRWjPoU .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-HonatfC2umRWjPoU .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-HonatfC2umRWjPoU .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-HonatfC2umRWjPoU .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-HonatfC2umRWjPoU .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-HonatfC2umRWjPoU .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-HonatfC2umRWjPoU .marker{fill:#333333;stroke:#333333;}#mermaid-svg-HonatfC2umRWjPoU .marker.cross{stroke:#333333;}#mermaid-svg-HonatfC2umRWjPoU svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-HonatfC2umRWjPoU p{margin:0;}#mermaid-svg-HonatfC2umRWjPoU .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-HonatfC2umRWjPoU .cluster-label text{fill:#333;}#mermaid-svg-HonatfC2umRWjPoU .cluster-label span{color:#333;}#mermaid-svg-HonatfC2umRWjPoU .cluster-label span p{background-color:transparent;}#mermaid-svg-HonatfC2umRWjPoU .label text,#mermaid-svg-HonatfC2umRWjPoU span{fill:#333;color:#333;}#mermaid-svg-HonatfC2umRWjPoU .node rect,#mermaid-svg-HonatfC2umRWjPoU .node circle,#mermaid-svg-HonatfC2umRWjPoU .node ellipse,#mermaid-svg-HonatfC2umRWjPoU .node polygon,#mermaid-svg-HonatfC2umRWjPoU .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-HonatfC2umRWjPoU .rough-node .label text,#mermaid-svg-HonatfC2umRWjPoU .node .label text,#mermaid-svg-HonatfC2umRWjPoU .image-shape .label,#mermaid-svg-HonatfC2umRWjPoU .icon-shape .label{text-anchor:middle;}#mermaid-svg-HonatfC2umRWjPoU .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-HonatfC2umRWjPoU .rough-node .label,#mermaid-svg-HonatfC2umRWjPoU .node .label,#mermaid-svg-HonatfC2umRWjPoU .image-shape .label,#mermaid-svg-HonatfC2umRWjPoU .icon-shape .label{text-align:center;}#mermaid-svg-HonatfC2umRWjPoU .node.clickable{cursor:pointer;}#mermaid-svg-HonatfC2umRWjPoU .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-HonatfC2umRWjPoU .arrowheadPath{fill:#333333;}#mermaid-svg-HonatfC2umRWjPoU .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-HonatfC2umRWjPoU .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-HonatfC2umRWjPoU .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-HonatfC2umRWjPoU .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-HonatfC2umRWjPoU .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-HonatfC2umRWjPoU .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-HonatfC2umRWjPoU .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-HonatfC2umRWjPoU .cluster text{fill:#333;}#mermaid-svg-HonatfC2umRWjPoU .cluster span{color:#333;}#mermaid-svg-HonatfC2umRWjPoU div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-HonatfC2umRWjPoU .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-HonatfC2umRWjPoU rect.text{fill:none;stroke-width:0;}#mermaid-svg-HonatfC2umRWjPoU .icon-shape,#mermaid-svg-HonatfC2umRWjPoU .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-HonatfC2umRWjPoU .icon-shape p,#mermaid-svg-HonatfC2umRWjPoU .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-HonatfC2umRWjPoU .icon-shape .label rect,#mermaid-svg-HonatfC2umRWjPoU .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-HonatfC2umRWjPoU .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-HonatfC2umRWjPoU .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-HonatfC2umRWjPoU :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} TTFT(看 P95,不看均值)
输出速度 token/s
流中断率
取消率
取消率升 + TTFT 稳定
两者同时上升
请求发出
meta 帧
首个 delta
后续 delta
done / error / 取消
用户觉得卡不卡
字出得快不快
多少回答是断掉的
多少回答用户不想读完
取消率与 TTFT 联动分析
内容质量问题:改提示词、控长度
链路性能问题:查 prefill 与代理链
(图 7:四个观测指标与它们各自回答的问题------最下方那个联动分析是分水岭:取消率上升到底是内容问题还是性能问题,靠它区分)
5.4 同一服务里三种链路的共存
到第 8 篇为止,这个系列已经出现了三种 AI 调用形态,它们打到最后必然出现在同一个服务里:
| 链路 | 出处 | 超时 | 并发模型 | 配额 |
|---|---|---|---|---|
| 流式对话 | 本篇 | 秒级首 token,分钟级总时长 | WebFlux 事件循环 | 与在线服务共享,但优先级最高 |
| 同步调用(结构化输出、工具) | 第 5 篇 | 10~30 秒 | 普通请求线程池 | 与在线服务共享 |
| 批处理 | 第 7 篇 | 单条 20~30 秒,整批小时级 | 受控并发 + 业务侧限流 | 必须分离、必须留份额 |
三者共存的第一条纪律是:批处理必须与在线链路分开配额与并发池 (第 7 篇 4.2 节)。这一条如果不做,批处理会在夜里吃掉配额,然后第二天早上用户发现 AI 功能全部 429 ------而这个故障的表现是"早上九点开始 AI 全挂,十点自己好了",排查方向极易跑偏到"早上流量高峰"。
第二条纪律是"流式链路的资源必须与同步链路隔离"。 因为流式连接是长连接,如果它和同步请求共用同一个线程池,长连接会把线程占满,导致同步接口全部排队。 MVC + SseEmitter 路线上这个问题尤其突出(3.2 节:每个连接一个线程)。
第三条纪律是"用同一个 ChatClient,但用不同的参数"。 具体是:流式链路开流式、temperature 按需;同步与批处理链路关流式、结构化输出 。共用同一个 ChatClient 实例,但参数在请求级覆盖 (第 2 篇讲过的 .options() 用法)------这样配置来源统一(第 7 篇 1.3 节说的"三统一"),行为各自独立。

6️⃣ 适用边界与风险提示
6.1 适用场景
流式在这些场景里是明确正确的选择:
- 面向人的长回答生成 (报告、方案、总结、代码解释)------首 token 延迟是可用性的底线;
- 交互式对话的每一轮 ------即使用户的问题很短,让用户尽早看到"它在回答"本身就是重要的反馈;
- 有"生成中途可读"价值的场景------比如"边生成边让用户判断方向对不对",用户可以在第 100 字就点停止(5.3 节的取消)。
- 链路中有较长准备时间的场景 ------检索、工具调用之后才生成内容,流式能让"准备阶段"也有反馈 (先用
meta帧告知"正在检索")。
6.2 不适用场景
第一,需要结构化输出的调用------不能开流式(2.4 节)。 这是硬约束,不是偏好。.entity() 需要完整 JSON。如果你的场景既要"给人看流式"又要"给程序结构化结果",正确做法是分流成两个通道(4.5 节),而不是想办法混在一起。
第二,机器对机器的调用------一般不开。 调用方需要完整结果才能继续处理,中间的过程对它没有价值,反而增加了实现复杂度(要处理分帧、要拼接、要处理不完整的最后一帧)。
第三,批处理与离线任务------必须关(第 7 篇 3.2 节)。 没有人看,且流式会阻碍"整段解析 + 校验"。这一点在批处理里还有个隐性代价:流式下无法使用 usage 之外的完整响应结构,而某些模型参数(如结束原因、内容过滤标记)在非流式响应里更完整。
第四,答案极短且可枚举的场景------收益极小。 比如意图分类("退款/咨询/其他"),生成只要 0.3 秒,开流式只会让链路复杂化而没有任何体验收益。
第五,对"最终一致性"有严格要求的场景。 流式过程中如果链路中断,用户看到的是不完整的回答,而系统可能认为"请求已响应" 。如果业务上不能接受"用户看到了半句话",那么要么不开流式,要么必须在协议里明确处理 error 事件(4.3 节)------这一点是流式最容易被低估的风险:它把"全有或全无"的语义变成了"部分可能"的语义。
第六,答案需要"整体判断"而不是"逐步阅读"的场景------流式可能反而有害。 有些回答的价值在整体结构(比如"三个方案各有什么利弊、综合建议选哪个"),用户逐字读到一半时会形成不完整的判断,甚至在中途就下了结论然后取消 (5.3 节的取消率)。更麻烦的是如果流在中途出错,用户已经根据半截内容做过判断了 ------这正是 6.2 节第 5 条那个"部分可能"的语义风险在体验层的体现。这类内容更适合"先生成完、再一次性给出",配一个明确的"生成中"状态,而不是流式文本。 判断标准可以简化为一句:这份回答是"读一段就有一段的价值",还是"必须读完才能理解"? 前者适合流式,后者不适合。
6.3 版本兼容与升级注意
| 变化项 | 影响 | 应对 |
|---|---|---|
| WebFlux 与 MVC 共存 | 同时引入两个 starter 时默认走 MVC,Flux 返回值被当普通对象序列化,流式静默失效 |
只引一个 starter;启动时打一条日志确认当前 Web 栈 |
| Spring AI 1.1.x → 2.0.x 流式 API | stream() 的返回类型与链式方法在版本间有差异;Advisor 位置变化会影响流式链路上的拦截器 |
升级前用"最小流式接口"跑通(4.1 节),再逐步加 Advisor |
| Jackson 3(2.0 起) | SSE 帧里的 JSON 序列化行为变化 | 检查 done/error 帧的自定义序列化 |
| Reactor 版本 | timeout / take 的语义细节在版本间有微调 |
写测试验证"帧间隔超时"确实生效(这类行为不测就是不知道) |
升级流式链路的第一条动作是"跑一遍 4.1 节的最小接口" ------因为它能在三十秒内告诉你"流式通道本身还是通畅的",把问题范围立刻缩小到"我新加的那些代码"上。 这个习惯在排查流式故障时价值极高。
6.4 生产建议清单
可以直接当上线检查表:
- Nginx
proxy_buffering off+ 响应头X-Accel-Buffering: no(3.3 节)------流式失效的头号原因; - 只引一个 Web 栈 starter,并在启动日志里确认(3.1 节);
- 心跳帧必须有,且用注释帧而不是数据帧(4.2 节);
- 事件协议至少五种 :
meta/delta/refs/done/error(4.2 节); usage必须放在流末尾的done帧,不能在开头(4.2 节);- 三阶段状态机:已流出内容绝不重试,且要同时检查"写过记录"这个条件(4.3 节);
- 流式链路上的错误必须"发出"而不是"抛出"(4.3 节)------HTTP 状态码此时已经是 200;
- 取消必须验证真的传播到了模型侧,方法是比较"取消请求"与"完成请求"的输出 token 数(4.4 节);
- 三层超时都要设:首 token / 帧间隔 / 总时长(5.2 节);
- TTFT 看 P95 而不看均值(5.3 节);
- 取消率与 TTFT 联动分析,用来区分"内容质量问题"与"链路性能问题"(5.3 节);
- "用户取消"与"异常断开"必须分开计数,否则错误率指标会被污染(5.3 节);
- 流式、同步、批处理三种链路分离配额与线程池(5.4 节);
- 前端的 SSE 解析必须做"不完整帧暂存",否则会偶发解析失败(3.4 节)。

7️⃣ 总结
7.1 关键决策点回顾
| 决策点 | 选择 | 核心理由 |
|---|---|---|
| 为什么开流式 | 降低首 token 延迟,不是降低总耗时 | 流式总耗时反而略增;它改变的是"用户何时看到第一个字" |
| 优化什么指标 | 想解决"卡"就优化 TTFT,想解决"久"就优化输出长度 | 两者由 prefill 与 decode 分别决定,手段完全不同 |
| SSE 还是 WebSocket | SSE | AI 输出天然单向;WebSocket 的双向能力换不来收益 |
| MVC 还是 WebFlux | 并发流连接 < 500 用 MVC + SseEmitter;更多用 WebFlux |
响应式改造的隐性成本在低并发下换不来收益 |
| WebFlux 里能调阻塞接口吗 | 必须切 boundedElastic |
阻塞会卡住共享事件循环,故障形态伪装成"数据库慢" |
| 流式失效先查什么 | Nginx proxy_buffering |
头号原因,且表现极易误导排查方向 |
前端用 EventSource 吗 |
生产用 fetch + ReadableStream |
EventSource 不能带请求头,无法传 Authorization |
| 要不要心跳 | 必须,15 秒,用注释帧 | 模型"思考"时的静默会被中间设备判为空闲 |
usage 放哪 |
流末尾的 done 帧 |
流结束时才拿得到完整用量 |
| 已流出内容能重试吗 | 不能;且还要检查"是否写过记录" | 两个独立条件任一成立即不可重试 |
| 流式接口怎么报错 | 发 error 事件,不抛异常 |
状态码在第 0 秒已是 200,抛出只会变成连接异常关闭 |
| 结构化字段怎么给 | 做成尾部独立事件,与内容不混流 | usage 与引用编号都只有流结束时才确定 |
| 取消怎么做才有效 | doOnCancel + 用 token 数验证传播 |
"写了取消代码"不等于"上游真的停了" |
| 取消率说明什么 | 先看它和 TTFT 的相关性 | 稳定 TTFT 下取消率上升 = 内容质量问题,不是性能问题 |
7.2 回到开头
开头我说,流式改变的不是"更快",而是"更早看到第一个字"。 走到这里可以把这个结论再推进一层:
流式的真正代价,是它把"请求-响应"这个清爽的契约,换成了一段"可能中途夭折、可能被随时打断、状态码不再表达结果"的时间序列。 1.3 节列的三处成本(重试语义变化、错误可能发生在中间、观测变难)全部源于此。
所以整篇所有技术细节其实都服务于同一件事:在这段"不确定的时间序列"上,重新建立起可以判断、可以收尾、可以止损的秩序。 三阶段状态机解决"什么时候能重试";error 事件解决"怎么收尾";取消传播解决"怎么止损";而 TTFT、中断率、取消率这三个指标,解决"怎么知道它现在好不好"。
最值得记住的仍然是那条跨篇一致的纪律:已经流出去的内容不能重试,而且判定条件不止一个。 它在第 2 篇是"流式已开始不重试",在第 5 篇是"工具已执行不重试",在第 7 篇是"批处理的幂等",在本篇则是"内容已流出不重试"------同一个原则在不同链路里的四次变形。
参考资料
- Spring AI Reference Documentation · Streaming Responses(
stream()与Flux返回类型、流式与结构化输出的互斥):https://docs.spring.io/spring-ai/reference/api/chatclient.html - Spring AI Reference Documentation · Chat Client(
ChatClient的流式调用与请求级参数覆盖):https://docs.spring.io/spring-ai/reference/api/chatclient.html - Spring AI Reference Documentation · Structured Output Converter(说明为何结构化输出需要完整响应,与流式不兼容):https://docs.spring.io/spring-ai/reference/api/structured-output-converter.html
- Spring Framework Reference · WebFlux(响应式 Web 栈、
Flux与背压模型):https://docs.spring.io/spring-framework/reference/web/webflux.html - Spring Framework Reference · Web on Reactive Stack / Server-Sent Events(
ServerSentEvent与 SSE 支持):https://docs.spring.io/spring-framework/reference/web/webflux/controller/ann-methods/server-sent-events.html - Spring Framework Javadoc ·
SseEmitter(MVC 路线下的 SSE 实现与线程模型):https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/servlet/mvc/method/annotation/SseEmitter.html - Project Reactor Reference ·
timeout/take/doOnCancel(帧间隔超时与取消传播的操作符语义):https://projectreactor.io/docs/core/release/reference/ - MDN Web Docs · Server-Sent Events /
EventSource(协议帧格式、Last-Event-ID与"不能自定义请求头"的限制):https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events - MDN Web Docs · Using ReadableStream(
fetch+ReadableStream手动解析 SSE 帧):https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Using_readable_streams - Nginx 官方文档 ·
proxy_buffering与proxy_read_timeout(流式响应失效的配置根因):https://nginx.org/en/docs/http/ngx_http_proxy_module.html - 阿里云百炼 · 通义千问流式接口与计费说明(
stream: true的响应结构与usage的返回时机):https://help.aliyun.com/zh/model-studio/