BroadRouter
开始使用

SSE(服务器发送事件,Server-sent events)

更新于

SSE(服务器发送事件,Server-sent events)是一项 Web 标准,让服务器通过一个内容类型为 text/event-stream 的长连接 HTTP 响应,向客户端推送一连串文本事件。每个事件由一行或多行字段(如 data:)组成,以一个空行结束。

又称: 服务器发送事件、服务端推送事件、事件流、SSE 流式输出、SSE、server-sent events、text/event-stream、event stream、EventSource

几乎每一条流式返回的大模型回复,底下都是 SSE 这种纯文本分帧格式。了解这个格式,在没有 SDK 可用或流出问题时会很有帮助。

工作原理

格式由 WHATWG HTML 标准定义。响应的 MIME 类型是 text/event-stream,编码始终是 UTF-8。正文由一行行 field: value 组成:

: keep-alive comment, ignored by clients

event: update
id: 42
data: first line
data: second line

data: {"choices":[{"delta":{"content":"Hi"}}]}

data: [DONE]

关键的解析规则:

  • 空行触发事件派发。 在空行到来之前,客户端一直缓冲。
  • 多行 data: 用换行符拼接成一条消息。
  • 以冒号开头的行是注释。 服务器发送注释来保持空闲连接不断开。
  • 冒号后的一个空格会被去掉。 行尾可以是 CRLF、LF 或 CR。
  • event、id 和 retry 分别设置事件类型、最后一个事件 ID 和以毫秒计的重连延迟。

网络读取和事件边界并不对齐。一次读取可能只拿到半个事件,也可能拿到三个,所以解析器必须缓冲字节、按空行切分,而不是按每次读取来切。

断线重连、代理与 [DONE]

标准为浏览器内置了恢复机制:连接断开后,EventSource 会重新连接并发送 Last-Event-ID 请求头,服务器可以用 HTTP 204 让它停止重试。规范还提醒,“legacy proxy servers”(译文:老旧的代理服务器)可能会在较短的超时后断开 HTTP 连接,建议 “every 15 seconds or so”(译文:大约每 15 秒)发送一行注释。

大模型 API 用到的部分更少。OpenAI 的 Chat Completions 流只发送 data: 行,并以 data: [DONE] 结束,这是该 API 的约定,而不是 SSE 的规定。流里没有可以用来续传的事件 ID,所以断开的流无法接着读;重试就是一个新的请求。流式输出的整体介绍以及它在首 token 延迟上的好处,见那一页。

在 BroadNet Inference 上

BroadNet 的文档要求设置 stream=true,并 “read Server-Sent Events until the literal data: [DONE] marker”(译文:读取服务器发送事件,直到出现字面的 data: [DONE] 标记)。如果连接在此之前结束,请把响应视为不完整,记录 X-Request-ID 响应头,再决定发起新的推理请求是否安全。加上 stream_options: {"include_usage": true} 后,用量信息会在最后一个分块中返回。文档的 curl 示例使用了 -N,让 curl 不做缓冲。一个流在结束前会一直占用一个并发名额:按量付费密钥为 4,按小时密钥为一个。文档要求在上生产之前逐个模型验证流式输出。各 SDK 的代码见流式输出指南,分块内容的解释见大模型流式输出详解。

常见问题

能用浏览器的 EventSource API 调用大模型 API 吗?

通常不能直接用。规范中的 EventSource 构造函数只接受一个 URL 和一个 withCredentials 标志,无法发送 POST 请求体或 Authorization 请求头。请用 fetch 自己解析流,或者使用 SDK。

“data: [DONE]” 是什么意思?

它不属于 SSE 标准。OpenAI 风格的 API 会把字面上的 “data: [DONE]” 这一行作为最后一个事件发送,表示回复已经完整结束。

为什么我的流是一次性全部到达的?

服务器和你的代码之间有某个环节在缓冲响应,比如反向代理、Web 框架,或者没加 -N 的 curl。请为这条路由关闭缓冲。

以 Markdown 格式阅读问 ChatGPT问 Claude问 Perplexity