BroadRouter
开始使用

流式输出(streaming)

更新于

流式输出是一种在语言模型仍在生成时,就把回复分成小块陆续返回的方式,而不是在最后一次性返回。当请求把 stream 设为 true 时,OpenAI 兼容 API 会通过服务器发送事件(SSE)进行流式输出。

又称: 流式响应、流式返回、流式调用、打字机效果、SSE 流式、streaming、streaming responses、stream=true、token streaming

不用流式输出,客户端要等整个回答写完;用了流式输出,文字会随着模型的生成逐步出现。

工作原理

流式输出使用服务器发送事件(SSE)。服务器以 text/event-stream 内容类型响应,并保持连接打开。MDN 描述了它的格式:由 field: value 形式的行组成,消息之间 “separated by a pair of newline characters.”(译文:用两个换行符分隔。)

在 Chat Completions 格式中,每个事件携带一个数据块,其中有一小段 delta:

data: {"choices":[{"index":0,"delta":{"content":"Hel"}}]}

data: {"choices":[{"index":0,"delta":{"content":"lo"}}]}

data: {"choices":[],"usage":{"prompt_tokens":12,"completion_tokens":2}}

data: [DONE]

客户端把这些增量拼接起来。字面上的 data: [DONE] 一行标志着结束。只有请求中用 stream_options: {"include_usage": true} 要求了用量,才会出现用量数据块。

为什么重要

  • 感知速度。 用户在首 token 延迟之后就能看到前几个字,而不必等整个回复完成。之后,文字以模型的每秒 token 数持续输出。
  • 长输出。 流式输出让连接保持活跃,可以避免某些代理关闭空闲请求。
  • 提前处理。 智能体和界面可以在结束之前就开始解析或渲染。

它也有代价。OpenAI 指出,流式输出让内容审核更难,因为 “partial completions may be more difficult to evaluate.”(译文:不完整的补全可能更难评估。)流还可能中途断开,而且一个流式回复会一直占用一个并发名额,直到结束。

在 BroadNet Inference 上

BroadNet 在 https://inference.broadnet.ai/v1/chat/completions 上使用标准的 chat completions 流式格式,所以 Python 和 Node SDK 会替你解析。使用 curl 时,加上 -N 关闭缓冲:

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 three."}]}'

思考模型可以在最后的用量数据块里报告 reasoning_tokens 和 cached_tokens。如果连接在 [DONE] 之前关闭,请把回答视为不完整,记录 X-Request-ID 响应头,再判断重新发起请求是否安全。BroadNet 的文档要求,在生产环境依赖流式输出之前,先在你要上线的模型上验证它。详情见流式输出指南和错误码与重试。

常见错误

  • 把连接关闭当成回答已完成。只有 [DONE] 才表示完整。
  • 在客户端前面放一个会缓冲的代理。这样回复就会一次性全部到达。

常见问题

流式输出会让模型更快吗?

不会。生成速度是一样的。流式输出让前几个字更早出现,所以回复感觉更快,也让代码可以处理部分输出。

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

在 Chat Completions 格式中,发送 stream_options 并把 include_usage 设为 true。最后一个数据块就会带上 usage,以及一个空的 choices 列表。

重试的流会被计费两次吗?

在按 token 计费的密钥上,通常会。重试是一次新的推理,会再次计费。在不计 token 的固定价格套餐上,它只花费时间。

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