Les garde-fous à la passerelle
- Leçon 12
- 35 min
- Module 4 : La passerelle de modèles
Où nous en sommes
Dans la dernière leçon, nous avons imposé des limites à chaque agent pour arrêter une boucle avant qu'elle coûte cher. Mais la passerelle transmet encore tout le contenu des requêtes : un numéro de carte ou une clé collée dans un billet. Dans cette leçon, nous ajoutons des vérifications des données à la passerelle. Nous mesurons leur coût en temps et en blocages erronés, puis décidons lesquelles doivent rester dans l'application. Nous commençons par la sécurité à l'aéroport.
Leçon 12 sur 21 · Gouverner les agents d'IA : passerelles, registres et contrôlesLes garde-fous à la passerelle
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
Arrêtez les données qui ne doivent jamais atteindre un modèle au seul endroit où passent tous les appels. Utilisez les classes de données, le masquage et les blocages à la passerelle. Mesurez ensuite le coût de chaque règle en temps et en blocages erronés. Gardez dans l’application les vérifications qui doivent connaître la tâche.
Avant de commencerCe qu’il faut savoir et avoir sous la main
Ce que vous devez savoir
- Le trajet dans la passerelle, présenté dans Une seule porte pour les appels de modèles, et ses limites, dans Quotas, budgets et limites de débit.
- Les classes de données de Larkfield (publiques, internes, personnelles, de paiement), présentées dans Un catalogue de capacités. Le cours Sécurité de l’IA, vie privée et conception responsable explique les menaces et les contrôles de confidentialité associés.
Ce qu’il vous faut sur votre ordinateur
- Le projet dans son état à la fin de la dernière leçon (153 tests réussissent). Les budgets d’équipe doivent être revenus à 40 et 10, et le parc doit fonctionner.
Testé sur macOS (Apple silicon) avec Python 3.12.13. Les commandes Windows et Linux sont fournies, mais n’ont pas été exécutées.
La sécurité à l’aéroport
Section intitulée « La sécurité à l’aéroport »À l’aéroport, chaque bagage passe dans le même scanner. Le personnel cherche les mêmes objets dans chaque bagage : liquides, couteaux, piles. Il ne connaît pas la raison de votre voyage et n’a pas besoin de la connaître. Une règle pour tout le monde, à un endroit que personne ne peut éviter.
Mais la sécurité ne peut pas vérifier si vous prenez le bon vol ou si votre siège vous appartient. La compagnie aérienne le fait à la porte d’embarquement, car elle seule connaît votre réservation. Les deux vérifications sont nécessaires, et aucune ne peut remplacer l’autre.
Le problème : des données qui ne doivent pas sortir
Section intitulée « Le problème : des données qui ne doivent pas sortir »Les clients écrivent des numéros de carte dans les billets de soutien. Le personnel colle une requête qui échoue, avec sa clé, dans une question destinée à l’assistant documentaire. La règle de Larkfield est claire : les données de paiement ne vont jamais à un modèle. Un secret ne quitte jamais l’entreprise dans une requête (prompt). Mais la passerelle de la dernière leçon transmet chaque requête exactement comme l’application l’a envoyée.
Chaque application pourrait vérifier ses propres requêtes. Cinq équipes écriraient alors cinq vérifications différentes, et le résumé hebdomadaire du module 1 n’en aurait aucune. La passerelle voit toutes les requêtes. C’est donc le seul endroit où une règle peut couvrir toutes les applications.
L’idée : des classes de données et des garde-fous à l’entrée
Section intitulée « L’idée : des classes de données et des garde-fous à l’entrée »La passerelle vérifie les données de deux façons.
Une classe de données indique le degré de sensibilité des données d’une requête. Le module 2 en a défini quatre : publiques, internes, personnelles et de paiement. Une requête porte sa classe dans l’en-tête X-Data-Class. Sans cet en-tête, la passerelle utilise la classe la plus sensible de l’enregistrement de l’agent. À la vérification 5, l’agent doit autoriser cette classe dans son enregistrement, et la capacité, dans son contrat. payment (paiement) n’est jamais autorisée. Cette vérification ne coûte presque rien : elle compare des étiquettes. Mais elle fait confiance à l’étiquette. Elle ne peut donc pas trouver un numéro de carte dans une requête étiquetée « interne ».
Un garde-fou est une règle automatique appliquée au texte de chaque requête. Il peut bloquer la requête, masquer une partie du texte (la remplacer avant l’envoi), ou seulement journaliser une correspondance. La passerelle de Larkfield a deux garde-fous, dans config/gateway.yaml :
card-numbers(numéros de carte) : de 13 à 19 chiffres, avec espaces ou traits d’union permis, qui passent la vérification de Luhn. C’est la somme de contrôle des cartes de paiement. Action : masquer.secrets(secrets) : clés d’API, clés privées et mots de passe écrits dans le texte. Action : bloquer.
Exemple détaillé : la vérification de Luhn
Section intitulée « Exemple détaillé : la vérification de Luhn »Le numéro de carte de test 4539 1488 0343 6467 est inventé, mais il passe la vérification. Partez de la droite et doublez un chiffre sur deux. Si le résultat dépasse 9, soustrayez 9 :
| chiffre | 4 | 5 | 3 | 9 | 1 | 4 | 8 | 8 | 0 | 3 | 4 | 3 | 6 | 4 | 6 | 7 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| doublé? | oui | oui | oui | oui | oui | oui | oui | oui | ||||||||
| valeur | 8 | 5 | 6 | 9 | 2 | 4 | 16 − 9 = 7 | 8 | 0 | 3 | 8 | 3 | 12 − 9 = 3 | 4 | 3 | 7 |
La somme est 80. La somme d’un numéro de carte se termine par 0, donc celui-ci passe. Remplacez le dernier chiffre par 8, et la somme devient 81 : il échoue. Essayez avec le code de la passerelle :
python -c "from gateway.guardrails import luhn; print(luhn('4539148803436467'), luhn('4539148803436468'))"True FalseLa plupart des longs nombres dans les billets de Larkfield ne sont pas des numéros de carte. Ce sont des identifiants de commande, des numéros de téléphone ou de suivi. Environ 9 nombres aléatoires sur 10 échouent à la vérification de Luhn. La somme de contrôle les exclut donc de la règle :
python -c "from gateway.guardrails import card_numbers; print(card_numbers('Order LK-640436, card 4539 1488 0343 6467, phone 514 555 0199, ticket 1234567890123'))"['4539 1488 0343 6467']L’identifiant de commande, le numéro de téléphone et le numéro de billet à 13 chiffres restent. Seule la carte est détectée.
Ajouter les fichiers de la leçon et essayer les règles
Section intitulée « Ajouter les fichiers de la leçon et essayer les règles »Les garde-fous et la vérification des classes de données accompagnaient la passerelle complète dans la première leçon de ce module. Cette leçon ajoute leurs tests.
-
Copiez les tests de l’instantané
end-of-m04:Fenêtre de terminal cp ../nextia-learning-labs/C32/snapshots/end-of-m04/tests/test_guardrails.py tests/Fenêtre de terminal Copy-Item ..\nextia-learning-labs\C32\snapshots\end-of-m04\tests\test_guardrails.py tests\Fenêtre de terminal cp ../nextia-learning-labs/C32/snapshots/end-of-m04/tests/test_guardrails.py tests/ -
Exécutez les tests :
python -m pytest -q. La dernière ligne indique159 passed, 1 deselected(159 réussis, 1 désélectionné). Un nouveau test applique les deux règles à chaque requête enregistrée du parc. -
Obtenez le jeton du service de triage :
TOKEN=$(python -m estate token ticket-triage)(PowerShell :$TOKEN = python -m estate token ticket-triage). -
Envoyez un billet contenant un numéro de carte et affichez les en-têtes :
Fenêtre de terminal 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": "fast-small", "messages": [{"role": "user", "content": "Refund please. My card is 4539 1488 0343 6467."}]}'La réponse (avec les en-têtes abrégés) :
HTTP/1.1 422 Unprocessable Entityx-gateway-redacted: card-numbers: 1 card number(s) redactedx-gateway-capability: fast-smallx-gateway-provider: azurex-gateway-model: chat-smallx-gateway-upstream-status: 422{"error":{"code":"no_recording","message":"The provider simulator has no recording of this request (key da656c31c33832049d51). It answers only requests that a course recorded, byte for byte; it never invents an answer.","type":"simulated"}}La passerelle a remplacé le numéro par
[card number removed](numéro de carte supprimé), puis a transmis la requête. Le code 422 vient du simulateur : la requête masquée est nouvelle et aucun cours ne l’a enregistrée. Un vrai modèle répondrait au texte masqué.python -m estate usage --last 1afficheguardrail card-numbers: 1 card number(s) redacted(garde-fou card-numbers : 1 numéro de carte masqué), sans numéro. -
Envoyez une clé dans une requête :
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": "fast-small", "messages": [{"role": "user", "content": "It fails with my key sim-az-service-team-0001"}]}'{"error":{"code":"blocked_by_guardrail","message":"Blocked by a guardrail: secrets: practice_key.","type":"gateway","check":"guardrail"}}Une clé est bloquée, pas masquée. Une clé dans une requête signifie que quelqu’un l’a déjà montrée à une personne. La passerelle arrête donc la requête, et le propriétaire de la clé doit la remplacer.
-
Étiquetez une requête comme contenant des données de paiement :
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" -H 'X-Data-Class: payment' \-d '{"model": "fast-small", "messages": [{"role": "user", "content": "Hello"}]}'{"error":{"code":"data_class_not_allowed","message":"payment data is never sent to a model.","type":"gateway","check":"data_class"}}
Sur Windows, écrivez les corps avec des guillemets échappés, comme dans la première leçon de ce module (non testé).
Le coût de chaque vérification : temps et blocages erronés
Section intitulée « Le coût de chaque vérification : temps et blocages erronés »Un garde-fou a deux coûts. Il ajoute du temps à chaque requête, car il lit tout le texte. Il peut aussi bloquer une requête qu’il devrait laisser passer : un blocage erroné. Pour une équipe de soutien, un blocage erroné est un billet que personne ne trie.
L’équipe du cours a appliqué les règles à chaque requête distincte enregistrée par les applications du parc. Cela représente 2,612 requêtes, d’une longueur médiane d’environ 6,805 caractères. Ce sont de vrais billets, documents et réponses des cours précédents. Les correspondances sont donc réelles.
- La règle des cartes avec la vérification de Luhn a détecté 0 requêtes. La même règle sans somme de contrôle (de 13 à 19 chiffres) en a aussi détecté 0. La règle des secrets en a détecté 0. Sur ce trafic, les deux règles réelles ne bloquent donc rien qu’elles devraient laisser passer.
- Ensemble, les deux règles ont pris 314.2 µs par requête à la médiane, et 452.9 µs au 95e centile. Ces temps ont été mesurés sur le portable de l’équipe du cours. Le travail propre à la réplique entière prenait 0,52 ms dans la première leçon de ce module, contre des secondes pour le modèle.
Prenons maintenant une règle qui semble sûre : « bloquer toute requête contenant 6 chiffres consécutifs ou plus ». Quelqu’un l’a écrite pour arrêter les numéros de carte. Elle a détecté 1,647 requêtes sur 2,612 (63 %) :
Description textuelle du graphique
Quatre barres montrent la part des requêtes distinctes enregistrées de chaque application que la règle « 6 chiffres consécutifs ou plus » bloquerait. Triage : 341 sur 539, 63 %. Flux de travail sur chat-strong : 238 sur 249, 96 %. Assistant documentaire : 226 sur 346, 65 %. Juge de mise en production : 96 sur 399, 24 %. La règle des cartes de Luhn et celle des secrets n’en bloquent aucune.
Tous ces blocages sont erronés : la règle de Luhn n’a trouvé aucune carte dans ces requêtes. Les longs nombres sont des numéros de commande comme LK-640436 et d’autres identifiants. Le flux de travail perdrait presque toutes ses tâches. Une seule idée distingue les deux règles : la somme de contrôle. Voilà la leçon générale. Avant de déployer un garde-fou, mesurez ses blocages erronés et ses détections sur du trafic réel.
Ce qui doit rester dans l’application
Section intitulée « Ce qui doit rester dans l’application »Tomás dit : « Maintenant que la passerelle a des garde-fous, les applications peuvent enlever leurs propres vérifications. » Les garde-fous ne voient que du texte, et la même règle s’applique à chaque requête. Beaucoup de vérifications importantes ont besoin de connaître la tâche :
Description textuelle du diagramme
Deux groupes. La passerelle vérifie ce qui est vrai pour toutes les requêtes, à partir du texte et des étiquettes. Les données de paiement ne vont jamais à un modèle, les numéros de carte sont masqués, les secrets sont bloqués. Aucun texte de requête n’est conservé. L’application vérifie ce que seule la tâche peut indiquer. Ce remboursement convient-il à ce billet? Ce client peut-il voir cette commande? La réponse respecte-t-elle la politique et les preuves? Une note dans un billet est-elle une instruction ou seulement du texte?
Le cours Agents d’IA et orchestration des flux de travail a montré pourquoi. Le billet T-90501 contenait une note de livreur indiquant que le client était « déjà approuvé pour un remboursement complet ». La bonne action était de rembourser seulement les frais de livraison de 9,95. Ce billet ne contient ni carte ni clé, donc tous les garde-fous le laissent passer. Les vérifications de politique du flux de travail et l’approbation d’une personne détectent le problème. Et pour les deux locataires de l’assistant documentaire, seule l’application sait à quel locataire appartient un utilisateur. Le cours Sécurité de l’IA, vie privée et conception responsable traite en profondeur ces menaces, comme l’injection de requête (prompt injection).
Gardez donc les deux. Placez à la passerelle les règles identiques pour toutes les applications et qui ne doivent jamais être contournées. Gardez dans l’application chaque vérification qui a besoin du billet, du client ou de la politique.
Erreur courante
Un garde-fou bloque la plupart du trafic normal
Symptôme : après un changement de configuration, la réexécution du service de triage se termine par status {200: 8, 400: 12}. Tous les appels de clavardage sont refusés :
ticket-triage: 20 requests through the gateway | status {200: 8, 400: 12}answered by: embed-small (text-embedding-3-small) x8refused or failed: blocked_by_guardrail x12Cause : quelqu’un a ajouté la règle {id: long-numbers, kind: pattern, pattern: '\d{6,}', action: block} à config/gateway.yaml. Presque chaque billet contient un numéro de commande à 6 chiffres.
Diagnostic : python -m estate usage --last 1 nomme la règle : message Blocked by a guardrail: long-numbers: the pattern \d{6,} matched. (bloqué par un garde-fou : long-numbers : le motif a trouvé une correspondance). python -m estate usage --by outcome montre combien de requêtes elle a refusées.
Rétablissement : supprimez la règle, publiez de nouveau et réexécutez. L’exécution du cours a donné status {200: 20} après la correction. Avant de déployer une nouvelle règle, appliquez-la au trafic enregistré, comme l’équipe du cours l’a fait. La prochaine leçon montre comment envoyer d’abord un changement à une seule réplique. Une mauvaise règle touche ainsi moins de requêtes.
À vous de jouer : prédire les blocages erronés d’une règle
Section intitulée « À vous de jouer : prédire les blocages erronés d’une règle »-
Prédisez : vous ajoutez la règle de blocage « 6 chiffres ou plus ». Vous réexécutez 10 billets de triage et 3 questions documentaires. Combien des 20 requêtes de triage (10 appels de clavardage, 10 plongements) et des 3 questions bloquera-t-elle? Utilisez le graphique.
-
Ouvrez
config/gateway.yaml. Sousguardrails:, après la lignesecrets, ajoutez cette ligne avec la même indentation :- {id: long-numbers, kind: pattern, pattern: '\d{6,}', action: block} # practice: too broad -
Publiez et réexécutez :
Fenêtre de terminal python -m estate config publish --note "practice: block long numbers"python -m apps.replay ticket-triage --units 10 --via gatewaypython -m apps.replay doc-assistant --units 3 --via gateway -
Supprimez la ligne, publiez de nouveau (
--note "the two guardrails again"), puis réexécutez les 10 billets.
Vérifiez votre prédiction
ticket-triage: 20 requests through the gateway | status {200: 8, 400: 12}answered by: embed-small (text-embedding-3-small) x8refused or failed: blocked_by_guardrail x12tokens: 710 in, 0 out | cost: US$0.0000doc-assistant: 3 requests through the gateway | status {200: 1, 400: 2}answered by: chat-small (gpt-6-luna-2026-09-22) x1refused or failed: blocked_by_guardrail x2tokens: 816 in, 175 out | cost: US$0.0002Les 10 appels de clavardage ont été bloqués, ainsi que 2 des 10 plongements (embeddings). Leur texte contenait aussi un long nombre. Votre graphique prédisait 63 % des requêtes de triage. Cet échantillon était pire, car chacune de ces requêtes de clavardage contenait un long nombre. L’assistant documentaire a perdu 2 questions sur 3. Après la suppression de la règle : status {200: 20}. Cette seule ligne bien intentionnée, à la passerelle, a arrêté le service de triage et l’assistant documentaire en même temps. La prochaine leçon mesure jusqu’où un tel changement se propage.
Vérification des connaissances
Section intitulée « Vérification des connaissances »Vérifiez votre compréhension
Pourquoi la règle des cartes utilise-t-elle la vérification de Luhn? Que produirait sur le trafic de Larkfield une règle « 6 chiffres ou plus », sans somme de contrôle?
Afficher la réponse
La plupart des longs nombres dans les billets sont des identifiants de commande, des numéros de téléphone et des dates. Environ 9 sur 10 échouent à la vérification de Luhn, donc la somme de contrôle les exclut. Sur les 2 612 requêtes enregistrées, la règle de Luhn n’en a détecté aucune. Une règle « 6 chiffres ou plus » en a détecté 1 647 (63 %). Chaque blocage était erroné, par exemple à cause d’un numéro de commande. Elle aurait arrêté la plupart des appels de triage et presque toutes les tâches du flux de travail.
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
Tomás veut supprimer les vérifications de remboursement du flux de travail parce que « la passerelle a maintenant des garde-fous ». Donnez un exemple de vérification qui doit rester dans l'application et dites pourquoi la passerelle ne peut pas la faire.
Afficher la réponse
Vérifier si un remboursement convient à ce billet. Dans le cours Agents d’IA et orchestration des flux de travail, le billet T-90501 contenait une note de livreur. Elle disait que le client était « déjà approuvé pour un remboursement complet ». La politique permettait seulement de rembourser les frais de livraison de 9,95. La passerelle voit du texte et des étiquettes, et la même règle s’applique à chaque application. Il n’y a ni carte ni clé, donc la requête passe. Seule l’application connaît le billet, la commande et la politique, et une personne approuve l’écriture.
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 la requête de l'assistant documentaire avec X-Data-Class : payment, puis une requête contenant une clé dans son texte. Quelle vérification arrête chacune, et quel code l'application reçoit-elle?
Afficher la réponse
La requête de paiement s’arrête à la vérification 5, celle de la classe de données : 403 data_class_not_allowed, « les données de paiement ne sont jamais envoyées à un modèle ». La clé s’arrête à la vérification 9, celle des garde-fous : 400 blocked_by_guardrail, « bloqué par un garde-fou : secrets : practice_key ». Les deux sont refusées avant qu’un fournisseur les voie. Chacune reçoit une ligne d’utilisation avec le nom de la vérification.
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
- La vérification des classes de données compare les étiquettes. L’agent et la capacité doivent autoriser la classe de la requête. Les données de paiement ne vont jamais à un modèle.
- Les garde-fous sont des règles appliquées au texte de chaque requête. Les numéros de carte qui passent la vérification de Luhn sont masqués, et les secrets sont bloqués. Les deux règles ont pris environ 0,3 ms par requête, sans blocage erroné sur 2 612 requêtes enregistrées.
- Une règle qui semble sûre, « 6 chiffres ou plus », bloquerait 63 % des mêmes requêtes. Mesurez une règle sur du trafic réel avant de la déployer.
- La passerelle vérifie ce qui est vrai pour toutes les requêtes. Les vérifications liées à la tâche, comme la pertinence d’un remboursement, restent dans l’application.
Votre projet maintenant : les tests des garde-fous, et 159 tests qui réussissent. Chaque appel de modèle passe maintenant des vérifications d’identité, de limites et de données. Tomás pose donc une bonne question : si la passerelle s’arrête, tous les agents s’arrêtent-ils aussi? Et une mauvaise règle a touché deux applications à la fois. Ensuite, vous arrêtez volontairement des parties de la passerelle. Vous verrez quels choix de conception déterminent ce qui fonctionne encore.
Leçon suivante : Quand la passerelle tombe en panne