Aller au contenu
English

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.

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 mainEnviron 40 minutes

Ce que vous devez savoir

Ce qu’il vous faut sur votre ordinateur

  • Le projet ~/projects/ai-estate dans 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 de end-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.

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 ».

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 :

Fenêtre de terminal
python -m estate up
python -m apps.replay ticket-triage --units 5 --via gateway
python -m apps.replay support-workflow --units 2 --via gateway
python -m provsim bill

La facture, simulée à partir de vos requêtes rejouées :

month,provider,key_id,deployment,requests,tokens_in,tokens_out,cost_usd
2026-10,azure,az-key-9,chat-small,5,9594,2025,0.001972
2026-10,azure,az-key-9,chat-strong,6,14776,738,0.036932
2026-10,azure,az-key-9,embed-small,5,424,0,0.000008

Chaque 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 :

Fenêtre de terminal
python -m estate usage
python -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.

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.

Un flux, de haut en bas. L'application envoie une requête avec une capacité, son jeton et ses données. Vérification 1, configuration : aucun instantané donne 503 control_unavailable. Vérification 2, identité : aucun jeton valide donne 401. Vérification 3, enregistrement : non enregistré ou suspendu donne 403. Vérification 4, capacité : absente de l'enregistrement ou du contrat donne 403 capability_not_allowed ou 400 feature_not_in_contract. Vérification 5, classe de données : non autorisée donne 403 data_class_not_allowed. Vérification 6, arrêts d'urgence : un arrêt donne 403 stopped. Vérification 7, mode de défaillance : si un contrôle ne peut pas s'exécuter et que le risque est élevé, 503 control_unavailable. Vérification 8, limites : dépasser une limite donne 429 rate_limited, run_step_limit, quota_exhausted ou budget_exhausted. Vérification 9, garde-fous : un secret donne 400 blocked_by_guardrail; un numéro de carte est masqué. Vérification 10, acheminement : aucun fournisseur ne répond donne 503 no_provider_available. Sinon, 200 avec des en-têtes qui nomment le modèle. Vérification 11, consignation : une ligne d'utilisation pour chaque requête.
Le parcours de la passerelle de modèles. Chaque vérification transmet la requête ou répond avec son propre code. Chaque requête reçoit une ligne d'utilisation.
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.

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.

  1. 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-m04
    cp $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.py donne à chaque rejeu ses propres identifiants d’exécution. Rejouer les mêmes billets crée donc une nouvelle exécution.

  2. Exécutez les tests :

    Fenêtre de terminal
    python -m pytest -q

    La 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.

  3. Ouvrez config/gateway.yaml dans 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 aussi prompts: keep: never et les règles d’un changement par étapes. Les prochaines leçons expliquent chaque partie.

  4. 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.

  5. Démarrez le parc :

    Fenêtre de terminal
    python -m estate up
    provsim up (process 70161) http://127.0.0.1:8320
    control up (process 70163) http://127.0.0.1:8321
    gateway up (process 70165) http://127.0.0.1:8322

    Vos 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 :

Fenêtre de terminal
python -m apps.replay ticket-triage --units 1 --via gateway --verbose

La 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) x1
tokens: 1,954 in, 375 out | cost: US$0.0004

L’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 :

Fenêtre de terminal
python -m estate usage --last 1
ts (the time of the call)
request_id 274f4fc12975486d
replica a
config_version v2.r15
agent_id ticket-triage
team service
capability embed
provider azure
deployment embed-small
model_version text-embedding-3-small
data_class personal
tokens_in 62
tokens_out 0
cost_usd 1.24e-06
gateway_ms 0.35
upstream_ms 0.93
recorded_ms 329.0
status 200
outcome ok
run_id ticket-triage:T-64856:r1:6f6b3d
fallback 0
degraded 0

Votre 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_id et team viennent 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 la data_class (classe de données) de la requête. Le service de tri n’a envoyé aucun en-tête X-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), le deployment (déploiement) et la model_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_ms mesure le travail propre à la passerelle (0,35 ms), et upstream_ms, le temps de réponse du fournisseur. Le simulateur répond immédiatement; recorded_ms est le temps enregistré du modèle réel, 329 ms.
  • La configuration : config_version v2.r15 dé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.

Demandez une capacité que l’enregistrement du service de tri ne contient pas. Obtenez d’abord le jeton du service :

Fenêtre de terminal
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 Forbidden
server: uvicorn
x-gateway-request-id: 3ea457c0fbb643cc
x-gateway-replica: a
x-gateway-config: v2.r15
content-length: 154
content-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?

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
Assistant documentaire, sa requête habituelle, rien n’est en panne
#ContrôleCe que la passerelle a trouvé
1ConfigurationLa réplique a un instantané de la configuration (elle interroge le plan de contrôle toutes les 2 s).
2IdentitéUn jeton d’accès valide pour la passerelle de modèles (sub : doc-assistant).
3Enregistrementdoc-assistant est enregistré et actif (risque low).
4Capacitéfast-small figure dans l’enregistrement et dans le catalogue ; le contrat offre ce que la requête demande.
5Classe de donnéesPas d’en-tête X-Data-Class : la passerelle prend internal, la classe la plus sensible de l’enregistrement.
6Coupe-circuitsAucun coupe-circuit n’arrête cet agent ni cette capacité.
7Mode de défaillanceChaque contrôle peut s’exécuter.
8LimitesSous ses limites : 60 requêtes par minute, ses jetons du jour, 3 $ US par mois, et le budget de son équipe.
9Garde-fousAucun numéro de carte et aucun secret dans le texte.
10Routageazure/chat-small répond : chat-small (gpt-6-luna-2026-09-22).
11Enregistrement de l’usageUne 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.

Calculé à partir des règles de la passerelle dans gateway/app.py et des enregistrements. Les codes d'erreur et les messages sont ceux de la passerelle.
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.

  1. Envoyez les requêtes des quatre applications par la passerelle :

    Fenêtre de terminal
    python -m apps.replay ticket-triage --units 5 --via gateway
    python -m apps.replay support-workflow --units 2 --via gateway
    python -m apps.replay doc-assistant --units 3 --via gateway
    python -m apps.replay release-judge --units 3 --via gateway

    Chacune 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é.

  2. Lisez l’utilisation par agent :

    Fenêtre de terminal
    python -m estate usage
    agent calls ok refused failed tokens in tokens out US$
    ------------------------------------------------------------------------------------------------------
    support-workflow 6 6 0 0 14,776 738 0.0369
    release-judge 3 3 0 0 4,559 309 0.0122
    ticket-triage 13 12 1 0 11,972 2,400 0.0024
    doc-assistant 3 3 0 0 2,385 681 0.0006
    total 25 24 1 0 33,692 4,128 0.0521

    La ligne du service de tri compte aussi l’exemple détaillé : un billet (2 appels), l’appel refusé et les cinq billets (10 appels).

  3. Lisez-la par modèle et par résultat :

    Fenêtre de terminal
    python -m estate usage --by model
    python -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) affiche refused: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.

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 :

Fenêtre de terminal
RESOLVER_PROVIDER=gateway python -m resolver run T-90103 --variant agent_structured --model strong-reasoning

Les 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-reasoning
Outcome: resolve (rule W5) | 2 model call(s), 1 tool call(s) | 4647 tokens in, 266 out | US$0.01195

L’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.

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_order du 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.

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.

Mesuré sur le portable de l'équipe du cours (271 requêtes de triage × 3 passages, simulateur à vitesse 0); ce n'est pas une capacité. Latence enregistrée du modèle pour les mêmes requêtes : 2 922 ms à la médiane.
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) x1
tokens: 779 in, 439 out | cost: US$0.0003

Mais 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é :

Fenêtre de terminal
python -m provsim egress
...,docs-01,larkfield-ai.openai.azure.example,azure,az-key-2,200,3472

docs-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.

  1. 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)
  2. 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"}]}'
  3. 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"}}}]}'
  4. 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"}]}'
  5. 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"}]}'
  6. 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é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.

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.

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.

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