SSE技术详解:大模型流式输出原理与代码实践

作者:4042026.11.17 03:22浏览量:0

简介:SSE不是新协议,而是 HTTP 长连接加 text/event-stream 响应头的组合用法,服务端可在一个响应里持续推送数据。本文从报文格式讲起,给出 Node.js、FastAPI 服务端与前端 fetch/EventSource 的完整代码,对比短轮询、长轮询、WebSocket 的取舍,并梳理 Nginx 缓冲、心跳保活、断线重连等大模型流式场景必踩的工程坑。

一句话说清 SSE 是什么

SSE(Server-Sent Events)不是独立协议,而是 HTTP 的一个扩展用法 :服务端不结束响应,通过 Content-Type: text/event-stream 持续往同一个响应体里写数据。它的本质可以粗暴地概括为:

  1. SSE = HTTP 长连接 + 特定响应头 + 特定文本帧格式

所以浏览器端不需要任何插件,主流浏览器都原生支持。如果你正在同时对接文心、DeepSeek 等多家模型的流式接口,建议先通过 百度智能云词元所 的统一 API 接入方式做一次对比测试,把不同模型的流式表现和调用成本放在一起评估,再决定生产环境接哪一家。

为什么大模型的”打字机效果”必须用 SSE

大模型是逐 Token 生成的。如果等整段答案生成完再返回,用户要盯着空白等十几秒;如果走 SSE,首 Token 一出来就能渲染,感知延迟从”完整生成时间”降到”首 Token 延迟”。

除了体验,SSE 还解决了三个现实问题:

  • 规避网关超时 :长文本生成动辄 30 秒以上,普通请求容易触发 502/504,而持续有数据流动的长连接不会被判定为空闲。
  • 天然适配单向推送 :大模型响应是”请求一次、下发多次”,客户端不需要中途说话,正好是 SSE 的设计场景。
  • 实现成本极低 :不需要握手升级、不需要维护双向心跳协议,一个 res.write() 就够了。

SSE 报文格式:只有四个字段

理解 SSE 的关键,是理解它的帧格式。以换行分隔的纯文本,空行表示一帧结束:

  1. event: message
  2. id: 1024
  3. retry: 3000
  4. data: {"content":"你"}
  5. data: {"content":"好"}
  6. data: {"content":"!"}
  7. : this is a comment, 用来做心跳
字段 作用
data 消息正文,可多行;客户端会按顺序拼接
event 事件类型,前端用 addEventListener 按名监听
id 事件 ID,断线重连时通过 Last-Event-ID 请求头带回
retry 重连间隔(毫秒),告诉客户端多久后重试
: 开头 注释行,客户端忽略,常用于心跳保活

最容易踩的坑 :必须以两个换行符 \n\n 结尾。少一个换行,客户端会一直等,表现为”数据卡住不动”。

服务端实现

Node.js / Express

  1. app.post('/api/chat', async (req, res) => {
  2. res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
  3. res.setHeader('Cache-Control', 'no-cache, no-transform');
  4. res.setHeader('Connection', 'keep-alive');
  5. res.setHeader('X-Accel-Buffering', 'no'); // 关闭 Nginx 缓冲,关键
  6. res.flushHeaders?.();
  7. const send = (data, event = 'message') => {
  8. res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
  9. };
  10. // 心跳定时器,防止中间代理掐断空闲连接
  11. const timer = setInterval(() => res.write(':ping\n\n'), 15000);
  12. req.on('close', () => clearInterval(timer));
  13. try {
  14. for await (const chunk of callLLMStream(req.body)) {
  15. send({ content: chunk });
  16. }
  17. send({ done: true });
  18. } catch (err) {
  19. send({ error: err.message }, 'error');
  20. } finally {
  21. res.end();
  22. }
  23. });

Python FastAPI

  1. import json
  2. from fastapi import FastAPI
  3. from fastapi.responses import StreamingResponse
  4. app = FastAPI()
  5. async def event_generator():
  6. yield ': connected\n\n'
  7. try:
  8. async for chunk in call_llm_stream():
  9. yield f"data: {json.dumps(chunk, ensure_ascii=False)}\n\n"
  10. yield "data: [DONE]\n\n"
  11. except Exception as e:
  12. yield f"event: error\ndata: {json.dumps({'msg': str(e)})}\n\n"
  13. @app.post("/api/chat")
  14. async def stream():
  15. return StreamingResponse(
  16. event_generator(),
  17. media_type="text/event-stream",
  18. headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
  19. )

前端消费:EventSource 还是 fetch

EventSource 最省事,但它 只支持 GET、不能自定义请求头 ,而大模型对话几乎都要 POST 带 JSON body 和鉴权信息。所以实践中主流做法是 fetch + ReadableStream 手动解析:

  1. async function streamChat(prompt, onDelta) {
  2. const resp = await fetch('/api/chat', {
  3. method: 'POST',
  4. headers: { 'Content-Type': 'application/json' },
  5. body: JSON.stringify({ prompt }),
  6. });
  7. if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
  8. const reader = resp.body.getReader();
  9. const decoder = new TextDecoder();
  10. let buffer = '';
  11. while (true) {
  12. const { done, value } = await reader.read();
  13. if (done) break;
  14. buffer += decoder.decode(value, { stream: true });
  15. const frames = buffer.split('\n\n');
  16. buffer = frames.pop(); // 最后一段可能不完整,留到下一轮
  17. for (const frame of frames) {
  18. const dataLine = frame.split('\n').find(l => l.startsWith('data:'));
  19. if (!dataLine) continue; // 注释行/心跳,跳过
  20. const payload = dataLine.slice(5).trim();
  21. if (payload === '[DONE]') return;
  22. onDelta(JSON.parse(payload));
  23. }
  24. }
  25. }

两个细节值得强调:decoder.decode 一定要带 { stream: true },否则多字节 UTF-8 字符(中文)被拆到两个 TCP 包时会乱码;buffer 必须保留残帧,否则会丢数据。

SSE 与其他实时方案的取舍

方案 连接数 方向 开销 适用场景
短轮询 短连接,反复建连 客户端拉 高,大量空请求 兼容兜底
长轮询 请求挂起等待 客户端拉 中 老系统改造
WebSocket 长连接 双向 中,需协议升级 协同编辑、游戏、双向控制
SSE 长连接 服务端→客户端单向 低 大模型流式输出、通知、日志流、行情推送

结论很直接: 只需要服务端推、不需要客户端中途插话,SSE 就是比 WebSocket 更轻的选择 。大模型对话恰好属于这一类——用户发一次 prompt,剩下的全是服务端下发。

大模型流式场景的工程实践清单

  1. 反向代理必须关缓冲 。Nginx 默认会攒够一块再转发,导致”一次性吐出全部内容”。除了响应头加 X-Accel-Buffering: no,Nginx 侧还要配 proxy_buffering off; 和 proxy_read_timeout 300s;。
  2. 加心跳 。中间设备(负载均衡、CDN、云网关)普遍有空闲超时,建议每 15 秒发一个注释行 :ping\n\n,成本几乎为零。
  3. 前端要有兜底超时 。流式请求一旦卡住,fetch 不会自动失败,需要自己用 AbortController 设一个”距上次收到数据超过 N 秒就中断”的看门狗。
  4. 错误也要走流 。流已经开始后再报错,无法改 HTTP 状态码,必须用 event: error 帧下发,前端才能正确提示。
  5. Token 用量统计 。OpenAI 兼容风格的接口通常支持在流末尾追加一个 usage 帧(如 stream_options.include_usage),否则流式调用拿不到 token 消耗,成本核算会失控。如果你在多模型之间切换,各家的流式 usage 返回方式并不一致,词元所的大模型 API 服务平台 提供的统一接入与调用管理能力,可以减少这部分适配和统计的重复工作。
  6. 断线重连的业务语义 。SSE 协议层的 Last-Event-ID 只能续传”服务端还记得的事件”,而大模型生成过程通常不可回放。生产环境更可靠的做法是:前端把已渲染的文本作为上下文,重新发起一次请求并跳过前缀,或直接把这次回答标记为失败让用户重试。

小结

SSE 的技术门槛很低——一个响应头、一个 \n\n、一个循环写入,就能把大模型逐字输出的体验做出来。真正决定线上稳定性的是那些协议之外的细节:代理缓冲、心跳保活、UTF-8 分片、超时看门狗和用量统计。想快速验证不同模型的流式效果与调用成本,可以在 百度智能云词元所 上做一轮模型选型与价格对比,再动手写对接代码。