Estrategia de reintentos

Las bibliotecas cliente del SDK de IA generativa de Google incluyen una lógica de reintento automático con retirada exponencial para controlar errores transitorios, como tiempos de espera, 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 un retraso inicial de aproximadamente 1 segundo y un retraso máximo 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 intentarlo

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

Elige el extremo adecuado

• 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 los reintentos inmediatos fallen. En su lugar, considera estrategias de conmutación por error.

Ajusta el modelo de pago

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

Define la tolerancia a la latencia

• En tiempo real (por ejemplo, chat): Falla rápido. Limita la cantidad de intentos de reintento para que los usuarios no tengan que esperar una respuesta de forma indefinida.
• Inferencia por lotes: No vuelvas a intentar procesar elementos individuales. El servicio de Batch controla automáticamente los reintentos de las solicitudes individuales dentro del trabajo para lograr un alto porcentaje de respuesta. 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

Existen dos factores principales que determinan si una solicitud es segura o no:

Respuesta

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

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

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

Nota: Los errores permanentes (p.ej., 401 Autorización, 400 Solicitud incorrecta) indican problemas con la solicitud en sí y no se deben reintentar sin cambios. 499 (Client Closed Request) suele significar que el cliente cerró la conexión antes de que el servidor pudiera responder. Verifica los registros y aumenta el tiempo de espera del cliente.

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 idempotentes: Operaciones de lista (no modifican recursos), solicitudes GET, solicitudes de recuento de tokens y solicitudes de incorporaciones.
• Nunca idempotentes: Son operaciones que crean recursos únicos cada vez que se realizan correctamente, como la creación de un nuevo modelo ajustado.
• Matiz de la IA generativa: Si bien generateContent no es estrictamente idempotente debido a la naturaleza estocástica de los modelos generativos, suele ser seguro volver a intentarlo en caso de 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 de reintento (predeterminado: 5).
• exp_base: Es la base para el cálculo de la retirada exponencial (predeterminado: 2).
• max_delay: Es la demora máxima en segundos entre reintentos (valor predeterminado: 60).
• jitter: Es un factor para agregar un retraso aleatorio 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 establecer 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 de 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,
        )
    )
)

Flex PayGo

En el caso de Flex PayGo, el tiempo de espera predeterminado es de 10 minutos debido a un procesamiento más lento y a un 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 período breve antes del primer reintento (por ejemplo, 1 segundo) y, luego, aumenta el retraso de forma exponencial (por ejemplo, 2 s, 4 s, 8 s).
• Agrega fluctuación: Agregar una "fluctuación" aleatoria al retraso ayuda a evitar que todos los clientes vuelvan a intentarlo exactamente al mismo tiempo.
• Reintentar en caso de errores específicos: Solo reintentar en caso de errores transitorios (429, 408, 5xx).
• Establece un máximo de reintentos: Define una cantidad máxima de reintentos para evitar bucles infinitos.
• Supervisa y registra: Registra detalles sobre los intentos de reintento, los tipos de errores y los tiempos de respuesta para depurar tu estrategia.

Antipatrones de reintento

• Reintentar sin retirada: Reintentar de inmediato puede provocar fallas en cascada y sobrecargar el servicio.
• Reintentar errores que no se pueden reintentar: No reintentes los errores del cliente (4xx que no sean 429/408), ya que indican problemas como claves de API no válidas o sintaxis incorrecta.
• Reintentar operaciones no idempotentes de forma incondicional: Ejecutar repetidamente operaciones que no son idempotentes puede generar efectos secundarios, como recursos duplicados.
• Ignorar los límites de reintentos: Reintentar de forma indefinida puede provocar el agotamiento de los recursos. Establece siempre una cantidad máxima de intentos.

¿Qué sigue?

• Configura las opciones de reintento en un Colab.
• Más información sobre los errores relacionados con las API
• Obtén más información sobre las cuotas y los límites del sistema.
• Obtén más información sobre las implementaciones y los extremos.