Stratégie de basculement pour API d’IA : matrice des défaillances
Politique par phase pour décider s’il faut réessayer, utiliser une route au contrat identique, arrêter, rapprocher les effets secondaires ou enquêter.

Réessayer un appel d’API d’IA, basculer vers une autre route et substituer le modèle sont trois actions distinctes. Le réessai répète une tentative sous le même contrat. Le basculement envoie le modèle et le protocole demandés vers un autre chemin admissible. La substitution change le modèle et peut modifier la qualité, le prix, la latence, le comportement des outils, les limites de contexte et le format de sortie.
Une politique fiable définit les actions autorisées avant l’incident. Elle tient compte de la classe de défaillance, de la phase de réponse, de l’idempotence de l’opération complète et du nombre de tentatives encore compatibles avec l’échéance de l’utilisateur.
Distinguer réessai, basculement de route et substitution de modèle
Employez des noms distincts dans la configuration, les journaux et les procédures d’exploitation.
| Action | Ce qui change | Usage approprié | Risque principal |
|---|---|---|---|
| Réessai sur la même route | Temps et numéro de tentative | Absorber une défaillance transitoire courte sur la même route | Ajouter de la charge à une dépendance défaillante |
| Route de secours au même contrat | Canal fournisseur, compte ou groupe ordonné | Conserver le modèle et le protocole lorsqu’un chemin échoue | Incompatibilité cachée entre routes supposées équivalentes |
| Substitution de modèle | ID du modèle ou politique de modèles nommée | Compromis de qualité, de coût ou de disponibilité validé par le produit | Changement silencieux de comportement et de facturation |
Ne regroupez pas ces actions sous le mot « réessai ». Les équipes d’exploitation doivent savoir si une requête a été rejouée, déplacée ou servie par un autre modèle. Pour l’utilisateur, la substitution de modèle doit être un contrat explicite, pas un raccourci de récupération invisible.
Certaines passerelles acceptent des étapes ordonnées par fournisseur ou modèle. La documentation Cloudflare sur les routes de secours indique par exemple l’étape qui a réussi. L’enseignement utile n’est pas de copier la politique d’un fournisseur, mais de conserver une preuve pour chaque tentative dès qu’une route change.
Appliquer quatre contrôles avant toute répétition
Un code d’état ne constitue pas à lui seul une politique de réessai. Évaluez quatre points :
- Classe de défaillance : erreur transitoire, permanente, imputable à l’appelant ou de résultat ambigu ?
- Phase de réponse : avant les en-têtes, avant une sortie effective ou après livraison ?
- Idempotence : l’opération complète peut-elle être rejouée sans dupliquer un effet externe ?
- Budget de tentatives : reste-t-il assez de temps réel et une tentative disponible ?
La stratégie de réessai de Google Cloud pose les mêmes distinctions pour les API générales : la réponse indique si un nouvel essai peut être utile, et l’idempotence s’il est sûr. Les erreurs 408, 429, 5xx, les délais d’attente de socket et les déconnexions sont souvent transitoires, mais les opérations non idempotentes exigent des conditions plus strictes.
Dans un flux de travail d’IA, l’idempotence dépasse la requête HTTP adressée au modèle. Rejouer une instruction peut reproposer le même e-mail, remboursement, déploiement ou écritures en base de données. Chaque exécution d’outil doit donc posséder une clé d’idempotence stable et un résultat persistant, même si l’inférence est en lecture seule.
Partir d’une matrice de défaillances
La matrice suivante propose une politique applicative prudente. La passerelle peut avoir basculé en interne vers un autre canal au même contrat avant que l’application reçoive le résultat final ; coordonnez les deux couches.
| Échec ou phase | Réessai sur la même route | Route de secours au même contrat | Arrêt ou investigation | Raison |
|---|---|---|---|---|
| Erreur de validation, champ non pris en charge ou requête mal formée | Non | Non | Corriger la requête | Rejouer le même contrat invalide ne peut pas réussir |
| Erreur d’authentification, d’autorisation, de quota ou de politique de la passerelle | Non | Non | Corriger le compte ou la politique | Une autre route ne doit pas contourner la décision de la passerelle |
| Échec des identifiants ou du compte fournisseur avant la sortie | Non sur la route défaillante | Oui avec un canal vérifié | Isoler et examiner le canal | Le contrat reste inchangé lorsque des identifiants défaillants sont retirés |
Erreur réseau ou 408 avant la sortie |
Au plus une tentative bornée si l’opération est idempotente | Oui | Arrêt à l’échéance | La panne peut être transitoire, mais le résultat peut être ambigu après une déconnexion |
429 avant la sortie |
Réessai différé avec Retry-After |
Oui si une route équivalente a de la capacité | Arrêt une fois le budget épuisé | Les réessais immédiats amplifient la limitation de débit |
500, 502, 503 ou 504 avant la sortie |
Tentatives bornées avec temporisation progressive | Oui | Examiner les échecs répétés | Souvent transitoires, sans garantir que toutes les routes sont sûres |
| Réponse du fournisseur non conforme au schéma avant la sortie vers le client | Généralement non | Seulement vers une route validée pour le même schéma | Isoler ou examiner la compatibilité | Répéter une implémentation incompatible aide rarement |
| Refus du modèle ou réponse conforme à la politique de sécurité | Non | Non | Renvoyer le résultat | Un refus valide n’est pas une panne d’infrastructure |
Annulation par l’appelant ou 499 en aval |
Non | Non | Arrêt immédiat | L’appelant n’a plus besoin du traitement |
| Flux partiel après livraison de contenu ou d’arguments d’outil | Pas de répétition transparente | Pas de basculement transparent | Marquer comme partiel ; décision applicative | Un second flux peut dupliquer ou contredire la sortie déjà livrée |
| Effet d’un outil dont l’achèvement est inconnu | Non avant rapprochement | Non avant rapprochement | Interroger le registre d’idempotence ou le système cible | Une nouvelle inférence peut proposer le même effet |
Un 503 avant toute sortie n’est pas équivalent à une connexion rompue après 400 tokens visibles.
Considérer le début du flux comme point d’engagement
Avant la sortie vers le client, la passerelle peut écarter une tentative défaillante et choisir une autre route sans exposer deux réponses. Après le premier octet significatif, la répétition transparente devient dangereuse.
Redémarrer le flux peut :
- répéter le début de la réponse ;
- produire une continuation différente ;
- émettre un appel de fonction dupliqué avec un nouvel ID d’appel ;
- modifier l’utilisation et le coût sans frontière claire ;
- empêcher le client d’associer les événements à leur tentative.
Si le flux se rompt après le début de la sortie, retournez une erreur de résultat partiel ou de transport avec l’ID de requête initial. L’application peut proposer un « réessayer » explicite, reprendre depuis un point de contrôle sûr ou écarter la sortie partielle. Elle ne doit pas raccorder silencieusement un nouveau flux du modèle à l’ancien.
Pour les appels de fonctions, conservez les ID d’appel acceptés et les résultats de leurs effets avant qu’un réessai puisse les recréer. La comparaison des formats d’appels de fonctions relie ces ID à l’idempotence de l’application.
Borner la temporisation par tentatives et temps total
La temporisation exponentielle espace les tentatives ; un aléa évite que tous les clients réessaient simultanément après une panne commune.
delay_cap = min(max_delay, base_delay * 2^retry_index)
sleep_for = random_between(0, delay_cap)
Respectez un Retry-After valide s’il tient dans l’échéance. La temporisation n’autorise pas à elle seule le réessai : les contrôles de défaillance et d’idempotence doivent être franchis.
Définissez un budget total, pas seulement un compteur :
- nombre maximal de tentatives par action utilisateur ;
- durée écoulée maximale, file d’attente et temporisation comprises ;
- tentatives avant et après la sélection d’un groupe de secours ;
- temps minimum pour produire une réponse utile ;
- propagation de l’annulation par l’appelant à toutes les tentatives actives.
Pour une requête interactive avec une échéance de 15 secondes, trois tentatives de 10 secondes ne constituent pas une politique réalisable. Un traitement par lot peut disposer d’un budget supérieur, mais requiert aussi une échéance finale et un ID de tâche persistant.
Éviter l’amplification des réessais entre couches
Si le SDK effectue trois tentatives, la passerelle essaie trois routes pour chacune et un proxy du fournisseur effectue deux appels par route :
3 tentatives du client × 3 tentatives de la passerelle × 2 tentatives vers le fournisseur = 18 appels au fournisseur
Une seule action produit 18 appels au fournisseur. Pendant une panne, les files d’attente, les limites de débit, les coûts et le temps de reprise augmentent.
Attribuez clairement la responsabilité des réessais :
- la passerelle gère le basculement immédiat vers un autre canal au même contrat ;
- l’application décide si l’action utilisateur complète peut être rejouée ;
- les réessais automatiques du SDK sont désactivés ou bornés si la passerelle réessaie déjà ;
- les tâches asynchrones utilisent un ID persistant et un registre de tentatives ;
- aucune couche ne démarre une tentative après l’annulation par l’appelant.
Consignez le numéro de tentative de chaque couche et un ID de requête stable de bout en bout. Sinon, chaque couche semble n’avoir fait que deux ou trois tentatives alors que l’amplification globale reste invisible.
Prouver que la route de secours préserve le contrat
Un même nom public de modèle ne garantit pas des routes équivalentes. Avant d’ajouter un canal à un ensemble transparent de routes de secours, exigez :
| Zone du contrat | Preuve requise |
|---|---|
| Identité du modèle | Le modèle demandé est disponible sans association silencieuse à un autre modèle |
| Point d’accès | La requête Responses ou Chat Completions est acceptée telle que configurée |
| Diffusion | Les types d’événements, la terminaison, l’utilisation et l’annulation fonctionnent |
| Sortie structurée | Le sous-ensemble requis de JSON Schema et le mode strict fonctionnent |
| Appels de fonctions | Les outils, les ID d’appel, les arguments diffusés et les résultats fonctionnent dans les deux sens |
| Limites | Le contexte, la sortie, le débit et la concurrence sont adaptés à la charge de travail |
| Erreurs | Les états et corps d’erreur sont classifiables sans fuite de secrets |
| Utilisation et coût | Les tokens, champs de cache, niveaux de service et règles tarifaires sont définis |
| Sécurité et région | La politique, le trajet des données et les exigences de résidence restent conformes |
Si une route échoue sur un prérequis, elle n’est pas une route de secours transparente pour cette charge de travail. Elle peut rester utilisable sous une politique produit séparée et explicite.
Changer de modèle est toujours une décision produit. Définissez les modèles autorisés, la qualité minimale, le prix maximal, le contrat des outils et l’information visible par l’utilisateur. Une route en erreur ne justifie pas le passage silencieux à un modèle moins cher ou moins capable.
Comprendre la sémantique actuelle de Modelflare
Modelflare recherche des chemins admissibles pour le modèle demandé par le client de l’API. Une clé d’API standard possède un groupe principal et éventuellement des groupes de secours ordonnés. Une clé d’API intelligente évalue les groupes accessibles selon sa stratégie de routage. Aucun mécanisme ne doit remplacer silencieusement le modèle demandé.
L’admission RPM au niveau du groupe intervient avant la facturation et la requête au fournisseur. Si le groupe sélectionné est plein, un groupe de secours ordonné ou un candidat du routage intelligent peut être évalué ; sans groupe admissible, la réponse est 429.
Dans un groupe, la priorité des canaux fixe l’ordre de basculement entre comptes. Après une erreur du fournisseur, le canal défaillant est exclu et la sélection continue. Le basculement actuel entre canaux est indépendant de RetryTimes et AutomaticRetryStatusCodes ; il s’arrête en cas de succès, d’épuisement des routes, d’annulation par l’appelant ou après le début de la sortie vers le client.
Ces décisions internes de chemin pour le même modèle n’autorisent pas une boucle illimitée côté client. Consultez Routage fiable des API d’IA pour les groupes et les canaux, puis Diagnostic des erreurs d’API d’IA pour distinguer les erreurs de politique de la passerelle des défaillances du fournisseur.
Conserver les preuves de chaque tentative
Un 200 final ne prouve pas que la première route a réussi. L’ID du canal final ne décrit pas les tentatives échouées. Conservez au minimum :
- ID de requête stable et ID de corrélation visible par l’appelant ;
- séquence des tentatives et références de groupe/canal ;
- modèle et contrat du point d’accès pour chaque tentative ;
- état de l’échec, classe d’erreur et phase du flux ;
- état de la sortie vers le client ;
- jalons temporels et état d’annulation ;
- utilisation en entrée, en sortie et des tokens en cache, lorsqu’elle est disponible ;
- attribution des coûts pour chaque tentative terminée ou facturable ;
- motif final : succès, routes épuisées, annulation, résultat partiel ou arrêt par politique.
Ne conservez pas les clés d’API, les instructions ou réponses brutes ni les identifiants du fournisseur uniquement pour diagnostiquer les changements de route. Des classes d’erreur expurgées et des métadonnées temporelles suffisent généralement ; les archives de requêtes doivent être restreintes, temporaires et activées explicitement.
Tester la politique avant le trafic de production
Avec les véritables limites du protocole et des entrées sûres et déterministes :
- désactivez le canal principal avant les en-têtes et vérifiez la route suivante pour le même modèle ;
- retournez une limitation de débit et contrôlez les limites de tentatives ainsi que
Retry-After; - annulez l’appel et prouvez qu’aucune nouvelle tentative ne démarre ;
- rompez le flux après la sortie et excluez toute répétition transparente ;
- envoyez une requête non valide et prouvez que le basculement ne la masque pas ;
- répétez un flux d’outils et vérifiez qu’un seul effet externe est produit ;
- épuisez toutes les routes et vérifiez une erreur finale claire ;
- examinez le registre des tentatives et rapprochez l’utilisation et les coûts.
Déployez d’abord sur une petite charge de travail. Surveillez séparément le nombre de tentatives, le succès après basculement et le taux de succès brut, avec un moyen rapide de retirer une route défaillante. L’objectif n’est pas de multiplier les basculements, mais de rétablir le service en sécurité dans une échéance bornée, sans changer le contrat du modèle et avec une preuve pour chaque tentative.