再試行の方法

Google Gen AI SDK クライアント ライブラリには、タイムアウト、ネットワークの問題、レート制限（HTTP 429 と 5xx ステータス コード）などの一時的なエラーを処理するための指数バックオフによる自動再試行ロジックが含まれています。たとえば、Python SDK は、一時的なエラーを最大 4 回自動的に再試行します。最初の遅延は約 1 秒で、最大遅延は 60 秒です。SDK はデフォルトでこの処理を行いますが、特定のワークロードに合わせてこの動作を構成できます。

再試行のタイミングを判断する

カスタム再試行戦略を実装する前に、エンドポイントの選択、支払いモデル、ワークロードがニーズにどのように影響するかを検討してください。

適切なエンドポイントを選択する

• グローバル エンドポイント: 可用性で推奨されます。グローバル エンドポイントはトラフィックを動的にルーティングするため、リージョン容量の問題によって発生するクライアントサイドの再試行の必要性を減らすことができます。
• リージョン エンドポイント: 特定のロケーションに制限されます。リージョンが過負荷状態の場合、すぐに再試行しても失敗する可能性があります。代わりにフェイルオーバー戦略を検討してください。

支払いモデルに合わせて調整する

• 標準の従量課金制: 共有リソースを使用します。指数バックオフを使用して、トラフィック スパイクによって発生する一時的なレート制限エラー（429）を処理します。
• Flex 従量課金: 優先度が低く、処理速度が遅いワークロード向けに設計されています。積極的に再試行するのではなく、リクエスト タイムアウトを延長（30 分など）して、システムがタスクを完了する時間を確保します。
• 優先従量課金: プロビジョニングされたスループットの事前コミットメントなしで、レイテンシの影響を受けやすい高信頼性のワークロード向けに設計されています。この階層で 429 エラーが発生した場合は、指数バックオフで再試行しますが、割り当てを超えていないことを確認してください。
• プロビジョンド スループット: 専用容量を使用します。エラーが頻繁に発生する場合は、購入した容量を超えていることが多いため、再試行を追加しても根本的な問題は解決しない可能性があります。

レイテンシ許容範囲を定義する

• リアルタイム（チャットなど）: 迅速に失敗します。ユーザーがレスポンスをいつまでも待つことがないように、再試行回数を制限します。
• バッチ推論: 個々のアイテムを再試行しないでください。Batch サービスは、ジョブ内の個々のリクエストの再試行を自動的に処理し、高い完了率を目指します。ジョブを 1 回だけ正常に送信することが、お客様の唯一の責任です。詳細については、バッチ予測をご覧ください。

再試行可能なエラーを特定する

リクエストの再試行が安全かどうかは、次の 2 つの要素で決まります。

レスポンス

受信したエラーコードまたはレスポンスは、問題が一時的なものか永続的なものかを示します。通常、一時的な問題に関連するレスポンスは再試行できます。たとえば、次のようなものが挙げられます。

• HTTP コード: 408（リクエスト タイムアウト）、429（リクエストが多すぎます）、5xx（サーバーエラー）。
• ネットワークの問題: ソケット タイムアウトと TCP 切断。

詳細については、API エラーをご覧ください。

注: 永続的なエラー（401 Authorization、400 Bad Request）はリクエスト自体に問題があることを示しているため、変更せずに再試行しないでください。499（クライアントがリクエストを閉じました）は、通常、サーバーが応答する前にクライアントが接続を閉じたことを意味します。ログを確認し、クライアントサイドのタイムアウトを増やします。

べき等性

べき等リクエストは、リソースの最終状態を変更せずに繰り返し実行できます。べき等性を判断する際は、次の点を考慮してください。

• 常にべき等: リスト オペレーション（リソースを変更しない）、get リクエスト、トークン数リクエスト、エンベディング リクエスト。
• べき等ではない: 成功するたびに一意のリソースを作成するオペレーション（新しいチューニング済みモデルの作成など）。
• 生成 AI のニュアンス: 生成モデルの確率的性質により、generateContent は厳密にはべき等ではありませんが、サーバーサイドの状態を変更しないため、一時的なエラーに対して再試行しても一般的に安全です。

再試行を構成する

Google Gen AI SDK を使用すると、クライアント パラメータまたは HttpRetryOptions を使用して再試行動作を構成できます。

主なパラメータ

• initial_delay: 最初の再試行までの初期遅延（秒単位）（デフォルト: 1.0）。
• attempts: 再試行の最大回数（デフォルト: 5）。
• exp_base: 指数バックオフ計算のベース（デフォルト: 2）。
• max_delay: 再試行間の最大遅延時間（秒単位）（デフォルト: 60）。
• jitter: バックオフにランダムな遅延を追加する係数（デフォルト: 1）。
• http_status_codes: 再試行をトリガーするステータス コードのリスト。

例

クライアント レベルの構成

クライアントの初期化時にオプションをグローバルに設定できます。

Python

from google import genai
from google.genai import types

client = genai.Client(
    vertexai=True,
    project=PROJECT_ID,
    location="global",
    http_options=types.HttpOptions(
        retry_options=types.HttpRetryOptions(
            initial_delay=1.0,
            attempts=5,
            http_status_codes=[408, 429, 500, 502, 503, 504],
        ),
        timeout=120 * 1000,
    ),
)

Java

import com.google.genai.Client;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.HttpRetryOptions;

HttpOptions httpOptions = HttpOptions.builder()
  .retryOptions(
      HttpRetryOptions.builder()
          .attempts(5)
          .httpStatusCodes(408, 429, 500, 502, 503, 504).build())
  .build();

Client client = Client.builder()
  .project(PROJECT_ID)
  .location("global")
  .vertexAI(true)
  .httpOptions(httpOptions)
  .build();

リクエスト レベルの構成

config パラメータを使用して、単一のリクエストの設定をオーバーライドすることもできます。

Python

from google import genai
from google.genai import types

client = genai.Client(vertexai=True, project=PROJECT_ID, location="global")

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="Tell me a joke about a rabbit.",
    config=types.GenerateContentConfig(
        http_options=types.HttpOptions(
            retry_options=types.HttpRetryOptions(
                initial_delay=1.0,
                attempts=10,
                http_status_codes=[408, 429, 500, 502, 503, 504],
            ),
            timeout=120 * 1000,
        )
    )
)

Flex 従量課金制

Flex 従量課金制の場合、処理速度が遅く、透過的な再試行が行われるため、デフォルトのタイムアウトは 10 分です。成功率を高めるために、この時間を 30 分に増やすことができます。

Python

from google import genai
from google.genai import types

client = genai.Client(
  vertexai=True, project=PROJECT_ID, location='global',
  http_options=types.HttpOptions(
    api_version="v1",
      headers={
        "X-Vertex-AI-LLM-Request-Type": "shared",
        "X-Vertex-AI-LLM-Shared-Request-Type": "flex" # Use Flex PayGo
      },
      timeout = 30 * 60 * 1000 # Increase to 30 minutes
  )
)

ベスト プラクティスとアンチパターン

デフォルトの再試行メカニズムを使用している場合でも、カスタマイズしている場合でも、独自の再試行ロジックを実装している場合でも、次のベスト プラクティスに従い、一般的なアンチパターンを回避してください。

ベスト プラクティス

• 指数バックオフを使用する: 最初の再試行の前に短時間待機し（1 秒など）、遅延を指数関数的に増やします（2 秒、4 秒、8 秒など）。
• ジッターを追加する: 遅延にランダムな「ジッター」を追加すると、すべてのクライアントが同時に再試行するのを防ぐことができます。
• 特定のエラーで再試行: 一時的なエラー（429、408、5xx）でのみ再試行します。
• 最大再試行回数を設定する: 無限ループを回避するために、再試行の最大回数を定義します。
• モニタリングとロギング: 再試行、エラータイプ、レスポンス時間に関する詳細をログに記録して、戦略をデバッグします。

再試行のアンチパターン

• バックオフなしで再試行する: すぐに再試行すると、カスケード障害が発生し、サービスが過負荷になる可能性があります。
• 再試行できないエラーの再試行: クライアント エラー（429/408 以外の 4xx）は、無効な API キーや不正な構文などの問題を示すため、再試行しないでください。
• べき等以外のオペレーションを無条件で再試行する: べき等でないオペレーションを繰り返し実行すると、リソースの重複などの副作用が発生する可能性があります。
• 再試行の上限を無視する: 無期限に再試行すると、リソースが枯渇する可能性があります。常に最大試行回数を設定してください。

次のステップ

• Colab で再試行オプションを構成する。
• API エラーの詳細
• 割り当てとシステムの上限について学習する。
• デプロイとエンドポイントについて学習する。