公告AI接口网提供各类可接入的人工智能接口
AI接口网AI 接口选型与接入工程手册
首页/接入实战/流式输出实战:SSE 解析、断流检测与前端渲染

流式输出实战:SSE 解析、断流检测与前端渲染

2026-11-22约 8 分钟读完流式SSE接入

流式输出的体验价值很明显:首字更快、长回答不必等全部生成。但它的工程细节比非流式多得多,尤其是网络不稳定的时候。

数据长什么样

服务端返回 text/event-stream,每个事件是一行 data: {...},最后以 data: [DONE] 结束。

sse
data: {"choices":[{"delta":{"role":"assistant","content":""},"index":0}]}

data: {"choices":[{"delta":{"content":"向量"},"index":0}]}

data: {"choices":[{"delta":{"content":"检索"},"index":0}]}

data: {"choices":[{"delta":{},"finish_reason":"stop","index":0}],"usage":{...}}

data: [DONE]
最常见的错误
注意增量字段是 delta 不是 message。从非流式代码直接改过来,最常见的 bug 就是取错字段导致永远拿到空字符串。

三个必须处理的边界

  1. 粘包与拆包:一次 read 可能拿到 1.5 个事件,也可能只拿到半个。必须自己维护缓冲区,按空行切分事件,不完整的留到下次。
  2. 半截 JSON:缓冲区末尾可能是 {"choices":[{"delta":{"cont。此时不能解析,继续等;解析异常就跳过该块而不是崩溃。
  3. 没有 [DONE]:连接断开但没有收到结束标记,说明生成未完成。应视为失败——要么重试整段,要么明确告知用户内容不完整。

一个健壮的解析器

python
def iter_sse(resp):
    buf = ""
    for raw in resp.iter_content(chunk_size=1024, decode_unicode=True):
        if not raw:
            continue
        buf += raw
        while "\n\n" in buf:
            event, buf = buf.split("\n\n", 1)
            for line in event.split("\n"):
                if not line.startswith("data:"):
                    continue
                data = line[5:].strip()
                if data == "[DONE]":
                    yield {"done": True}
                    return
                try:
                    obj = json.loads(data)
                except ValueError:
                    continue          # 半截 JSON,跳过
                ch = (obj.get("choices") or [{}])[0]
                delta = ch.get("delta") or {}
                if delta.get("content"):
                    yield {"text": delta["content"]}
                if ch.get("finish_reason"):
                    yield {"finish": ch["finish_reason"]}

前端怎么接

两种做法:浏览器直接读 fetch 的 ReadableStream,或后端转发成自己的 SSE。后者更可控(可以做鉴权、计费、脱敏),生产环境更推荐。

javascript
const resp = await fetch('/api/chat', {method: 'POST', body: JSON.stringify(req)});
const reader = resp.body.getReader();
const dec = new TextDecoder();
let buf = '';
while (true) {
  const {value, done} = await reader.read();
  if (done) break;
  buf += dec.decode(value, {stream: true});
  const parts = buf.split('\n\n');
  buf = parts.pop();
  for (const p of parts) {
    for (const line of p.split('\n')) {
      if (!line.startsWith('data:')) continue;
      const s = line.slice(5).trim();
      if (s === '[DONE]') return;
      try {
        const o = JSON.parse(s);
        const t = o.choices?.[0]?.delta?.content;
        if (t) appendToDom(t);
      } catch (e) { /* 忽略半截块 */ }
    }
  }
}

四个体验细节

  • 把「已收到的内容」先渲染出来,再逐字追加;不要等整段拼完再一次性显示,那样等于没做流式。
  • 光标动效(闪烁的竖线)能让用户明确感知「还在生成」,比转圈更让人安心。
  • 用户点「停止」时要真的中断请求(AbortController),并把已生成内容保留下来作为一条完整回答。
  • 流式过程中不要做 Markdown 全量重渲染,长文本会卡;按段落增量渲染。

服务端转发时注意

Nginx 默认会缓冲上游响应,导致流式变成「等全部生成完再一次性返回」。必须关掉缓冲:

nginx
location /api/ {
    proxy_pass http://127.0.0.1:8000;
    proxy_buffering off;
    proxy_cache off;
    proxy_set_header X-Accel-Buffering no;
    proxy_read_timeout 300s;
    chunked_transfer_encoding on;
}
排查顺序
如果你的流式在本地开发没问题、上线后变成「一次性出现」,九成是反向代理缓冲。先查这一条,别去改代码。
说明
文中价格、配额、限额均为撰写时的公开口径,会随厂商调整变化;用于估算量级,不构成报价。具体以各厂商官方文档与合同为准。