Une passerelle d’IA qui garde les données personnelles hors de ses journaux
Un assistant de support doit travailler avec les noms et les adresses e-mail des clients, donc le modèle qu’il appelle doit les voir. La passerelle placée devant ce modèle tient des journaux pour l’audit et le débogage, et ces journaux ne doivent pas les conserver. Ce workspace compile une telle passerelle en manifestes Kubernetes.
Ce qui s’en charge est une valeur de la passerelle elle-même, values.log_masking sur core/gateway/litellm. Elle masque la copie de chaque appel que la passerelle remet à ses journaux, et rien d’autre : le modèle reçoit la requête exactement telle que l’appelant l’a envoyée, et l’appelant reçoit la réponse exactement telle que le modèle l’a écrite. C’est la différence avec la Feature core/data-masking, qui cache le texte au modèle lui-même. Les deux sont des alternatives, et la section ci-dessous sur le choix entre elles montre ce qui se passe lorsque les deux sont définies sur une même passerelle.
Ce workspace ne rédige aucune entité de catalogue qui lui soit propre. Les trois fichiers d’entité présents ici — un Aggregate, un Manifest et une Release — sont tout ce que quiconque écrit.
Ce qu’il construit
| instance | Component du catalogue | ce qu’il est ici |
|---|---|---|
router | core/gateway/litellm | la passerelle d’IA : un seul alias publié, assistant, servi par le modèle câblé à son socket models |
gpt | core/ai-model/openai | le modèle derrière cet alias, l’API d’OpenAI elle-même, atteint en tant que référence : rien ne s’exécute pour lui dans le cluster |
analyzer | core/security/presidio-analyzer | trouve les passages sensibles dans un texte |
anonymizer | core/security/presidio-anonymizer | remplace les passages qui lui sont remis |
Trois arêtes uses : le socket models de la passerelle vers le modèle, portant comme credential la clé que la passerelle lui présente, et ses sockets pii_analyzer et pii_anonymizer vers les deux services de reconnaissance. L’Aggregate rattache ces informations d’identification sans nommer de secret, et la Release les nomme dans l’infra du rattachement : un Secret que le namespace contient déjà, que la réalisation du Manifest référence et ne rend pas. La valeur values.log_masking de la passerelle liste ce qu’il faut masquer : une expression régulière pour les numéros de ticket de l’entreprise sous patterns, et les types d’entités PERSON et EMAIL_ADDRESS sous entities. Il n’existe pas de liste par défaut ; une passerelle qui ne liste ni l’un ni l’autre ne masque rien dans ses journaux, et est rendue exactement comme sans la valeur.
Générer l’exemple
Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.
Écrivez l’exemple dans un nouveau dossier qui porte son nom :
aggrega scaffold --example ai-gateway-log-maskingElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :
cd ai-gateway-log-maskingBuild
aggrega build --release release.yaml --auto-pullUne release a besoin d’un lockfile avant son build, et les lockfiles sont générés plutôt que livrés, de sorte qu’un clone neuf n’en contient aucun. Résolvez-en un d’abord, ou laissez le build le remplir :
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildCe workspace résout les entités du catalogue depuis le registre par défaut que nomme .aggrega-config.yaml. C’est la propre Recipe de la passerelle qui écrit le masquage des journaux, de sorte que le build n’exécute aucun plugin au-delà de ceux que porte le compilateur.
Le build affiche, <workspace> désignant le dossier de cet exemple :
[… omitted: the resolution's summary, a notice that core/referenced-secret declares origin in both of its pillars, and a total build time, which differs per run]Build completed: 9 files written to <workspace>/distAvec un assistant IA
Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.
Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier de l’espace de travail ne contient pas encore de dossier `ai-gateway-log-masking`, appelez une seule fois l’outil `scaffold` avec `example` défini sur `ai-gateway-log-masking` et sans `dir` : il écrit l’exemple dans un nouveau dossier `ai-gateway-log-masking`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `ai-gateway-log-masking`, `release` défini sur `release.yaml`, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi quels fichiers le build a écrits ; ils se trouvent sous `ai-gateway-log-masking/dist/`.L’arborescence rendue
dist/helm/├── analyzer-default-service.yaml├── analyzer-deployment.yaml├── anonymizer-default-service.yaml├── anonymizer-deployment.yaml├── gpt-service.yaml├── router-default-service.yaml├── router-deployment.yaml└── router/ ├── litellm-gateway-config/ │ └── configmap.yaml └── request-guard/ └── request-guard.yamlLa valeur n’apporte aucun fichier à elle. La Recipe de la passerelle l’écrit dans la configuration de la passerelle, et ajoute à la ConfigMap de la passerelle un module que cette configuration charge. Le modèle rend un seul fichier, gpt-service.yaml, un Service qui fait correspondre un nom interne au cluster à l’hôte de l’API d’OpenAI, api.openai.com ; sa clé n’en rend aucun, parce que le Secret qui la contient existe déjà.
La table de routage, le début du corps de configuration de la passerelle, a une seule entrée, écrite à partir de ce que publie le modèle — son endpoint, l’URL de base de l’API d’OpenAI, et son nom de modèle — et nommant la variable sous laquelle la Recipe de la passerelle livre la clé de la connexion :
model_list: - model_name: "assistant" litellm_params: model: "openai/gpt-4o" api_base: "https://api.openai.com/v1" api_key: os.environ/LITELLM_MODEL_ASSISTANT_API_KEYL’entrée du garde-fou
Voici le corps de configuration de la passerelle, la clé config.yaml de dist/helm/router/litellm-gateway-config/configmap.yaml, à partir de sa section litellm_settings :
[… omitted: the routing table]litellm_settings: callbacks: - /etc/litellm-request-guard/request_field_filter.filter - log_masking.withhold_failed_calls redact_messages_in_exceptions: trueguardrails: - guardrail_name: "router.log-masking" litellm_params: guardrail: log_masking.LogMasking default_on: true mode: logging_only patterns: - pattern_type: regex name: "ticket" pattern: "\\bTCK-[0-9]{6}\\b" action: MASK pii_entities_config: "PERSON": MASK "EMAIL_ADDRESS": MASKgeneral_settings: disable_error_logs: trueLa Recipe de la passerelle écrit tout cela à partir de values.log_masking, et nomme l’entrée d’après la passerelle, ici router, avec un point là où les entrées de garde-fou qu’écrivent les réalisations de la bibliothèque standard portent un trait d’union, de sorte qu’aucun de leurs rattachements, quel que soit son nom, ne peut prendre la place de cette entrée. Cinq choses méritent d’y être lues.
mode: logging_only est le mode propre à la passerelle pour un garde-fou qui s’exécute là où un appel terminé est remis à ses journaux, et nulle part ailleurs. La classe que charge l’entrée s’y tient quoi que nomme une entrée, de sorte qu’elle n’est jamais appelée sur une requête avant que la requête soit transmise, ni sur une réponse avant que la réponse soit renvoyée.
default_on: true l’exécute à chaque appel. Un appelant ne peut pas le désactiver depuis la requête, y compris par une requête demandant de désactiver les garde-fous toujours actifs de la passerelle.
Le motif atteint la passerelle exactement tel qu’il a été rédigé. Il est mis en correspondance à l’intérieur de la passerelle, sans tenir compte de la casse, et chaque correspondance est remplacée définitivement par le nom du motif en majuscules entre crochets : [TICKET_REDACTED]. La passerelle compile l’expression à son démarrage, et une expression qui ne compile pas l’empêche de démarrer — le compilateur transmet la chaîne sans la lire.
Les types d’entités sont trouvés par les deux services de reconnaissance. L’entrée ne nomme aucune adresse : la passerelle lit les deux dans son environnement, que la Recipe de la passerelle remplit à partir des deux arêtes. Extrait de dist/helm/router-deployment.yaml, l’env du conteneur de la passerelle :
env: - name: LITELLM_MODEL_ASSISTANT_API_KEY valueFrom: secretKeyRef: name: openai-api-key key: api-key - name: PRESIDIO_ANALYZER_API_BASE value: http://analyzer-default:3000 - name: PRESIDIO_ANONYMIZER_API_BASE value: http://anonymizer-default:3000La première est la clé du modèle, référencée depuis le Secret que nomme la Release et jamais écrite en clair ; les deux autres sont les adresses des services de reconnaissance. Le nom d’une personne devient <PERSON> et une adresse e-mail <EMAIL_ADDRESS>.
Un appel échoué est retenu plutôt que masqué. La passerelle n’exécute aucun garde-fou de journalisation pour un appel qui échoue, donc le module que charge l’entrée fournit aussi log_masking.withhold_failed_calls, enregistré juste après le garde des requêtes, et la Recipe de la passerelle écrit les deux réglages à côté. Le callback reçoit l’enregistrement d’un appel échoué avant tout callback enregistré après lui, et remplace chaque texte qu’a écrit un appelant ou le modèle par [TEXT_WITHHELD], correspondant ou non, et le texte de l’erreur par [ERROR_TEXT_WITHHELD], en laissant tel quel ce qu’envoie une tentative répétée. disable_error_logs tient les appels échoués à l’écart des journaux de dépenses, et redact_messages_in_exceptions tient les messages de la requête à l’écart des détails que la passerelle joint à une erreur.
La même ConfigMap porte une seconde clé, log_masking.py : le module que nomment le guardrail de l’entrée et la seconde entrée de callbacks. La Recipe de la passerelle n’ajoute le module, cette entrée de callbacks, l’entrée du garde-fou et les deux réglages que tant que values.log_masking liste quelque chose, de sorte qu’une passerelle qui ne liste rien rend la ConfigMap sans aucun d’eux, octet pour octet comme une passerelle sans la valeur.
Ce que voit un lecteur des journaux, et ce que voit le modèle
Prenez un appelant dont la requête porte ce texte :
My name is David Johnson and my email is david.johnson@example.com, ticket TCK-104882. Call me on 212-555-0147.Le bloc ci-dessus et les trois ci-dessous illustrent ce que la passerelle en cours d’exécution en fait ; ce n’est pas une sortie du build.
Le fournisseur du modèle reçoit la requête exactement telle que l’appelant l’a envoyée, et l’appelant reçoit la réponse du modèle exactement telle qu’elle est arrivée. Une intégration de journalisation à laquelle la passerelle remet l’appel reçoit les mêmes messages masqués :
My name is <PERSON> and my email is <EMAIL_ADDRESS>, ticket [TICKET_REDACTED]. Call me on 212-555-0147.Le numéro de téléphone est journalisé tel qu’envoyé, parce que le rattachement ne liste pas PHONE_NUMBER et qu’aucun motif ne lui correspond. Un texte auquel rien de listé ne correspond n’est jamais masqué.
Chaque copie d’un appel réussi que la passerelle remet à ses journaux est masquée de la même façon : les messages, les messages et la réponse de la charge utile de journalisation standard, une réponse en streaming à mesure que la passerelle l’assemble, la requête et la réponse telles que le fournisseur les a vues, la requête que conservent les journaux de dépenses, et la réponse que reçoit chaque intégration. La réponse du modèle est masquée dans ces copies aussi :
Reply for <PERSON> (<EMAIL_ADDRESS>) about [TICKET_REDACTED].Ce qui reste non masqué
Masquer les journaux ne cache le texte à personne d’autre, et la description de values.log_masking le dit :
- Le fournisseur du modèle reçoit tout sans masquage, tout comme la passerelle et les deux services de reconnaissance.
- Un appel échoué ne conserve aucun texte de requête dans aucun journal qu’écrit la passerelle, et cela coûte deux choses. La propre ligne de la passerelle pour un appel échoué ne conserve que le type d’erreur, par exemple
An error was logged with its text withheld, as log masking is on: BadRequestError, de sorte que le message du fournisseur et sa trace d’appels quittent ce journal ; et les appels échoués quittent les journaux de dépenses et les totaux de dépenses quotidiens, qui ne comptent que les appels réussis. Une intégration de journalisation configurée hors du catalogue peut toujours lire le message d’erreur propre à un fournisseur sur l’exception que porte un appel échoué, et une intégration enregistrée avant le callback propre à la passerelle reçoit le texte d’un appel échoué tel qu’il est arrivé. - Seuls les journaux par lesquels écrit le masquage sont couverts : ni la sortie de débogage de la passerelle, ni les journaux propres à un fournisseur. Les métadonnées d’une requête, ses définitions d’outils et ses en-têtes sont journalisés tels qu’envoyés.
- Un appel dont les copies ne peuvent pas être masquées est journalisé avec son texte retenu. Lorsqu’un service de reconnaissance est injoignable, aucune copie n’est journalisée partiellement masquée : chaque texte de chaque copie de cet appel est remplacé par
[TEXT_WITHHELD], et l’enregistrement est remis aux journaux comme d’habitude, de sorte que l’appel est toujours compté dans les journaux de dépenses. Le journal propre à la passerelle consigne que le texte de l’appel a été retenu. L’appel lui-même reçoit une réponse comme d’habitude.
Tel que le catalogue rend cette passerelle, elle ne remet ses journaux à aucune intégration de journalisation, et ses journaux de dépenses ne conservent aucun texte de requête ou de réponse ni aucun appel échoué. Les copies que protège le masquage sont donc celles que recevrait une intégration ou un journal de dépenses conservant le texte, configuré sur la passerelle.
Masquage des journaux ou masquage des données
core/data-masking cache au modèle le texte listé, et sur cette passerelle sa réalisation désactive la journalisation du contenu des messages par la passerelle tant qu’elle est rattachée. À côté d’elle, le masquage des journaux n’aurait plus rien sur quoi agir, et un lecteur pourrait prendre les deux pour une seule protection. La passerelle refuse donc les deux ensemble : tant que values.log_masking liste quelque chose, un rattachement core/data-masking sur la passerelle arrête le build, par une assertion du propre Component de la passerelle. Ajouter un tel rattachement nommé masked à la passerelle, avec sa réalisation liée dans le Manifest, affiche :
[… omitted: what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars][DEVELOPER_ERROR E0033] Component/Feature assertions caused by: Component "core/gateway/litellm" instance "router" assertion "log_masking_not_beside_data_masking": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: "router" lists what to mask in its logs under values.log_masking, and the core/data-masking attachment "masked" is on it too: that attachment's realization turns the gateway's logging of message contents off, so log masking would have nothing left to act on, and a reader could take the two for one protection. Remove values.log_masking to mask what travels, or the "masked" attachment to mask only what is loggedRecourez au masquage des journaux là où le modèle doit voir les données et où les journaux ne doivent pas les conserver ; recourez au masquage des données là où le modèle ne doit pas les voir non plus. Les deux lisent les mêmes patterns et entities, donc une liste signifie la même chose dans l’un comme dans l’autre.
Là où le compilateur n’interprète pas
Le compilateur route le motif et les types d’entités vers la configuration de la passerelle sous forme de chaînes. Il ne compile pas l’expression, ne sait pas ce qu’est un numéro de ticket ou une personne, et ne voit pas le trafic que la passerelle transportera. Chaque arrêt que peut rencontrer ce workspace — des types d’entités avec un socket de reconnaissance non câblé, un type d’entité que l’analyseur ne reconnaît pas en anglais, le masquage des journaux à côté du masquage des données sur une même passerelle, la connexion au modèle géré ne portant aucune information d’identification — est déclaré par les propres entités du catalogue, comme une assertion du Component de la passerelle ou de sa Recipe, et aucun d’eux ne repose sur une quelconque compréhension du texte.
L’adapter
- Masquer uniquement des motifs. Retirez
entitiesdevalues.log_masking, ainsi que les deux composants de reconnaissance avec leurs arêtes et leurs entrées dans la Release ; les motifs sont mis en correspondance à l’intérieur de la passerelle et n’ont besoin d’aucun des deux services. - Masquer davantage de types d’entités. Ajoutez-les à
entities, dans le vocabulaire propre au service de reconnaissance ; un type que l’analyseur ne reconnaît pas en anglais arrête le build et nomme ceux qu’il reconnaît. - Cacher aussi le texte au modèle. Remplacez
values.log_maskingpar un rattachementcore/data-maskingsur la passerelle listant les mêmespatternsetentities, et liez sa réalisation dans le Manifest. - Servir un second modèle. Câblez un autre composant de modèle au socket
modelssous un alias qui lui est propre, avec la clé que la passerelle lui présente sur cette connexion ;values.modelcontinue de nommer l’alias que publie la passerelle. Le masquage s’applique aux appels de chaque alias que sert la passerelle.