ストリーミングを使わないと、chat completion は回答全体ができあがるまで何も返しません。600 トークンの返答は、毎秒約 100 トークン の速度では数秒間の沈黙になります。ストリーミングなら、モデルが書いたそばから最初の言葉が表示されます。この記事では、実際に通信で何が流れるか、それをどうパースするか、ストリームからトークンの使用量をどう取り出すか、どうきれいに止めるかを解説します。BroadNet 固有のルールを手短に知りたい場合は、ストリーミングのリファレンスガイドをご覧ください。
SSE のストリームは通信上どう見えますか?
Server-Sent Events は、Content-Type: text/event-stream のごく普通の HTTP レスポンスです。サーバーは接続を開いたままにして、イベントを書き込みます。各イベントは 1 行以上の data: 行と、それに続く空行です。OpenAI 互換 API は各イベントに JSON のチャンクを 1 つ入れ、最後はリテラルの [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 も含まれ、推論モデルでは usage に推論トークンが報告されることがあります。
チャンクには何が入っていますか?
| フィールド | 場所 | 意味 |
|---|---|---|
choices[0].delta.role |
最初のチャンク | 通常は assistant。1 回だけ送られる。 |
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 になってからパースしてください。
ストリームからトークンの使用量を取得するには?
ストリーミングでないレスポンスには、必ず usage が含まれます。ストリームでは、求めない限り含まれません。stream_options: {"include_usage": true} を設定すると、サーバーは [DONE] の前にチャンクを 1 つ追加で送ります。このチャンクは合計を持ち、choices 配列は空です。BroadNet Inference では、モデルが報告する場合、usage に prompt_tokens_details.cached_tokens と completion_tokens_details.reasoning_tokens も含まれます。コストのログ記録に必要なのはまさにこれです。
よくあるバグは、すべてのチャンクで chunk.choices[0] を読むコードが、usage のチャンクでインデックスエラーを出すことです。先に choices を確認してください。
Python:ストリーミング、usage の取得、キャンセル
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 リクエストビルダーを使えば、どのモデルとベース URL でも、このリクエストと Python・Node 版を生成できます。
ストリームはどうキャンセルし、コストはどうなりますか?
SSE でのキャンセルは、接続を閉じることだけです。「停止」メッセージはありません。その後どうなるかはサーバー次第で、行儀のよいサーバーはソケットが閉じたことに気づいて生成を止めます。それまでに生成されたトークンは、実際に行われた処理です。BroadNet の API リファレンスにはキャンセルしたストリームの課金について記載がないので、従量課金では切断までに生成されたトークンは課金されるものとして計画し、利用記録を確認してください。定額プランでは、キャンセルしたストリームに追加料金はかかりませんが、セッションが空くのはサーバーが生成を止めてからです。
チェックすべき 5 つのストリーミングのバグ
- **バッファリングするプロキシ。**Nginx や一部の CDN はレスポンスをバッファリングするので、クライアントにはすべてが一度に届きます。ストリーミングのルートではプロキシのバッファリングを無効にしてください。
- **
[DONE]を確認しない。**接続が切れると、短い回答のように見えます。[DONE]がなければ不完全として扱い、エラーのガイドにあるとおりX-Request-IDを記録してください。 - **ストリームの途中でリトライする。**ボディが届き始めたら、SDK はリトライしません。リトライは新しいリクエストであり、従量課金なら新しい請求です。
finish_reason: lengthを無視する。DeepSeek V4.1 Flash のような推論モデルでは、思考が max_tokens に含まれるので、上限が小さいと、目に見えるテキストが出る前にストリームが止まることがあります。推論トークンのコストを参照してください。- **行の分割を間違える。**SSE を自前でパースするなら、空行が来るまでバイトをバッファしてください。TCP の 1 回の読み取りが、JSON チャンクの途中で終わることがあります。
BroadNet Inference が向いている場面
BroadNet Inference は標準的な OpenAI 互換のストリーミング形式を使うので、Python と Node の SDK がそのままパースできます。最後のチャンクの usage には、モデルが報告する場合、キャッシュトークンと推論トークンが含まれます。ドキュメントには、本番で使う前にモデルごとにストリーミングを確認すべきとあるので、実際にリリースするモデルで上のコードを動かしてください。最初のトークンが届く速さがいちばん気になるなら、次は TTFT とスループットをお読みください。WebSocket によるリアルタイム音声が必要なら、この API はそのために作られていません。提供しているのは chat completions とファイルの文字起こしです。
