Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Un gateway AI che tiene i dati personali fuori dai propri log

Un assistente di supporto deve lavorare con i nomi e gli indirizzi email dei clienti, quindi il modello che chiama deve vederli. Il gateway davanti a quel modello conserva log per l’audit e per il debug, e quei log non devono conservarli. Questo workspace compila un gateway di questo tipo in manifest Kubernetes.

A farlo è un valore del gateway stesso, values.log_masking su core/gateway/litellm. Maschera la copia di ogni chiamata che il gateway passa ai propri log, e nient’altro: il modello riceve la richiesta esattamente come l’ha inviata il chiamante, e il chiamante riceve la risposta esattamente come l’ha scritta il modello. È questa la differenza rispetto alla Feature core/data-masking, che nasconde il testo al modello stesso. Le due sono alternative, e la sezione più sotto su come scegliere tra di esse mostra che cosa succede quando entrambe sono impostate su un unico gateway.

Questo workspace non scrive alcuna entità di catalogo propria. I tre file di entità qui presenti — un Aggregate, un Manifest e una Release — sono tutto ciò che chiunque scrive.

Che cosa costruisce

istanzaComponent del catalogoche cosa è qui
routercore/gateway/litellmil gateway AI: un solo alias pubblicato, assistant, servito dal modello cablato al suo socket models
gptcore/ai-model/openaiil modello dietro quell’alias, l’API di OpenAI stessa, raggiunta come riferimento: per esso non viene eseguito nulla nel cluster
analyzercore/security/presidio-analyzertrova i frammenti sensibili in un testo
anonymizercore/security/presidio-anonymizersostituisce i frammenti che gli vengono passati

Tre archi uses: il socket models del gateway verso il modello, che porta come sua credential la chiave che il gateway gli presenta, e i suoi socket pii_analyzer e pii_anonymizer verso i due servizi di riconoscimento. L’Aggregate associa quella credenziale senza nominare un secret, e la Release la nomina nell’infra dell’associazione: un Secret che il namespace contiene già, a cui la realizzazione del Manifest fa riferimento e che non renderizza. Il values.log_masking del gateway elenca che cosa mascherare: un’espressione regolare per i numeri di ticket dell’azienda sotto patterns, e i tipi di entità PERSON e EMAIL_ADDRESS sotto entities. Non esiste un elenco predefinito; un gateway che non elenca né gli uni né gli altri non maschera nulla nei propri log, e viene renderizzato esattamente come senza il valore.

Generare l’esempio

Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.

Scrivi l’esempio in una nuova cartella che porta il suo nome:

Terminal window
aggrega scaffold --example ai-gateway-log-masking

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:

Terminal window
cd ai-gateway-log-masking

Build

Terminal window
aggrega build --release release.yaml --auto-pull

Una release ha bisogno di un lockfile prima di eseguire il build, e i lockfile sono generati anziché distribuiti, quindi un clone appena creato non ne ha nessuno. Risolvine prima uno, oppure lascia che sia il build a crearlo:

Terminal window
aggrega pull --release release.yaml # resolve once, then build with no flag
aggrega build --release release.yaml --auto-pull # or resolve during the build

Questo workspace risolve le entità del catalogo dal registry predefinito che .aggrega-config.yaml indica. È la Recipe stessa del gateway a scrivere il mascheramento dei log, quindi il build non esegue alcun plugin oltre a quelli che il compilatore porta con sé.

Il build stampa, con <workspace> al posto della cartella di questo esempio:

[… 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>/dist

Con un assistente AI

Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.

Usa solo gli strumenti di Aggrega e non creare tu stesso alcuna cartella. Se la cartella del workspace non contiene ancora una cartella `ai-gateway-log-masking`, chiama una sola volta lo strumento `scaffold` con `example` impostato su `ai-gateway-log-masking` e senza `dir`: scrive l’esempio in una nuova cartella `ai-gateway-log-masking`. Poi chiama lo strumento `build` con `workspace_root` impostato su `ai-gateway-log-masking`, `release` impostato su `release.yaml`, `auto_pull` impostato su true e `write` impostato su true. Dimmi quali file ha scritto la build; si trovano in `ai-gateway-log-masking/dist/`.

L’albero renderizzato

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

Il valore non porta alcun file proprio. La Recipe del gateway lo scrive nella configurazione del gateway, e aggiunge alla ConfigMap del gateway un modulo che quella configurazione carica. Il modello renderizza un solo file, gpt-service.yaml, un Service che mappa un nome interno al cluster sull’host dell’API di OpenAI, api.openai.com; la sua chiave non ne renderizza nessuno, perché il Secret che la contiene esiste già.

La tabella di instradamento, l’inizio del corpo della configurazione del gateway, ha una sola voce, scritta a partire da ciò che il modello pubblica — il suo endpoint, l’URL di base dell’API di OpenAI, e il suo nome di modello — e che nomina la variabile sotto cui la Recipe del gateway consegna la chiave della connessione:

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_KEY

La voce del guardrail

Ecco il corpo della configurazione del gateway, la chiave config.yaml di dist/helm/router/litellm-gateway-config/configmap.yaml, dalla sua sezione litellm_settings in poi:

[… omitted: the routing table]
litellm_settings:
callbacks:
- /etc/litellm-request-guard/request_field_filter.filter
- log_masking.withhold_failed_calls
redact_messages_in_exceptions: true
guardrails:
- 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": MASK
general_settings:
disable_error_logs: true

La Recipe del gateway lo scrive tutto a partire da values.log_masking, e dà alla voce il nome del gateway, qui router, con un punto dove le voci di guardrail scritte dalle realizzazioni della libreria standard portano un trattino, così nessuna loro associazione, qualunque sia il suo nome, può prendere il posto di questa voce. Cinque cose meritano di essere lette da essa.

mode: logging_only è la modalità propria del gateway per un guardrail che viene eseguito nel punto in cui una chiamata conclusa viene passata ai suoi log, e in nessun altro. La classe che la voce carica vi si attiene qualunque cosa nomini una voce, quindi non viene mai chiamata su una richiesta prima che la richiesta venga inoltrata, né su una risposta prima che la risposta venga restituita.

default_on: true lo esegue su ogni chiamata. Un chiamante non può disattivarlo dalla richiesta, nemmeno con una richiesta che chiede di disabilitare i guardrail sempre attivi del gateway.

Il pattern raggiunge il gateway esattamente come è stato scritto. Viene confrontato all’interno del gateway, senza distinguere tra maiuscole e minuscole, e ogni corrispondenza viene sostituita definitivamente dal nome del pattern in maiuscolo tra parentesi quadre: [TICKET_REDACTED]. Il gateway compila l’espressione all’avvio, e una che non si compila ne impedisce l’avvio — il compilatore passa la stringa senza leggerla.

I tipi di entità vengono trovati dai due servizi di riconoscimento. La voce non nomina alcun indirizzo: il gateway li legge entrambi dal proprio ambiente, che la Recipe del gateway riempie a partire dai due archi. Da dist/helm/router-deployment.yaml, l’env del container del gateway:

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

La prima è la chiave del modello, referenziata dal Secret che la Release nomina e mai scritta per esteso; le altre due sono gli indirizzi dei servizi di riconoscimento. Il nome di una persona diventa <PERSON> e un indirizzo email <EMAIL_ADDRESS>.

Una chiamata fallita viene trattenuta anziché mascherata. Il gateway non esegue alcun guardrail di logging per una chiamata che fallisce, quindi il modulo che la voce carica fornisce anche log_masking.withhold_failed_calls, registrata subito dopo la guardia delle richieste, e la Recipe del gateway scrive le due impostazioni accanto a essa. Alla callback viene passato il record di una chiamata fallita prima che a qualsiasi callback registrata dopo di essa, e sostituisce ogni testo scritto da un chiamante o dal modello con [TEXT_WITHHELD], che corrisponda o no, e il testo dell’errore con [ERROR_TEXT_WITHHELD], lasciando com’era ciò che invia un tentativo ripetuto. disable_error_logs tiene le chiamate fallite fuori dai log di spesa, e redact_messages_in_exceptions tiene i messaggi della richiesta fuori dai dettagli che il gateway allega a un errore.

La stessa ConfigMap porta una seconda chiave, log_masking.py: il modulo che nominano il guardrail della voce e la seconda voce di callbacks. La Recipe del gateway aggiunge il modulo, quella voce di callbacks, la voce del guardrail e le due impostazioni solo finché values.log_masking elenca qualcosa, quindi un gateway che non elenca nulla renderizza la ConfigMap senza nessuno di essi, byte per byte come un gateway senza il valore.

Che cosa vede chi legge i log, e che cosa vede il modello

Prendi un chiamante la cui richiesta porta questo testo:

My name is David Johnson and my email is david.johnson@example.com, ticket TCK-104882. Call me on 212-555-0147.

Il blocco qui sopra e i tre qui sotto illustrano che cosa fa con esso il gateway in esecuzione; non sono output del build.

Il provider del modello riceve la richiesta esattamente come l’ha inviata il chiamante, e il chiamante riceve la risposta del modello esattamente come è arrivata. Un’integrazione di logging a cui il gateway passa la chiamata riceve gli stessi messaggi mascherati:

My name is <PERSON> and my email is <EMAIL_ADDRESS>, ticket [TICKET_REDACTED]. Call me on 212-555-0147.

Il numero di telefono viene registrato nei log così come è stato inviato, perché l’associazione non elenca PHONE_NUMBER e nessun pattern vi corrisponde. Il testo a cui non corrisponde nulla di ciò che è elencato non viene mai mascherato.

Ogni copia di una chiamata riuscita che il gateway passa ai propri log viene mascherata allo stesso modo: i messaggi, i messaggi e la risposta del payload di logging standard, una risposta in streaming man mano che il gateway la assembla, la richiesta e la risposta come le ha viste il provider, la richiesta che conservano i log di spesa, e la risposta che riceve ogni integrazione. Anche la risposta del modello viene mascherata in quelle copie:

Reply for <PERSON> (<EMAIL_ADDRESS>) about [TICKET_REDACTED].

Che cosa resta non mascherato

Mascherare i log non nasconde il testo a nessun altro, e la descrizione di values.log_masking lo dice:

  • Il provider del modello riceve tutto senza mascheramento, e lo stesso vale per il gateway e per entrambi i servizi di riconoscimento.
  • Una chiamata fallita non conserva alcun testo della richiesta in nessun log che il gateway scrive, e questo costa due cose. La riga propria del gateway per una chiamata fallita conserva solo il tipo di errore, come An error was logged with its text withheld, as log masking is on: BadRequestError, quindi il messaggio del provider e il suo traceback escono da quel log; e le chiamate fallite escono dai log di spesa e dai totali giornalieri di spesa, che contano solo le chiamate riuscite. Un’integrazione di logging configurata al di fuori del catalogo può comunque leggere il messaggio di errore proprio di un provider sull’eccezione che una chiamata fallita porta, e a una registrata prima della callback propria del gateway viene passato il testo di una chiamata fallita così come è arrivato.
  • Sono coperti solo i log attraverso cui scrive il mascheramento: non l’output di debug del gateway, e non i log propri di un provider. I metadati di una richiesta, le sue definizioni di strumenti e le sue intestazioni vengono registrati nei log così come sono stati inviati.
  • Una chiamata le cui copie non possono essere mascherate viene registrata nei log con il testo trattenuto. Quando un servizio di riconoscimento non è raggiungibile, nessuna copia viene registrata mascherata in parte: ogni testo in ogni copia di quella chiamata viene sostituito da [TEXT_WITHHELD], e il record viene passato ai log come di consueto, quindi la chiamata viene comunque conteggiata nei log di spesa. Il log proprio del gateway registra che il testo della chiamata è stato trattenuto. Alla chiamata stessa viene data risposta come di consueto.

Così come il catalogo renderizza questo gateway, esso non passa i propri log ad alcuna integrazione di logging, e i suoi log di spesa non conservano alcun testo di richiesta o di risposta né alcuna chiamata fallita. Le copie che il mascheramento protegge sono quindi quelle che riceverebbero un’integrazione o un log di spesa che conserva il testo, configurati sul gateway.

Mascheramento dei log o mascheramento dei dati

core/data-masking nasconde al modello il testo elencato, e su questo gateway la sua realizzazione disattiva la registrazione nei log dei contenuti dei messaggi da parte del gateway finché è associata. Accanto a essa, il mascheramento dei log non avrebbe più nulla su cui agire, e un lettore potrebbe scambiare le due per un’unica protezione. Il gateway rifiuta quindi le due insieme: finché values.log_masking elenca qualcosa, un’associazione core/data-masking sul gateway arresta il build, tramite un’asserzione del Component stesso del gateway. Aggiungerne una di nome masked al gateway, con la sua realizzazione vincolata nel Manifest, stampa:

[… 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 logged

Ricorri al mascheramento dei log quando il modello deve vedere i dati e i log non devono conservarli; ricorri al mascheramento dei dati quando nemmeno il modello deve vederli. Entrambi leggono gli stessi patterns ed entities, quindi un elenco significa la stessa cosa nell’uno e nell’altro.

Dove il compilatore non interpreta

Il compilatore instrada il pattern e i tipi di entità nella configurazione del gateway come stringhe. Non compila l’espressione, non sa che cosa siano un numero di ticket o una persona, e non vede il traffico che il gateway trasporterà. Ogni arresto che questo workspace può incontrare — tipi di entità con un socket di riconoscimento non cablato, un tipo di entità che l’analizzatore non riconosce in inglese, il mascheramento dei log accanto al mascheramento dei dati su un unico gateway, la connessione al modello gestito che non porta alcuna credenziale — è dichiarato dalle entità stesse del catalogo, come asserzione del Component del gateway o della sua Recipe, e nessuno di essi si basa su una comprensione del testo.

Adattarlo

  • Maschera solo i pattern. Togli entities da values.log_masking, e i due componenti di riconoscimento con i loro archi e le loro voci nella Release; i pattern vengono confrontati all’interno del gateway e non hanno bisogno di nessuno dei due servizi.
  • Maschera più tipi di entità. Aggiungili a entities, nel vocabolario proprio del servizio di riconoscimento; un tipo che l’analizzatore non riconosce in inglese arresta il build e nomina quelli che riconosce.
  • Nascondi il testo anche al modello. Sostituisci values.log_masking con un’associazione core/data-masking sul gateway che elenca gli stessi patterns ed entities, e vincola la sua realizzazione nel Manifest.
  • Servi un secondo modello. Cabla un altro componente di modello al socket models sotto un alias proprio, con la chiave che il gateway gli presenta su quella connessione; values.model continua a nominare l’alias che il gateway pubblica. Il mascheramento si applica alle chiamate di ogni alias che il gateway serve.