Ein KI-Gateway, das personenbezogene Daten aus seinen Logs heraushält
Ein Support-Assistent muss mit den Namen und E-Mail-Adressen von Kunden arbeiten, daher muss das Modell, das er aufruft, sie sehen. Das Gateway vor diesem Modell führt Logs für Audits und zur Fehlersuche, und diese Logs dürfen sie nicht festhalten. Dieser Workspace kompiliert ein solches Gateway zu Kubernetes-Manifesten.
Was das bewirkt, ist ein Wert des Gateways selbst, values.log_masking an core/gateway/litellm. Er maskiert die Kopie jedes Aufrufs, die das Gateway an seine Logs übergibt, und nichts sonst: Das Modell erhält die Anfrage genau so, wie der Aufrufer sie gesendet hat, und der Aufrufer erhält die Antwort genau so, wie das Modell sie geschrieben hat. Darin liegt der Unterschied zum Feature core/data-masking, das den Text vor dem Modell selbst verbirgt. Die beiden sind Alternativen, und der Abschnitt zur Wahl zwischen ihnen weiter unten zeigt, was geschieht, wenn beide an einem Gateway gesetzt sind.
Dieser Workspace schreibt keine eigene Katalogentität. Die drei Entitätsdateien hier — ein Aggregate, ein Manifest und ein Release — sind alles, was irgendjemand schreibt.
Was es baut
| Instanz | Katalog-Component | was es hier ist |
|---|---|---|
router | core/gateway/litellm | das KI-Gateway: ein veröffentlichter Alias, assistant, bereitgestellt von dem Modell, das mit seinem Socket models verdrahtet ist |
gpt | core/ai-model/openai | das Modell hinter diesem Alias, die eigene API von OpenAI, als Referenz erreicht: Dafür läuft nichts im Cluster |
analyzer | core/security/presidio-analyzer | findet die sensiblen Textstellen in einem Text |
anonymizer | core/security/presidio-anonymizer | ersetzt die Textstellen, die ihm übergeben werden |
Drei Kanten uses: der Socket models des Gateways zum Modell, der als seine credential den Schlüssel trägt, den das Gateway ihm vorlegt, und seine Sockets pii_analyzer und pii_anonymizer zu den beiden Erkennungsdiensten. Das Aggregate bindet diese Zugangsdaten an, ohne ein Secret zu nennen, und das Release nennt sie in der infra der Anbindung: ein Secret, das der Namespace bereits enthält, auf das die Realisierung des Manifest verweist und das sie nicht rendert. values.log_masking des Gateways listet auf, was zu maskieren ist: einen regulären Ausdruck für die Ticketnummern des Unternehmens unter patterns und die Entitätstypen PERSON und EMAIL_ADDRESS unter entities. Es gibt keine Standardliste; ein Gateway, das keines von beiden auflistet, maskiert nichts in seinen Logs und wird genau so gerendert wie ohne den Wert.
Das Beispiel generieren
Sie können dieses Beispiel mit den folgenden Befehlen bauen oder es von Ihrem KI-Assistenten für Sie bauen lassen.
Schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:
aggrega scaffold --example ai-gateway-log-maskingDanach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:
cd ai-gateway-log-maskingBuild
aggrega build --release release.yaml --auto-pullEin Release braucht ein Lockfile, bevor es baut, und Lockfiles werden erzeugt statt mitgeliefert, daher hat ein frischer Klon keines. Lösen Sie zuerst eines auf, oder lassen Sie den Build es füllen:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildDieser Workspace löst die Katalogentitäten aus der Standard-Registry auf, die .aggrega-config.yaml nennt. Das eigene Recipe des Gateways schreibt die Log-Maskierung, daher führt der Build kein Plugin über die hinaus aus, die der Compiler mitbringt.
Der Build gibt aus, wobei <workspace> für den Ordner dieses Beispiels steht:
[… 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>/distMit einem KI-Assistenten
Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie ihm diesen Prompt ein.
Verwenden Sie nur die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Workspace-Ordner noch keinen Ordner `ai-gateway-log-masking` enthält, rufen Sie das Tool `scaffold` einmal auf, mit `example` auf `ai-gateway-log-masking` gesetzt und ohne `dir`: Es schreibt das Beispiel in einen neuen Ordner `ai-gateway-log-masking`. Rufen Sie dann das Tool `build` auf, mit `workspace_root` auf `ai-gateway-log-masking`, `release` auf `release.yaml`, `auto_pull` auf true und `write` auf true gesetzt. Nennen Sie mir die Dateien, die der Build geschrieben hat; sie liegen unter `ai-gateway-log-masking/dist/`.Der gerenderte Baum
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.yamlDer Wert bringt keine eigene Datei mit. Das Recipe des Gateways schreibt ihn in die Konfiguration des Gateways und fügt der ConfigMap des Gateways ein Modul hinzu, das diese Konfiguration lädt. Das Modell rendert eine Datei, gpt-service.yaml, einen Service, der einen clusterinternen Namen auf den API-Host von OpenAI abbildet, api.openai.com; sein Schlüssel rendert keine, weil das Secret, das ihn enthält, bereits existiert.
Die Routing-Tabelle, der Anfang des Konfigurationsinhalts des Gateways, hat einen Eintrag, geschrieben aus dem, was das Modell veröffentlicht — seinem Endpunkt, der API-Basis-URL von OpenAI, und seinem Modellnamen —, und nennt die Variable, unter der das Recipe des Gateways den Schlüssel der Verbindung zustellt:
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_KEYDer Guardrail-Eintrag
Hier ist der Konfigurationsinhalt des Gateways, der Schlüssel config.yaml von dist/helm/router/litellm-gateway-config/configmap.yaml, ab seinem Abschnitt 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: trueDas Recipe des Gateways schreibt all das aus values.log_masking und benennt den Eintrag nach dem Gateway, hier router, mit einem Punkt, wo die Guardrail-Einträge, die die Realisierungen der Standardbibliothek schreiben, einen Bindestrich tragen, sodass keine ihrer Anbindungen, wie auch immer sie heißt, den Platz dieses Eintrags einnehmen kann. Fünf Dinge lohnt es sich daraus abzulesen.
mode: logging_only ist der eigene Modus des Gateways für einen Guardrail, der dort läuft, wo ein abgeschlossener Aufruf an seine Logs übergeben wird, und nirgends sonst. Die Klasse, die der Eintrag lädt, hält sich daran, was auch immer ein Eintrag nennt, sodass sie nie für eine Anfrage aufgerufen wird, bevor die Anfrage weitergeleitet ist, oder für eine Antwort, bevor die Antwort zurückgegeben ist.
default_on: true führt ihn bei jedem Aufruf aus. Ein Aufrufer kann ihn nicht aus der Anfrage heraus abschalten, auch nicht mit einer Anfrage, die verlangt, die stets aktiven Guardrails des Gateways zu deaktivieren.
Das Muster erreicht das Gateway genau so, wie es verfasst wurde. Es wird innerhalb des Gateways abgeglichen, ohne Rücksicht auf Groß- und Kleinschreibung, und jeder Treffer wird endgültig durch den Namen des Musters in Großbuchstaben in eckigen Klammern ersetzt: [TICKET_REDACTED]. Das Gateway kompiliert den Ausdruck beim Start, und einer, der sich nicht kompilieren lässt, verhindert den Start — der Compiler reicht den String durch, ohne ihn zu lesen.
Die Entitätstypen werden von den beiden Erkennungsdiensten gefunden. Der Eintrag nennt keine Adresse: Das Gateway liest beide aus seiner Umgebung, die das Recipe des Gateways aus den beiden Kanten füllt. Aus dist/helm/router-deployment.yaml, die env des Containers des Gateways:
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:3000Der erste ist der Schlüssel des Modells, referenziert aus dem Secret, das das Release nennt, und nie ausgeschrieben; die anderen beiden sind die Adressen der Erkennungsdienste. Der Name einer Person wird zu <PERSON> und eine E-Mail-Adresse zu <EMAIL_ADDRESS>.
Ein fehlgeschlagener Aufruf wird zurückgehalten statt maskiert. Das Gateway führt für einen fehlschlagenden Aufruf keinen Logging-Guardrail aus, daher stellt das Modul, das der Eintrag lädt, auch log_masking.withhold_failed_calls bereit, registriert direkt nach dem Anfragewächter, und das Recipe des Gateways schreibt die beiden Einstellungen daneben. Der Callback erhält den Datensatz eines fehlgeschlagenen Aufrufs vor jedem Callback, der nach ihm registriert ist, und ersetzt jeden Text, den ein Aufrufer oder das Modell geschrieben hat, durch [TEXT_WITHHELD], ob getroffen oder nicht, und den Text des Fehlers durch [ERROR_TEXT_WITHHELD], wobei er unverändert lässt, was ein wiederholter Versuch sendet. disable_error_logs hält fehlgeschlagene Aufrufe aus den Ausgaben-Logs heraus, und redact_messages_in_exceptions hält die Nachrichten der Anfrage aus den Details heraus, die das Gateway einem Fehler anhängt.
Dieselbe ConfigMap trägt einen zweiten Schlüssel, log_masking.py: das Modul, das der guardrail des Eintrags und der zweite Eintrag von callbacks nennen. Das Recipe des Gateways fügt das Modul, diesen Eintrag von callbacks, den Guardrail-Eintrag und die beiden Einstellungen nur hinzu, solange values.log_masking etwas auflistet, sodass ein Gateway, das nichts auflistet, die ConfigMap ohne jedes davon rendert, Byte für Byte wie ein Gateway ohne den Wert.
Was ein Log-Leser sieht und was das Modell sieht
Nehmen Sie einen Aufrufer, dessen Anfrage diesen Text trägt:
My name is David Johnson and my email is david.johnson@example.com, ticket TCK-104882. Call me on 212-555-0147.Der Block oben und die drei unten veranschaulichen, was das laufende Gateway damit tut; sie sind keine Ausgabe des Builds.
Der Modell-Provider erhält die Anfrage genau so, wie der Aufrufer sie gesendet hat, und der Aufrufer erhält die Antwort des Modells genau so, wie sie kam. Eine Logging-Integration, an die das Gateway den Aufruf übergibt, erhält dieselben Nachrichten maskiert:
My name is <PERSON> and my email is <EMAIL_ADDRESS>, ticket [TICKET_REDACTED]. Call me on 212-555-0147.Die Telefonnummer wird so protokolliert, wie sie gesendet wurde, weil die Anbindung PHONE_NUMBER nicht auflistet und kein Muster auf sie passt. Text, auf den nichts Aufgelistetes passt, wird nie maskiert.
Jede Kopie eines erfolgreichen Aufrufs, die das Gateway an seine Logs übergibt, wird auf dieselbe Weise maskiert: die Nachrichten, die Nachrichten und die Antwort der Standard-Logging-Nutzlast, eine gestreamte Antwort, während das Gateway sie zusammensetzt, die Anfrage und die Antwort, wie der Provider sie gesehen hat, die Anfrage, die die Ausgaben-Logs festhalten, und die Antwort, die jede Integration erhält. Auch die Antwort des Modells wird in diesen Kopien maskiert:
Reply for <PERSON> (<EMAIL_ADDRESS>) about [TICKET_REDACTED].Was unmaskiert bleibt
Die Maskierung der Logs verbirgt den Text vor niemandem sonst, und die Beschreibung von values.log_masking sagt das:
- Der Modell-Provider erhält alles unmaskiert, und ebenso das Gateway und beide Erkennungsdienste.
- Ein fehlgeschlagener Aufruf hinterlässt in keinem Log, das das Gateway schreibt, Anfragetext, und das kostet zweierlei. Die eigene Zeile des Gateways für einen fehlgeschlagenen Aufruf hält nur die Art des Fehlers fest, etwa
An error was logged with its text withheld, as log masking is on: BadRequestError, sodass die Meldung des Providers und ihr Traceback aus diesem Log verschwinden; und fehlgeschlagene Aufrufe verschwinden aus den Ausgaben-Logs und aus den täglichen Ausgabensummen, die nur erfolgreiche Aufrufe zählen. Eine außerhalb des Katalogs konfigurierte Logging-Integration kann die eigene Fehlermeldung eines Providers weiterhin an der Exception lesen, die ein fehlgeschlagener Aufruf trägt, und einer, die vor dem eigenen Callback des Gateways registriert ist, wird der Text eines fehlgeschlagenen Aufrufs so übergeben, wie er kam. - Abgedeckt sind nur die Logs, über die die Maskierung schreibt: nicht die Debug-Ausgabe des Gateways und nicht die eigenen Logs eines Providers. Die Metadaten einer Anfrage, ihre Tool-Definitionen und ihre Header werden so protokolliert, wie sie gesendet wurden.
- Ein Aufruf, dessen Kopien nicht maskiert werden können, wird mit zurückgehaltenem Text protokolliert. Ist ein Erkennungsdienst nicht erreichbar, wird keine Kopie teilweise maskiert protokolliert: Jeder Text in jeder Kopie dieses Aufrufs wird durch
[TEXT_WITHHELD]ersetzt, und der Datensatz wird wie üblich an die Logs übergeben, sodass der Aufruf weiterhin in den Ausgaben-Logs gezählt wird. Das eigene Log des Gateways hält fest, dass der Text des Aufrufs zurückgehalten wurde. Der Aufruf selbst wird wie üblich beantwortet.
So, wie der Katalog dieses Gateway rendert, übergibt es seine Logs an keine Logging-Integration, und seine Ausgaben-Logs halten weder Anfrage- noch Antworttext und keinen fehlgeschlagenen Aufruf fest. Die Kopien, die die Maskierung schützt, sind also diejenigen, die eine Integration oder ein textspeicherndes Ausgaben-Log erhalten würde, das am Gateway konfiguriert ist.
Log-Maskierung oder Datenmaskierung
core/data-masking verbirgt den aufgelisteten Text vor dem Modell, und an diesem Gateway schaltet seine Realisierung das Protokollieren von Nachrichteninhalten durch das Gateway ab, solange es angebunden ist. Daneben hätte die Log-Maskierung nichts mehr, worauf sie wirken könnte, und ein Leser könnte die beiden für einen einzigen Schutz halten. Daher weist das Gateway die beiden zusammen zurück: Solange values.log_masking etwas auflistet, bricht eine Anbindung core/data-masking am Gateway den Build ab, durch eine Assertion der eigenen Component des Gateways. Eine solche Anbindung mit dem Namen masked zum Gateway hinzuzufügen, mit ihrer im Manifest gebundenen Realisierung, gibt aus:
[… 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 loggedGreifen Sie zur Log-Maskierung, wo das Modell die Daten sehen muss und die Logs sie nicht festhalten dürfen; greifen Sie zur Datenmaskierung, wo auch das Modell sie nicht sehen darf. Beide lesen dieselben patterns und entities, sodass eine Liste bei beiden dasselbe bedeutet.
Wo der Compiler nicht interpretiert
Der Compiler routet das Muster und die Entitätstypen als Strings in die Konfiguration des Gateways. Er kompiliert den Ausdruck nicht, weiß nicht, was eine Ticketnummer oder eine Person ist, und sieht den Datenverkehr nicht, den das Gateway transportieren wird. Jeder Abbruch, auf den dieser Workspace stoßen kann — Entitätstypen bei unverdrahtetem Erkennungs-Socket, ein Entitätstyp, den der Analyzer auf Englisch nicht erkennt, Log-Maskierung neben Datenmaskierung an einem Gateway, die Verbindung zum verwalteten Modell ohne Zugangsdaten —, wird von den eigenen Entitäten des Katalogs deklariert, als Assertion der Component des Gateways oder seines Recipe, und keiner davon beruht auf irgendeinem Verständnis des Textes.
Anpassen
- Nur Muster maskieren. Entfernen Sie
entitiesausvalues.log_maskingsowie die beiden Erkennungskomponenten mit ihren Kanten und ihren Einträgen im Release; die Muster werden innerhalb des Gateways abgeglichen und benötigen keinen der beiden Dienste. - Mehr Entitätstypen maskieren. Fügen Sie sie zu
entitieshinzu, im eigenen Vokabular des Erkennungsdienstes; ein Typ, den der Analyzer auf Englisch nicht erkennt, bricht den Build ab und nennt die, die er erkennt. - Den Text auch vor dem Modell verbergen. Ersetzen Sie
values.log_maskingdurch eine Anbindungcore/data-maskingam Gateway, die dieselbenpatternsundentitiesauflistet, und binden Sie ihre Realisierung im Manifest. - Ein zweites Modell bereitstellen. Verdrahten Sie eine weitere Modellkomponente mit dem Socket
modelsunter einem eigenen Alias, mit dem Schlüssel, den das Gateway ihr an dieser Verbindung vorlegt;values.modelnennt weiterhin den Alias, den das Gateway veröffentlicht. Die Maskierung gilt für die Aufrufe jedes Alias, den das Gateway bedient.