AI API ストリーミング:SSE、最初の出力、タイムアウト

Chat Completions と Responses のイベント、SSE の解析、最初の有効な出力の指標、段階別のタイムアウト、499 の診断を押さえて、信頼性の高い AI API ストリーミングを実装します。

AI API ストリーミング:SSE、最初の出力、タイムアウト

AI API のストリーミングでは、レスポンスボディ全体の完成を待たずに、モデルが生成している途中の出力を順次送信します。体感的な応答性は向上しますが、モデルのレイテンシが自動的に短くなるわけではありません。また、クライアントが正しく解析しなければならないプロトコル上の仕様が 1 つ増えます。

最初のルールは、パーサーをエンドポイントに合わせることです。Chat Completions はストリーミングされた completion チャンクを使用し、Responses は型付きのレスポンスイベントを使用します。クライアントが想定しているイベントの形式が違うと、HTTP 200 を受け取っても何も表示されないことがあります。

バッファリングなしのリクエストから始める

Chat Completions のモデルでは、curl -N で curl の出力バッファリングを無効にします。

curl -N -sS https://modelflare.dev/v1/chat/completions \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [{"role": "user", "content": "Explain SSE in three points."}],
    "stream": true
  }'

Responses 互換のモデルの場合:

curl -N -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_RESPONSES_MODEL",
    "input": "Explain SSE in three points.",
    "stream": true
  }'

モデルと料金に掲載されている正確なモデル ID を使用してください。まず同じリクエストをストリーミングを無効にして 1 回テストすると、リクエスト自体の検証とストリームの解析の問題を切り分けられます。

イベントストリームをプロトコルとして扱う

Server-Sent Events は区切られたレコードであり、任意の JSON 断片ではありません。本番環境のクライアントでは、次の対応が必要です。

  • HTTP ライブラリ、プロキシ、UI レイヤーのいずれでもレスポンスボディをバッファリングしない
  • 完全なイベントが揃うまで、ネットワークから部分的に読み取ったデータを蓄積する
  • 選択したエンドポイントが使用するイベントタイプを解析する
  • テキストの差分、推論やツールのイベント、完了イベント、エラーイベントを処理する
  • 有用なレスポンスには必ず可視テキストが含まれる、と想定しない
  • キャンセルの状態と最終的な使用量の情報を保持する
  • 終端イベントを受け取ったら、待ち続けずにストリームを閉じる

可能であれば、選択したプロトコルにネイティブ対応している SDK を使用してください。独自に実装したパーサーは、分割されたフレーム、1 回の読み取りに含まれる複数のイベント、ツールのみの出力、正常な終端イベントでテストする必要があります。

最初のトークンまでの時間以外も測定する

エージェントのトラフィックでは、「最初のトークンまでの時間」だけでは曖昧すぎることがよくあります。次の測定値を分けて考えてください。

測定項目 意味
接続と認証 ゲートウェイに到達し、キーが検証されるまでの時間
サービス提供元のレスポンスヘッダー 選択されたルートがレスポンスを開始するまでの時間
最初の有効な出力 最初の有用なテキスト、推論、ツールイベント
最初の可視テキスト ユーザーが実際に目にする最初のテキスト
出力スループット 出力が始まった後の可視テキストの生成速度
合計応答時間 完了、失敗、キャンセルのいずれかに至るまでの時間

ツール呼び出しは、可視テキストより先に有効な出力を生成することがあります。そのため、運用上の指標としては最初の有効な出力のほうが確実であり、最初の可視テキストはユーザー体験の評価に役立ちます。

Modelflare の利用ログにはリクエスト単位のタイミングの記録が保持されるため、これらの各段階を、モデル、グループ、ステータス、トークン、コストと照らし合わせて比較できます。

タイムアウトは段階ごとに設計する

全体に 1 つの短いタイムアウトを設定すると、原因のわかりにくい失敗が発生します。ストリーミングクライアントでは、次の複数の時間枠を考慮する必要があります。

  1. 接続タイムアウト: HTTP 接続を確立できない場合。
  2. ヘッダーまたは最初の出力のタイムアウト: リクエストが受け付けられた後、レスポンスも有効なイベントも届かない場合。
  3. アイドルタイムアウト: ストリームは始まったものの、想定外に長い時間、新しいイベントが届かない場合。
  4. 全体の期限: 処理全体が、ワークロードの業務上の上限を超えた場合。

推論の比重が大きいリクエストやツール主導のリクエストでは、短いチャットの応答よりも、可視テキストが表示されるまでに長く待つことは珍しくありません。時間枠は実際に観測したワークロードの挙動に基づいて決め、ユーザーが結果を必要としなくなった時点で意図的にキャンセルしてください。

キャンセルと 499 の記録を理解する

クライアント、リバースプロキシ、ブラウザーのタブ、呼び出し元の期限によってダウンストリームの接続が閉じられると、ゲートウェイはそのリクエストをクライアントによるキャンセルとして記録することがあります。リクエスト記録の 499 は、完了前にダウンストリームの接続が終了したことを示す根拠です。それだけで、選択されたモデルやチャネルに障害があったことの証明にはなりません。

キャンセルを調査するときは、次の点を比較します。

  • クライアントの期限と中止シグナル
  • プロキシのバッファリングとアイドルタイムアウト
  • 最初の有効な出力までの時間
  • クライアントにイベントが 1 つでも届いたかどうか
  • 選択されたモデルとグループ
  • リクエスト ID とキャンセルのタイムスタンプ

可視テキストが返らないストリームを診断する

次の順序で確認します。

  1. "stream": false を指定して同じリクエストを再送します。
  2. モデルが選択したエンドポイントに対応していることを確認します。
  3. UI で変換される前の生のイベントを取得します。
  4. レスポンスに、テキストではなくツール呼び出しや推論のイベントが含まれていないか確認します。
  5. 中間のレイヤーがボディをバッファリングしていないことを確認します。
  6. パーサーがエンドポイントの終端イベントを処理できることを確認します。
  7. 利用ログで、ステータス、最初の出力、合計時間、キャンセルの有無を確認します。

非ストリーミングでは成功し、生のストリーミングイベントも届いている場合、原因は通常、認証やモデルへのアクセスではなく、クライアントでの解析や描画にあります。生のイベントが 1 つも届かない場合は、AI API エラーガイドに進んでください。

本番環境のストリーミングチェックリスト

  • パーサーを Chat Completions または Responses のどちらかに明示的に合わせる
  • HTTP クライアントと、管理下にあるすべてのプロキシレイヤーでバッファリングを無効にする
  • アプリケーションで使用するテキスト、推論、ツールのみ、エラーの各イベントをテストする
  • 最初の有効な出力と最初の可視テキストを区別する
  • 段階に応じたタイムアウトと、意図的な中止シグナルを使用する
  • 安全な冪等性の設計がない限り、再試行は新しいリクエストとして扱う
  • 診断のために、リクエスト ID、ステータス、選択されたモデル、グループ、タイミングを保持する
  • Responses API と Chat Completions の比較で、エンドポイントの選択を見直す

よくある質問

ストリーミングを使うと、モデルの生成は速くなりますか?

必ずしもそうではありません。ストリーミングによって出力を早く表示できますが、生成速度や最初のイベントまでの時間は、引き続きモデル、ルート、コンテキスト、推論、ツールに左右されます。

curl では動作するのに、アプリケーションに何も表示されないのはなぜですか?

アプリケーションや中間のレイヤーがボディをバッファリングしているか、パーサーが Chat Completions のチャンクを想定しているのに Responses のイベントを受け取っている可能性があります。モデルやルートを変更する前に、アプリケーションの境界で生のフレームを取得してください。

ストリームが切断された後、クライアントは再試行すべきですか?

処理を繰り返しても安全な場合に限ります。切断されたストリームでも、サービス提供元側の処理やツールの実行がすでに発生している可能性があります。副作用の重複が問題になる場合は、回数に上限を設けた再試行と、アプリケーションレベルの冪等性を使用してください。