重試策略

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

判斷何時重試

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

選擇合適的端點

• 全球端點：建議使用，可確保服務可用性。全域端點會動態轉送流量，因此可減少因區域容量問題而導致的用戶端重試需求。
• 區域端點：僅限特定位置。如果區域超載，立即重試可能會失敗，請改為考慮容錯移轉策略。

根據付款模式調整

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

定義延遲容許度

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

找出可重試的錯誤

決定是否可安全重試要求的主要因素有兩個：

回應

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

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

詳情請參閱「API 錯誤」。

注意： 永久性錯誤 (例如 401授權、400錯誤要求) 表示要求本身有問題，因此不應重試，除非您已進行變更。499 (用戶端關閉要求) 通常表示用戶端在伺服器回應前關閉連線。檢查記錄並增加用戶端逾時時間。

冪等

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

• 一律為等冪：列出作業 (不會修改資源)、取得要求、權杖計數要求和嵌入要求。
• 永不具備等冪性：每次成功時都會建立專屬資源的作業，例如建立新的微調模型。
• 生成式 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,
        )
    )
)

彈性即付即用

由於處理速度較慢且重試作業透明化，因此彈性隨用隨付方案的預設逾時時間為 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 金鑰無效或語法有誤等問題。
• 無條件重試非等冪作業：重複執行非等冪作業可能會導致副作用，例如重複的資源。
• 忽略重試次數上限：無限次數的重試可能會導致資源耗盡，請務必設定嘗試次數上限。

後續步驟

• 在 Colab 中設定重試選項。
• 進一步瞭解 API 錯誤。
• 瞭解配額和系統限制。
• 瞭解部署作業和端點。