流式输出:让 AI 回答像打字机一样实时返回(SSE 全链路实战)

本文是《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();          // 注意:是增量,不是累积
    }
}

这段代码能跑,但它在生产里会出四个问题,正好对应后面四节:

  1. 只发内容,没有元信息与结束标记------前端无法知道"流结束了"与"这次用了多少 token"(4.5 节);
  2. 没有心跳------长回答中途"静默"时会被中间设备断开(4.2 节);
  3. 错误直接打断流------已流出的内容无法收尾,前端只能显示一个断掉的句子(4.3 节);
  4. 没有取消处理------用户关页面后模型继续生成,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"单独列出来的原因。

最后一个指标"取消率"是流式场景独有的、也最有价值的指标,我要重点说。 它的定义是"用户主动点了停止"------在对话产品里,这个动作的含义非常明确:他判断这段回答不值得继续等下去。

取消率上升通常对应三种问题,而且都不是技术问题:

  1. 回答太长/太啰嗦 ------用户看到第 3 段就知道自己不需要后 10 段了。对策是调整提示词要求"结论先行、控制在 N 字以内",而不是优化模型。
  2. 回答跑偏 ------用户在前 200 字里就发现它理解错了,于是停止。对策是检查意图理解与提示词,这类上升往往同时伴随"追问率"上升。
  3. 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 适用场景

流式在这些场景里是明确正确的选择:

  1. 面向人的长回答生成 (报告、方案、总结、代码解释)------首 token 延迟是可用性的底线;
  2. 交互式对话的每一轮 ------即使用户的问题很短,让用户尽早看到"它在回答"本身就是重要的反馈;
  3. 有"生成中途可读"价值的场景------比如"边生成边让用户判断方向对不对",用户可以在第 100 字就点停止(5.3 节的取消)。
  4. 链路中有较长准备时间的场景 ------检索、工具调用之后才生成内容,流式能让"准备阶段"也有反馈 (先用 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 生产建议清单

可以直接当上线检查表:

  1. Nginx proxy_buffering off + 响应头 X-Accel-Buffering: no(3.3 节)------流式失效的头号原因;
  2. 只引一个 Web 栈 starter,并在启动日志里确认(3.1 节);
  3. 心跳帧必须有,且用注释帧而不是数据帧(4.2 节);
  4. 事件协议至少五种 :meta / delta / refs / done / error(4.2 节);
  5. usage 必须放在流末尾的 done 帧,不能在开头(4.2 节);
  6. 三阶段状态机:已流出内容绝不重试,且要同时检查"写过记录"这个条件(4.3 节);
  7. 流式链路上的错误必须"发出"而不是"抛出"(4.3 节)------HTTP 状态码此时已经是 200;
  8. 取消必须验证真的传播到了模型侧,方法是比较"取消请求"与"完成请求"的输出 token 数(4.4 节);
  9. 三层超时都要设:首 token / 帧间隔 / 总时长(5.2 节);
  10. TTFT 看 P95 而不看均值(5.3 节);
  11. 取消率与 TTFT 联动分析,用来区分"内容质量问题"与"链路性能问题"(5.3 节);
  12. "用户取消"与"异常断开"必须分开计数,否则错误率指标会被污染(5.3 节);
  13. 流式、同步、批处理三种链路分离配额与线程池(5.4 节);
  14. 前端的 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 篇是"批处理的幂等",在本篇则是"内容已流出不重试"------同一个原则在不同链路里的四次变形。


参考资料

相关推荐
AI导出鸭PC端14 分钟前
纳米AI怎么复制表格?对话导出总是格式崩塌,我用“AI 导出鸭”重构了工作流
人工智能·重构·豆包·ai导出鸭
AI导出鸭PC端30 分钟前
用 AI 导出鸭高效处理:豆包导 pdf 怎么压缩但清晰
android·人工智能·pdf·豆包·ai导出鸭
装不满的克莱因瓶32 分钟前
【AI时代必学】一篇文章教会你从零搭建Serverless架构
java·人工智能·ai·云原生·架构·serverless
数字融合1 小时前
透明化视频驱动化工生产动态三维重建管控技术
大数据·人工智能·python
七夜zippoe2 小时前
多轮对话管理:Session/记忆在 Java 后端怎么存(存储设计实战)
java·开发语言·ai·session·记忆
知行产研2 小时前
会感知、能协同,金科【钻孔】智能化路线 | bauma CHINA 2026
大数据·人工智能
谙弆悕博士2 小时前
从“预测下一个词”到“预测世界下一状态”:世界模型是不是下一个AGI叙事?
人工智能·gpt·深度学习·神经网络·agi·jepa·genie 4
敖老师2 小时前
企业知识库 × 飞书机器人 —— 从 0 到 1 接入
人工智能
AI前端工程狮2 小时前
我给 MCP 长任务做了持久化,结果造出一堆僵尸
人工智能·程序员