不使用流式输出时,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
- **会缓冲的代理。**Nginx 和一些 CDN 会缓冲响应,于是客户端一下子收到全部内容。为流式输出的路由关闭代理缓冲。
- **不检查
[DONE]。**连接中断看起来就像一个较短的回答。把缺少[DONE]视为不完整,并按错误指南所述记录X-Request-ID。 - **在流的中途重试。**响应体开始到达后,SDK 就不会再重试。重试就是一个新请求,在按量付费下也就是一笔新账单。
- **忽略
finish_reason: length。**在 DeepSeek V4.1 Flash 这类思考模型上,思考过程计入 max_tokens,所以上限太小时,流可能在出现任何可见文本之前就停止了。参见思考 token 的成本。 - **行切分出错。**如果你手动解析 SSE,要先缓冲字节,直到看到空行为止。一次 TCP 读取可能在某个 JSON 分块的中间结束。
BroadNet Inference 适合什么场景
BroadNet Inference 使用标准的 OpenAI 兼容流式输出格式,所以 Python 和 Node SDK 无需修改就能解析。模型报告时,最后一个分块中的用量包含缓存 token 和思考 token。它的文档表示,在投入生产之前仍应逐个模型验证流式输出,所以请在你实际上线的模型上运行上面的代码。如果你最关心第一个 token 多快到达,接下来请读 TTFT 与吞吐量。如果你需要基于 WebSocket 的实时语音,这个 API 并不是为此设计的;它提供的是 chat completions 和文件转写。
