Estrategia de reintentos

Las bibliotecas cliente del SDK de IA generativa de Google incluyen lógica de reintento automática con retirada exponencial para controlar errores transitorios, como tiempos de espera agotados, problemas de red y límites de frecuencia (códigos de estado HTTP 429 y 5xx). Por ejemplo, el SDK de Python reintenta automáticamente los errores transitorios hasta cuatro veces con una demora inicial de aproximadamente 1 segundo y una demora máxima de 60 segundos. Si bien el SDK controla esto de forma predeterminada, puedes configurar este comportamiento para que se adapte mejor a tu carga de trabajo específica.

Determina cuándo volver a intentar

Antes de implementar una estrategia de reintento personalizada, considera cómo la selección de extremos, el modelo de pago y la carga de trabajo afectan tus necesidades.

Elige el extremo correcto

  • Extremo global: Se recomienda para la disponibilidad. El extremo global enruta el tráfico de forma dinámica, lo que puede reducir la necesidad de reintentos del cliente causados por problemas de capacidad regional.
  • Extremos regionales: Se restringen a una ubicación específica. Si una región está sobrecargada, es posible que fallen los reintentos inmediatos. En su lugar, considera las estrategias de conmutación por error.

Ajusta tu modelo de pago

  • Pago por uso estándar: Usa recursos compartidos. Usa la retirada exponencial para controlar los errores transitorios de límite de frecuencia (429) causados por picos de tráfico.
  • **Pago por uso flexible**: Diseñado para un procesamiento más lento y de menor prioridad. No vuelvas a intentar de forma agresiva. En su lugar, aumenta el tiempo de espera de la solicitud (por ejemplo, a 30 minutos) para darle tiempo al sistema para completar la tarea.
  • **Pago por uso prioritario**: Diseñado para cargas de trabajo de alta confiabilidad y sensibles a la latencia sin el compromiso inicial de la capacidad de procesamiento aprovisionada. Si recibes un error 429 en este nivel, vuelve a intentar con la retirada exponencial, pero asegúrate de no exceder tu cuota.
  • **Capacidad de procesamiento aprovisionada**: Usa la capacidad reservada. Por lo general, los errores frecuentes indican que excediste la capacidad comprada, por lo que agregar reintentos podría no resolver el problema subyacente.

Define la tolerancia a la latencia

  • Tiempo real (por ejemplo, chat): Falla rápido. Limita la cantidad de intentos para que los usuarios no esperen indefinidamente una respuesta.
  • Inferencia por lotes: No vuelvas a intentar elementos individuales. El servicio por lotes controla automáticamente los reintentos de solicitudes individuales dentro del trabajo para lograr una tasa de finalización alta. Tu única responsabilidad es enviar el trabajo correctamente una vez. Para obtener más información, consulta Predicción por lotes.

Identifica errores que se pueden volver a intentar

Hay dos factores principales que determinan si es seguro volver a intentar una solicitud:

Respuesta

El código de error o la respuesta recibida indica si el problema es transitorio o permanente. Por lo general, las respuestas relacionadas con los problemas transitorios se pueden reintentar. Estos incluyen los siguientes:

  • Códigos HTTP: 408 (tiempo de espera agotado de la solicitud), 429 (demasiadas solicitudes) y 5xx (errores del servidor)
  • Problemas de red: Tiempos de espera de sockets agotados y desconexiones de TCP

Para obtener más información, consulta Errores de API.

Idempotencia

Las solicitudes idempotentes se pueden ejecutar de forma reiterada sin cambiar el estado final del recurso. Ten en cuenta lo siguiente cuando determines la idempotencia:

  • Siempre idempotente: Operaciones de lista (no modifican recursos), solicitudes de obtención, solicitudes de recuento de tokens y solicitudes de incorporación
  • Nunca idempotente: Operaciones que crean recursos únicos cada vez que tienen éxito, como crear un modelo optimizado nuevo
  • Matiz de IA generativa: Si bien generateContent no es estrictamente idempotente debido a la naturaleza estocástica de los modelos generativos, por lo general, es seguro volver a intentar errores transitorios, ya que no modifica el estado del servidor.

Configura reintentos

El SDK de IA generativa de Google te permite configurar el comportamiento de reintento a través de parámetros del cliente o HttpRetryOptions.

Parámetros clave

  • initial_delay: Es la demora inicial en segundos antes del primer reintento (predeterminado: 1.0).
  • attempts: Es la cantidad máxima de intentos (predeterminado: 5).
  • exp_base: Es la base para el cálculo de retirada exponencial (predeterminado: 2).
  • max_delay: Es la demora máxima en segundos entre reintentos (predeterminado: 60).
  • jitter: Es un factor para agregar una demora aleatoria a la retirada (predeterminado: 1).
  • http_status_codes: Es una lista de códigos de estado que activan un reintento.

Ejemplos

Configuración a nivel del cliente

Puedes configurar opciones de forma global cuando inicializas el cliente.

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();

Configuración a nivel de la solicitud

También puedes anular la configuración para una sola solicitud con el parámetro 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,
        )
    )
)

Pago por uso flexible

En el caso del pago por uso flexible, el tiempo de espera predeterminado es de 10 minutos debido al procesamiento más lento y al reintento transparente. Los usuarios pueden aumentar este valor a 30 minutos para obtener una mejor tasa de éxito.

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
  )
)

Prácticas recomendadas y antipatrones

Ya sea que uses los mecanismos de reintento predeterminados, los personalices o implementes tu propia lógica de reintento, sigue estas prácticas recomendadas y evita los antipatrones comunes.

Prácticas recomendadas

  • Usa la retirada exponencial: Espera un breve período antes del primer reintento (por ejemplo, 1 segundo) y, luego, aumenta la demora de forma exponencial (por ejemplo, 2 s, 4 s, 8 s).
  • Agrega fluctuación: Agregar una "fluctuación" aleatoria a la demora ayuda a evitar que todos los clientes vuelvan a intentar al mismo tiempo.
  • Vuelve a intentar errores específicos: Solo vuelve a intentar errores transitorios (429, 408, 5xx).
  • Establece reintentos máximos: Define una cantidad máxima de intentos para evitar bucles infinitos.
  • Supervisa y registra: Registra detalles sobre los intentos, los tipos de errores y los tiempos de respuesta para depurar tu estrategia.

Antipatrones de reintento

  • Reintenta sin retirada: Volver a intentar de inmediato puede provocar fallas en cascada y sobrecargar el servicio.
  • Reintenta errores que no se pueden volver a intentar: No vuelvas a intentar errores del cliente (4xx que no sean 429/408), ya que indican problemas como claves de API no válidas o sintaxis incorrecta.
  • Reintenta incondicionalmente operaciones no idempotentes: La ejecución reiterada de operaciones que no son idempotentes puede provocar efectos secundarios, como recursos duplicados.
  • Ignora los límites de reintento: Volver a intentar de forma indefinida puede provocar el agotamiento de los recursos. Siempre establece una cantidad máxima de intentos.

¿Qué sigue?