Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

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

InstanzKatalog-Componentwas es hier ist
routercore/gateway/litellmdas KI-Gateway: ein veröffentlichter Alias, assistant, bereitgestellt von dem Modell, das mit seinem Socket models verdrahtet ist
gptcore/ai-model/openaidas Modell hinter diesem Alias, die eigene API von OpenAI, als Referenz erreicht: Dafür läuft nichts im Cluster
analyzercore/security/presidio-analyzerfindet die sensiblen Textstellen in einem Text
anonymizercore/security/presidio-anonymizerersetzt 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:

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

Danach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:

Terminal window
cd ai-gateway-log-masking

Build

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

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

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

Dieser 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>/dist

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

Der 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_KEY

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

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

Der 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 logged

Greifen 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 entities aus values.log_masking sowie 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 entities hinzu, 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_masking durch eine Anbindung core/data-masking am Gateway, die dieselben patterns und entities auflistet, und binden Sie ihre Realisierung im Manifest.
  • Ein zweites Modell bereitstellen. Verdrahten Sie eine weitere Modellkomponente mit dem Socket models unter einem eigenen Alias, mit dem Schlüssel, den das Gateway ihr an dieser Verbindung vorlegt; values.model nennt weiterhin den Alias, den das Gateway veröffentlicht. Die Maskierung gilt für die Aufrufe jedes Alias, den das Gateway bedient.