BroadRouter

大模型流式输出详解:SSE 分块、delta、用量与取消

BroadNet Inference 团队 · 阅读约 4 分钟 · 发布于 · 更新于

大模型 API 以 Server-Sent Events(SSE)的形式流式返回 chat completion:每个 data 行包含一个 JSON 分块,其中 choices[0].delta 携带下一段文本。把各个 delta 拼接起来,遇到 data: [DONE] 时停止;把 stream_options 的 include_usage 设为 true,就能在最后一个 choices 为空的分块中拿到 token 用量。要取消,关闭连接即可。

不使用流式输出时,chat completion 要等整个回答写完才会返回。一个 600 token 的回复,在 约每秒 100 个 token 的速度下,意味着好几秒的静默等待。使用流式输出,模型一写出第一个字,用户就能看到。本文介绍传输层上实际传输的内容、如何解析、如何从流中取得 token 用量,以及如何干净地停止。BroadNet 相关规则的简要版本,见流式输出参考指南。

SSE 流在传输层是什么样子?

Server-Sent Events 是一个 Content-Type: text/event-stream 的普通 HTTP 响应。服务器保持连接打开,不断写入事件。每个事件由一行或多行 data: 加一个空行组成。OpenAI 兼容 API 在每个事件中放一个 JSON 分块,最后以字面量 [DONE] 结束:

data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}],"usage":null}

data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"One, "},"finish_reason":null}],"usage":null}

data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"two, three."},"finish_reason":"stop"}],"usage":null}

data: {"id":"c1","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":14,"completion_tokens":6,"total_tokens":20}}

data: [DONE]

上面的结构只是示意,并做了精简。真实的分块还带有 model 和 created,思考模型还可能在用量中报告思考 token。

分块里有什么?

字段 位置 含义
choices[0].delta.role 第一个分块 通常是 assistant。只发送一次。
choices[0].delta.content 大多数分块 下一段文本。可能为空。
choices[0].delta.tool_calls 工具调用 函数名和 JSON 参数的片段,按 index 拼接。
choices[0].finish_reason 最后一个内容分块 stop、length 或 tool_calls。在此之前为 null。
usage 最后一个分块(如有请求) 整个请求的总计。其他地方都是 null。

关键在于增量(delta),而不是快照。每个分块只包含新增的内容。你要按顺序把这些片段拼起来,还原整条消息。工具调用也以同样的方式流式传输:参数以字符串片段的形式到达,直到最后一个片段到达之前都不是合法的 JSON,所以要等 finish_reason 为 tool_calls 之后再解析。

怎么从流式输出中拿到 token 用量?

非流式响应总是包含 usage。流式输出则不会,除非你主动请求。设置 stream_options: {"include_usage": true},服务器就会在 [DONE] 之前多发一个分块。这个分块包含总计,并且 choices 数组为空。在 BroadNet Inference 上,模型报告时,用量中还可能包含 prompt_tokens_details.cached_tokens 和 completion_tokens_details.reasoning_tokens,这正是成本记录所需要的。

常见的 bug:在每个分块上都读取 chunk.choices[0] 的代码,遇到用量分块时会抛出索引错误。先检查 choices。

Python:流式输出、收集用量、取消

import os
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

stream = client.chat.completions.create(
    model="broadnet/deepseek-v4.1-flash",  # DeepSeek V4.1 Flash, a reasoning model
    messages=[{"role": "user", "content": "Explain SSE in three sentences."}],
    stream=True,
    stream_options={"include_usage": True},
    max_tokens=2000,  # reasoning counts toward this limit
)

def user_pressed_stop():  # replace with your own condition
    return False

parts, usage, finish = [], None, None
try:
    for chunk in stream:
        if chunk.choices:
            choice = chunk.choices[0]
            if choice.delta.content:
                parts.append(choice.delta.content)
                print(choice.delta.content, end="", flush=True)
            if choice.finish_reason:
                finish = choice.finish_reason
        if chunk.usage:
            usage = chunk.usage
        if user_pressed_stop():  # your own condition
            break
finally:
    stream.close()  # closes the HTTP connection

text = "".join(parts)

只用 break 会停止读取,但套接字会一直打开,直到被垃圾回收。要显式关闭,让服务器察觉到断开。

Node:用 AbortController 流式输出

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://inference.broadnet.ai/v1", apiKey: process.env.BROADNET_API_KEY });
const controller = new AbortController();
setTimeout(() => controller.abort(), 30_000); // hard stop after 30 s

const stream = await client.chat.completions.create(
  {
    model: "broadnet/deepseek-v4.1-flash",
    messages: [{ role: "user", content: "Explain SSE in three sentences." }],
    stream: true,
    stream_options: { include_usage: true },
  },
  { signal: controller.signal },
);

let text = "";
for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) text += delta;
  if (chunk.usage) console.log(chunk.usage);
}

openai-node README 说明了 signal 选项,而且在响应体仍在读取时也有效。在 Web 服务器中,把 controller.abort() 绑定到客户端请求的 close 事件上,这样用户离开页面时生成也会随之停止。更多配置见 Node SDK 指南。

curl:查看原始事件

curl -N https://inference.broadnet.ai/v1/chat/completions \
  -H "Authorization: Bearer $BROADNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"broadnet/gemma-4-26b-a4b","stream":true,"stream_options":{"include_usage":true},"messages":[{"role":"user","content":"Count to five."}]}'

-N 关闭输出缓冲,事件一到就打印出来。按 Ctrl+C 取消,这会关闭连接。API 请求构建器可以为任意模型和 base URL 生成这个请求,以及对应的 Python 和 Node 版本。

怎么取消流式输出?要花多少钱?

在 SSE 中,取消就是关闭连接,没有专门的“停止”消息。之后会发生什么取决于服务器:表现良好的服务器会察觉到套接字已关闭,并停止生成。在那之前生成的 token 都是实打实的计算。BroadNet 的 API 参考没有说明被取消的流如何计费,所以在按量付费时,请按“断开前生成的 token 都会计费”来规划,并核对你的用量记录。在固定价格套餐上,取消的流不会产生额外费用,但只有服务器停止生成后,会话才会被释放。

需要检查的五个流式输出 bug

  1. **会缓冲的代理。**Nginx 和一些 CDN 会缓冲响应,于是客户端一下子收到全部内容。为流式输出的路由关闭代理缓冲。
  2. **不检查 [DONE]。**连接中断看起来就像一个较短的回答。把缺少 [DONE] 视为不完整,并按错误指南所述记录 X-Request-ID。
  3. **在流的中途重试。**响应体开始到达后,SDK 就不会再重试。重试就是一个新请求,在按量付费下也就是一笔新账单。
  4. **忽略 finish_reason: length。**在 DeepSeek V4.1 Flash 这类思考模型上,思考过程计入 max_tokens,所以上限太小时,流可能在出现任何可见文本之前就停止了。参见思考 token 的成本。
  5. **行切分出错。**如果你手动解析 SSE,要先缓冲字节,直到看到空行为止。一次 TCP 读取可能在某个 JSON 分块的中间结束。

BroadNet Inference 适合什么场景

BroadNet Inference 使用标准的 OpenAI 兼容流式输出格式,所以 Python 和 Node SDK 无需修改就能解析。模型报告时,最后一个分块中的用量包含缓存 token 和思考 token。它的文档表示,在投入生产之前仍应逐个模型验证流式输出,所以请在你实际上线的模型上运行上面的代码。如果你最关心第一个 token 多快到达,接下来请读 TTFT 与吞吐量。如果你需要基于 WebSocket 的实时语音,这个 API 并不是为此设计的;它提供的是 chat completions 和文件转写。

常见问题

大模型流式输出用 SSE 和 WebSocket 有什么区别?

SSE 是单向的,从服务器到客户端,走的是普通的 HTTP 响应。chat completion 只需要这些,所以 OpenAI 兼容 API 都用 SSE。WebSocket 是双向的,需要协议升级;它用于实时语音,而不是 chat completions。

为什么流式分块里的 usage 是 null?

只有你请求时才会发送用量。加上 stream_options,并把 include_usage 设为 true。之后除最后一个分块外,所有分块的 usage 都是 null,最后一个分块携带总计,choices 列表为空。

取消流式输出还会计费吗?

各服务商不同,很多都没有在文档中说明。请假设服务器在察觉连接关闭之前生成的 token 会被计费。记录 X-Request-ID,并与你的用量记录核对。

怎么判断流式输出是正常结束的?

你收到了 data: [DONE],并且最后一个内容分块带有 stop 之类的 finish_reason。finish_reason 为 length 表示回答被 max_tokens 截断了。没有 [DONE] 则说明连接中断了。

流式输出能让模型变快吗?

不能。总的生成时间是一样的。流式输出缩短的是用户看到第一个字之前的等待时间,这正是聊天界面让人感觉很快的原因。

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