Checklist de repli du modèle le travail commence avant qu’un routeur ne bascule le trafic. Un modèle de repli peut sauver une requête lorsque l’itinéraire principal échoue, mais il peut aussi modifier la qualité des réponses, le coût en jetons, le comportement des outils, la sémantique du streaming, le traitement des données et la visibilité des incidents. Traitez le repli comme une politique de production évaluée, et non comme un simple interrupteur « essayer un autre modèle ».
Ce guide fournit aux équipes IA de production une checklist de repli du modèle pratique pour les passerelles LLM, les routeurs compatibles OpenAI et les parcours d’API IA multi-fournisseurs. Il se concentre sur les questions qui doivent être résolues avant que le repli ne touche le trafic client : le modèle de secours est-il suffisamment bon, suffisamment abordable, suffisamment compatible avec les outils, suffisamment observable et autorisé pour la même frontière de données ?
Flatkey est pertinent parce que le texte public de son produit positionne flatkey.ai autour d’une clé API unique, d’une URL de base compatible OpenAI à https://router.flatkey.ai/v1, d’une tarification claire, d’une facturation unifiée, d’analyses d’utilisation, de contrôles du tableau de bord, de basculement automatique, d’équilibrage de charge et de limites de quota. Ces fonctionnalités facilitent la centralisation du routage. Elles ne suppriment pas le besoin d’une checklist de repli du modèle explicite que l’ingénierie, le produit, la finance et la sécurité peuvent examiner.
Réponse rapide : la checklist de fallback de modèle
Utilisez cette checklist de fallback de modèle comme point de décision go/no-go avant d’activer un fallback de modèle LLM en production. Chaque ligne doit avoir un responsable, une condition de validation et une condition d’arrêt.
| Garde-fou | Question de validation | Condition d’arrêt | Preuves à conserver |
|---|---|---|---|
| Qualité | Le fallback répond-il aux mêmes évaluations spécifiques à la tâche que le chemin principal ? | Bloquez le fallback s’il modifie les faits requis, le format, la posture de sécurité ou le ton visible par le client au-delà du budget de régression accepté. | Jeu d’évaluation, taux de réussite, exemples d’échec, notes des reviewers, périmètre de fallback approuvé. |
| Coût et quota | Le fallback peut-il s’exécuter dans le même budget, plafond de tokens, pool de quota et hypothèses d’unité de tarification ? | Bloquez le fallback s’il consomme le budget d’une autre équipe, d’un autre compte, d’une autre modalité ou d’un autre fournisseur sans approbation. | Capture d’écran tarifaire, estimation d’utilisation, responsable des dépenses, responsable du quota, nombre maximal de tentatives. |
| Outils et schéma | Le fallback peut-il gérer les mêmes appels de fonctions, sorties structurées, effets de bord des outils et formats de réponse ? | Bloquez le fallback si les appels d’outils requis, le schéma JSON, les événements de streaming ou les champs de sortie ne sont pas pris en charge ou sont incohérents. | Tests du contrat d’outil, validation de schéma, vérifications des appels d’outil requis/parallèles, notes de sécurité de relecture. |
| Streaming et frontière de retry | Le fallback n’est-il autorisé qu’avant toute sortie visible par l’utilisateur, ou l’interface est-elle conçue pour redémarrer après une sortie partielle ? | Bloquez un fallback silencieux après une sortie partielle, une exécution d’outil ou tout effet de bord non idempotent. | Chronologie des tentatives, horodatage de la première sortie, indicateur de sortie partielle, raison du retry/fallback. |
| Conformité et frontière des données | Le fallback est-il approuvé pour la même classe de données, la même région, le même compte fournisseur, la même politique de rétention et le même mode de journalisation ? | Bloquez le fallback en cas de problèmes de sécurité, de confidentialité, de DLP, d’authentification, d’allowlist IP, de région non prise en charge ou de fournisseur/compte non approuvé. | Tag de classe de données, liste de fournisseurs approuvés, mode de journalisation, décision de politique, approbation du reviewer. |
| Observabilité | Les opérateurs peuvent-ils reconstituer le modèle demandé, le modèle sélectionné, le fournisseur, les tentatives, les erreurs, le coût et le résultat final ? | Bloquez le fallback si le succès final masquerait des tentatives de chemin échouées ou l’impact sur le budget. | ID de requête, ID de politique de routage, chaîne des tentatives de modèle, erreurs du fournisseur, utilisation, coût, lien du tableau de bord. |
Pourquoi le fallback n’est pas la même chose qu’un retry
Un retry envoie la même requête via la même route logique après une panne transitoire. Un fallback change le modèle, le fournisseur, le compte, la famille de points de terminaison ou la surface de comportement. C’est pourquoi un fallback de passerelle IA nécessite un processus d’approbation plus strict qu’un retry réseau standard.
La documentation actuelle d’OpenAI sur les codes d’erreur distingue les erreurs d’authentification, les limites de débit, l’épuisement du quota, les erreurs serveur, la surcharge et les ralentissements soudains du taux de requêtes. Seules certaines de ces catégories sont des candidates au retry ou au fallback. Une erreur 500 ou une surcharge temporaire peut justifier un retry limité. Une erreur 401, une région non prise en charge, un blocage de sécurité, une requête mal formée ou un budget mensuel épuisé devraient généralement échouer en mode fermé jusqu’à ce que le propriétaire corrige le problème sous-jacent.
La documentation publique de Vercel AI Gateway décrit des fallbacks de modèles ordonnés et des métadonnées de tentatives par fournisseur comme un schéma de passerelle : la passerelle peut essayer des modèles de secours lorsque le modèle principal échoue ou n’est pas disponible, et les métadonnées peuvent montrer quels essais de modèle/fournisseur ont été effectués. Utilisez cela comme preuve de schéma, pas comme affirmation de comportement de Flatkey. Dans votre propre système, la liste de contrôle du fallback de modèle doit définir quelles pannes sont autorisées à passer à la route suivante et quelles pannes doivent arrêter le processus.
Définir les niveaux de repli avant le trafic
Tous les replis ne présentent pas le même risque. Un basculement vers un fournisseur sur le même modèle peut mieux préserver le comportement qu’une famille de modèles différente, tandis qu’un petit modèle moins coûteux peut convenir à la classification mais pas aux réponses du support client. Classez chaque route dans un niveau avant d’activer le basculement automatique.
| Niveau de repli | Utilisation typique | Risque principal | Règle d’approbation |
|---|---|---|---|
| Même modèle, fournisseur ou compte différent | Panne du fournisseur, problème au niveau du compte, problème de capacité régionale. | Les paramètres spécifiques au fournisseur, la tarification, les limites de débit et la journalisation peuvent différer. | Approuver après vérification de la parité des points de terminaison, des paramètres, des quotas, des coûts et des champs de journal. |
| Même famille, modèle plus petit ou plus rapide | Tâches sensibles à la latence, résumés légers, extraction simple. | Régressions de qualité et de suivi des instructions. | Approuver uniquement pour les workflows qui passent les évaluations avec le modèle plus petit. |
| Famille de modèles différente | Panne du fournisseur ou récupération liée à une fonctionnalité spécifique. | Le style de sortie, le comportement de sécurité, l’appel d’outils, la profondeur de raisonnement et l’utilisation de jetons peuvent changer. | Exiger l’approbation du produit, de l’ingénierie et des équipes de conformité pour chaque workflow. |
| Mettre en file d’attente au lieu d’un repli | Tâches par lots, enrichissement non urgent, reprises de traitement, génération de rapports. | Résultat utilisateur retardé, accumulation cachée de tâches, données obsolètes. | Approuver lorsque l’expérience utilisateur peut tolérer le délai et que le travail conserve les métadonnées de propriété. |
| Échec fermé | Authentification, autorisations, sécurité, frontière des données, épuisement du budget, requête mal formée. | Une défaillance à court terme est visible pour les utilisateurs ou les opérateurs. | Valeur par défaut pour les cas de politique, de sécurité, de conformité et de budget non approuvé. |
Garde qualité : évaluez la tâche, pas le nom du modèle
La ligne qualité d’une checklist de repli de modèle doit utiliser des évaluations spécifiques au workflow. Un repli peut convenir pour la génération de titres et être inadapté à la revue de contrats. Il peut convenir pour un libellé de classification et être risqué pour un workflow d’assistance utilisant des outils. La politique doit tester la forme de tâche qui s’exécutera réellement en production.
Constituez un petit jeu d’évaluation de repli, mais représentatif :
- Exemples « golden » : sorties réussies du chemin principal pour les cas normaux, les cas limites et les clients à forte valeur.
- Exemples d’échec : prompts qui ont précédemment provoqué des hallucinations, des refus, une dérive de schéma, un mauvais usage des outils ou des réponses trop longues.
- Vérifications de régression : faits requis, affirmations interdites, schéma de sortie, ton, règles de citation et posture de sécurité.
- Revue humaine : notes des relecteurs pour les exemples où les contrôles automatisés ne peuvent pas déterminer la qualité.
- Périmètre du repli : workflow exact, environnement, niveau client, liste de modèles et nombre maximal de tentatives pour lesquels le repli est approuvé.
Les exemples d’évaluation d’OpenAI décrivent des évaluateurs capables de vérifier des champs précis, de comparer à la vérité terrain ou d’évaluer une sortie de manière plus globale. Utilisez ce modèle pour l’approbation des replis : chaque candidat au repli doit avoir des critères de réussite/échec concrets, et non une évaluation vague du type « ça a l’air bien ».
Point de contrôle des coûts : tarifer le chemin de repli, pas seulement le principal
Le repli peut transformer un incident de fiabilité en incident de coût s’il déplace silencieusement le trafic vers un modèle plus coûteux, une fenêtre de contexte plus grande, une modalité différente, un niveau de fournisseur premium ou un pool de quotas séparé. La partie coût de cette checklist de repli de modèle doit répondre à quatre questions avant le lancement :
- Quelle est l’unité de coût ? Les jetons de texte, l’entrée mise en cache, les jetons de raisonnement, la sortie d’image, les secondes de vidéo ou une unité propre au fournisseur peuvent modifier la structure du budget.
- Quel est le coût maximal d’une requête ? Définissez les limites d’entrée, de sortie, de contexte, de raisonnement et de tentatives pour le chemin de repli.
- Quel budget est utilisé ? N’acheminez pas le trafic de production vers une autre équipe, un autre client, un compte BYOK ou le solde d’un fournisseur sans approbation.
- Comment la finance le verra-t-elle ? Les journaux doivent distinguer le modèle demandé, le modèle चयनné, le fournisseur, le motif de routage, l’utilisation des jetons et le coût.
La documentation de l’AI Gateway de Cloudflare est ici une preuve de modèle utile : sa page de journalisation répertorie des métadonnées de requête telles que le fournisseur, le statut, l’utilisation des jetons, le coût et la durée ; des métadonnées personnalisées peuvent associer des requêtes à une équipe ou à des identifiants de test ; et des en-têtes de coût personnalisés peuvent remplacer les hypothèses de coût publiques d’un modèle pour la comptabilisation au niveau de la requête. Les utilisateurs de Flatkey devraient rendre visible le même type de preuves via le tableau de bord Flatkey, les journaux d’utilisation et la revue de facturation avant de s’appuyer sur le repli automatique.
Portail outils et schéma : prouvez la compatibilité avant de basculer
Les workflows très orientés outils ont besoin d’une checklist de repli de modèle plus stricte que la simple génération de texte. Le guide de function calling d’OpenAI définit les outils comme des fonctionnalités que vous exposez au modèle, et décrit un flux en عدة étapes : envoyer les outils disponibles, recevoir un appel d’outil, exécuter le code côté application, renvoyer la sortie de l’outil, puis recevoir la réponse finale. Cela signifie que le modèle de secours doit être testé sur l’ensemble de la boucle d’outils, et pas seulement sur la première réponse.
Exécutez des tests de compatibilité des outils pour :
- Sélection de l’outil : le modèle de secours appelle-t-il le bon outil lorsque le modèle principal le fait ?
- Arguments : les champs requis, les énumérations, les ID et les objets JSON imbriqués sont-ils validés ?
- Effets secondaires : l’outil est-il idempotent, ou un secours pourrait-il répéter un remboursement, un e-mail, une mise à jour de ticket ou une écriture en base de données ?
- Outils parallèles : si le parcours principal utilise des appels d’outils parallèles, le modèle de secours prend-il en charge le même comportement ou faut-il une sérialisation ?
- Sortie structurée : le modèle de secours satisfait-il le schéma attendu par le code en aval ?
- Refus et résultats liés aux politiques : l’application peut-elle détecter lorsque le modèle de secours a refusé ou bloqué une requête dangereuse ?
La documentation d’OpenAI sur les sorties structurées indique que les Structured Outputs sont conçues pour que les réponses du modèle respectent un JSON Schema fourni, et distingue le function calling des schémas de response-format. Elle précise aussi que les sorties structurées peuvent malgré tout contenir des erreurs et qu’il faut les gérer avec des instructions, des exemples ou des sous-tâches plus simples lorsque c’est nécessaire. Pour une politique de repli, cela signifie que la validation du schéma est nécessaire mais pas suffisante : validez aussi le contenu et l’effet secondaire.
Passerelle de streaming : ne masquez pas la sortie partielle
Le streaming ajoute une frontière distincte à la liste de contrôle de repli du modèle. Avant le premier jeton visible, le repli peut être un choix de routage propre. Une fois que l’utilisateur a vu une sortie partielle, un changement silencieux de route peut fusionner deux réponses de modèle différentes et masquer l’incident.
Utilisez cette règle par défaut :
- Avant la première sortie : le repli peut être autorisé si l’échec est transitoire et que la route de repli est préapprouvée.
- Après la première sortie : marquez la réponse comme incomplète et demandez à l’utilisateur de redémarrer ou de réessayer explicitement.
- Après un effet de bord d’outil : échouez de manière fermée ou utilisez un chemin de récupération idempotent. Ne rejouez pas aveuglément.
- Après un blocage de sécurité ou de conformité : échouez de manière fermée. Ne redirigez pas vers un modèle moins contraint pour obtenir une réponse.
Cela s’associe aux playbooks de stratégie de retry de l’API IA et de répartition de charge et basculement de l’API IA. Les décisions de retry, de repli, de mise en file d’attente et d’échec fermé doivent partager une seule taxonomie des échecs afin que le succès final n’efface pas le chemin de routage.
Compliance Gate: Conservez la même frontière de données
Un chemin de repli peut franchir des frontières invisibles dans un simple chemin de code. Il peut utiliser un fournisseur, un compte, une région, un mode de journalisation, un propriétaire d’identifiants, un paramètre de conservation ou une politique de modération différents. La ligne de conformité d’une checklist de repli de modèle doit être suffisamment explicite pour qu’un évaluateur puisse répondre oui ou non avant que le trafic ne bascule.
| Boundary | Question To Ask | Default Posture |
|---|---|---|
| Data class | Is this fallback allowed for customer content, internal docs, regulated data, secrets, or PII-like payloads? | Fail closed unless the data class is approved for the fallback route. |
| Provider and account | Does the route use the same vendor account, BYOK account, or approved vendor list? | Require account-owner approval before cross-account spillover. |
| Logging mode | Are prompts and outputs stored, or is the route metadata-only? | Use metadata-only where sensitive payload retention is not approved. |
| Region or access policy | Could the fallback violate an IP allowlist, unsupported-region rule, or customer data-location rule? | Fail closed and alert the owner. |
| Safety and policy | Was the primary route blocked by safety, moderation, DLP, or tool authorization? | Do not bypass a policy block with fallback. |
La documentation de journalisation de Cloudflare fournit un exemple public concret de l’importance de cette question : les journaux de requêtes peuvent inclure les prompts et les réponses, tandis qu’un en-tête par requête peut ignorer le stockage du contenu et ne conserver que les métadonnées. Votre politique de repli Flatkey devrait de même décider quand le contenu brut peut être stocké et quand les preuves de routage doivent se limiter aux métadonnées.
Champs d’observabilité pour la revue du fallback
Si le journal indique seulement « request succeeded », la checklist de fallback du modèle a échoué. Les opérateurs doivent voir la chaîne de tentatives qui a conduit au succès ou à l’échec.
| Champ | Pourquoi c’est important |
|---|---|
| ID et version de la politique de routage | Indique quelle politique approuvée a autorisé ou bloqué le fallback. |
| Modèle demandé et modèle sélectionné | Sépare l’intention de l’utilisateur de la décision du routeur. |
| Fournisseur, compte, famille d’endpoint et région le cas échéant | Indique si la requête a franchi une frontière opérationnelle ou de conformité. |
| Classe d’erreur et code d’état par tentative | Distingue une défaillance transitoire du fournisseur d’un problème d’authentification, de quota, de forme de requête ou de politique. |
| IDs d’appel d’outil, résultat de validation du schéma et état des effets de bord | Empêche l’exécution en double d’outils et la dérive de schéma cachée. |
| Utilisation, coût, cache et propriétaire du quota | Relie la reprise de la fiabilité aux dépenses et à la revue budgétaire. |
| Drapeau de sortie partielle et horodatage de la première sortie | Précise si le fallback s’est produit avant ou après une sortie visible par l’utilisateur. |
| Disposition finale | Une des options suivantes : succès du primaire, succès du fallback, mis en file d’attente, nouvelle tentative utilisateur requise, échec fermé. |
L’article compagnon sur les journaux d’observabilité de l’API IA va plus loin sur les champs d’incident. Pour le fallback, donnez la priorité à la chaîne de tentatives de routage et au motif d’arrêt.
Plan de déploiement d’un staging Flatkey
Utilisez ce plan de déploiement lors des tests d’un repli du gateway IA via Flatkey ou tout routeur compatible OpenAI. Il maintient la checklist de repli du modèle fondée sur des preuves plutôt que sur des hypothèses.
- Créer une clé de staging : éloignez les tests de repli du trafic client de production.
- Confirmer la route de base : pointez un client compatible OpenAI vers
https://router.flatkey.ai/v1et vérifiez le modèle principal, la famille d’endpoint, la ligne d’utilisation et la visibilité dans le tableau de bord. - Capturer les faits actuels du catalogue : le 18 juin 2026, l’API de tarification Flatkey a renvoyé 638 lignes de modèles, 23 fournisseurs, et des familles d’endpoint incluant OpenAI chat completions, OpenAI Responses, Anthropic messages, Gemini generateContent, la génération d’images et la génération de vidéos. Considérez cela comme une preuve datée, pas comme un contrat permanent.
- Choisir un niveau de repli : commencez par le repli le moins risqué qui convient au workflow, comme une route sur le même modèle ou un modèle à coût inférieur clairement circonscrit pour une tâche limitée.
- Exécuter des évaluations avant le trafic : testez des exemples de référence, des cas limites, la validation de schéma, les appels d’outils, les limites du streaming et les blocages de politique.
- Exécuter des tests d’échec forcé : simulez un timeout du principal, une limite de taux, une erreur fournisseur, une requête malformée, une erreur d’authentification, une saturation du quota, un blocage de politique et un échec du flux après sortie.
- Examiner les logs et la facturation : confirmez que le modèle demandé, le modèle sélectionné, la raison du repli, la tentative fournisseur, l’utilisation, le coût, la clé, l’équipe et l’environnement sont visibles.
- Définir une règle de retour arrière : désactivez le repli automatiquement ou manuellement si les garde-fous de qualité, de coût, de politique ou d’observabilité échouent.
Associez cela à architecture de gateway API LLM, à checklist de gateway API IA d’entreprise et à tarification Flatkey lorsque vous passez du staging à la production.
Modèle de politique de repli
Ce modèle n’est pas un contrat d’API Flatkey. C’est un artefact de revue que votre équipe peut adapter avant d’activer le repli.
{
"policy_id": "support-chat-fallback-v1",
"workflow": "customer-support-chat",
"environment": "production",
"primary_route": {
"model": "primary-approved-model",
"endpoint_family": "openai-chat-completions"
},
"fallback_routes": [
{
"model": "approved-backup-model",
"allowed_reasons": ["primary_timeout", "temporary_5xx", "provider_unavailable"],
"blocked_reasons": ["auth_error", "invalid_request", "quota_exhausted", "safety_block", "unapproved_data_class"],
"requires_eval_pass": true,
"requires_cost_owner": true,
"requires_tool_contract_pass": true,
"allow_after_partial_output": false
}
],
"limits": {
"max_total_attempts": 2,
"max_elapsed_ms": 12000,
"max_input_tokens": 8000,
"max_output_tokens": 1200,
"max_estimated_cost_usd": 0.05
},
"logging": {
"record_attempt_chain": true,
"record_requested_and_selected_model": true,
"record_error_class_per_attempt": true,
"record_usage_and_cost": true,
"payload_logging_mode": "metadata_only"
},
"rollback": {
"disable_on_schema_failures": true,
"disable_on_unapproved_cost_spike": true,
"disable_on_policy_boundary_error": true
}
}Questions fréquentes
Qu’est-ce qu’une liste de contrôle de repli de modèle ?
Une liste de contrôle de repli de modèle est une liste d’examen de production destinée à déterminer si un modèle ou un fournisseur de secours peut gérer le trafic en toute sécurité lorsque le chemin principal échoue. Elle doit couvrir la qualité, le coût, le quota, les outils, le comportement de streaming, les limites de conformité, l’observabilité et les règles de retour arrière.
Quand dois-je utiliser un repli de modèle LLM plutôt que de relancer ?
Utilisez un repli de modèle LLM lorsque le chemin principal présente une défaillance transitoire côté fournisseur ou une indisponibilité, et que le chemin de secours est déjà approuvé pour le même flux de travail. N’utilisez pas le repli pour des requêtes mal formées, des erreurs d’authentification, des blocages de sécurité, un épuisement du budget ou des classes de données non approuvées.
Comment un repli de passerelle d’IA doit-il gérer les appels d’outils ?
Un repli de passerelle d’IA doit prouver la compatibilité des outils avant la mise en production. Testez la sélection des outils, les arguments JSON, les champs requis, la validation du schéma, les effets de bord, l’idempotence, les appels parallèles et le format de la réponse finale. Si un outil a déjà provoqué un effet de bord, ne rejouez pas la requête via un autre modèle, sauf si l’opération est explicitement sans danger à répéter.
Étape de révision finale
Avant d’activer le repli, posez une question directe : pouvons-nous expliquer pourquoi cet itinéraire a basculé, ce qui a changé, combien cela a coûté, s’il a franchi une frontière de politique, et comment le restaurer ? Si la réponse est non, la checklist de repli du modèle n’est pas complète.
Flatkey peut centraliser l’accès aux modèles, le routage, la facturation, la visibilité de l’utilisation et la gestion des clés derrière un seul chemin compatible OpenAI. Utilisez ce point central pour rendre les décisions de repli testables avant que le basculement automatique n’atteigne le trafic de production. Lorsque vous êtes prêt à valider les itinéraires en préproduction, obtenez une clé et commencez avec une politique de repli approuvée.
