Stratégie de nouvelle tentative

Les bibliothèques clientes du SDK Google Gen AI incluent une logique de nouvelle tentative automatique avec intervalle exponentiel entre les tentatives pour gérer les erreurs temporaires telles que les délais d'attente, les problèmes de réseau et les limites de débit (codes d'état HTTP 429 et 5xx). Par exemple, le SDK Python retente automatiquement les erreurs temporaires jusqu'à quatre fois, avec un délai initial d'environ une seconde et un délai maximal de 60 secondes. Bien que le SDK gère cela par défaut, vous pouvez configurer ce comportement pour mieux l'adapter à votre charge de travail spécifique.

Déterminer quand réessayer

Avant d'implémenter une stratégie de réessai personnalisée, réfléchissez à la façon dont la sélection de votre point de terminaison, votre modèle de paiement et votre charge de travail affectent vos besoins.

Choisir le bon point de terminaison

  • Point de terminaison mondial : recommandé pour la disponibilité. Le point de terminaison mondial achemine le trafic de manière dynamique, ce qui peut réduire la nécessité de nouvelles tentatives côté client en raison de problèmes de capacité régionaux.
  • Points de terminaison régionaux : limités à un emplacement spécifique. Si une région est surchargée, les nouvelles tentatives immédiates peuvent échouer. Envisagez plutôt des stratégies de basculement.

Ajuster votre modèle de paiement

  • Paiement à l'usage standard : utilise des ressources partagées. Utilisez un intervalle exponentiel entre les tentatives pour gérer les erreurs temporaires de limitation du débit (429) causées par des pics de trafic.
  • Paiement à l'usage Flex : conçu pour les tâches à faible priorité et au traitement plus lent. Ne faites pas de nouvelles tentatives de manière agressive. Augmentez plutôt le délai avant expiration de votre requête (par exemple, à 30 minutes) pour donner au système le temps d'effectuer la tâche.
  • Paiement à l'utilisation avec priorité : conçu pour les charges de travail sensibles à la latence et à haute fiabilité, sans l'engagement initial du débit provisionné. Si vous recevez une erreur 429 dans ce niveau, relancez la requête avec un intervalle exponentiel entre les tentatives, mais assurez-vous de ne pas dépasser votre quota.
  • Débit provisionné : utilise une capacité dédiée. Les erreurs fréquentes indiquent généralement que vous avez dépassé votre capacité achetée. L'ajout de nouvelles tentatives ne résoudra donc peut-être pas le problème sous-jacent.

Définir la tolérance à la latence

  • Temps réel (par exemple, le chat) : échouez rapidement. Limitez le nombre de tentatives pour que les utilisateurs n'attendent pas indéfiniment une réponse.
  • Inférence par lot : ne réessayez pas les éléments individuels. Le service Batch gère automatiquement les nouvelles tentatives pour les requêtes individuelles au sein du job afin de s'efforcer d'obtenir un taux d'achèvement élevé. Votre seule responsabilité est de soumettre la tâche une seule fois. Pour en savoir plus, consultez Prédiction par lot.

Identifier les erreurs récupérables

Deux facteurs principaux déterminent si une requête peut être relancée de manière sécurisée :

Réponse

Le code d'erreur ou la réponse reçue indiquent si le problème est temporaire ou permanent. Les réponses correspondant à des problèmes temporaires peuvent généralement faire l'objet d'une nouvelle tentative. Exemples :

  • Codes HTTP : 408 (Délai d'expiration de la requête), 429 (Trop de requêtes) et 5xx (Erreurs de serveur).
  • Problèmes de réseau : délais d'expiration de sockets et déconnexions TCP.

Pour en savoir plus, consultez Erreurs d'API.

Idempotence

Les requêtes idempotentes peuvent être exécutées à plusieurs reprises sans modifier l'état final de la ressource. Tenez compte des points suivants lorsque vous déterminez l'idempotence :

  • Toujours idempotentes : opérations de liste (elles ne modifient pas les ressources), requêtes GET, requêtes de nombre de jetons et requêtes d'embedding.
  • Jamais idempotentes : opérations qui créent des ressources uniques chaque fois qu'elles réussissent, comme la création d'un modèle ajusté.
  • Nuance concernant l'IA générative : bien que generateContent ne soit pas strictement idempotent en raison de la nature stochastique des modèles génératifs, il est généralement possible de réessayer en cas d'erreurs temporaires, car cela ne modifie pas l'état côté serveur.

Configurer les nouvelles tentatives

Le SDK Google Gen AI vous permet de configurer le comportement de réessai à l'aide de paramètres client ou de HttpRetryOptions.

Paramètres clés

  • initial_delay : délai initial en secondes avant la première tentative (par défaut : 1.0).
  • attempts : nombre maximal de tentatives (par défaut : 5).
  • exp_base : base du calcul de l'intervalle exponentiel entre les tentatives (par défaut : 2).
  • max_delay : délai maximal en secondes entre les tentatives (par défaut : 60).
  • jitter : facteur permettant d'ajouter un délai aléatoire au délai avant nouvelle tentative (par défaut : 1).
  • http_status_codes : liste des codes d'état qui déclenchent une nouvelle tentative.

Exemples

Configuration au niveau du client

Vous pouvez définir des options de manière globale lors de l'initialisation du client.

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

Configuration au niveau de la requête

Vous pouvez également remplacer les paramètres pour une seule requête à l'aide du paramètre 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

Pour Flex avec paiement à l'utilisation, le délai avant expiration par défaut est de 10 minutes en raison du traitement plus lent et de la transparence des nouvelles tentatives. Les utilisateurs peuvent augmenter cette durée à 30 minutes pour améliorer le taux de réussite.

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

Bonnes pratiques et antipatrons

Que vous utilisiez les mécanismes de nouvelle tentative par défaut, que vous les personnalisiez ou que vous implémentiez votre propre logique de nouvelle tentative, suivez ces bonnes pratiques et évitez les antimodèles courants.

Bonnes pratiques

  • Utilisez un intervalle exponentiel entre les tentatives : attendez un court instant avant la première nouvelle tentative (par exemple, 1 seconde), puis augmentez le délai de manière exponentielle (par exemple, 2 s, 4 s, 8 s).
  • Ajouter une gigue : l'ajout d'une "gigue" aléatoire au délai permet d'éviter que tous les clients ne fassent une nouvelle tentative exactement au même moment.
  • Réessayer en cas d'erreurs spécifiques : ne réessayez que si des erreurs temporaires se produisent (429, 408, 5xx).
  • Définissez le nombre maximal de nouvelles tentatives : définissez un nombre maximal de nouvelles tentatives pour éviter les boucles infinies.
  • Surveiller et consigner : consignez des informations sur les tentatives de réessai, les types d'erreurs et les temps de réponse pour déboguer votre stratégie.

Antimodèles de nouvelle tentative

  • Nouvelle tentative sans intervalle : le fait de relancer immédiatement une requête peut entraîner des défaillances en cascade et submerger le service.
  • Nouvelle tentative pour les erreurs non réessayables : ne réessayez pas les erreurs client (4xx autres que 429/408), car elles indiquent des problèmes tels que des clés API non valides ou une syntaxe incorrecte.
  • Nouvelle tentative inconditionnelle pour les opérations non idempotentes : l'exécution répétée d'opérations non idempotentes peut entraîner des effets secondaires, tels que la duplication de ressources.
  • Ignorer les limites de nouvelles tentatives : les nouvelles tentatives indéfinies peuvent entraîner l'épuisement des ressources. Définissez toujours un nombre maximal de tentatives.

Étapes suivantes