BroadRouter

对话补全的流式输出,以及连接中断的处理

更新于

在 /v1/chat/completions 上把 stream 设为 true,然后一直读取 Server-Sent Events,直到出现字面上的 data: [DONE] 标志。加上 stream_options 的 include_usage,就能在最后一个数据块里拿到 token 数。如果连接在 [DONE] 之前断开,请把回答视为不完整,并记录 X-Request-ID。

流式输出让智能体或聊天界面在回答生成的同时就把它显示出来。BroadNet Inference 使用标准的 chat completions 流式格式,所以 OpenAI Python SDK 和 OpenAI Node SDK 会替你完成解析。

用 curl

curl -N -D stream-headers.txt 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 from one to three."}]}'

-N 关闭 curl 的缓冲,-D 保存响应头,其中包括 X-Request-ID。

流是什么样子的?

响应是一个 Server-Sent Events 流。按照 WHATWG HTML 标准,每个事件由一行或多行 data: 加一个空行组成;以冒号开头的行是注释,可以忽略。每一行 data: 包含一个 JSON 数据块,文本出现在 choices[0].delta.content 中。

规则

  1. 一直读取事件,直到出现字面上的 data: [DONE] 这一行,然后关闭读取器。
  2. 使用 stream_options: {"include_usage": true} 时,在 [DONE] 之前会多来一个数据块。它带有整个请求的 usage,以及一个空的 choices 列表,所以在按下标访问 choices 之前要先检查它。
  3. 当模型报告这些字段时,usage 中会包含 completion_tokens_details.reasoning_tokens(DeepSeek V4.1 Flash、GLM 5.3 和 Qwen3.8 27B 会先思考)和 prompt_tokens_details.cached_tokens。缓存 token 按较低的缓存输入价计费。

用 Python SDK

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/gemma-4-26b-a4b",
    messages=[{"role": "user", "content": "Count from one to three."}],
    stream=True,
    stream_options={"include_usage": True},
)
usage = None
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:
        usage = chunk.usage
print()
print(usage)  # None means the stream ended before the usage chunk

SDK 会替你读到 [DONE] 为止。最后打印出的 usage 如果是 None,说明流在 usage 数据块到达之前就结束了。OpenAI Node SDK 指南展示了同样循环的 JavaScript 写法。

流提前结束时

如果连接在 [DONE] 之前关闭,回答就是不完整的。BroadNet 的建议是:

  • 记录 X-Request-ID;
  • 判断你的应用能否安全地发起一个新请求。重试是一次新的推理,在按量付费下会再次计费。

对于使用不限量套餐的智能体,重试不会产生额外费用,但在运行期间仍会占用会话。

BroadNet 的文档指出,在生产环境中依赖流式输出之前,仍需要按模型进行发布验证,所以请在你实际上线的模型上测试。

故障排查

  • 所有内容都在最后才打印出来。 curl 需要加 -N。如果前面有你自己的代理,请对 text/event-stream 关闭响应缓冲。
  • 最后一个数据块报 IndexError 或 undefined。 usage 数据块的 choices 列表是空的。读取 [0] 之前先检查 chunk.choices。
  • 完全没有 usage。 你没有发送 stream_options,或者流在最后一个数据块之前就断了。
  • 流以 finish_reason length 结束,文本却很少。 思考模型把 max_tokens 花在了思考上。参见为什么思考模型会返回空回答。
  • 并行流式输出时返回 429。 每个打开的流都算一个进行中的请求;按量付费密钥允许 4 个。参见BroadNet 错误码与重试。

常见问题

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

发送 stream_options,并把 include_usage 设为 true。在 data: [DONE] 之前会多来一个数据块,其中 usage 有值,choices 为空数组。如果流先断了,这个数据块就不会到达。

为什么 curl 一次性打印出整个流式回答?

curl 默认会缓冲输出。加上 -N 参数(不缓冲),每个 Server-Sent Event 到达时就会立即打印。

重试的流会被重复计费吗?

按量付费下会。重试是一次新的推理请求。在 DeepSeek V4.1 Flash 不限量套餐上没有 token 计量,但重试在运行期间仍会占用会话。

流式输出比普通请求更贵吗?

不会。流式输出改变的是回答的交付方式,而不是计费方式。按量付费下,你支付的每 token 输入和输出价格与非流式请求相同。

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