流式输出是什么意思?API开发者必懂的原理与网页体验

入门与上手

讲清流式输出的原理与网页打字机效果,给开发者可落地的接入判断、参数调整与验收清单。

你一定遇到过这种场景:调用接口后界面白屏好几秒,用户以为卡死了,其实内容早就生成好了,只是被一次性攒着没返回。这篇就从请求和响应两条链路讲清流式输出到底在做什么、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# 观察点:输出是持续刷新的,还是一次性全冒出来

网页端打字机效果怎么做才不掉链子

拿到增量后马上追加渲染,这是打字机效果的基本做法。但别每来一个字就整段重绘,长回答下这种写法会肉眼可见地卡;更稳的是把增量先塞进缓冲区,用固定节奏合并渲染。

  1. 先拼后渲收到增量先进缓冲区,按帧或按毫秒节流合并成一次渲染,验证方式是长回答滚动是否顺滑
  2. 处理半个词中英文切分可能落在词中间,渲染层要能接受半截字符再补齐,别在中间做分词高亮
  3. 滚动跟随监听用户是否手动上滑过,上滑后就别自动拽回底部,否则用户想回看会被反复打断
  4. 收尾确认收到结束标记后再标记「完成」,别用「多久没新数据」当结束条件,网络抖动会误判

接入前后的设置与验收清单

很多「流式没生效」其实是链路上的缓冲吃掉了增量:典型表现是很久没反应,然后一次性全来。所以验收要分层做,每层都单独确认,别一步到位放页面里再排查。

检查层要确认什么异常表现
请求侧流式开关参数名、协议头是否正确参数写错直接返回完整结果
代理/网关是否允许长连接、有没有开缓冲长时间无输出后一次全来
客户端解析是否按行读增量、能否处理半行JSON 解析报错或内容错位
渲染层节流合并、滚动跟随是否生效长回答卡顿或页面被拽回底部
  • 请求侧:不同协议的流式开关参数名不一样,参考 /base-url 里的协议对照再写
  • 网络侧:代理和网关要允许长连接,关掉会吃掉增量的中间缓冲
  • 验收顺序:先本地直连跑通,再经代理,最后放进页面,每步都记首字时间和总时长
  • 测速:具体延迟基线拿 /tools/speed-test 量一次,别用感觉判断快慢
  • 中断验证:点一次取消,确认上游真的停了,而不是界面停了、请求还在跑

首字时间、总时长这些数字会随模型、网络、地区变化,站内不做固定承诺,需要就看 /tools/speed-test 和 /price-watch 里当时的实测数据,别拿别人截图当基线。

什么时候别用流式

要落库、过结构化校验、拿完整结果再走后续流程的任务,攒完整更省事。硬上流式,你反而要额外维护一份拼接缓冲和异常回滚逻辑,复杂度换不来体验提升。

  • 结构化输出场景:要解析成 JSON、入库、再触发下游,攒完再解析更稳
  • 服务端渲染或静态导出:没有持续连接可用,接流式只会白折腾
  • 中断成本敏感:取消要能真正停掉上游调用,否则用户点取消、账单还在走
  • 提示词或参数还在调:格式频繁变的时候,先跑通非流式再上流式,省得两头排查
流式不是「更快的接口」,而是「更早给反馈的接口」——用不用,取决于用户在等的是什么。
下一步把你现在这个接口按「直连→代理→页面」三层各跑一次,记下首字时间和总时长,再对照站内实测数据看差在哪。

常见问题

流式输出会让总耗时变短吗?

不会。总生成时间基本一样,流式只是把已经生成的片段提前给你,所以首字时间大幅缩短,整体结束时间差别不大。如果你的痛点是「等太久没反应」,流式有效;如果痛点是「总共就要很久」,得从模型和提示词长度上想办法。

SSE 和 WebSocket 该选哪个?

只是把模型生成的内容推到网页上,用 SSE 就够,实现简单、走普通 HTTP、断线重连也好写。需要用户边说话边回传、或者双方频繁互推的场景才轮到 WebSocket。别为了「看起来高级」上双向通道,多出来的状态管理是负担。

流式输出断流了怎么排查?

按顺序看:客户端有没有正确按行解析、代理或网关是不是开了缓冲、连接读取超时是不是设得太短、上游本身有没有中断。先直连绕开代理测一次,能定位是链路还是代码问题。更细的排查放到生产接入那篇里讲。

本文依据各平台公开文档与官方公告整理,只做中文归纳;具体做法、参数与限制以官方文档为准。