流式输出工程实践:从首字延迟到生产级稳定性

本文系统梳理流式输出在AI对话、大数据导出等场景中的核心工程问题,聚焦首字延迟优化、SSE/WebSocket/分块响应选型、JDBC游标流式查询、AI增量渲染与标签保护、生产级四道稳定性防线(心跳、背压、优雅关闭、幂等重连),以及流式专属可观测性与压测方法。强调链路视角下的缓冲、超时、协议语义与中间件配置协同。

流式输出这几年几乎是 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。如果某个正在生成的请求被强杀,用户看到的不是“失败”而是“毫无反应”。比较好的策略是:

  1. 节点进入“排空状态”,不再接受新连接。
  2. 对已建立的流式连接,先发送一个 event: system_notice 或 event: error 帧,明确告知即将断开。
  3. 给在途模型调用一个最大等待时间(比如 10 秒),超时后强制断开。
  4. 客户端收到异常帧后,可以展示“服务即将升级,请稍后重试”,而不是留下一个永远转圈的界面。

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。很多流式问题,都不在你以为的那个地方。

评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符  | 博主筛选后可见
 
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付:10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值
⌂ 换网址