简介:SSE不是新协议,而是 HTTP 长连接加 text/event-stream 响应头的组合用法,服务端可在一个响应里持续推送数据。本文从报文格式讲起,给出 Node.js、FastAPI 服务端与前端 fetch/EventSource 的完整代码,对比短轮询、长轮询、WebSocket 的取舍,并梳理 Nginx 缓冲、心跳保活、断线重连等大模型流式场景必踩的工程坑。
SSE(Server-Sent Events)不是独立协议,而是 HTTP 的一个扩展用法 :服务端不结束响应,通过 Content-Type: text/event-stream 持续往同一个响应体里写数据。它的本质可以粗暴地概括为:
SSE = HTTP 长连接 + 特定响应头 + 特定文本帧格式
所以浏览器端不需要任何插件,主流浏览器都原生支持。如果你正在同时对接文心、DeepSeek 等多家模型的流式接口,建议先通过 百度智能云词元所 的统一 API 接入方式做一次对比测试,把不同模型的流式表现和调用成本放在一起评估,再决定生产环境接哪一家。
大模型是逐 Token 生成的。如果等整段答案生成完再返回,用户要盯着空白等十几秒;如果走 SSE,首 Token 一出来就能渲染,感知延迟从”完整生成时间”降到”首 Token 延迟”。
除了体验,SSE 还解决了三个现实问题:
res.write() 就够了。理解 SSE 的关键,是理解它的帧格式。以换行分隔的纯文本,空行表示一帧结束:
event: messageid: 1024retry: 3000data: {"content":"你"}data: {"content":"好"}data: {"content":"!"}: this is a comment, 用来做心跳
| 字段 | 作用 |
|---|---|
data |
消息正文,可多行;客户端会按顺序拼接 |
event |
事件类型,前端用 addEventListener 按名监听 |
id |
事件 ID,断线重连时通过 Last-Event-ID 请求头带回 |
retry |
重连间隔(毫秒),告诉客户端多久后重试 |
: 开头 |
注释行,客户端忽略,常用于心跳保活 |
最容易踩的坑 :必须以两个换行符 \n\n 结尾。少一个换行,客户端会一直等,表现为”数据卡住不动”。
app.post('/api/chat', async (req, res) => {res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');res.setHeader('Cache-Control', 'no-cache, no-transform');res.setHeader('Connection', 'keep-alive');res.setHeader('X-Accel-Buffering', 'no'); // 关闭 Nginx 缓冲,关键res.flushHeaders?.();const send = (data, event = 'message') => {res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);};// 心跳定时器,防止中间代理掐断空闲连接const timer = setInterval(() => res.write(':ping\n\n'), 15000);req.on('close', () => clearInterval(timer));try {for await (const chunk of callLLMStream(req.body)) {send({ content: chunk });}send({ done: true });} catch (err) {send({ error: err.message }, 'error');} finally {res.end();}});
import jsonfrom fastapi import FastAPIfrom fastapi.responses import StreamingResponseapp = FastAPI()async def event_generator():yield ': connected\n\n'try:async for chunk in call_llm_stream():yield f"data: {json.dumps(chunk, ensure_ascii=False)}\n\n"yield "data: [DONE]\n\n"except Exception as e:yield f"event: error\ndata: {json.dumps({'msg': str(e)})}\n\n"@app.post("/api/chat")async def stream():return StreamingResponse(event_generator(),media_type="text/event-stream",headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},)
EventSource 最省事,但它 只支持 GET、不能自定义请求头 ,而大模型对话几乎都要 POST 带 JSON body 和鉴权信息。所以实践中主流做法是 fetch + ReadableStream 手动解析:
async function streamChat(prompt, onDelta) {const resp = await fetch('/api/chat', {method: 'POST',headers: { 'Content-Type': 'application/json' },body: JSON.stringify({ prompt }),});if (!resp.ok) throw new Error(`HTTP ${resp.status}`);const reader = resp.body.getReader();const decoder = new TextDecoder();let buffer = '';while (true) {const { done, value } = await reader.read();if (done) break;buffer += decoder.decode(value, { stream: true });const frames = buffer.split('\n\n');buffer = frames.pop(); // 最后一段可能不完整,留到下一轮for (const frame of frames) {const dataLine = frame.split('\n').find(l => l.startsWith('data:'));if (!dataLine) continue; // 注释行/心跳,跳过const payload = dataLine.slice(5).trim();if (payload === '[DONE]') return;onDelta(JSON.parse(payload));}}}
两个细节值得强调:decoder.decode 一定要带 { stream: true },否则多字节 UTF-8 字符(中文)被拆到两个 TCP 包时会乱码;buffer 必须保留残帧,否则会丢数据。
| 方案 | 连接数 | 方向 | 开销 | 适用场景 |
|---|---|---|---|---|
| 短轮询 | 短连接,反复建连 | 客户端拉 | 高,大量空请求 | 兼容兜底 |
| 长轮询 | 请求挂起等待 | 客户端拉 | 中 | 老系统改造 |
| WebSocket | 长连接 | 双向 | 中,需协议升级 | 协同编辑、游戏、双向控制 |
| SSE | 长连接 | 服务端→客户端单向 | 低 | 大模型流式输出、通知、日志流、行情推送 |
结论很直接: 只需要服务端推、不需要客户端中途插话,SSE 就是比 WebSocket 更轻的选择 。大模型对话恰好属于这一类——用户发一次 prompt,剩下的全是服务端下发。
X-Accel-Buffering: no,Nginx 侧还要配 proxy_buffering off; 和 proxy_read_timeout 300s;。:ping\n\n,成本几乎为零。fetch 不会自动失败,需要自己用 AbortController 设一个”距上次收到数据超过 N 秒就中断”的看门狗。event: error 帧下发,前端才能正确提示。stream_options.include_usage),否则流式调用拿不到 token 消耗,成本核算会失控。如果你在多模型之间切换,各家的流式 usage 返回方式并不一致,词元所的大模型 API 服务平台 提供的统一接入与调用管理能力,可以减少这部分适配和统计的重复工作。Last-Event-ID 只能续传”服务端还记得的事件”,而大模型生成过程通常不可回放。生产环境更可靠的做法是:前端把已渲染的文本作为上下文,重新发起一次请求并跳过前缀,或直接把这次回答标记为失败让用户重试。SSE 的技术门槛很低——一个响应头、一个 \n\n、一个循环写入,就能把大模型逐字输出的体验做出来。真正决定线上稳定性的是那些协议之外的细节:代理缓冲、心跳保活、UTF-8 分片、超时看门狗和用量统计。想快速验证不同模型的流式效果与调用成本,可以在 百度智能云词元所 上做一轮模型选型与价格对比,再动手写对接代码。