Une seule porte pour les appels de modèles
- Leçon 10
- 40 min
- Module 4 : La passerelle de modèles
Où nous en sommes
Dans le module 3, nous avons enregistré chaque application, donné à chacune sa propre identité et construit une première passerelle. Elle refuse tout appel sans enregistrement valide. Mais cette passerelle dit seulement oui ou non : elle ne consigne rien, ne limite rien et n'examine pas les données. Dans cette leçon, nous construisons le parcours complet de la passerelle de modèles. Il comprend onze vérifications et un enregistrement d'utilisation pour chaque appel. Nous commençons dans le service du courrier d'une entreprise.
Leçon 10 sur 21 · Gouverner les agents d'IA : passerelles, registres et contrôlesUne seule porte pour les appels de modèles
1. Pourquoi les agents ont besoin de contrôles de plateforme
2. Demander des capacités, pas des modèles
3. Enregistrer chaque agent
4. La passerelle de modèles
5. Gouverner les outils et les actions
6. Utilisation, preuves et IA fantôme
7. Construire, acheter et déployer
Ce que vous saurez faire
Placez la passerelle de modèles complète devant les applications de Larkfield. Cette porte unique vérifie chaque appel dans un ordre fixe, l’envoie à un modèle et le consigne. Les applications gardent leur API et changent un seul paramètre.
Avant de commencerCe qu’il faut savoir et avoir sous la main
Ce que vous devez savoir
- Ce que contient un enregistrement et pourquoi un agent doit être enregistré, selon Le contenu d’un enregistrement.
- Comment chaque agent obtient son propre jeton et comment la première passerelle refuse un appel sans jeton, selon Une identité par agent.
- Ce qu’est une capacité et comment le catalogue l’associe à un modèle, selon Un catalogue de capacités.
Ce qu’il vous faut sur votre ordinateur
- Le projet
~/projects/ai-estatedans l’état laissé par le module 3 : identique à l’instantanéend-of-m03, avec son.venv. Chaque application doit être enregistrée et les identifiants des cinq applications doivent avoir été délivrés. Si vous commencez ici, suivez la section « Start the estate » (démarrer le parc) du README deend-of-m03. - Le dépôt des laboratoires dans
~/projects/nextia-learning-labs, pour l’instantanéend-of-m04. - Deux terminaux, avec l’environnement virtuel actif dans les deux. Les ports 8320 à 8322 doivent être libres.
Testé sur macOS (Apple silicon) avec Python 3.12.13. Les commandes Windows (PowerShell) et Linux sont fournies, mais elles n’ont pas été exécutées pour ce cours.
Un service du courrier
Section intitulée « Un service du courrier »Imaginez une entreprise où chaque lettre passe par un seul service du courrier. Une commis vérifie que l’expéditeur y travaille. Elle vérifie que son service peut envoyer ce genre de lettre. Elle s’assure aussi qu’aucune lettre contenant une carte bancaire ne sort. Elle la pèse, choisit un transporteur et écrit une ligne dans un registre : l’expéditeur, le transporteur et le coût.
Le personnel ne change pas sa façon d’écrire les lettres. Il les dépose simplement dans un nouveau bac. À la fin du mois, le registre indique ce que chaque service a envoyé et dépensé. La facture du transporteur dit une seule chose : « L’entreprise a envoyé 4 000 lettres ».
Le problème : une porte qui ne retient rien
Section intitulée « Le problème : une porte qui ne retient rien »La première passerelle du module 3 est une porte avec un gardien, mais sans registre. Démarrez le parc et faites-y passer deux applications, comme dans ce module :
python -m estate uppython -m apps.replay ticket-triage --units 5 --via gatewaypython -m apps.replay support-workflow --units 2 --via gatewaypython -m provsim billLa facture, simulée à partir de vos requêtes rejouées :
month,provider,key_id,deployment,requests,tokens_in,tokens_out,cost_usd2026-10,azure,az-key-9,chat-small,5,9594,2025,0.0019722026-10,azure,az-key-9,chat-strong,6,14776,738,0.0369322026-10,azure,az-key-9,embed-small,5,424,0,0.000008Chaque ligne indique maintenant az-key-9 : la clé de la passerelle. Avant la passerelle, la facture séparait au moins les appels par clé. Maintenant, elle ne peut plus dire quelle application a fait un appel. Interrogez plutôt le parc :
python -m estate usagepython -m estate: error: argument command: invalid choice: 'usage' (choose from init, up, down, status, serve, reset, catalog, remap, check, register, list, show, suspend, resume, retire, drain, review, review-due, events, credentials, token, config)Il n’y a aucun enregistrement. La première passerelle n’a pas non plus de limite. Un agent pris dans une boucle pourrait donc appeler un modèle toute la nuit. Et elle n’examine jamais les données d’une requête. Arrêtez le parc avant de le modifier : python -m estate down.
L’idée : une seule porte avec un parcours fixe
Section intitulée « L’idée : une seule porte avec un parcours fixe »Une passerelle d’IA est un service par lequel passent tous les appels de modèles d’une organisation. C’est le service du courrier : elle vérifie l’appelant, décide où envoyer l’appel et le consigne. Ce cours l’appelle la passerelle de modèles, car le module 5 en ajoute une deuxième pour les outils.
La passerelle effectue les mêmes vérifications sur chaque requête, toujours dans le même ordre. La première vérification qui échoue répond, et la requête ne va pas plus loin. Chaque requête, traitée ou refusée, reçoit une ligne dans le stockage d’utilisation : le registre de la passerelle.
Description textuelle du diagramme
L’application envoie une requête avec une capacité, son jeton et ses données. La vérification 1 détermine si la réplique possède sa configuration. La vérification 2 vérifie le jeton, et la vérification 3, l’enregistrement. La vérification 4 détermine si l’enregistrement inclut la capacité. Elle vérifie aussi si le contrat de la capacité fournit ce que la requête exige, comme des outils. La vérification 5 vérifie la classe de données. La vérification 6 détermine si un arrêt d’urgence bloque l’appel. La vérification 7 détermine si chaque contrôle peut s’exécuter et quoi faire si l’un d’eux ne le peut pas. La vérification 8 compare l’utilisation de l’agent à ses limites. La vérification 9 cherche des secrets et des numéros de carte dans le texte. La vérification 10 envoie la requête au fournisseur de l’association, ou à un fournisseur de secours. La réponse contient des en-têtes qui nomment le modèle. La vérification 11 écrit une ligne d’utilisation, même pour un refus.
L’ordre n’est pas aléatoire. Chaque vérification a besoin de ce que les précédentes ont découvert. La passerelle ne peut pas chercher un enregistrement avant de savoir qui appelle. Elle ne peut pas appliquer les limites d’un agent avant de savoir de quel agent il s’agit. Les vérifications peu coûteuses viennent en premier. Celle qui coûte de l’argent, l’appel au fournisseur, vient en dernier. Une requête refusée coûte donc une fraction de milliseconde et rien sur la facture.
Cette leçon construit le parcours complet. Vous utilisez maintenant les vérifications 1 à 4 et 10 à 11. La prochaine leçon porte sur les limites, et la suivante, sur les classes de données et les garde-fous. La dernière leçon de ce module traite du mode de défaillance.
Garder l’interface que les applications utilisent déjà
Section intitulée « Garder l’interface que les applications utilisent déjà »La passerelle utilise la même API que le fournisseur : des complétions de clavardage et des plongements (embeddings) compatibles avec OpenAI. Une application ne change donc pas son code. Elle change trois valeurs. L’URL de base est celle de la passerelle, pas celle du fournisseur. L’identifiant est son propre jeton, pas une clé de fournisseur. Le nom du modèle est une capacité, comme strong-reasoning, pas un déploiement.
Le flux de travail de soutien du cours Agents d’IA et orchestration des flux de travail le montre. Ses appels de modèles passent par une seule classe adaptateur. Cette leçon ajoute un petit fichier, resolver/platform.py. Son adaptateur dirige le même client OpenAI vers la passerelle avec le jeton du flux de travail. Une variable d’environnement, RESOLVER_PROVIDER=gateway, le sélectionne. Rien d’autre ne change dans le flux de travail.
Ajouter les fichiers de la leçon
Section intitulée « Ajouter les fichiers de la leçon »La passerelle complète arrive d’un coup : le code de chaque vérification, le stockage d’utilisation et les paramètres de la passerelle. Les prochaines leçons en activent des parties et les expliquent.
-
Copiez les fichiers de cette leçon depuis l’instantané
end-of-m04. Dans~/projects/ai-estate:Fenêtre de terminal S=../nextia-learning-labs/C32/snapshots/end-of-m04cp $S/gateway/app.py $S/gateway/guardrails.py $S/gateway/telemetry.py gateway/cp $S/estate/usage.py $S/estate/switches.py estate/cp $S/estate/cli/usage.py estate/cli/cp $S/config/gateway.yaml config/cp $S/resolver/platform.py $S/resolver/config.py $S/resolver/__main__.py resolver/cp $S/apps/client.py apps/cp $S/tests/test_usage.py tests/Fenêtre de terminal $S = "..\nextia-learning-labs\C32\snapshots\end-of-m04"Copy-Item $S\gateway\app.py, $S\gateway\guardrails.py, $S\gateway\telemetry.py gateway\Copy-Item $S\estate\usage.py, $S\estate\switches.py estate\Copy-Item $S\estate\cli\usage.py estate\cli\Copy-Item $S\config\gateway.yaml config\Copy-Item $S\resolver\platform.py, $S\resolver\config.py, $S\resolver\__main__.py resolver\Copy-Item $S\apps\client.py apps\Copy-Item $S\tests\test_usage.py tests\Fenêtre de terminal S=../nextia-learning-labs/C32/snapshots/end-of-m04cp $S/gateway/app.py $S/gateway/guardrails.py $S/gateway/telemetry.py gateway/cp $S/estate/usage.py $S/estate/switches.py estate/cp $S/estate/cli/usage.py estate/cli/cp $S/config/gateway.yaml config/cp $S/resolver/platform.py $S/resolver/config.py $S/resolver/__main__.py resolver/cp $S/apps/client.py apps/cp $S/tests/test_usage.py tests/Le nouveau fichier
apps/client.pydonne à chaque rejeu ses propres identifiants d’exécution. Rejouer les mêmes billets crée donc une nouvelle exécution. -
Exécutez les tests :
Fenêtre de terminal python -m pytest -qLa dernière ligne indique
137 passed, 1 deselected(137 réussis, 1 désélectionné). Les deux nouveaux tests vérifient les rapports d’utilisation et les compteurs. -
Ouvrez
config/gateway.yamldans votre éditeur. Il contient les paramètres de la passerelle. Ils comprennent le mode de défaillance de chaque niveau de risque, l’avertissement de budget et deux garde-fous. Ils incluent aussiprompts: keep: neveret les règles d’un changement par étapes. Les prochaines leçons expliquent chaque partie. -
Publiez la configuration pour que la passerelle reçoive les nouveaux paramètres :
Fenêtre de terminal python -m estate config publish --note "the gateway's settings"Published version 2.Told 0 of 1 gateways to refresh now.Le parc est arrêté, donc aucune passerelle n’était là pour recevoir l’avis. Elle lit la nouvelle version au démarrage.
-
Démarrez le parc :
Fenêtre de terminal python -m estate upprovsim up (process 70161) http://127.0.0.1:8320control up (process 70163) http://127.0.0.1:8321gateway up (process 70165) http://127.0.0.1:8322Vos numéros de processus diffèrent. L’adresse des applications est la même que dans le module 3 :
http://127.0.0.1:8322/v1.
Exemple détaillé : un appel dans le parcours complet
Section intitulée « Exemple détaillé : un appel dans le parcours complet »Envoyez un billet de soutien à trier par la passerelle et affichez chaque requête :
python -m apps.replay ticket-triage --units 1 --via gateway --verboseLa sortie, rejouée (la requête de tri du cours MLOps et LLMOps : exploiter l’IA en production et le plongement de ce cours) :
200 fast-small -> chat-small (gpt-6-luna-2026-09-22)200 embed -> embed-small (text-embedding-3-small)ticket-triage: 2 requests through the gateway | status {200: 2}answered by: chat-small (gpt-6-luna-2026-09-22) x1, embed-small (text-embedding-3-small) x1tokens: 1,954 in, 375 out | cost: US$0.0004L’application a demandé deux capacités, fast-small et embed. La passerelle a choisi le modèle pour chacune. Son en-tête de réponse x-gateway-model nommait le modèle qui a répondu. Lisez maintenant l’enregistrement du dernier appel dans la passerelle :
python -m estate usage --last 1ts (the time of the call)request_id 274f4fc12975486dreplica aconfig_version v2.r15agent_id ticket-triageteam servicecapability embedprovider azuredeployment embed-smallmodel_version text-embedding-3-smalldata_class personaltokens_in 62tokens_out 0cost_usd 1.24e-06gateway_ms 0.35upstream_ms 0.93recorded_ms 329.0status 200outcome okrun_id ticket-triage:T-64856:r1:6f6b3dfallback 0degraded 0Votre identifiant de requête et la dernière partie de l’identifiant d’exécution diffèrent, et le cours omet l’heure. Lisez cet enregistrement comme une ligne du registre du service du courrier :
- Qui :
agent_idetteamviennent du jeton et de l’enregistrement, pas de ce que l’application dit d’elle-même. - Pour quoi : la
capability(capacité) demandée par l’application et ladata_class(classe de données) de la requête. Le service de tri n’a envoyé aucun en-têteX-Data-Class. La passerelle a donc choisi la classe la plus sensible de son enregistrement,personal(données personnelles). - Ce qui a répondu : le
provider(fournisseur), ledeployment(déploiement) et lamodel_version(version du modèle) exacte. Quand la réassociation du module 2 déplace une capacité vers un autre modèle, ce champ le montre dès le premier appel. - Le coût : les jetons et
cost_usd(coût en dollars américains), aux prix du catalogue : 62 jetons × 0,02 $ US par million = 0,00000124 $ US. - La durée :
gateway_msmesure le travail propre à la passerelle (0,35 ms), etupstream_ms, le temps de réponse du fournisseur. Le simulateur répond immédiatement;recorded_msest le temps enregistré du modèle réel, 329 ms. - La configuration :
config_version v2.r15désigne la version 2 publiée, avec la révision 15 du registre. Le module 3 a expliqué les révisions; la dernière leçon de ce module utilise la version.
La ligne ne contient ni requête (prompt) ni texte de réponse. La règle est prompts: keep: never dans config/gateway.yaml. La passerelle voit chaque requête, ce qui en fait le pire endroit pour conserver leur texte.
Un appel refusé est aussi consigné
Section intitulée « Un appel refusé est aussi consigné »Demandez une capacité que l’enregistrement du service de tri ne contient pas. Obtenez d’abord le jeton du service :
TOKEN=$(python -m estate token ticket-triage)curl -s -i -X POST http://127.0.0.1:8322/v1/chat/completions \ -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" \ -d '{"model": "strong-reasoning", "messages": [{"role": "user", "content": "Hello"}]}'$TOKEN = python -m estate token ticket-triagecurl.exe -s -i -X POST http://127.0.0.1:8322/v1/chat/completions ` -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" ` -d '{\"model\": \"strong-reasoning\", \"messages\": [{\"role\": \"user\", \"content\": \"Hello\"}]}'TOKEN=$(python -m estate token ticket-triage)curl -s -i -X POST http://127.0.0.1:8322/v1/chat/completions \ -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" \ -d '{"model": "strong-reasoning", "messages": [{"role": "user", "content": "Hello"}]}'HTTP/1.1 403 Forbiddenserver: uvicornx-gateway-request-id: 3ea457c0fbb643ccx-gateway-replica: ax-gateway-config: v2.r15content-length: 154content-type: application/json
{"error":{"code":"capability_not_allowed","message":"ticket-triage's registration does not list strong-reasoning.","type":"gateway","check":"capability"}}Le jeton est valide pendant 10 minutes; dans un nouveau terminal, obtenez-le de nouveau. La réponse nomme la vérification (capability) et indique quoi changer : l’enregistrement, pas la passerelle. Exécutez de nouveau python -m estate usage --last 1. La ligne contient maintenant outcome refused (résultat refusé), check_name capability (vérification de capacité), le même message et aucun fournisseur. La requête n’a jamais quitté la passerelle. Les refus sont aussi des preuves. Dans le module 6, ils montrent quels agents tentent de faire ce que leur enregistrement n’autorise pas.
Explorer
Où cette requête s'arrête-t-elle?
Prédisez d’abord : L'assistant documentaire envoie une requête avec l'en-tête X-Data-Class : personal. Passe-t-elle? Sinon, quelle vérification l'arrête?
- Résultat
- 200 chat-small
- Contrôles passés
- 10 / 10
- Réplique
- a, b ou c
200 : passe chaque contrôle, et chat-small (gpt-6-luna-2026-09-22) répond.
- passe
- passe, dégradé ou avec un repli
- arrête la requête
- non atteint
| # | Contrôle | Ce que la passerelle a trouvé |
|---|---|---|
| 1 | Configuration | La réplique a un instantané de la configuration (elle interroge le plan de contrôle toutes les 2 s). |
| 2 | Identité | Un jeton d’accès valide pour la passerelle de modèles (sub : doc-assistant). |
| 3 | Enregistrement | doc-assistant est enregistré et actif (risque low). |
| 4 | Capacité | fast-small figure dans l’enregistrement et dans le catalogue ; le contrat offre ce que la requête demande. |
| 5 | Classe de données | Pas d’en-tête X-Data-Class : la passerelle prend internal, la classe la plus sensible de l’enregistrement. |
| 6 | Coupe-circuits | Aucun coupe-circuit n’arrête cet agent ni cette capacité. |
| 7 | Mode de défaillance | Chaque contrôle peut s’exécuter. |
| 8 | Limites | Sous ses limites : 60 requêtes par minute, ses jetons du jour, 3 $ US par mois, et le budget de son équipe. |
| 9 | Garde-fous | Aucun numéro de carte et aucun secret dans le texte. |
| 10 | Routage | azure/chat-small répond : chat-small (gpt-6-luna-2026-09-22). |
| 11 | Enregistrement de l’usage | Une ligne d’usage : agent, équipe, capacité, modèle, jetons, coût, durée, résultat. Aucun texte de prompt. |
Calculé à partir des règles de la passerelle ; les résultats concordent avec les exécutions mesurées.
Description textuelle de l’explorateur
Choisissez un des cinq agents : le service de tri, le flux de travail de soutien ou l’assistant documentaire. Vous pouvez aussi choisir le juge des mises en production ou le résumé hebdomadaire, qui n’est pas enregistré. Choisissez ensuite ce qu’il envoie : sa requête habituelle, une requête pour strong-reasoning ou une requête avec des outils. Les autres choix sont des données personnelles, des données de paiement ou une requête contenant une clé. Un tableau montre les 11 vérifications dans l’ordre. Chaque vérification laisse passer la requête, l’arrête avec son code et son message, ou n’est pas atteinte. Par exemple, l’assistant documentaire avec des données personnelles s’arrête à la vérification 5, la classe de données : « doc-assistant is not registered for personal data » (doc-assistant n’est pas enregistré pour les données personnelles). Le service de tri qui demande strong-reasoning s’arrête à la vérification 4 : son enregistrement ne contient pas cette capacité. Le flux de travail avec des outils s’arrête aussi à la vérification 4, car le contrat de strong-reasoning n’inclut aucun outil. Le résumé hebdomadaire s’arrête à la vérification 2 : il n’a pas de jeton, seulement une clé personnelle. La passerelle répond 401 invalid_token. Les données de paiement arrêtent chaque agent à la vérification 5. Une clé dans la requête l’arrête à la vérification 9, les garde-fous.
Chaque application dans le parcours complet
Section intitulée « Chaque application dans le parcours complet »-
Envoyez les requêtes des quatre applications par la passerelle :
Fenêtre de terminal python -m apps.replay ticket-triage --units 5 --via gatewaypython -m apps.replay support-workflow --units 2 --via gatewaypython -m apps.replay doc-assistant --units 3 --via gatewaypython -m apps.replay release-judge --units 3 --via gatewayChacune se termine par
status {200: …}(état 200), avec les mêmes jetons et coûts que dans le module 1. Les réponses sont les mêmes enregistrements. Seule la porte a changé. -
Lisez l’utilisation par agent :
Fenêtre de terminal python -m estate usageagent calls ok refused failed tokens in tokens out US$------------------------------------------------------------------------------------------------------support-workflow 6 6 0 0 14,776 738 0.0369release-judge 3 3 0 0 4,559 309 0.0122ticket-triage 13 12 1 0 11,972 2,400 0.0024doc-assistant 3 3 0 0 2,385 681 0.0006total 25 24 1 0 33,692 4,128 0.0521La ligne du service de tri compte aussi l’exemple détaillé : un billet (2 appels), l’appel refusé et les cinq billets (10 appels).
-
Lisez-la par modèle et par résultat :
Fenêtre de terminal python -m estate usage --by modelpython -m estate usage --by outcome--by model(par modèle) nomme chaque version de modèle qui a répondu. Une ligne-représente l’appel refusé, auquel aucun modèle n’a répondu.--by outcome(par résultat) afficherefused:capability 1(un refus lié à la capacité).
C’est la question à laquelle le module 1 ne pouvait pas répondre avec la facture : quelle application a utilisé quoi, à quel coût? La réponse vient maintenant des enregistrements de la passerelle, par agent et par équipe, et ne dépend pas des clés.
Le flux de travail change un seul paramètre
Section intitulée « Le flux de travail change un seul paramètre »Exécutez l’agent réel du flux de travail de soutien sur le billet T-90103, avec ses appels de modèles par la passerelle :
RESOLVER_PROVIDER=gateway python -m resolver run T-90103 --variant agent_structured --model strong-reasoning$env:RESOLVER_PROVIDER = "gateway"python -m resolver run T-90103 --variant agent_structured --model strong-reasoningRESOLVER_PROVIDER=gateway python -m resolver run T-90103 --variant agent_structured --model strong-reasoningLes premières lignes, rejouées (l’agent structuré du cours Agents d’IA et orchestration des flux de travail sur chat-strong) :
Run T-90103-agent_structured-strong-reasoning-1 | single agent with one JSON step per call (for models without tool calling) | strong-reasoningOutcome: resolve (rule W5) | 2 model call(s), 1 tool call(s) | 4647 tokens in, 266 out | US$0.01195L’agent propose un nouvel envoi et une étiquette de retour gratuite pour une jardinière fissurée, puis attend une personne. Approuvez sa proposition comme dans le cours Agents d’IA et orchestration des flux de travail, avec le même paramètre : RESOLVER_PROVIDER=gateway python -m resolver approve T-90103-agent_structured-strong-reasoning-1 --as agent (dans PowerShell, la variable est encore définie). Les deux modifications sont faites dans la base de données d’exercice. Exécutez de nouveau python -m estate usage : support-workflow a maintenant 2 appels de plus et un coût supplémentaire de 0,0120 $ US. Les appels d’outils du flux de travail s’exécutent toujours dans l’application. La passerelle ne les a pas vus, ce qui nous amène au point suivant.
Ce que la porte ne voit pas
Section intitulée « Ce que la porte ne voit pas »Tomás, un ingénieur en IA, dit ce que beaucoup d’équipes pensent : « Nous avons une passerelle maintenant, donc nous sommes gouvernés. » Le stockage d’utilisation montre pourquoi c’est faux :
- Elle voit les appels de modèles, pas le travail de l’agent. L’appel
get_orderdu flux de travail et les deux écritures approuvées ne sont jamais passés par la passerelle de modèles. Le module 5 place une passerelle d’outils devant eux. - Elle voit seulement ce qui passe par elle. L’assistant documentaire crée les plongements de ses documents sur son propre processeur, avec un modèle local. Ces plongements n’atteignent jamais la passerelle. Une application qui garde une clé de fournisseur peut encore contourner la porte, comme le montre le cas d’échec ci-dessous.
- Elle voit le texte, pas le sens. Elle peut trouver un numéro de carte dans une requête. Elle ne peut pas savoir si un remboursement convient à ce billet. La leçon sur les garde-fous de ce module revient sur ce point.
Ce que coûte la porte
Section intitulée « Ce que coûte la porte »Une porte à chaque appel ajoute du temps. L’équipe du cours l’a mesuré sur un portable avec 271 requêtes de triage enregistrées, envoyées trois fois chacune. Elles passaient directement au simulateur, par une réplique de la passerelle, puis par la porte d’entrée de la dernière leçon du module. Le simulateur répondait aussitôt (vitesse 0), ce qui laisse seulement le temps pris par la porte.
Description textuelle du graphique
Trois barres, le temps médian d’une requête en millisecondes. Directement au simulateur : 0.61 ms. Par une réplique de la passerelle : 1.82 ms. Par la porte d’entrée et une réplique : 2.66 ms. La passerelle ajoute donc environ 1.2 ms, et 2.0 ms avec la porte d’entrée. Le vrai modèle prenait 2,922 ms à la médiane pour les mêmes requêtes.
La passerelle ajoute environ 1.2 ms à la médiane, et 2.0 ms avec la porte d’entrée (p95 : 3.06 ms au total). Le modèle lui-même prenait 2,922 ms pour les mêmes requêtes, soit plus de mille fois plus de temps. Le travail propre à la réplique, y compris la ligne d’utilisation, prenait 0.52 ms. Ces temps viennent d’un seul portable, pas d’une mesure de capacité. Une vraie passerelle fonctionne sur d’autres machines, reliées par un réseau. Mais l’ordre de grandeur reste valable. Pour une application qui attend un modèle pendant plusieurs secondes, les millisecondes de la passerelle ne déterminent pas la conception.
Voici ce qui la détermine :
- Vous n’avez pas besoin d’une passerelle pour une seule application avec un seul fournisseur. Le guide des passerelles de Microsoft indique qu’une passerelle sert des « scénarios précis qui ne sont pas nécessairement présents dans toutes les charges de travail ». Elle devient utile quand plusieurs équipes et agents partagent modèles, fournisseurs et budgets, comme chez Larkfield.
- Elle devient une dépendance partagée. Si la porte tombe en panne, toutes les applications échouent, sauf si elles sont conçues pour cette éventualité. La dernière leçon de ce module traite de ce sujet.
- Elle détient toutes les clés des fournisseurs et voit chaque requête. Elle exige donc un accès strict, des versions de dépendances fixées et aucun texte de requête dans ses enregistrements.
Erreur courante
Le stockage d'utilisation ne montre pas les appels d'une application
Symptôme : vous envoyez la question de l’assistant documentaire, et la reproduction fonctionne :
doc-assistant: 1 requests straight to the provider | status {200: 1}answered by: chat-small (gpt-6-luna-2026-09-22) x1tokens: 779 in, 439 out | cost: US$0.0003Mais python -m estate usage ne montre aucune nouvelle ligne pour doc-assistant.
Cause : l’application n’a pas utilisé la passerelle. La première ligne le dit : « directement au fournisseur ». La reproduction s’est exécutée sans --via gateway (par la passerelle). L’application a donc utilisé son ancienne clé de fournisseur, sim-az-data-team-0002. Dans un vrai parc, c’est une application que quelqu’un a oublié de migrer, ou une copie qui conserve l’ancienne clé.
Diagnostic : le journal du trafic sortant montre l’appel. Sa dernière ligne indique la machine et la clé :
python -m provsim egress...,docs-01,larkfield-ai.openai.azure.example,azure,az-key-2,200,3472docs-01 s’est connecté au fournisseur avec az-key-2, sans passer par la passerelle.
Rétablissement : faites passer l’application par la passerelle (--via gateway; pour le flux de travail, RESOLVER_PROVIDER=gateway). La vraie correction consiste à désactiver l’ancienne clé et à réserver l’accès réseau au fournisseur à la passerelle. Trouver l’IA non enregistrée repère ces appels et active cette règle réseau. La leçon sur le déploiement du module 7 prévoit quand révoquer les anciennes clés.
À vous : prédisez quel contrôle arrête chaque requête
Section intitulée « À vous : prédisez quel contrôle arrête chaque requête »Chaque requête ci-dessous enfreint une règle. Avant de l’envoyer, notez le contrôle qui l’arrête et le code que vous attendez. Utilisez le schéma du parcours d’une requête. Envoyez-les ensuite avec les jetons des bonnes applications.
-
Obtenez les jetons de l’assistant documentaire et du flux de travail :
Fenêtre de terminal DOC=$(python -m estate token doc-assistant)WF=$(python -m estate token support-workflow)Fenêtre de terminal $DOC = python -m estate token doc-assistant$WF = python -m estate token support-workflowFenêtre de terminal DOC=$(python -m estate token doc-assistant)WF=$(python -m estate token support-workflow) -
L’assistant documentaire envoie des données personnelles :
Fenêtre de terminal curl -s -X POST http://127.0.0.1:8322/v1/chat/completions -H 'Content-Type: application/json' \-H "Authorization: Bearer $DOC" -H 'X-Data-Class: personal' \-d '{"model": "fast-small", "messages": [{"role": "user", "content": "Hello"}]}' -
Le flux de travail demande à strong-reasoning un appel d’outil :
Fenêtre de terminal curl -s -X POST http://127.0.0.1:8322/v1/chat/completions -H 'Content-Type: application/json' \-H "Authorization: Bearer $WF" \-d '{"model": "strong-reasoning", "messages": [{"role": "user", "content": "Hello"}], "tools": [{"type": "function", "function": {"name": "get_order", "parameters": {"type": "object"}}}]}' -
Le service de triage demande
vision, avec son jeton de l’exemple détaillé dans$TOKEN:Fenêtre de terminal curl -s -X POST http://127.0.0.1:8322/v1/chat/completions -H 'Content-Type: application/json' \-H "Authorization: Bearer $TOKEN" \-d '{"model": "vision", "messages": [{"role": "user", "content": "Hello"}]}' -
Le résumé hebdomadaire essaie la passerelle avec sa clé Fernway :
Fenêtre de terminal curl -s -X POST http://127.0.0.1:8322/v1/chat/completions -H 'Content-Type: application/json' \-H 'Authorization: Bearer sim-fw-personal-7Q2K9XW4' \-d '{"model": "fast-small", "messages": [{"role": "user", "content": "Hello"}]}' -
Comptez les refus par contrôle avec
python -m estate usage --by outcome.
Sous Windows, écrivez les corps avec des guillemets échappés, comme dans l’exemple détaillé (non testé).
Vérifiez vos prédictions
{"error":{"code":"data_class_not_allowed","message":"doc-assistant is not registered for personal data.","type":"gateway","check":"data_class"}}{"error":{"code":"feature_not_in_contract","message":"strong-reasoning does not offer tool calling (its contract has no tools).","type":"gateway","check":"capability"}}{"error":{"code":"capability_not_allowed","message":"ticket-triage's registration does not list vision.","type":"gateway","check":"capability"}}{"error":{"code":"invalid_token","message":"The token is not a JWT.","type":"gateway","check":"identity"}}L’assistant documentaire s’arrête au contrôle 5 : son enregistrement permet seulement les données internal (internes). Le flux de travail s’arrête au contrôle 4, avant qu’un fournisseur voie la requête. Le contrat de strong-reasoning du module 2 n’inclut aucun outil, car chat-strong refuse les outils par cette API. vision figure au catalogue, mais pas dans l’enregistrement du service de triage. Le contrôle 4 la refuse donc avant de découvrir qu’aucun modèle ne fournit encore la capacité vision. Le résumé s’arrête au contrôle 2 : une clé de fournisseur n’est pas un jeton. Le registre ne donnera pas de jeton au résumé tant que son responsable aura quitté l’organisation. --by outcome (par résultat) montre chaque refus sous son contrôle, et aucun de ces refus ne coûte quoi que ce soit.
Vérification des connaissances
Section intitulée « Vérification des connaissances »Vérifiez votre compréhension
Pourquoi la passerelle vérifie-t-elle le jeton et l'enregistrement avant les limites et les garde-fous, puis le fournisseur en dernier?
Afficher la réponse
Chaque contrôle a besoin de ce que les précédents ont établi. Les limites et les classes de données permises appartiennent à un agent. La passerelle doit donc d’abord savoir quel agent appelle (le jeton) et s’il peut appeler (l’enregistrement). Les contrôles peu coûteux passent en premier. Ainsi, une requête refusée prend une fraction de milliseconde et n’ajoute rien à la facture. L’appel au fournisseur est la seule étape qui coûte de l’argent. Il vient donc en dernier, quand tous les contrôles ont réussi.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Vérifiez votre compréhension
Après la migration, la facture du fournisseur montre tous les appels sur az-key-9. Comment Larkfield connaît-elle maintenant les dépenses du service de triage? Pourquoi une application mal configurée ne peut-elle pas cacher ses appels dans ce total?
Afficher la réponse
Grâce au stockage d’utilisation. La passerelle écrit une ligne par requête, avec l’agent, l’équipe, le modèle qui a répondu et le coût. python -m estate usage les additionne par agent. Une application ne peut pas écrire le nom d’un autre agent dans ses lignes. La passerelle prend ce nom dans le jeton signé, pas dans la requête. Mais le stockage voit seulement les appels qui passent par la passerelle. Une application qui utilise encore une ancienne clé de fournisseur n’y figure pas. Le journal du trafic sortant ou la facture doit la repérer.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Vérifiez votre compréhension
Vérification pratique : envoyez une question de l'assistant documentaire par la passerelle, puis affichez sa ligne d'utilisation. Quels champs indiquent qui a appelé, quel modèle a répondu et combien l'appel a coûté?
Afficher la réponse
python -m apps.replay doc-assistant –units 1 –via gateway, puis python -m estate usage –last 1. Qui : agent_id doc-assistant et team data. Quel modèle : provider azure, deployment chat-small et model_version gpt-6-luna-2026-09-22. Le coût : tokens_in, tokens_out et cost_usd, aux prix du catalogue. La classe de données est internal, la classe la plus sensible de son enregistrement, car la requête n’envoyait aucun en-tête X-Data-Class. La ligne ne contient aucun texte de requête.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Récapitulatif
- Une passerelle d’IA est une seule porte pour chaque appel de modèle. La passerelle de modèles de Larkfield exécute 11 contrôles dans un ordre fixe. Le premier contrôle qui échoue répond avec son propre code.
- Chaque requête, acceptée ou refusée, reçoit une ligne d’utilisation : qui a appelé, pourquoi, quel modèle a répondu, les jetons, le coût et le temps. Aucun texte de requête n’est conservé.
- Les applications gardent l’API compatible avec OpenAI et changent trois valeurs : l’URL de base, leur identifiant d’accès et le nom du modèle. Le flux de travail change un paramètre,
RESOLVER_PROVIDER=gateway. - La passerelle ajoutait environ 1,2 ms à la médiane sur le portable de l’équipe du cours, contre 2,9 secondes pour le modèle. Ses vrais coûts sont ailleurs : une dépendance partagée et les clés qu’elle détient.
- La passerelle voit seulement les appels de modèles, et seulement ceux qui passent par elle.
Votre projet maintenant : toute la passerelle dans gateway/, le stockage d’utilisation dans estate/usage.py, config/gateway.yaml, l’adaptateur de passerelle du flux de travail dans resolver/platform.py, et 137 tests qui réussissent. Vous pouvez maintenant voir qui a appelé quel modèle et combien l’appel a coûté. Mais rien n’arrête un agent qui appelle un modèle en boucle : l’enregistrement montre seulement le coût après coup. Vous allez maintenant définir les limites qui l’arrêtent.
Leçon suivante : Quotas, budgets et limites de débit