重試策略

Google Gen AI SDK 用戶端程式庫包含自動重試邏輯，會以指數輪詢方式處理暫時性錯誤，例如逾時、網路問題和頻率限制 (HTTP 429 和 5xx 狀態碼)。舉例來說，Python SDK 會自動重試暫時性錯誤最多四次，初始延遲時間約為 1 秒，最大延遲時間為 60 秒。雖然 SDK 預設會處理這項作業，但您可以設定這項行為，更符合特定工作負載的需求。

判斷重試時機

實作自訂重試策略前，請先考量端點選擇、付款模式和工作負載對需求的影響。

選擇合適的端點

  • 全球端點：建議用於可用性。全域端點會動態轉送流量，因此可減少因區域容量問題而需要用戶端重試的情況。
  • 區域端點：僅限特定位置。如果區域超載，立即重試可能會失敗，建議改用容錯移轉策略。

根據付款模式調整

  • 標準即付即用：使用共用資源。使用指數輪詢，處理流量激增導致的暫時性頻率限制錯誤 (429)。
  • Flex 即付即用：適合優先順序較低、處理速度較慢的工作。請勿頻繁重試，而是應增加要求逾時時間 (例如 30 分鐘)，讓系統有時間完成工作。
  • 優先即付即用：適合對延遲敏感、高可靠性的工作負載，不必像佈建輸送量一樣預付費用。如果在這個級別收到 429 錯誤，請使用指數輪詢重試，但請確保未超出配額。
  • 佈建輸送量：使用預留容量。如果經常發生錯誤，通常表示您已超出購買的容量，因此新增重試次數可能無法解決根本問題。

定義延遲容許值

  • 即時 (例如即時通訊)：快速失敗。限制重試次數，避免使用者無限期等待回應。
  • 批次推論：請勿重試個別項目。Batch 服務會自動重試工作中的個別要求，盡可能提高完成率。您只需要成功提交工作一次。詳情請參閱「批次預測」。

找出可重試的錯誤

判斷要求是否可以安全重試的主要因素有兩個：

回應

收到的錯誤代碼或回應會指出問題是暫時性還是永久性。與暫時性問題相關的回應通常可以重試。包括：

  • HTTP 代碼：408 (要求逾時)、429 (要求過多) 和 5xx (伺服器錯誤)。
  • 網路問題：通訊端逾時和 TCP 中斷連線。

詳情請參閱「API 錯誤」。

冪等

冪等要求可以重複執行，不會變更資源的最終狀態。判斷冪等性時，請考量下列事項：

  • 一律冪等：列出作業 (不會修改資源)、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 PayGo

Flex PayGo 的處理速度較慢，且會自動重試，因此預設逾時時間為 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) 時重試。
  • 設定重試次數上限：定義重試次數上限，避免無限迴圈。
  • 監控及記錄：記錄重試次數、錯誤類型和回應時間等詳細資料，以便偵錯策略。

重試反面模式

  • 重試時不採用輪詢機制：立即重試可能會導致連鎖故障，並使服務超載。
  • 重試無法重試的錯誤：請勿重試用戶端錯誤 (4xx，429/408 除外)，因為這類錯誤代表 API 金鑰無效或語法錯誤等問題。
  • 無條件重試非等冪作業：重複執行非等冪作業可能會產生副作用，例如重複建立資源。
  • 忽略重試限制：無限重試可能導致資源耗盡，因此請務必設定重試次數上限。

後續步驟