流式输出这几年几乎是 AI 对话、数据导出、实时通知类服务的标配,但做过的人都知道,“接口能流式返回”和“用户真的觉得流畅”是两码事。我去年接手一个基于大模型能力的问答服务,线上反馈最多的不是答案错,而是两个现象:第一,按回车之后要愣几秒才看到第一个字,体验像假流式;第二,刷到一半连接断掉,前端要么卡在白屏,要么永远显示“正在生成”。把这些坑一个个填完之后,我整理了一套从首字延迟到生产级稳定性的工程实践,覆盖传输层协议选型、JDBC 查询流式输出、AI 对话的增量渲染、以及上线后怎么观测和压测。如果你正在做类聊天、SSE 推送或大数据导出功能,这篇文章应该能省掉不少弯路。
1. 首字延迟被流式输出掩盖:拆开“等待”这口锅
很多团队评估流式改造时,只盯着“后续 token 是否连续”,却忽略了用户真正感知的起点是首字延迟。聊天场景里用户按下发送键后,如果 1 秒内没有反馈,就会开始怀疑程序挂了。这个数字在流式接口里的构成比普通接口复杂得多,不能简单用
time_starttransfer
一个指标去归因。
1.1 首字延迟的时间分段
一次流式请求从用户点击到 UI 出现第一个字符,粗略可以拆成五段:
| 阶段 | 说明 | 典型耗时区间 |
|---|---|---|
| 网络建连 | DNS、TCP、TLS 握手、HTTP 连接复用判断 | 20ms ~ 300ms |
| 服务端接入 | 网关路由、鉴权、限流、请求解析 | 5ms ~ 100ms |
| 业务预处理 | 会话上下文组装、向量检索、知识库检索、模型调度 | 200ms ~ 2000ms |
| 上游首包生成 | 大模型首 token 生成、数据库首行返回 | 300ms ~ 3000ms |
| 输出链路缓冲 | 后端框架聚集写、网关/代理缓冲满才转发、前端 debounce 合并渲染 | 50ms ~ 2000ms |
很多人查首字延迟只盯着业务代码里“调用模型前做了什么”,但其实输出链路缓冲往往是隐藏最深的一层。我遇到过 Spring WebFlux 里用默认
Flux
写 SSE,数据量小时框架会攒到一定大小才真正 flush 到 socket;也见过 Nginx 默认
proxy_buffering on
,如果上游响应头没有显式禁用缓冲,Nginx 会等后端吐满一个 buffer 才往客户端转发。这些配置叠加起来,首字直接凭空多出几百毫秒是常事。
1.2 实测首字延迟的手段
不要凭感觉,直接用 curl 拉一版对照数据。下面这个命令适合所有 HTTP 流式接口:
curl -N \
-H "Authorization: Bearer $TOKEN" \
-d '{"prompt":"你好"}' \
-o /tmp/stream.out \
-s \
-w "TTFB: %{time_starttransfer}s\nTotal: %{time_total}s\nSize: %{size_download} bytes\n" \
https://your-api.example.com/v1/chat/completions
time_starttransfer
在流式响应里代表“首字节到达”的时间,但它只是粗粒度指标。更精确的做法是用
tcpdump
或
ngrep
看服务端发出第一帧的时间,再用浏览器 Performance API 里的
responseStart
减去
requestStart
,这样才能把公网链路抖动从服务端耗时的归因中剥离开。
1.3 压缩首字延迟的几个有效动作
先解决“前置动作过多”的问题。AI 对话场景里最常见的做法是把用户输入、历史记录、检索结果组装成 prompt,这个过程如果放在模型调用前面,通常会拖慢几百毫秒。多数时候这些动作可以异步化:先立刻返回一帧
ping
或
event: meta
,把连接占住,同时告诉客户端“服务已收到”,再在后台做上下文组装。浏览器和网关看到数据流动,就不会轻易掐断连接。
其次检查框架和网关的 flush 策略。后端如果是响应式编程,尽量按时间窗口 flush,而不是按字节攒;比如每 50ms 或 100ms 定时发射当前缓冲区,配合模型输出时本身就是一串 token,完全足够。Nginx 或云 LB 层记得关掉响应缓冲:
proxy_buffering off;
proxy_cache off;
proxy_http_version 1.1;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
最后,如果是短连接环境下反复建连,TLS 握手时间也会摊薄在首字里。要么客户端开启 HTTP keep-alive / HTTP/2 多路复用,要么在服务端用会话复用减少握手往返。实测下来,把连接复用做好,首字延迟往往能稳定降低 100ms 以上。
2. 传输通道选型:SSE、WebSocket 与分块响应的实际边界
流式方案一上来就要面临协议选择。现在主流无非三种:SSE(Server-Sent Events)、WebSocket、纯 HTTP chunked 响应。它们表面上都能“持续推数据”,但各自对断线重连、代理穿越、二进制传输和连接生命周期的处理差异非常大,选错后面就是给自己挖坑。
2.1 三种通道的定位差异
| 维度 | SSE | WebSocket | HTTP chunked |
|---|---|---|---|
| 数据方向 | 服务端到客户端单向 | 双向 | 单向 |
| 协议复杂度 | 低,基于 HTTP 文本 | 高,需要握手与帧协议 | 低 |
| 断线重连 | 原生支持,自动重连 + Last-Event-ID | 需自己实现 | 无 |
| 代理兼容 | 好 | 需要显式 Upgrade 透传,不少 LB 要额外配置 | 好 |
| 二进制帧 | 可传 base64,效率一般 | 原生二进制 | 可传任意字节 |
| 典型场景 | AI 聊天、通知推送、日志回流 | 聊天互动、协作文档、游戏 | 大文件下载、临时流式接口 |
AI 对话类接口我默认建议 SSE。原因很直接:它天然有一个“事件”语义,每条
data:
可以是一段增量结果,结尾的
[DONE]
又能表达正常结束,浏览器端
fetch
或
EventSource
都能简单消费。WebSocket 适合需要双向实时指令的场景,比如你不仅要接收 AI 输出,还要中途修改生成参数、暂停、恢复,那 SSE 的语义就不够了。纯 chunked 响应最灵活,但客户端拿到的是裸字节流,增量边界、结束标志、错误标识都得自己定义,工程成本不低。
2.2 一套可执行的事件协议
无论用 SSE 还是 WebSocket,我建议服务端输出的帧结构保持一致,方便前端统一处理。以 SSE 为例,推荐定义这几类事件:
event: meta
data: {"request_id":"req_20250301_001","model":"gpt-4o-mini","created":1710000000}
event: delta
data: {"index":0,"content":"你好"}
event: delta
data: {"index":0,"content":",很高兴"}
event: done
data: {"reason":"stop","usage":{"prompt_tokens":20,"completion_tokens":35}}
meta
帧用于建立上下文,
delta
才是真正要展示的内容增量,
done
表示正常结束。出错时用统一的
error
事件:
event: error
data: {"code":"upstream_timeout","message":"model timeout"}
这样客户端只需要解析事件类型,不用担心“某一行数据是不是最后一个”。还要特别注意:SSE 事件之间必须有空行分隔,且帧内容里的换行符
\n
要转义或者 base64,否则会破坏帧边界。很多初稿就是在模型输出文本里遇到换行后,把整个 SSE 流打崩的。
2.3 网关与负载均衡器的坑
流式长连接最怕中间链路被静默掐断。常见的坑有三个:
-
Nginx 默认
proxy_read_timeout是 60s,流式接口超过 60s 没有新数据就会被断开。解决是靠心跳:服务端每 15~30s 发一个注释帧或者ping事件。 - 云上负载均衡器如果开启了“空闲连接超时”,同样会掐断长时间无语义的连接。心跳能救。
- 如果走 WebSocket,要在 LB 上把 Upgrade 头透传,并且确认存在一致性哈希或者固定后端,否则断线重连可能跳到另一个节点,导致会话状态丢失。
我个人的习惯是:不分后端业务是什么,只要是面向公网的流式接口,统一加心跳,统一把超时调到远大于业务最大空闲时间。虽然看起来多花一点点流量,但比排查“用户停在某个页面 50 秒后回来发现连接断了”要划算得多。
3. 数据库查询怎么做成流式:JDBC 游标与 HTTP 输出桥接
除了 AI 对话,工程里另一类高频流式需求是“查大量数据并导出”或“边查边推”。很多后端同学写查询接口时习惯把全量
List<Entity>
查出来再统一序列化,结果数据量一大,接口超时是小事,内存直接被撑爆。其实 JDBC 层面就支持流式读取,关键看你用对没有。
3.1 不同数据库驱动如何开启游标流式
JDBC 默认不一定是一次性拉全量。以 MySQL 为例,Connector/J 有个历史遗留行为:
setFetchSize(Integer.MIN_VALUE)
会让驱动采用逐行流式读取;新版本更推荐
useCursorFetch=true
配合
setFetchSize(500)
。PostgreSQL 则要求
autoCommit=false
并且设置 fetch size,否则驱动照样把结果集全部拉到应用内存。Oracle 用
setFetchSize
调控行预取量;SQL Server 要开启
adaptive buffering
。
| 数据库 | 开启流式的关键配置 | 注意事项 |
|---|---|---|
| MySQL |
useCursorFetch=true
+
setFetchSize(500)
;老驱动用
Integer.MIN_VALUE
| 只能读取一遍,不能回退;要串行读取,期间同一连接不能跑其他查询 |
| PostgreSQL |
autoCommit=false
+
setFetchSize(500)
|
必须持有事务,读完要
commit
或
rollback
|
| Oracle |
setFetchSize(1000)
| fetch size 调大能减少往返,但内存占用会上升 |
| SQL Server |
setResponseBuffering("adaptive")
+
setFetchSize(500)
| 打开流式后连接会被独占 |
3.2 一个建议的最小实现:JDBC 行直接进 SSE
如果后端是 Java,最简单的写法是直接用
SseEmitter
把数据库里的行逐条推给前端。核心思路是:不要先收集成完整列表,而是每读到一行就序列化并发送。
@GetMapping("/export/stream")
public void exportStream(SseEmitter emitter) {
executor.execute(() -> {
try (Connection conn = dataSource.getConnection();
PreparedStatement ps = conn.prepareStatement("SELECT * FROM big_table WHERE id > ?")) {
conn.setAutoCommit(false);
ps.setFetchSize(500);
ps.setLong(1, lastId);
try (ResultSet rs = ps.executeQuery()) {
while (rs.next()) {
String json = rowToJson(rs);
emitter.send(SseEmitter.event().data(json));
}
emitter.complete();
}
} catch (Exception e) {
emitter.completeWithError(e);
}
});
}
看起来很简单,但这里有一个非常隐蔽的坑:数据库连接在“读一行推一行”的整个过程中是被独占的。如果并发导出的请求一多,连接池瞬间被打满。所以流式导出接口一定要做并发限制,通常用一个信号量控制同时在跑的导出任务数量,比如最多 5 个,其余请求直接返回 429 或稍后重试。
3.3 行数据在中间链路的缓冲策略
从数据库游标读出来的行,不应该再经过一个“全量聚合”的内存队列。如果中间需要做过滤、聚合或拼接,建议用有界队列:生产者线程从 ResultSet 读一行,塞进
ArrayBlockingQueue
,消费者线程从队列取出来转 JSON 并发给客户端。队列容量要设置上限,否则生产者读取速度远大于发送速度时,内存又会无限膨胀。
这里还要提一个反直觉的经验:对大数据量导出,不要追求“每个数据库行都单独发一个 HTTP 包”,否则网络包数量和序列化开销会非常夸张。更好的做法是攒一个小批次,比如 100 行或 200 行,合并成一个 JSON 数组再发送。这样既保持低首行延迟,又避免逐行发送的系统调用成本。我实测过,行数据很小的情况下逐行发 SSE,CPU 在
write
系统调用上的开销能占掉 30% 以上。
4. AI 对话的增量渲染:合并 token、不完整标签与前端保护
AI 对话场景里,流式输出的链路通常是:模型 API 把 token 增量推给后端,后端再做透传或二次加工给前端。这里有两个核心难点:一是后端如何把增量透传得又稳又快,二是前端拿到增量片段后,怎么避免渲染出“断了一半的 Markdown 标签”。
4.1 模型侧增量透传的注意点
以 OpenAI 风格接口为例,流式响应里每个
delta
的
content
可能不是完整词,而是一个 token 片段或几个字。后端如果做透传,要保证两点:不要对文本做“完整句子”级别的缓存后再发,也不要粗暴地拼成整段再一次性返回。前者会破坏打字机效果,后者直接退化成非流式。
后端可以做微批聚合,比如把 20~50ms 内收到的 token 合并成一帧
delta
,再发给前端。这个做法能显著减少网络包数量,同时视觉上几乎察觉不到延迟。我常用 30ms 作为默认值,模型输出越快,这个窗口可以适当调小;模型输出慢时,窗口调大反而能防止前端每 token 刷一次 DOM 导致卡顿。
Buffer batch = new Buffer();
long windowStart = System.currentTimeMillis();
while (!upstream.isFinished()) {
Token t = upstream.nextToken();
batch.append(t);
if (batch.isNotEmpty() && System.currentTimeMillis() - windowStart >= 30) {
emitter.send(sseEvent("delta", batch.toJson()));
batch.clear();
windowStart = System.currentTimeMillis();
}
}
if (batch.isNotEmpty()) emitter.send(sseEvent("delta", batch.toJson()));
emitter.send(sseEvent("done", "{}"));
4.2 “标签返回未完整”到底怎么处理
这是 ChatGPT 类网页开发中几乎必踩的坑。假设模型这次回答是一篇带 Markdown 的文章,流式输出到“### 标”时,前端如果直接对这段半截文本做 Markdown 解析并渲染,得到的结果可能是一个残缺的
<h3>
,甚至在某些解析器里会把后面的内容全部包进去。要是模型输出的是 HTML 片段,情况更糟:一个没闭合的
<div>
能让你整个聊天页面布局瞬间崩掉。
我给出三层处理方案:
第一层,如果产品只要求看得到文字,最稳妥的做法是把增量文本直接追加到
textarea
或
<pre>
,不做任何富文本渲染。这样标签问题天然不存在,缺点是界面单调。
第二层,如果必须渲染 Markdown,就要在客户端保留完整原始字符串,用节流定时器周期性重新渲染全量文本。不要在每次收到增量时都调一次
markdown.render()
,那会随着文本长度增长卡到没法用;用一个 100~200ms 的定时器合并渲染,能兼顾实时性和性能。
let rawMarkdown = '';
let timer: number | null = null;
function onDelta(text: string) {
rawMarkdown += text;
if (timer) return;
timer = setTimeout(() => {
renderedHtml.value = markdown.render(rawMarkdown);
timer = null;
}, 120);
}
第三层,如果有代码高亮需求,注意高亮器对“处于代码块中间”的文本通常不友好。一个实用的妥协是:当未闭合的代码块标记(比如
```
)出现时,暂停对代码块的高亮,等拿到完整闭合后强制刷新一次。这需要你在底层区分当前输出是否在代码块内,操作起来稍微麻烦,但视觉体验提升非常明显。
4.3 中断、取消与异常结束的约定
流式接口很容易出现“生成了 80% 用户主动取消”的情况。如果前端只是简单关闭弹窗,后端并不知道连接断了,底层模型调用会继续运行,白白消耗 token 费用和 GPU 资源。正确做法是:前端用
AbortController
取消 fetch,后端监听连接关闭,并将取消信号传给模型 API。
同时要约定结束语义:正常结束必须收到
done
事件,如果客户端等到 EOF 但没收到
done
,一律视为异常。基于这个约定,前端可以显示“生成中断”,并提供重试按钮。这里不建议前端自动重试,因为流式响应是不可重放的——你不知道模型已经输出了哪一部分,盲目重试会造成内容重复和顺序错乱。
5. 生产级稳定性:从“能流”到“敢上生产”的四道防线
流式接口上线后被投诉最多的问题,不是功能不对,而是“用着用着就断了”“卡住不动”。这类问题从根子上讲,是连接的生命周期被链路中的某一环误杀了。要长期稳定,至少得布好四道防线。
5.1 防线一:连接层的心跳与超时配合
流式接口的“空闲”不是真的没数据,而是“暂时没数据”。如果网关和负载均衡器把 60 秒没有新字节的连接判定为超时,那用户正在思考、模型正在检索外部知识时,连接就被杀了。服务端应该用定时心跳主动刷新连接活性。
SSE 的心跳有两种写法:一种是发空注释行
: heartbeat\n\n
,不触发客户端业务事件;另一种是定义显式
ping
事件,客户端收到后更新时间戳。我推荐显式事件,因为可以对端到端链路做健康检查,客户端能区分“连接活着”和“收到业务数据”。
心跳间隔要小于网关的最小超时时间。如果网关是 60 秒,心跳就设 20 秒或 30 秒,太紧凑会浪费流量,太疏又卡在临界点。
5.2 防线二:背压与并发流控制
流式服务最容易忽略的是背压。数据库一直往下吐数据,客户端却读得慢,最后要么数据库连接堆积,要么内存被尚未发送出去的缓冲塞满。常规接口靠线程池排队就能挡住突发流量,但流式接口连接会挂很久,不能用“排队”解决,必须显式控制“同时存在的流数量”。
我自己的做法是:
- 对每个流式网关维护一个并发计数,超过阈值直接拒绝新连接,而不是排队等待。
- 如果某条流的输出队列积压超过上限,执行降级:要么断开客户端触发重连,要么丢弃非关键帧只保心跳和最终结果。
- 不要让“持续推送”无上限地抢占内存。每个长连接都会占用 socket 缓冲、业务缓冲、上下文对象,1000 条流连接的内存占用远高于 1000 个普通短连接。
5.3 防线三:优雅关闭与降级
发布新的模型版本或缩容时,流式连接不能直接 kill。如果某个正在生成的请求被强杀,用户看到的不是“失败”而是“毫无反应”。比较好的策略是:
- 节点进入“排空状态”,不再接受新连接。
-
对已建立的流式连接,先发送一个
event: system_notice或event: error帧,明确告知即将断开。 - 给在途模型调用一个最大等待时间(比如 10 秒),超时后强制断开。
- 客户端收到异常帧后,可以展示“服务即将升级,请稍后重试”,而不是留下一个永远转圈的界面。
5.4 防线四:幂等与重连语义
SSE 规范里的
Last-Event-ID
能帮客户端在断线后从上次成功的位置继续接收,但 AI 对话场景很难真正重放,因为模型输出不会精确缓存每一条增量。更实际的方案是在
meta
帧里携带
request_id
,前端在会话维度保存已收到的内容;如果连接断开,重试时把“已显示内容”的背景信息发给服务端,服务端可以据此重新请求,或者直接建议用户“从上次中断位置继续”。这个方案虽然不能做到字节级精确,但至少避免了“重试后整段内容重复”的尴尬。
6. 可观测性与压测:让流式链路的稳定性可量化
流式服务的可观测性和普通接口不一样。普通接口看
RT
、
TPS
、
错误率
就够了;流式接口还需要回答“首字延迟是多少”“每秒吐字速度是否稳定”“有没有半路断流”。这些指标不建立起来,稳定性只会是一句空话。
6.1 流式专属指标与日志规范
我建议至少收集以下指标:
| 指标 | 含义 | 采集方式 |
|---|---|---|
| ttft_seconds | 首帧到达时间 | 服务端发送 meta 帧时打点,客户端收到时打点 |
| inter_token_gap | 相邻 delta 帧间隔 | 服务端/客户端统一记录 |
| stream_duration | 完整流时长 | 从首帧到 done 事件 |
| stream_failure_rate | 未收到 done 的流占比 | 服务端把正常结束与异常结束分开计数 |
| concurrent_streams | 同时在途流数量 | 网关注册表实时统计 |
日志里必须在第一帧就带上
request_id
,并且让网关、后端、模型调用的日志都关联同一个 ID。流式请求涉及多段异步链,没有这个关联,排查“用户说卡在中间”时根本无从下手。
6.2 用 curl 和脚本做连通性巡检
日常巡检,我会在每台节点上定期执行下面这段逻辑:
curl -N --max-time 30 https://internal-api.example.com/stream/ping \
-H 'Accept: text/event-stream' \
2>/dev/null | head -n 3
如果 30 秒内连前三帧都收不到,说明节点代理链路的连接有问题,立刻报警。线上环境建议用外部拨测再补一层,从用户视角验证首字和断流情况。
6.3 流式压测不要把 TPS 当唯一目标
普通压测工具看
requests/s
,但流式接口必须模拟“一个连接持续很久”的特征。我建议用 k6 或自研压测脚本,脚本里读响应体直到
done
事件出现,并且记录首帧时间、总时长、帧间隔。压测指标要分几个维度看:
- 服务端支持多少并发流而不超时;
- 首字延迟在并发升高时从 200ms 涨到多少;
- 有没有出现“连接正常但数据长时间不动”的空洞窗口;
- 断开重连后,服务端连接清理是否及时。
压测场景建议用真实数据形状:模型服务用固定速率输出模拟 token,数据库流式场景用大数据量表查询,不要用几行测试数据糊弄。因为流式系统的瓶颈往往在长连接数量、缓冲压力和数据库游标生命周期,而不是请求处理时长的平均值。
从我自己这几轮踩坑复盘来看,流式输出的工程化核心其实是“链路视角”:首字延迟不只看模型速度,还要看客户端、网关、框架缓冲是否配合;生产稳定性不只看代码写得对不对,还要看连接生命周期、并发控制、可观测性是否做全。先把传输链路上的缓冲和超时理顺,再谈首字优化和 AI 增量渲染,往往能少走很多弯路。最后分享一个我印象最深的小细节:测试环境首字才 50ms,生产环境却稳定在 700ms,查到最后是生产 Nginx 默认开了缓冲,一条配置改动直接回到 80ms。很多流式问题,都不在你以为的那个地方。
本文系统梳理流式输出在AI对话、大数据导出等场景中的核心工程问题,聚焦首字延迟优化、SSE/WebSocket/分块响应选型、JDBC游标流式查询、AI增量渲染与标签保护、生产级四道稳定性防线(心跳、背压、优雅关闭、幂等重连),以及流式专属可观测性与压测方法。强调链路视角下的缓冲、超时、协议语义与中间件配置协同。
278

被折叠的 条评论
为什么被折叠?



