Architecture de passerelle d’API IA : une clé, routage des modèles et bascule

Une passerelle d’API IA offre à une application un point de terminaison stable, tandis que l’infrastructure derrière ce point de terminaison peut utiliser plusieurs modèles, fournisseurs, comptes ou régions. L’intérêt ne consiste pas seulement à masquer plusieurs clés API derrière une seule clé. L’intérêt est de créer un point de décision contrôlé pour chaque requête.

Ce point de décision peut répondre à des questions opérationnelles avant que le trafic n’atteigne un fournisseur de modèle :

• Ce client est-il autorisé à appeler le modèle demandé ?
• Quel service en amont satisfait actuellement les exigences de capacité, de latence et de coût de la requête ?
• Ce service en amont est-il suffisamment sain pour recevoir davantage de trafic ?
• La requête peut-elle être retentée en toute sécurité ?
• Quel mécanisme de repli préserve le contrat de réponse ?
• Comment l’équipe expliquera-t-elle ensuite l’itinéraire, le coût et l’échec ?

Ce guide transforme ces responsabilités en une architecture de production. Il montre également où une clé API unique aide, où elle n’aide pas, et comment migrer un client compatible avec OpenAI sans faire de la passerelle une source invisible de surprises de routage.

L’architecture de référence dans un seul chemin de requête

Une requête pratique via une passerelle IA traverse cinq couches :

1. Contrat client : l’application envoie une requête authentifiée vers une seule URL de base stable.
2. Contrôles d’admission : la passerelle valide l’identité, le quota, les autorisations de modèle, les limites de charge utile et les métadonnées de la requête.
3. Politique de routage : un moteur de règles convertit le modèle ou la capacité demandé(e) en cibles en amont éligibles.
4. Contrôles d’exécution : les règles de santé, de concurrence, de délai d’attente, de nouvelle tentative, de repli et de streaming déterminent comment la cible sélectionnée est appelée.
5. Télémétrie et comptabilisation : la passerelle enregistre l’itinéraire sélectionné, l’état de la réponse, la latence, l’utilisation de tokens ou de médias et l’imputation des coûts.

Application / agent
        |
        |  une clé API + un schéma de requête stable
        v
Passerelle d’API IA
  ├─ authentification et politique de tenant
  ├─ registre des alias de modèles et des capacités
  ├─ politique de routage et règles de budget
  ├─ contrôles de santé, de délai d’attente, de nouvelle tentative et de repli
  └─ journaux, traces, utilisation et imputation des coûts
        |
        ├────────> Fournisseur ou déploiement A
        ├────────> Fournisseur ou déploiement B
        └────────> Fournisseur ou déploiement C

La passerelle est donc à la fois un plan de contrôle et un plan de données. Le plan de contrôle stocke les politiques, les identifiants, les alias, les quotas et la configuration de routage. Le plan de données gère les requêtes en direct, les réponses en streaming, les nouvelles tentatives et la télémétrie. Garder ces responsabilités séparées sur le plan conceptuel rend les changements plus sûrs : les opérateurs peuvent mettre à jour la politique de routage sans demander à chaque équipe applicative de livrer un nouveau code client.

Ce que « une clé » devrait signifier

« Une clé » devrait signifier un seul contrat d’identifiant côté application, et non un identifiant partagé par chaque personne, service et environnement.

Une conception saine émet des identifiants de passerelle distincts pour la production, le préproduction, le développement local, l’intégration continue et les charges de travail indépendantes. Chaque clé doit avoir un périmètre restreint, un propriétaire, un quota et un chemin de révocation. La passerelle conserve ensuite les identifiants des fournisseurs côté serveur et associe une identité entrante aux identifiants en amont qu’elle est autorisée à utiliser.

Cela crée une frontière de sécurité utile :

La clé de passerelle ne doit jamais être considérée comme une raison d’assouplir l’hygiène des clés. Placez-la dans un gestionnaire de secrets, jamais dans du code navigateur ni dans un dépôt public, faites-la pivoter et isolez-la par environnement. Pour une liste de contrôle opérationnelle plus détaillée, consultez la gestion sécurisée des clés API pour les produits IA.

Les alias de modèle séparent le contrat client des fournisseurs

Le premier niveau d’abstraction du routage est un alias de modèle. Au lieu de coder en dur un identifiant de modèle spécifique à un fournisseur dans toute une application, le client demande un nom stable tel que :

support-fast
reasoning-high
code-review-default
image-generation-standard

Le registre derrière chaque alias définit un contrat de capacité. Un alias textuel peut spécifier l’appel d’outils, la sortie structurée, une taille de contexte minimale, la prise en charge du streaming et une famille de repli approuvée. Un alias d’image ou de vidéo nécessite des champs différents, tels que les types d’entrée acceptés, les dimensions de sortie, le comportement des tâches asynchrones et les contraintes de sécurité.

Un alias ne doit pas promettre que tous les modèles candidats se comportent de manière identique. Il doit définir le comportement minimal sur lequel l’application peut compter.

alias: support-fast
contract:
  modality: text
  streaming: true
  tools: optional
  structured_output: required
  maximum_latency_ms: 3500
routes:
  - target: provider-a/model-fast
    priority: 1
  - target: provider-b/model-balanced
    priority: 2

C’est cette indirection qui rend précieuse une URL de base stable. Les applications s’intègrent au contrat de l’alias ; les responsables de la plateforme peuvent modifier l’ensemble des cibles après une évaluation, un incident chez un fournisseur, un changement de tarification ou une exigence régionale.

La décision de routage doit être explicite

Le routage en production combine généralement des filtres stricts et un classement souple.

1. Appliquer des filtres stricts d’éligibilité

Supprimez toute cible qui ne peut pas satisfaire la requête. Les filtres courants incluent :

• Modalité et type d’entrée requis
• Exigence de fenêtre de contexte ou de taille de sortie
• Prise en charge de l’appel d’outils ou de la sortie structurée
• Résidence des données ou disponibilité régionale
• Liste d’autorisation du tenant ou du projet
• Politique de sécurité ou de conformité
• Quota actuel, limite de débit ou état de concurrence
• Compatibilité avec le streaming

Une cible qui ne satisfait pas une exigence stricte ne doit jamais l’emporter simplement parce qu’elle est moins chère.

2. Classer les cibles éligibles

Après filtrage, attribuez un score aux routes restantes. Une politique simple peut être plus facile à exploiter qu’un optimiseur opaque :

route score =
  quality_weight × evaluation_score
  - latency_weight × predicted_latency
  - cost_weight × estimated_cost
  - risk_weight × recent_error_rate

Les pondérations doivent varier selon la charge de travail. Un chat interactif peut privilégier le temps jusqu’au premier token. Un job d’extraction nocturne peut privilégier le coût par enregistrement structuré réussi. Un agent de codage peut accorder plus d’importance à la fiabilité des outils et au comportement sur de longs contextes qu’à une faible différence de prix.

3. Enregistrer la raison

Chaque décision de routage doit produire des métadonnées lisibles par machine, telles que :

{
  "requested_alias": "support-fast",
  "selected_target": "provider-a/model-fast",
  "policy_version": "support-fast-2026-07-29.3",
  "selection_reason": "healthy_primary_within_latency_budget",
  "fallback_count": 0
}

Si une équipe ne peut pas reconstruire pourquoi une route a été sélectionnée, elle ne peut pas déboguer la dérive des coûts, les régressions de qualité ou les incidents du fournisseur.

Les vérifications de santé nécessitent plus qu’un HTTP 200

Un upstream peut renvoyer des probes de santé réussies tout en échouant sur le trafic réel du modèle. La santé d’une passerelle IA a donc besoin de plusieurs signaux :

• Santé du transport : échecs de connexion, erreurs TLS, erreurs DNS et timeouts upstream
• Santé de l’API : réponses de limitation de débit, échecs d’authentification, erreurs du fournisseur et réponses mal formées
• Santé du modèle : sortie vide, sortie structurée invalide, appels d’outils défectueux ou segments de streaming incompatibles
• Santé des performances : temps jusqu’au premier token, latence totale, temps d’attente en file et débit
• Santé de la capacité : requêtes concurrentes, pression en tokens par minute, solde du compte ou quota de déploiement

Utilisez une fenêtre glissante plutôt qu’un seul échec. Un disjoncteur peut retirer temporairement une cible après le dépassement de son seuil d’échec ou de latence, puis autoriser des probes limitées avant de rétablir tout le trafic. La détection des valeurs aberrantes peut également expulser un déploiement malsain tout en laissant disponibles les déploiements sains du même fournisseur.

Le principe est bien établi dans l’infrastructure de gateway et de service mesh : les retries, le circuit breaking et la détection des valeurs aberrantes sont des contrôles distincts, et chacun nécessite une politique bornée. Envoy documente ces mécanismes séparément dans ses recommandations sur le retry HTTP, le circuit breaking et la détection des valeurs aberrantes.

Ne réessayez que lorsque la requête est sûre

Les retries améliorent la fiabilité uniquement lorsqu’ils ne multiplient pas le travail ni ne créent d’effets secondaires en double.

Pour une complétion textuelle sans streaming qui a échoué avant l’arrivée du moindre octet de réponse, un seul retry vers la même cible peut être raisonnable. Pour une requête qui déclenche un outil, lance un job d’image ou de vidéo, débite un compte externe, ou a déjà diffusé une sortie partielle, un retry aveugle peut créer des doublons ou corrompre l’expérience utilisateur.

Définissez l’éligibilité au retry à l’aide de trois questions :

1. La demande a-t-elle été acceptée en amont ? Une défaillance de connexion avant l’acceptation est différente d’un délai d’expiration après que le fournisseur a commencé à travailler.
2. Une quelconque sortie a-t-elle atteint le client ? Une fois le streaming commencé, le changement de fournisseur peut produire une réponse discontinue.
3. Existe-t-il une clé d’idempotence ou un enregistrement de déduplication ? Les workflows média de longue durée et les workflows d’agent ont besoin d’une identité d’opération stable.

Une matrice de reprise prudente ressemble à ceci :

Conservez un seul délai de bout en bout. Si le client autorise huit secondes, la passerelle ne peut pas passer sept secondes sur le primaire puis donner encore huit secondes au repli. Chaque tentative consomme le même budget de requête.

Les replis doivent préserver le contrat

Un repli ne consiste pas simplement à « essayer un autre modèle ». C’est un accord sur ce qui peut changer lorsque la route principale échoue.

Définissez les replis à trois niveaux :

1. Même modèle, déploiement ou compte différent : risque comportemental le plus faible ; utile pour les échecs de quota ou régionaux.
2. Famille de modèles équivalente : risque modéré ; nécessite des tests de régression pour le schéma, les outils, la sécurité et le style de sortie.
3. Capacité dégradée : risque le plus élevé ; peut désactiver les outils, réduire le contexte ou renvoyer une réponse en file d’attente au lieu d’une réponse en direct.

Pour chaque alias, documentez :

• Quelles classes de défaillance déclenchent le repli
• Quelles cibles sont compatibles avec le contrat
• Si le client est informé qu’un repli s’est produit
• Le nombre maximal de tentatives et le délai total
• Comment les changements de qualité et de coût sont mesurés
• Si la réponse peut être mise en cache ou rejouée

L’accès régional au fournisseur ajoute une autre dimension. Un fournisseur ou un modèle peut être disponible dans une géographie, un type de compte ou un accord commercial, et indisponible dans un autre. Le routage régional des fournisseurs LLM explique les vérifications distinctes d’accès, de politique et de bascule nécessaires pour ces routes.

Le streaming fait partie du contrat de la passerelle

Les formes de requête compatibles avec OpenAI peuvent simplifier la migration des clients, mais la compatibilité du streaming exige une traduction délibérée. La passerelle doit préserver l’ordre des événements, les raisons de fin, les métadonnées d’utilisation, les fragments d’appels d’outils, la signalisation d’erreur et l’annulation de connexion.

Avant de router deux modèles derrière un seul alias de streaming, testez :

• Temps jusqu’au premier événement et comportement du battement de cœur
• Format delta incrémental du texte
• Assemblage des arguments d’appel d’outil
• Rapport d’utilisation dans l’événement final
• Propagation de l’annulation par le client
• Comportement des délais avant et après le premier événement
• Format des erreurs après que les en-têtes ont déjà été envoyés

N’enterrez pas un redémarrage de flux dans une seule réponse, sauf si le protocole prend explicitement en charge la reprise. Dans la plupart des clients, mélanger une réponse partielle d’un modèle avec une deuxième réponse d’un autre est pire que de renvoyer une erreur claire.

L’observabilité relie le routage aux résultats

Les tableaux de bord de passerelle sont utiles, mais le diagnostic en production nécessite une télémétrie structurée qui puisse associer une requête de modèle à la trace applicative environnante.

Au minimum, capturez :

Évitez par défaut de journaliser les invites et les sorties brutes. N’enregistrez le contenu que lorsque le cas d’usage, la politique de rétention et les attentes des utilisateurs le permettent. Le projet OpenTelemetry maintient des conventions sémantiques pour les systèmes d’IA générative en évolution, qui peuvent aider les équipes à utiliser des noms de spans et de métriques cohérents plutôt que d’inventer un schéma distinct pour chaque fournisseur.

Les contrôles des coûts doivent précéder l’appel en amont

Les rapports de dépenses a posteriori ne peuvent pas empêcher un incident. La politique d’admission et de routage doit évaluer le coût avant d’envoyer le trafic.

Les contrôles utiles incluent :

• Quotas stricts par clé et par projet
• Alertes de budget souples
• Nombre maximal d’unités d’entrée ou de sortie
• Listes d’autorisation de modèles par environnement
• Routage tenant compte du coût pour les charges de travail flexibles
• Politique de cache pour les requêtes répétables
• Limites de concurrence pour les tâches média coûteuses
• Interrupteurs d’arrêt pour un modèle, un fournisseur, un locataire ou une route

Le moteur de routage a besoin d’un tableau de prix versionné et d’une couche cohérente de normalisation de l’utilisation. Sinon, une politique de « modèle le moins cher » peut comparer des unités incompatibles ou des prix obsolètes. Pour un cadre qui sépare les tarifs des fournisseurs, les frais de plateforme et les contrôles opérationnels, voir tarification de passerelle IA.

Une migration OpenAI-compatible minimale

Le plus petit changement côté client est généralement une nouvelle clé API, une nouvelle URL de base et un nouveau nom de modèle. Avec une passerelle compatible OpenAI, le code de l’application peut conserver la même bibliothèque cliente :

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

response = client.chat.completions.create(
    model="your-model-or-alias",
    messages=[
        {"role": "user", "content": "Résumez ce rapport d’incident."}
    ],
)

Cette modification du code est la partie la plus simple. Une migration sûre comporte quatre étapes :

1. Inventorier le contrat actuel. Consignez les modèles, les paramètres, le comportement de streaming, les outils, les schémas, les délais d’attente et la gestion des erreurs.
2. Exécuter des évaluations en parallèle ou hors ligne. Comparez la qualité des résultats, la validité du schéma, la latence et le coût sur des requêtes représentatives.
3. Mettre une charge de travail en canari. Commencez avec un pourcentage de trafic limité et un chemin de retour en arrière immédiat.
4. Activer séparément les fonctionnalités de routage. Changez d’abord le point de terminaison, puis ajoutez les alias, puis le basculement basé sur l’état de santé, puis l’optimisation des coûts ou de la qualité.

La séparation de ces changements rend les incidents plus faciles à diagnostiquer. Si la migration du point de terminaison, le remplacement du modèle, la politique de nouvelle tentative et l’optimiseur de coûts sont tous lancés en même temps, l’équipe ne saura pas quelle variable a causé une régression. Le starter d’intégration Flatkey détaille davantage le modèle de migration du base URL.

Liste de contrôle de préparation à la production

Utilisez cette liste de contrôle avant de considérer la passerelle comme une infrastructure partagée.

Contrat client

• Base URL stable et schéma de requête versionné
• Alias nommés avec des capacités minimales documentées
• Enveloppe d’erreur cohérente et identifiants de requête
• Streaming, appels d’outils et sortie structurée testés

Identité et sécurité

• Clés séparées par service et environnement
• Identifiants de fournisseur côté serveur
• Périmètres de clés, quotas, rotation et révocation
• Journalisation des invites et des réponses désactivée ou explicitement régie

Routage et fiabilité

• Filtres d’éligibilité stricts avant le classement par coût
• Politiques de routage et données de prix versionnées
• État de santé basé sur le comportement réel des requêtes
• Nouvelles tentatives bornées avec une seule échéance de bout en bout
• Cibles de secours compatibles avec le contrat
• Disjoncteur et sondes de récupération

Opérations

• Télémétrie du motif de routage, des erreurs du fournisseur, de la latence et de l’utilisation
• Alertes sur le taux de secours, le taux d’erreur, la dérive des coûts et la pression des quotas
• Interrupteurs d’arrêt par modèle et par route
• Procédure d’exploitation pour les pannes du fournisseur et de la passerelle
• Chemin d’urgence direct ou alternatif pour les charges de travail critiques

Comment Flatkey s’intègre à cette architecture

Flatkey fournit une clé API unique, une seule base URL compatible OpenAI et un tableau de bord unique pour l’accès aux modèles pris en charge, l’utilisation et la facturation. Son routeur est conçu pour réduire les comptes fournisseurs séparés et les chemins d’intégration fragmentés tout en prenant en charge le basculement en amont et l’équilibrage de charge.

Pour une équipe applicative, l’avantage architectural est une frontière client stable : pointez un client compatible OpenAI vers https://router.flatkey.ai/v1, sélectionnez un modèle pris en charge et conservez l’accès aux modèles derrière le même point de terminaison de passerelle. Les équipes doivent tout de même définir leurs propres contrats au niveau de l’application, seuils d’évaluation, périmètres de clé, budgets de défaillance et attentes de repli.

La meilleure architecture de passerelle ne rend pas le routage invisible. Elle rend le routage modifiable, borné et explicable.

FAQ

Qu’est-ce qu’une passerelle d’API IA ?

Une passerelle d’API IA est un intermédiaire entre les applications et les fournisseurs de modèles. Elle centralise l’authentification, l’accès aux modèles, le routage, les contrôles de fiabilité, le suivi de l’utilisation et les politiques, tout en exposant une API stable côté client.

Une seule clé API signifie-t-elle que tous les services partagent la même clé ?

Non. Cela signifie que les applications utilisent des identifiants émis par la passerelle au lieu de gérer directement chaque identifiant de fournisseur. Les services de production, les environnements et les équipes doivent tout de même recevoir des clés distinctes avec des périmètres définis.

Qu’est-ce que le routage des modèles ?

Le routage des modèles est le processus consistant à filtrer les modèles ou déploiements éligibles et à sélectionner une cible selon les capacités, les politiques, l’état de santé, la latence, la qualité, le coût, la région ou la capacité.

Quelle est la stratégie de repli la plus sûre ?

Commencez par le même modèle sur un autre déploiement ou compte sain. Le repli entre modèles ne doit intervenir qu’après des tests montrant que la cible alternative préserve le schéma, les outils, le streaming, la sécurité et le contrat de qualité de l’application.

Une passerelle peut-elle réessayer une réponse en streaming sur un autre modèle ?

En général non, une fois que la sortie est parvenue au client. Changer en cours de flux peut combiner des réponses partielles incompatibles. Utilisez une erreur de flux claire, sauf si le client et la passerelle implémentent un protocole explicite de reprise.

Une API compatible OpenAI suffit-elle pour une migration sans changement ?

Elle réduit les changements liés au SDK et à la forme des requêtes, mais les équipes doivent quand même vérifier les paramètres pris en charge, les erreurs, les événements de streaming, les appels d’outils, la sortie structurée, la comptabilisation des tokens et le comportement du modèle.