BroadRouter
始める

LLM のストリーミング解説:SSE のチャンク、delta、usage、キャンセル

BroadNet Inference チーム · 約 4 分で読めます · 公開日 · 更新日

LLM API は chat completion を Server-Sent Events で流します。各 data 行には JSON のチャンクが入り、その choices[0].delta が次のテキスト片を運びます。delta を連結し、data: [DONE] で止めます。stream_options の include_usage を true にすると、choices が空の最後のチャンクでトークン数を受け取れます。キャンセルは接続を閉じるだけです。

ストリーミングを使わないと、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 つのストリーミングのバグ

  1. **バッファリングするプロキシ。**Nginx や一部の CDN はレスポンスをバッファリングするので、クライアントにはすべてが一度に届きます。ストリーミングのルートではプロキシのバッファリングを無効にしてください。
  2. **[DONE] を確認しない。**接続が切れると、短い回答のように見えます。[DONE] がなければ不完全として扱い、エラーのガイドにあるとおり X-Request-ID を記録してください。
  3. **ストリームの途中でリトライする。**ボディが届き始めたら、SDK はリトライしません。リトライは新しいリクエストであり、従量課金なら新しい請求です。
  4. finish_reason: length を無視する。DeepSeek V4.1 Flash のような推論モデルでは、思考が max_tokens に含まれるので、上限が小さいと、目に見えるテキストが出る前にストリームが止まることがあります。推論トークンのコストを参照してください。
  5. **行の分割を間違える。**SSE を自前でパースするなら、空行が来るまでバイトをバッファしてください。TCP の 1 回の読み取りが、JSON チャンクの途中で終わることがあります。

BroadNet Inference が向いている場面

BroadNet Inference は標準的な OpenAI 互換のストリーミング形式を使うので、Python と Node の SDK がそのままパースできます。最後のチャンクの usage には、モデルが報告する場合、キャッシュトークンと推論トークンが含まれます。ドキュメントには、本番で使う前にモデルごとにストリーミングを確認すべきとあるので、実際にリリースするモデルで上のコードを動かしてください。最初のトークンが届く速さがいちばん気になるなら、次は TTFT とスループットをお読みください。WebSocket によるリアルタイム音声が必要なら、この API はそのために作られていません。提供しているのは chat completions とファイルの文字起こしです。

よくある質問

LLM のストリーミングで SSE と WebSocket はどう違いますか?

SSE はサーバーからクライアントへの一方向で、通常の HTTP レスポンスの上で動きます。chat completion に必要なのはこれだけなので、OpenAI 互換 API は SSE を使います。WebSocket は双方向で、プロトコルのアップグレードが必要です。使われるのはリアルタイム音声で、chat completions ではありません。

ストリーミングのチャンクで usage が null になるのはなぜですか?

usage は求めたときにしか送られません。stream_options を付け、include_usage を true にしてください。すると最後以外のすべてのチャンクで usage は null になり、最後のチャンクが合計を運び、choices のリストは空になります。

ストリームをキャンセルしても課金されますか?

プロバイダーによって違い、多くはドキュメントに書いていません。サーバーが接続の切断に気づくまでに生成されたトークンは課金されると考えてください。X-Request-ID を記録し、自分の利用記録と照らし合わせてください。

ストリームが正常に終わったかどうかはどうわかりますか?

data: [DONE] を受け取り、最後のコンテンツチャンクに stop などの finish_reason が付いていれば正常です。finish_reason が length なら、max_tokens で回答が切れています。[DONE] がなければ、接続が切れています。

ストリーミングでモデルは速くなりますか?

なりません。生成にかかる合計時間は同じです。ストリーミングで短くなるのは、ユーザーが最初の言葉を目にするまでの時間で、それがチャット画面を速く感じさせます。

Markdown で読むChatGPT に聞くClaude に聞くPerplexity に聞く