Estrategia de reintentos

Las bibliotecas cliente del SDK de IA generativa de Google incluyen lógica de reintentos automática 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 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.

Cómo determinar cuándo volver a intentar la operación

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

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 regionales.
• 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 usar estrategias de conmutación por error.

Ajusta tu modelo de pagos

• Estándar de pago por uso: Usa recursos compartidos. Usa la retirada exponencial para controlar los errores transitorios de límite de frecuencia (429) causados por picos de tráfico.
• Flex pay-as-you-go: Diseñado para el procesamiento más lento y de menor prioridad. No reintentes de forma agresiva. En cambio, 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 anticipado 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 capacidad dedicada. Los errores frecuentes suelen indicar que superaste la capacidad que compraste, por lo que agregar reintentos tal vez no resuelva el problema subyacente.

Cómo definir la tolerancia a la latencia

• En tiempo real (por ejemplo, chat): Falla rápido. Limita la cantidad de intentos 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 solicitudes individuales dentro del trabajo para lograr un alto porcentaje de finalización. Tu única responsabilidad es enviar el trabajo correctamente una vez. Para obtener más información, consulta Predicción por lotes.

Cómo identificar errores que se pueden reintentar

Existen dos factores principales que determinan si una solicitud es segura para reintentarse:

Respuesta

El código de error o la respuesta recibidos indican 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 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 la API.

Nota: Los errores permanentes (p.ej., 401 Authorization, 400 Bad Request) indican problemas con la solicitud en sí y no se deben volver a intentar 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 de obtención, solicitudes de recuento de tokens y solicitudes de incorporaciones.
• Nunca idempotentes: Son las operaciones que crean recursos únicos cada vez que se completan correctamente, como la creación de un modelo ajustado nuevo.
• Matiz de la IA generativa: Si bien generateContent no es estrictamente idempotente debido a la naturaleza estocástica de los modelos generativos, generalmente es 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 (valor predeterminado: 1.0).
• attempts: Es la cantidad máxima de intentos de reintento (el valor predeterminado es 5).
• exp_base: Es la base para el cálculo de la retirada exponencial (el valor predeterminado es 2).
• max_delay: Es la demora máxima en segundos entre los reintentos (el valor predeterminado es 60).
• jitter: Es un factor para agregar una demora aleatoria a la espera exponencial (valor 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,
        )
    )
)

Flex Pay-as-you-go

En el caso de Flex Pay-as-you-go, 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 tiempo 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 Jitter: Agregar un "Jitter" aleatorio a la demora ayuda a evitar que todos los clientes reintenten la solicitud exactamente al mismo tiempo.
• Volver a intentar en errores específicos: Solo se vuelve a intentar en errores transitorios (429, 408, 5xx).
• Configura la cantidad máxima 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 espera: Reintentar de inmediato puede provocar fallas en cascada y sobrecargar el servicio.
• Reintenta errores que no se pueden reintentar: No reintentes errores del cliente (4xx que no sean 429/408), ya que indican problemas como claves de API no válidas o sintaxis incorrecta.
• Reintento incondicional de operaciones no idempotentes: La ejecución repetida de operaciones que no son idempotentes puede generar efectos secundarios, como recursos duplicados.
• Ignorar los límites de reintentos: Reintentar indefinidamente puede agotar los recursos. Siempre debes establecer 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.