不用流式输出,客户端要等整个回答写完;用了流式输出,文字会随着模型的生成逐步出现。
工作原理
流式输出使用服务器发送事件(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]才表示完整。 - 在客户端前面放一个会缓冲的代理。这样回复就会一次性全部到达。