Diagramme d'architecture d'une passerelle API LLM pour le routage multi-fournisseurs et le basculement

Une passerelle d’API LLM est le plan de contrôle entre le code applicatif et plusieurs fournisseurs de modèles. Une architecture utile n’est pas seulement une URL de proxy. Elle doit authentifier les appelants, faire correspondre les modèles, appliquer des politiques, choisir une route en amont, imposer des quotas, enregistrer l’utilisation, calculer les coûts et décider de ce qui se passe lorsqu’un fournisseur tombe en panne.

Ce guide fournit aux ingénieurs plateforme un schéma d’architecture pratique de passerelle d’API LLM pour le routage multi-fournisseurs et le basculement. Il s’appuie sur les modèles publics de passerelles de Vercel et Pydantic comme références de catégorie, puis limite les affirmations spécifiques à Flatkey aux preuves publiques actuelles : une seule clé API, un endpoint routeur compatible OpenAI à https://router.flatkey.ai/v1, une tarification claire, une facturation unifiée, un tableau de bord pour les clés, l’utilisation et le routage, le basculement automatique et l’équilibrage de charge.

L’objectif est de vous aider à examiner la conception avant que le trafic de production n’en dépende. Utilisez le schéma comme une checklist pour votre propre passerelle, une évaluation de fournisseur ou un test de préproduction Flatkey.

Diagramme d’architecture de la passerelle API LLM

Le diagramme montre le chemin de la requête depuis les applications clientes vers les fournisseurs de modèles en amont. Le centre de l’architecture est la passerelle API LLM. Autour se trouvent les services de stratégie qui rendent le routage sûr à exploiter : portée de clé, mappage de modèle, classe de route, registre de quotas, facturation, journaux, vérifications de santé et règles de repli.

Couche	Responsabilité	Question de conception
Applications clientes	Envoient des requêtes de chat, de réponses, d’image, de vidéo, d’agent ou d’outil.	Quels SDK et formats d’endpoint doivent continuer à fonctionner ?
Endpoint de la passerelle	Reçoit les requêtes via une URL de base stable et une clé API.	Les applications peuvent-elles migrer en ne modifiant que la clé, l’URL de base ou la configuration du fournisseur ?
Authentification et portée de clé	Identifie l’appelant, l’équipe, l’application, l’environnement et l’ensemble de modèles autorisés.	Les environnements de test, de production et le trafic client peuvent-ils être séparés ?
Moteur de stratégie	Applique le mappage de modèle, la classe de route, le budget, le quota et les règles de repli.	La stratégie explique-t-elle pourquoi une requête peut ou ne peut pas utiliser une route ?
Routeur	Sélectionne un fournisseur en amont, un compte, un modèle ou un chemin de secours.	Le routage est-il basé sur une stratégie approuvée plutôt que sur une magie cachée ?
Santé et basculement	Suit les erreurs du fournisseur, les délais d’attente, les nouvelles tentatives, le repli et les conditions d’arrêt.	Quelles défaillances doivent être retentées, faire basculer, mettre en file d’attente ou échouer de manière fermée ?
Journaux, quota et facturation	Enregistre le modèle, la route, le statut, les unités de jetons ou de médias, le coût, le propriétaire et la clé.	Les ingénieurs et la finance peuvent-ils retracer une requête après un incident ?
Fournisseurs en amont	Servent le modèle sélectionné via des API natives du fournisseur ou compatibles.	Quels fournisseurs sont approuvés pour chaque classe de trafic ?

Comment une requête traverse la passerelle

Une passerelle d’API LLM de production doit rendre le parcours de la requête facile à expliquer. Si votre équipe ne peut pas dessiner ce parcours, elle ne peut probablement pas le déboguer pendant une panne ou un contrôle de facturation.

1. Le client envoie une requête. L’application appelle la passerelle avec un nom de modèle, un point de terminaison, des messages ou une entrée média, ainsi qu’une clé API d’application.
2. La passerelle authentifie la clé. La clé est associée à un propriétaire, un environnement, un quota, un ensemble de modèles autorisés et une politique de journalisation.
3. Le moteur de règles classe le trafic. La requête est étiquetée comme chat client, tâche en arrière-plan, évaluation, génération de médias, trafic d’outil de codage ou autre classe de routage.
4. Le routeur choisit une route candidate. Il vérifie le mapping du modèle, la disponibilité du fournisseur, les comptes en amont autorisés, la politique de coût, l’état du quota et toute priorité ou pondération configurée.
5. La passerelle envoie la requête en amont. Selon le fournisseur et le point de terminaison, cela peut conserver une forme de requête compatible OpenAI ou utiliser un protocole natif du fournisseur.
6. La réponse est normalisée lorsque c’est possible. La passerelle renvoie au client la forme de réponse attendue, une erreur, un flux ou une référence de tâche.
7. La requête est enregistrée. Les journaux capturent la route, le modèle, le statut, la latence, les unités d’utilisation, l’estimation de coût, la clé et le propriétaire afin que l’équipe puisse déboguer et rapprocher les dépenses.

C’est pourquoi l’étape de migration d’API compatible OpenAI n’est qu’une partie de l’architecture. Changer une URL de base envoie le trafic vers la passerelle. La préparation à la production dépend ensuite de la politique, du routage, du quota, de la facturation, des journaux et du comportement de repli.

La politique de routage vient avant le basculement

L’erreur d’architecture la plus courante consiste à traiter le basculement comme un bien universel. Une passerelle d’API LLM ne doit pas rejouer aveuglément chaque requête en échec auprès de chaque fournisseur. Elle doit d’abord décider si le chemin de secours est autorisé pour cette classe de trafic.

La documentation publique des passerelles montre pourquoi cette distinction est importante. Pydantic documente des groupes de routage où les fournisseurs peuvent avoir une priorité, un poids et un état actif, ce qui permet le basculement entre des fournisseurs servant le même modèle ou l’équilibrage de charge entre des membres de même priorité. Vercel positionne AI Gateway autour du routage, de la facturation, de l’observabilité, de nombreux modèles et du routage fournisseur/modèle avec des solutions de repli. Ces schémas sont des références utiles, mais votre politique de production doit toujours définir ce qui est acceptable pour votre charge de travail.

Classe de trafic	Règle de routage principale	Règle de basculement
Chat orienté client	Utiliser uniquement des familles de modèles et des fournisseurs approuvés.	Basculer seulement vers un équivalent approuvé, ou renvoyer une erreur contrôlée.
Résumé en arrière-plan	Privilégier le coût et le débit lorsque les exigences de qualité sont stables.	Réessayer, mettre en file d’attente, ou utiliser un modèle approuvé moins coûteux si la qualité de sortie reste acceptable.
Évaluation et benchmarks	Conserver une identité de modèle stable.	Échec fermé ; un fallback caché rend les résultats difficiles à comparer.
Génération de médias	Respecter la forme de l’endpoint, le cycle de vie des tâches, la politique média et le budget.	Échec fermé sauf si le modèle alternatif possède le même contrat de sortie approuvé.
Workflows d’agents	Respecter la prise en charge des outils, les limites de contexte, la frontière des données et les besoins d’audit.	Fallback uniquement lorsque le comportement des outils et la gestion des données restent valides.

Le texte public de Flatkey indique qu’il route plusieurs comptes amont avec commutation automatique et équilibrage de charge. Utilisez cela comme point de départ produit, puis définissez quelles classes de trafic peuvent basculer automatiquement et lesquelles doivent échouer de manière fermée.

Le basculement a besoin d’une condition d’arrêt

Chaque conception de basculement d’passerelle d’API LLM a besoin d’une condition d’arrêt. Sans elle, une requête mal formée peut se transformer en cascade d’appels invalides répétés, de dépenses dupliquées, de journaux confus et d’un comportement utilisateur incohérent.

Une échelle pratique des échecs ressemble à ceci :

1. Rejeter avant l’amont : échouer de manière fermée pour une authentification invalide, un modèle interdit, un quota dépassé, un point de terminaison non pris en charge ou des paramètres obligatoires manquants.
2. Réessayer le même trajet : ne réessayer que lorsque l’erreur est vraisemblablement transitoire, comme un délai d’attente réseau ou un 5xx amont sélectionné.
3. Basculer sur le même contrat : utiliser un autre compte, une autre région ou un autre chemin de fournisseur uniquement s’il sert le même contrat de modèle approuvé.
4. Utiliser une solution de secours approuvée : passer à un autre modèle uniquement lorsque les responsables produit, qualité, conformité et budget approuvent la solution de secours.
5. Mettre en file d’attente ou dégrader : retarder les tâches non urgentes lorsqu’un repli immédiat serait coûteux ou risqué.
6. Renvoyer une erreur contrôlée : s’arrêter lorsque la politique indique qu’il ne reste plus de solution sûre.

Le guide sur l’équilibrage de charge et le basculement des API d’IA traite cela plus en détail. Lors de la revue d’architecture, la question importante est de savoir si chaque transition est explicite et observable.

Quota, facturation et journaux font partie du chemin de requête

Le trafic des modèles n’est pas facturé comme du trafic HTTP ordinaire. Une seule passerelle API LLM peut devoir prendre en compte les jetons d’entrée, les jetons de sortie, les jetons mis en cache, les jetons de raisonnement, les unités d’image, la durée vidéo, les appels d’outils, les nouvelles tentatives et les unités de quota spécifiques au fournisseur. Si la facturation et le quota sont traités comme un rapport nocturne, la passerelle ne peut pas empêcher, sur le moment, une utilisation galopante.

Placez le quota et la facturation au plus près de la politique de routage :

• Vérifiez le budget restant de l’appelant avant de transmettre des requêtes coûteuses.
• Bloquez ou signalez les routes dont les données de tarification sont manquantes lorsque les limites de dépenses comptent.
• Enregistrez le modèle sélectionné, la famille de point de terminaison, la route en amont, la clé, le propriétaire, le statut et les unités d’utilisation.
• Séparez les nouvelles tentatives et les appels de repli dans les journaux afin qu’une requête utilisateur ne masque pas plusieurs tentatives auprès du fournisseur.
• Rendez les clés de préproduction et de production visibles comme des centres de coûts différents.
• Exportez suffisamment de données pour la finance, le support et l’examen des incidents.

Le positionnement public actuel de Flatkey inclut une tarification claire, une facturation unifiée, la visibilité de l’utilisation, des limites de quota et un tableau de bord unique pour les clés, l’utilisation et le routage. Un instantané de l’API de tarification publié le jour de la publication a renvoyé 656 lignes de modèles et prenait en charge les métadonnées de point de terminaison pour le trafic compatible OpenAI, OpenAI Responses, Anthropic, Gemini, génération d’images et génération vidéo. Considérez cela comme une preuve datée, puis vérifiez votre modèle et votre unité exacts sur la page de tarification en direct.

Où Flatkey s’intègre dans cette architecture

Flatkey est conçu pour réduire la prolifération des comptes fournisseurs derrière une seule clé. Dans cette architecture de passerelle d’API LLM, Flatkey correspond au point de terminaison de passerelle hébergée, à la couche d’accès fournisseur, au tableau de bord, à la couche d’utilisation/de facturation et à la couche de routage.

Un test de préproduction Flatkey rigoureux devrait ressembler à ceci :

1. Créez une clé hors production dans le tableau de bord Flatkey.
2. Pointez un client vers https://router.flatkey.ai/v1.
3. Exécutez une requête connue comme valide pour la famille d’endpoint dont vous avez besoin.
4. Confirmez que la requête apparaît dans les journaux d’utilisation avec le modèle, le statut, les unités et la preuve de coût.
5. Examinez la page de tarification en direct pour le modèle et l’unité de facturation sélectionnés.
6. Définissez quelles classes de trafic peuvent utiliser la commutation automatique ou l’équilibrage de charge.
7. Exécutez un test d’échec sûr, ou documentez pourquoi la simulation d’échec n’est pas autorisée en préproduction.

N’en déduisez pas un SLA de disponibilité, une garantie de latence, un algorithme de routage exact ni une disponibilité garantie du fournisseur à partir de cet article. L’architecture vous indique ce qu’il faut valider ; vos preuves de préproduction vous indiquent si un déploiement spécifique est prêt.

Liste de contrôle de mise en œuvre

Avant d’envoyer du trafic de production via une passerelle API LLM, assurez-vous que l’architecture dispose de ces contrôles :

Élément de la liste de contrôle	Condition de réussite
Mise à jour de l’URL de base et du SDK	Au moins une requête de préproduction réussit via la passerelle avec le SDK ou le client prévu.
Mappage des modèles et des points de terminaison	Chaque famille de points de terminaison de production dispose d’un modèle, d’un protocole et d’un responsable approuvés.
Portée de la clé	Les clés sont séparées par application, environnement, équipe ou client lorsque nécessaire.
Politique de routage	Les classes de trafic définissent les routes primaires et les routes de secours autorisées.
Condition d’arrêt du basculement	La passerelle sait quand réessayer, basculer, mettre en file d’attente et échouer de manière fermée.
Vérifications des quotas et du budget	Les limites peuvent arrêter ou contraindre le trafic coûteux avant qu’il n’atteigne un fournisseur en amont.
Journaux et observabilité	Les preuves de requête, route, modèle, responsable, statut, usage et coût peuvent être examinées a posteriori.
Retour arrière	L’application peut revenir à sa configuration de fournisseur précédente si le déploiement de la passerelle échoue.

Pour une vue d’ensemble plus large des exigences, commencez par la liste de contrôle de la passerelle API IA. Pour les travaux de comparaison de plateformes, le guide des alternatives à OpenRouter montre en quoi les compromis d’une passerelle gérée diffèrent des places de marché de fournisseurs et des couches de routage auto-gérées.

FAQ

Qu'est-ce qu'une passerelle API LLM ?

Une passerelle API LLM est une couche de contrôle entre les applications et les fournisseurs de modèles. Elle peut centraliser les clés API, l'accès aux modèles, le routage, les quotas, la facturation, les journaux et la politique de basculement pour le trafic LLM.

Que doit inclure l'architecture d'une passerelle API LLM ?

L'architecture d'une passerelle API LLM doit inclure les applications clientes, un endpoint de passerelle stable, l'authentification, la portée des clés, les vérifications de politique, le mappage des modèles, le routage des fournisseurs, les contrôles de santé, les règles de basculement, les quotas, la facturation, les journaux et les fournisseurs en amont.

Le basculement est-il toujours sûr pour le trafic LLM ?

Non. Le basculement n'est sûr que lorsque la route de secours préserve le contrat de modèle approuvé, la frontière des données, le comportement de l'endpoint, les attentes de qualité et la politique de coût. Certains trafics doivent échouer de manière fermée au lieu de basculer.

En quoi une passerelle API LLM diffère-t-elle d'une passerelle API normale ?

Une passerelle API normale gère le trafic API général. Une passerelle API LLM ajoute des préoccupations spécifiques aux modèles, telles que les formats des fournisseurs, l'utilisation des jetons et des médias, le mappage des modèles, la politique de repli, les contrôles de dépenses, l'observabilité des prompts/réponses et le routage spécifique à l'IA.

Où Flatkey s'inscrit-il dans le diagramme ?

Flatkey s'inscrit en tant que couche hébergée de passerelle, de routeur, d'accès aux fournisseurs, d'utilisation, de facturation et de tableau de bord. Son message public prend en charge une seule clé API, https://router.flatkey.ai/v1, une tarification claire, une facturation unifiée, la visibilité de l'utilisation et du routage, le basculement automatique et l'équilibrage de charge.

Conclusion finale

Une passerelle d’API LLM en production devrait rendre le trafic des modèles plus facile à contrôler, et non plus difficile à expliquer. L’architecture doit prévoir un point de terminaison stable, des clés à périmètre limité, un mappage des modèles, des vérifications de politique, des règles de routage, des contrôles de quota et de facturation, des journaux et une condition d’arrêt du basculement.

Flatkey offre aux équipes une seule clé, un point de terminaison de routeur compatible avec OpenAI et un seul tableau de bord pour l’accès aux modèles et les opérations. Pour tester l’architecture avec votre propre charge de travail de préproduction, obtenez une clé et vérifiez le chemin de la requête avant de faire basculer le trafic de production.