重试策略

Google Gen AI SDK 客户端库包含自动重试逻辑，并采用指数退避算法来处理暂时性错误，例如超时、网络问题和速率限制（HTTP 429 和 5xx 状态代码）。例如，Python SDK 会自动重试暂时性错误，最多重试 4 次，初始延迟时间约为 1 秒，最长延迟时间为 60 秒。虽然 SDK 默认会处理此问题，但您可以配置此行为，以更好地适应您的特定工作负载。

确定何时重试

在实施自定义重试策略之前，请考虑端点选择、付款模式和工作负载如何影响您的需求。

选择合适的端点

  • 全球端点：建议使用，可提高可用性。全球端点会动态路由流量，从而减少因区域容量问题而导致的客户端重试需求。
  • 区域级端点：仅限在特定位置使用。如果某个区域过载，立即重试可能会失败；请考虑改用故障切换策略。

针对您的支付模式进行调整

  • 标准随用随付：使用共享资源。使用指数退避算法处理因流量高峰而导致的暂时性速率限制错误 (429)。
  • 灵活的随用随付：专为优先级较低、处理速度较慢的作业而设计。请勿频繁重试；而是应增加请求超时时间（例如，增加到 30 分钟），以便系统有时间完成任务。
  • 优先按需付费：专为延迟敏感型、高可靠性工作负载而设计，无需预先承诺预置吞吐量。如果您在此层级中收到 429 错误，请使用指数退避算法重试，但请确保您未超出配额。
  • 预配吞吐量：使用专用容量。频繁出现错误通常表示您已超出购买的容量，因此添加重试可能无法解决根本问题。

定义延迟时间容忍度

  • 实时（例如，聊天）：快速失败。限制重试次数，以免用户无限期等待响应。
  • 批量推理：不重试单个商品。Batch 服务会自动处理作业中各个请求的重试，力求实现高完成率。您只需成功提交一次作业。如需了解详情，请参阅批量预测。

识别可重试的错误

有两个主要因素决定了能否安全地重试请求：

响应

收到的错误代码或响应会指明问题是暂时性的还是永久性的。与暂时性问题相关的响应通常可以重试。其中包括：

  • HTTP 代码：408（请求超时）、429（请求过多）和 5xx（服务器错误）。
  • 网络问题：套接字超时和 TCP 断开连接。

如需了解详情，请参阅 API 错误。

幂等性

幂等请求可以重复执行，而不会更改资源的最终状态。确定幂等性时，请考虑以下事项：

  • 始终具有幂等性：列表操作（不会修改资源）、获取请求、token 数请求和嵌入请求。
  • 永远不具有幂等性：每次成功时都会创建唯一资源的操作，例如创建新的调优模型。
  • 生成式 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 Pay-as-you-go，由于处理速度较慢且重试透明，默认超时时间为 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 密钥无效或语法错误等问题。
  • 无条件重试非幂等操作：重复执行非幂等操作可能会导致副作用，例如资源重复。
  • 忽略重试限制：无限期重试可能会导致资源耗尽；请务必设置最大尝试次数。

后续步骤