Stratégie de nouvelle tentative

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

Déterminer quand effectuer une nouvelle tentative

Avant d'implémenter une stratégie de nouvelle tentative personnalisée, réfléchissez à l'impact de votre sélection de point de terminaison, de votre modèle de paiement et de votre charge de travail sur 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 le besoin de nouvelles tentatives côté client causées par des 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 limite de débit (429) causées par des pics de trafic.
  • **Paiement à l'usage flexible** : conçu pour un traitement plus lent et de priorité inférieure. N'effectuez 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 laisser au système le temps d'effectuer la tâche.
  • Paiement à l'usage prioritaire : conçu pour les charges de travail à haute fiabilité et sensibles à la latence, sans l'engagement initial du débit provisionné. Si vous recevez une erreur 429 dans ce niveau, effectuez une nouvelle tentative 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é la capacité achetée. Par conséquent, l'ajout de nouvelles tentatives ne résoudra peut-être pas le problème sous-jacent.

Définir la tolérance à la latence

  • Temps réel (par exemple, chat) : échec rapide. Limitez le nombre de nouvelles tentatives afin que les utilisateurs n'aient pas à attendre une réponse indéfiniment.
  • Inférence par lot : n'effectuez pas de nouvelle tentative pour des éléments individuels. Le service par lot gère automatiquement les nouvelles tentatives pour les requêtes individuelles au sein du job afin de viser un taux d'achèvement élevé. Votre seule responsabilité consiste à envoyer le job une seule fois. Pour en savoir plus, consultez la section Prédiction par lot.

Identifier les erreurs pour lesquelles une nouvelle tentative est possible

Deux facteurs principaux déterminent si une requête peut être relancée en toute sécurité :

Réponse

Le code d'erreur ou la réponse reçue indique 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 avant expiration de la requête), 429 (Trop de requêtes) et 5xx (Erreurs de serveur).
  • Problèmes réseau : délais avant expiration de sockets et déconnexions TCP.

Pour en savoir plus, consultez la section 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’embeddings.
  • 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 de l'IA générative : bien que generateContent ne soit pas strictement idempotente en raison de la nature stochastique des modèles génératifs, il est généralement sûr de réessayer en cas d'erreurs temporaires, car elle ne modifie pas l'état côté serveur.

Configurer les nouvelles tentatives

Le SDK Google Gen AI vous permet de configurer le comportement des nouvelles tentatives via des paramètres client ou HttpRetryOptions.

Paramètres clés

  • initial_delay: délai initial en secondes avant la première nouvelle tentative (par défaut : 1.0).
  • attempts: nombre maximal de nouvelles 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 nouvelles tentatives (par défaut : 60).
  • jitter: facteur permettant d'ajouter un délai aléatoire à l'intervalle (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 d'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,
        )
    )
)

Paiement à l'usage flexible

Pour le paiement à l'usage flexible, le délai avant expiration par défaut est de 10 minutes en raison du traitement plus lent et de la nouvelle tentative transparente. Les utilisateurs peuvent augmenter ce délai à 30 minutes pour un meilleur 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 antimodèles

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

  • Utiliser un intervalle exponentiel entre les tentatives : attendez un court instant avant la première nouvelle tentative (par exemple, une 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 tentent de relancer la requête exactement au même moment.
  • Nouvelle tentative en cas d'erreurs spécifiques : n'effectuez de nouvelles tentatives que pour les erreurs temporaires (429, 408, 5xx).
  • Définir un nombre maximal de nouvelles tentatives : définissez un nombre maximal de nouvelles tentatives pour éviter les boucles infinies.
  • Surveiller et enregistrer : enregistrez les détails concernant les nouvelles tentatives, 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 : une nouvelle tentative immédiate peut entraîner des défaillances en cascade et surcharger le service.
  • Nouvelle tentative pour les erreurs irrécupérables : n'effectuez pas de nouvelles tentatives pour 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 des ressources en double.
  • Ignorer les limites de nouvelles tentatives : les nouvelles tentatives indéfinies peuvent entraîner une épuisement des ressources. Définissez toujours un nombre maximal de tentatives.

Étape suivante