SSE流式输出实战:原理、代码与生产踩坑

作者:十万个为什么2026.11.17 03:45浏览量:0

简介:大模型逐字输出靠的是SSE。本文讲清它的报文格式,给出服务端与客户端的可运行代码,并说明Nginx缓冲、心跳、断连后中止上游请求等生产问题的处理方法,以及流式调用中的Token成本控制思路。读完即可自己搭建一套流式接口。

一句话说清SSE

SSE(Server-Sent Events)是一种构建在HTTP/1.1之上的服务端单向推送技术。它不是新协议,本质是一个普通的HTTP响应,Content-Type 设为 text/event-stream,服务端不关闭响应,而是持续把事件写入连接,客户端边接收边渲染。

和WebSocket相比,SSE只有”服务端到客户端”一个方向,协议更简单,实现成本更低。因为它走普通HTTP,多数情况下能穿过代理和网关,但代理需要关闭缓冲并放宽超时,否则流式效果会失效,这一点后面会展开。

为什么大模型普遍采用SSE

大模型是逐token生成答案的。如果等整段内容生成完再返回,用户要面对十几秒的空白。用SSE把每个增量片段立即推送出去,用户能更早看到第一个字。具体能缩短多少等待时间,取决于模型、网络和服务端的首包处理方式,需要在自己的环境中实测。

几种常见方案的对比如下:

方案 连接方式 通信方向 自动重连 浏览器原生支持 大模型适配度
短轮询 每次请求新建连接 客户端拉取 不需要 是 差,大量请求浪费
长轮询 连接挂起等待 客户端拉取 需自行实现 是 一般,逻辑复杂
WebSocket 一条TCP长连接 全双工 需自行实现 是 偏重,需额外握手协议
SSE 一条HTTP长连接 服务端推送 EventSource内置 EventSource 高

大模型对话的典型场景是:客户端提交一次完整的prompt,服务端流式返回答案。下行数据远多于上行数据,SSE的单向模型正好匹配,而且不需要WebSocket的协议升级、自定义心跳和状态管理。

SSE报文格式

SSE是纯文本协议。每个事件以一个空行结束,常用字段如下:

  1. event: token # 事件类型,省略时默认为 message
  2. id: 42 # 事件ID,断线重连时浏览器通过 Last-Event-ID 请求头带回
  3. retry: 3000 # 建议的重连间隔,单位毫秒
  4. data: 第一段内容
  5. data: 第二段内容 # 多行data会被客户端用 \n 拼接成一个值
  6. : ping # 以冒号开头的是注释,客户端忽略,常用作心跳
  7. data: [DONE] # OpenAI兼容接口的结束约定,告诉客户端可以关闭连接

有三个细节容易出错:

  • 字段名和值之间的冒号后面可以有空格,也可以没有。解析时应该取冒号后的部分并调用 trim(),兼容两种写法。
  • 多行data会被拼接。因此每个JSON对象必须压成一行,不能为了可读性换行。
  • [DONE] 不属于SSE规范。它是OpenAI兼容接口形成的事实约定,客户端需要专门识别它。

服务端实现

下面的示例用Express转发上游模型的流式响应。服务端原样转发上游的data行,客户端就只需要按一种数据结构解析。

  1. import express from 'express';
  2. const app = express();
  3. app.use(express.json());
  4. const UPSTREAM_URL = process.env.LLM_BASE_URL + '/v1/chat/completions';
  5. const API_KEY = process.env.LLM_API_KEY; // 密钥从环境变量读取,不写进代码
  6. const MODEL = process.env.LLM_MODEL;
  7. app.post('/stream', async (req, res) => {
  8. const { messages } = req.body;
  9. const ac = new AbortController();
  10. res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
  11. res.setHeader('Cache-Control', 'no-cache, no-transform');
  12. res.setHeader('Connection', 'keep-alive');
  13. res.setHeader('X-Accel-Buffering', 'no'); // 告诉Nginx关闭该响应的缓冲
  14. res.flushHeaders();
  15. // 心跳:防止网关因空闲超时断开连接
  16. const heartbeat = setInterval(() => res.write(': ping\n\n'), 15000);
  17. // 客户端断开时,中止上游请求,停止继续消耗token
  18. req.on('close', () => {
  19. clearInterval(heartbeat);
  20. ac.abort();
  21. });
  22. try {
  23. const upstream = await fetch(UPSTREAM_URL, {
  24. method: 'POST',
  25. headers: {
  26. 'Content-Type': 'application/json',
  27. Authorization: `Bearer ${API_KEY}`,
  28. },
  29. body: JSON.stringify({ model: MODEL, stream: true, messages }),
  30. signal: ac.signal,
  31. });
  32. if (!upstream.ok) throw new Error(`upstream status ${upstream.status}`);
  33. const reader = upstream.body.getReader();
  34. const decoder = new TextDecoder();
  35. let buffer = '';
  36. while (true) {
  37. const { done, value } = await reader.read();
  38. if (done) break;
  39. buffer += decoder.decode(value, { stream: true });
  40. const lines = buffer.split('\n');
  41. buffer = lines.pop(); // 最后一段可能被截断,留到下一轮拼接
  42. for (const line of lines) {
  43. if (!line.startsWith('data:')) continue;
  44. const payload = line.slice(5).trim();
  45. if (!payload) continue;
  46. res.write(`data: ${payload}\n\n`); // 原样转发,保持上游数据结构
  47. if (payload === '[DONE]') return res.end();
  48. }
  49. }
  50. res.end();
  51. } catch (err) {
  52. if (err.name !== 'AbortError' && !res.writableEnded) {
  53. res.write(`event: error\ndata: ${JSON.stringify({ message: '上游请求失败' })}\n\n`);
  54. res.end();
  55. }
  56. } finally {
  57. clearInterval(heartbeat);
  58. }
  59. });
  60. app.listen(3000);

这段代码做了几件事。它把上游按行切分,遇到不完整的行会留在缓冲区里。客户端断开时调用 ac.abort(),上游请求随之中止。[DONE] 原样发给客户端,客户端据此结束读取。

客户端实现

浏览器的 EventSource 只支持GET请求,而且不能自定义请求头。大模型接口通常需要POST传入messages,还要携带鉴权信息,所以实际项目中多用 fetch 配合 ReadableStream 手动解析:

  1. async function chatStream(messages, onDelta) {
  2. const resp = await fetch('/stream', {
  3. method: 'POST',
  4. headers: { 'Content-Type': 'application/json' },
  5. body: JSON.stringify({ messages }),
  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 lines = buffer.split('\n');
  16. buffer = lines.pop();
  17. for (const line of lines) {
  18. if (!line.startsWith('data:')) continue;
  19. const payload = line.slice(5).trim();
  20. if (payload === '[DONE]') return;
  21. const chunk = JSON.parse(payload);
  22. const delta = chunk.choices?.[0]?.delta?.content ?? '';
  23. if (delta) onDelta(delta);
  24. }
  25. }
  26. }
  27. // 使用示例
  28. let answer = '';
  29. await chatStream([{ role: 'user', content: '解释一下SSE' }], text => {
  30. answer += text;
  31. document.querySelector('#output').textContent = answer;
  32. });

fetch 方案不会自动重连。如果需要断线续传,要自己记录已收到的内容,并在服务端实现基于 Last-Event-ID 的恢复逻辑。

如果场景只是GET方式的进度推送,例如长任务状态或日志流,直接用 EventSource 更省事,它自带断线重连:

  1. const es = new EventSource('/api/task/progress');
  2. es.addEventListener('progress', e => update(JSON.parse(e.data)));
  3. es.onerror = () => console.log('连接断开,浏览器会自动重连');

重连时,浏览器会带上 Last-Event-ID 请求头,服务端需要根据它续发事件。

生产环境常见的五类问题

1. Nginx缓冲导致内容一次性返回

这是最常见的问题。反向代理默认会攒够一定数据再转发,流式输出就退化成了一次性返回。处理方法是在代理配置中关闭缓冲:

  1. location /stream {
  2. proxy_pass http://backend;
  3. proxy_http_version 1.1;
  4. proxy_set_header Connection '';
  5. proxy_buffering off; # 关闭代理缓冲
  6. proxy_cache off;
  7. chunked_transfer_encoding on;
  8. proxy_read_timeout 300s; # 超时要大于模型最长生成时间
  9. }

2. 中间层压缩

gzip压缩会引入缓冲。应当在流式接口上关闭压缩,或者确认压缩层不会缓冲SSE响应。服务端响应头中的 Cache-Control: no-transform 可以提示中间代理不要修改内容。

3. 空闲超时

模型思考或prompt较长时,首包可能超过10秒。服务端需要定期发送注释心跳(如示例中每15秒一次),同时把网关和负载均衡器的空闲超时调到60秒以上。

4. 客户端提前断开

用户关闭页面后,如果服务端不处理,上游模型会继续生成,token仍在计费。服务端应监听连接关闭事件,并中止上游请求,如本文服务端代码所示。

5. HTTP/1.1的连接数限制

浏览器对同一域名的HTTP/1.1连接数有上限,通常为6条。多个并发SSE会占满连接,导致其他请求排队。升级到HTTP/2后,多路复用可以显著缓解这个问题。如果链路上无法使用HTTP/2,就需要控制同一页面内的并发流数量。

Token成本怎么控制

开启 stream: true 不会改变计费规则。Token仍然按实际输入和实际输出结算,流式只是改变了返回的时机和分片方式,分片多不会多收费。具体计费规则以服务商文档为准。

真正影响成本的因素主要有三类:

  • 输出token通常是主要成本。 长回答应设置合理的 max_tokens 上限,避免模型输出冗长内容。
  • 失败重试可能重复计费。 客户端需要区分两种情况:网络中断导致的失败可以重试;已经生成部分答案的,应先判断已消耗的内容,再决定是否从头请求。
  • 不同模型的单价差异可能很大。 同一个任务,选用不同档位的模型,成本可能相差数倍。正式上线前,建议用真实样本分别测试各模型的效果、延迟和单价,确认目标模型支持流式输出,再决定使用哪一个。

如果团队需要同时接入多家模型,可以在统一的接入层中处理流式解析、错误重试和调用统计。这样每个模型不必单独维护一套适配代码。

选型建议

  • 只需要服务端向客户端单向推送,例如通知、日志、进度、AI逐字输出:选择SSE,实现成本最低。
  • 需要客户端频繁上行,实现双向实时交互,例如协同编辑、在线游戏、语音通话:选择WebSocket。
  • 已有WebSocket服务,只想增加AI对话的流式输出:不必改造现有通道,单独新增一个SSE端点即可,两者可以共存。

SSE本身的技术门槛不高,真正的难点在工程细节:代理缓冲、超时配置、断连清理、分片解析的边界处理。把这几处处理好,流式输出就能稳定运行在生产环境中。