タイムアウト、レート制限とリトライ

SDKのタイムアウトと限定的なリトライを設定し、リトライ可能なエラーと設定エラーを区別して、重複送信を防ぎます。

まず設定エラーを修正し、その後に一時的な障害に対処します。リトライ回数、並列数、総待機時間をまとめて制限し、短時間に同じ失敗リクエストを何度も再送信しないようにします。

リトライすべき状況

状況	推奨対応
400 / 401 / 403 / 404	まずリクエスト、権限、モデルを修正する。元のリクエストを自動的に再送しない
429	レスポンスのヒントを確認する。`Retry-After` がある場合は待機時間に従い、並列数を下げる
500 / 502 / 503 / 504 / 529	限定的にリトライ可能。継続的に失敗する場合は停止し、リクエストIDを報告する
接続失敗	DNS、プロキシ、ネットワークを確認し、タスクが許容する時間内で限定的にリトライする
リクエスト送信後のタイムアウトやストリーム切断	結果が不確定な場合があるため、まずログを確認する。上流側がまだ処理していないと仮定してはならない

クライアントライブラリのリトライ範囲が上表と完全に同じとは限りません。どの層でリトライする場合も、その層で明示的にポリシーを設定してください。

まずSDK組み込みのリトライを使う

PythonとNode.jsのタイムアウトの単位は異なります。Pythonは秒、Node.jsはミリ秒を使用します。次の例では120秒のタイムアウトと最大2回の自動リトライを設定しています。初回接続時のデバッグ時は0に変更できます。

Python
Node.js

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ONEZHE_API_KEY"],
    base_url="https://1zheai.com/v1",
    timeout=120.0,
    max_retries=2,
)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ONEZHE_API_KEY,
  baseURL: "https://1zheai.com/v1",
  timeout: 120_000,
  maxRetries: 2,
});

タイムアウト設定はビジネスタスク全体の総所要時間の上限ではありません。リトライと待機により総所要時間は増加します。外側の層でタスクを再実行する場合は、別途総締め切り時間とキャンセル機構を設定してください。

自分でリトライを実装する場合

SDKの自動リトライを無効にし、重複を防ぎます。段階的に増加する待機間隔とランダムジッターを加え、試行回数、最長待機時間、並列キューを明示的に制限します。Retry-After を解析する際は、秒数の場合とHTTP日付の場合の両方があり得ることに注意してください。

すでにユーザーに部分的なストリーミング結果を表示している場合、自動的に最初から再生し直して古いテキストの後に追加しないでください。「未完了」状態を維持し、ユーザーに再生成するか継続するかを判断させてください。

画像生成、ツール実行、その他の外部結果を生み得るタスクでは、重複送信に特に注意してください。任意のリクエストIDを設定すればサーバー側が自動的に重複排除すると仮定してはなりません。

デバッグに十分な情報を記録する

時間、エンドポイント、モデル、ステータスコード、所要時間、試行番号、サーバーから返されたリクエストIDを記録します。認証リクエストヘッダーと完全なプライベートプロンプトの記録は避けてください。これらの情報を呼び出しログと照合してください。

SDKの設定は OpenAI Python SDK と Node SDK を参照してください。具体的なエラーについてはエラーコードとデバッグを参照してください。