你一定遇到过这种场景:调用接口后界面白屏好几秒,用户以为卡死了,其实内容早就生成好了,只是被一次性攒着没返回。这篇就从请求和响应两条链路讲清流式输出到底在做什么、SSE 是怎么把字一个个送到浏览器的,再给你一份接入前后的设置与验收清单。
你一定遇到过这种场景:调用接口后界面白屏好几秒,用户以为卡死了,其实内容早就生成好了,只是被一次性攒着没返回。这篇就从请求和响应两条链路讲清流式输出到底在做什么、SSE 是怎么把字一个个送到浏览器的,再给你一份接入前后的设置与验收清单。
先把一句话记住:流式输出不缩短总生成时间,它改变的是「你什么时候开始看到东西」。所以判断要不要用,核心不是快不快,而是用户等的时候有没有东西可看。
流式输出到底在解决什么
非流式是一次性把整段回复攒完再返回,流式是把内容切成小块陆续推送。总耗时基本不变,但体感完全不同:非流式是白屏几秒后整段蹦出来,流式是几乎立刻看到第一个字,后面持续吐字。
- 首字等待:用户最先感知到的是「多久看到第一个字」,不是「多久全部结束」
- 长回答白屏:内容越长,一次性返回前的空白期越难熬,流式的优势越明显
- 中途可中断:用户看到前几句就知道跑偏了,能立刻取消,不用干等完整结果
- 渐进渲染:前端可以边收边排版,长文档、代码块、列表都能提前铺出来
| 判断维度 | 适合流式 | 更适合攒完整再返回 |
|---|---|---|
| 回答长度 | 偏长、开放式 | 短、固定格式 |
| 使用场景 | 用户盯着屏幕等结果 | 后台任务、批处理 |
| 后续依赖 | 拿到一段就能展示 | 必须过校验、落库才能走下一步 |
| 中断需求 | 用户想随时喊停 | 跑完就行,不需要中止 |
| 客户端能力 | 能按行解析增量 | 只能处理完整 JSON |
SSE 是怎么把字送到你面前的
流式响应的载体通常是 SSE(Server-Sent Events),本质是一条不关闭的 HTTP 连接持续吐数据。服务端不结束响应,客户端不结束读取,双方就这么一段段传,直到服务端发出结束标记。
- SSE
- 基于普通 HTTP 的单向长连接,服务端持续推、客户端持续收
- 事件类型
- 标记这一块是正文增量、还是心跳、还是结束,客户端据此分流处理
- 数据增量
- 每块只带新增的那几个字,不是整段重发,所以客户端要自己拼接
- 结束标记
- 告诉客户端上游已经吐完,可以收尾、关连接、触发后续逻辑
- WebSocket
- 双向实时通道,接起来更重;只需要服务端往客户端推,SSE 就够
最常见的接入错误是等 JSON 完整再解析。SSE 的数据是流式字节,得按行读、按空行切事件,遇到不完整的一行要暂存等下一批,不能直接丢给 JSON.parse。协议名和字段对照可以去 /ai-dict/category/tech 查一遍,别凭记忆拼。
# 用 curl 直连看原始字节,确认是不是真的在分段吐\ncurl -N -H "Accept: text/event-stream" <你的接口地址>\n# 观察点:输出是持续刷新的,还是一次性全冒出来网页端打字机效果怎么做才不掉链子
拿到增量后马上追加渲染,这是打字机效果的基本做法。但别每来一个字就整段重绘,长回答下这种写法会肉眼可见地卡;更稳的是把增量先塞进缓冲区,用固定节奏合并渲染。
- 先拼后渲收到增量先进缓冲区,按帧或按毫秒节流合并成一次渲染,验证方式是长回答滚动是否顺滑
- 处理半个词中英文切分可能落在词中间,渲染层要能接受半截字符再补齐,别在中间做分词高亮
- 滚动跟随监听用户是否手动上滑过,上滑后就别自动拽回底部,否则用户想回看会被反复打断
- 收尾确认收到结束标记后再标记「完成」,别用「多久没新数据」当结束条件,网络抖动会误判
接入前后的设置与验收清单
很多「流式没生效」其实是链路上的缓冲吃掉了增量:典型表现是很久没反应,然后一次性全来。所以验收要分层做,每层都单独确认,别一步到位放页面里再排查。
| 检查层 | 要确认什么 | 异常表现 |
|---|---|---|
| 请求侧 | 流式开关参数名、协议头是否正确 | 参数写错直接返回完整结果 |
| 代理/网关 | 是否允许长连接、有没有开缓冲 | 长时间无输出后一次全来 |
| 客户端解析 | 是否按行读增量、能否处理半行 | JSON 解析报错或内容错位 |
| 渲染层 | 节流合并、滚动跟随是否生效 | 长回答卡顿或页面被拽回底部 |
- 请求侧:不同协议的流式开关参数名不一样,参考 /base-url 里的协议对照再写
- 网络侧:代理和网关要允许长连接,关掉会吃掉增量的中间缓冲
- 验收顺序:先本地直连跑通,再经代理,最后放进页面,每步都记首字时间和总时长
- 测速:具体延迟基线拿 /tools/speed-test 量一次,别用感觉判断快慢
- 中断验证:点一次取消,确认上游真的停了,而不是界面停了、请求还在跑
首字时间、总时长这些数字会随模型、网络、地区变化,站内不做固定承诺,需要就看 /tools/speed-test 和 /price-watch 里当时的实测数据,别拿别人截图当基线。
什么时候别用流式
要落库、过结构化校验、拿完整结果再走后续流程的任务,攒完整更省事。硬上流式,你反而要额外维护一份拼接缓冲和异常回滚逻辑,复杂度换不来体验提升。
- 结构化输出场景:要解析成 JSON、入库、再触发下游,攒完再解析更稳
- 服务端渲染或静态导出:没有持续连接可用,接流式只会白折腾
- 中断成本敏感:取消要能真正停掉上游调用,否则用户点取消、账单还在走
- 提示词或参数还在调:格式频繁变的时候,先跑通非流式再上流式,省得两头排查
流式不是「更快的接口」,而是「更早给反馈的接口」——用不用,取决于用户在等的是什么。下一步把你现在这个接口按「直连→代理→页面」三层各跑一次,记下首字时间和总时长,再对照站内实测数据看差在哪。→
常见问题
流式输出会让总耗时变短吗?
不会。总生成时间基本一样,流式只是把已经生成的片段提前给你,所以首字时间大幅缩短,整体结束时间差别不大。如果你的痛点是「等太久没反应」,流式有效;如果痛点是「总共就要很久」,得从模型和提示词长度上想办法。
SSE 和 WebSocket 该选哪个?
只是把模型生成的内容推到网页上,用 SSE 就够,实现简单、走普通 HTTP、断线重连也好写。需要用户边说话边回传、或者双方频繁互推的场景才轮到 WebSocket。别为了「看起来高级」上双向通道,多出来的状态管理是负担。
流式输出断流了怎么排查?
按顺序看:客户端有没有正确按行解析、代理或网关是不是开了缓冲、连接读取超时是不是设得太短、上游本身有没有中断。先直连绕开代理测一次,能定位是链路还是代码问题。更细的排查放到生产接入那篇里讲。