コアガイド

ストリーミング

モデルの出力を到着次第表示する

概要

ストリーミングを使用すると、完全な回答を待つことなく、モデルの出力を小さなイベントとして受け取ることができます。accepted_request_formats に openai_responses を含むモデルには Responses ストリーミングを使用してください。SDK やアプリケーションがすでに想定している場合は、Chat Completions ストリーミングをそのまま使用してください。

Responses ストリーミング

curl https://api.tokenlab.sh/v1/responses \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "input": "Write a short poem.",
    "stream": true
  }'

Responses SSE は、ドキュメント化されたイベント名、順序、およびフィールドを維持します。最初のイベントが到着した後にストリームが中断された場合、それは不完全なものとみなされ、自動的に再開されることはありません。

Responses WebSocket

wss://api.tokenlab.sh/v1/responses に接続し、response.create イベントを送信します。WebSocket のレスポンスは常にストリーミングされ、background や response.cancel はサポートされていません。generate: false を指定した response.create は、モデルの出力を生成したりモデルの料金を発生させたりすることなく、継続可能な ID を返します。

各接続は一度に1つのアクティブなレスポンスを処理し、最大60分間持続します。イベントにはレスポンススコープの sequence_number が含まれます。error という名前のストリームイベントはフラットなイベントオブジェクトを使用しますが、接続やプロトコルの障害はネストされた error オブジェクトを使用します。

Chat Completions ストリーミング

お使いのフレームワークが /v1/chat/completions からの SSE チャンクを想定している場合、それも機能します:

import os
from openai import OpenAI

with OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
) as client:
    finish_reason = None
    with client.chat.completions.create(
        model="gpt-5.6-terra",
        messages=[{"role": "user", "content": "Write a short poem."}],
        stream=True,
        stream_options={"include_usage": True},
    ) as stream:
        for chunk in stream:
            if not chunk.choices:
                continue
            choice = chunk.choices[0]
            if choice.delta.content:
                print(choice.delta.content, end="", flush=True)
            if choice.finish_reason:
                finish_reason = choice.finish_reason
    if finish_reason != "stop":
        raise RuntimeError(f"Stream ended without a complete text answer: {finish_reason}")

Messages ストリーミング

"stream": true を指定した POST /v1/messages は、Anthropic Messages SSE イベントを返します。ストリームは message_stop イベントの後にのみ完了とみなしてください。それ以前に終了したストリームは不完全です。

Gemini ストリーミング

POST /v1beta/models/{model}:streamGenerateContent?alt=sse は Gemini チャンクを返します。イベントにはメタデータのみが含まれる場合があり、中間イベントでは finishReason が省略されることがあり、ストリームは Chat Completions の [DONE] マーカーなしで自然に終了する可能性があります。

ストリーム終了条件

一般的な完了条件:

  • Responses API ストリームの場合:response.completed
  • Messages ストリームの場合:message_stop
  • Chat Completions ストリームの場合:finish_reason: "stop"
  • トークン制限に達した場合:finish_reason: "length"
  • モデルがツールを使用する場合:ツール/関数呼び出しイベント

Web アプリのパターン

SDK ストリームコンシューマーをサーバー上で実行してください。ブラウザは認証済みの自社バックエンドを呼び出し、TokenLab キーはサーバー環境内に保持するようにします。テキストのデルタをブラウザに転送し、ユーザーが停止または切断したときにアップストリームのストリームをキャンセルしてください。SDK を使用して SSE イベントを解析してください。ネットワークチャンクが必ずしも1つの完全なイベントであるとは限りません。

ストリームを適切に処理する

このページの内容