Konzepte
Maskierung
Wie das Gateway personenbezogene Daten durch Platzhalter ersetzt, die Antwort zurückübersetzt und die Zuordnung dafür speichert.
Bei aktiver Maskierung ersetzt das Gateway erkannte personenbezogene Daten durch Platzhalter, bevor es die Anfrage an den Anbieter weiterleitet. In der Antwort setzt es die Originalwerte wieder ein. Ihre Anwendung arbeitet mit den Originalwerten, der Anbieter erhält die Platzhalter.
Ablauf
- Erkennen: Das Gateway sucht in den maskierbaren Feldern der Anfrage nach personenbezogenen Daten, zum Beispiel Namen, E-Mail-Adressen und IBANs. Welche Felder das je Endpunkt sind, steht unter Maskierte Felder.
- Ersetzen: Jeder erkannte Wert wird zu einem Platzhalter der Form
<<TYP_N>>: dem Typ des Werts und einer laufenden Nummer, etwa<<PERSON_1>>oder<<IBAN_1>>. Derselbe Wert erhält überall in der Anfrage denselben Platzhalter. Legen Admins unter Models → Datenschutz ein Pseudonym-Label fest, steht dieses Label statt des Typs in jedem Platzhalter. - Weiterleiten: Das Gateway leitet die Anfrage mit den Platzhaltern weiter. Enthält sie Platzhalter, ergänzt das Gateway eine Systemanweisung: Das Modell soll die Platzhalter wie echte Werte verwenden und nicht kommentieren.
- Wiederherstellen: In der Antwort ersetzt das Gateway die Platzhalter durch die Originalwerte. Beim Streaming geschieht das satzweise: Das Gateway hält Text zurück, bis ein Satz vollständig ist, und gibt ihn dann zurückübersetzt weiter.
Sie senden
Schreiben Sie Anna Schmidt, dass die Zahlung auf DE89 3704 0044 0532 0130 00 eingegangen ist.
Das Modell sieht
Schreiben Sie <<PERSON_1>>, dass die Zahlung auf <<IBAN_1>> eingegangen ist.
Die Erkennung arbeitet automatisch. Sie findet nicht jeden Wert mit Sicherheit. Was das Gateway in einem Text erkennt, prüfen Sie mit POST /v1/detect.
Maskierungsrichtlinie
Ob das Gateway eine Anfrage maskiert, entscheidet die Maskierungsrichtlinie Ihrer Organisation zusammen mit dem Header X-Noirdoc-Mask. Admins Ihrer Organisation stellen die Richtlinie unter Models → Datenschutz ein.
| Richtlinie | Verhalten | Wirkung des Headers |
|---|---|---|
default_off | Das Gateway maskiert nicht. Standard für neue Organisationen. | X-Noirdoc-Mask: on schaltet die Maskierung für diese Anfrage ein. |
default_on | Das Gateway maskiert jede Anfrage. | X-Noirdoc-Mask: off schaltet die Maskierung für diese Anfrage aus. |
enforced | Das Gateway maskiert jede Anfrage. | Keine. Das Gateway ignoriert den Header. |
Der Header akzeptiert nur on und off, Groß- und Kleinschreibung spielt keine Rolle. Andere Werte ignoriert das Gateway. Es entfernt den Header, bevor es die Anfrage weiterleitet; der Anbieter sieht ihn nie. Wie Sie den Header im SDK setzen, zeigt Maskierung einschalten.
Ist die Maskierung für eine Anfrage aus, überspringt das Gateway Erkennen, Ersetzen und Wiederherstellen vollständig. Weiterleitung, Protokollierung und Abrechnung laufen unverändert. Ob die Maskierung für eine Anfrage aktiv war, zeigt der Antwort-Header X-Noirdoc-Masked (siehe Authentifizierung & Header).
Endpunkte ohne Maskierung
Diese Endpunkte leiten den Inhalt immer unmaskiert weiter:
| Endpunkt | Inhalt |
|---|---|
POST /v1/embeddings | Eingabetext |
POST /v1/audio/transcriptions | Audiodatei |
POST /v1/audio/speech | Eingabetext |
POST /v1/images/generations | Prompt |
Auf diesen Endpunkten lehnt das Gateway eine Anfrage mit Statuscode 403 ab, wenn die Richtlinie enforced gilt oder die Anfrage X-Noirdoc-Mask: on sendet. So entsteht nie der Eindruck, der Inhalt sei maskiert worden. Unter default_off und default_on ohne diesen Header leitet das Gateway die Anfrage unmaskiert weiter.
| Status | Code | Bedeutung |
|---|---|---|
| 403 | masking_not_supported_for_endpoint | Der Endpunkt kann nicht maskieren, aber die Maskierungsrichtlinie ist enforced oder die Anfrage sendet X-Noirdoc-Mask: on. |
Die Endpunkte /v1/files und /v1/skills reicht das Gateway ohne Maskierung durch. Aufrufe mit Inhalt, etwa das Hochladen einer Datei, lehnt es nach derselben Regel mit 403 ab; Auflisten, Abrufen, Herunterladen und Löschen bleiben erlaubt. Wie das Gateway mit Dateien umgeht, die im Body einer Chat-Anfrage stecken, beschreibt Dateien.
Zuordnung über mehrere Anfragen
Die Zuordnung verbindet jeden Platzhalter mit seinem Originalwert. Das Gateway speichert sie, damit eine Unterhaltung über mehrere Anfragen dieselben Platzhalter behält und spätere Antworten zurückübersetzt werden können:
- Chat Completions und Messages: Sendet Ihre Anwendung den bisherigen Verlauf unverändert mit, erkennt das Gateway die Unterhaltung wieder und verwendet die gespeicherte Zuordnung.
<<PERSON_1>>bleibt dann dieselbe Person. - Responses: Das Gateway findet die Zuordnung über
previous_response_id. Der Anbieter hält den Verlauf in diesem Fall mit Platzhaltern; nur mit der Zuordnung kann das Gateway spätere Antworten zurückübersetzen. - Erzeugte Dateien: Lädt Ihre Anwendung über
/v1/files/{id}/contenteine Datei herunter, die das Modell aus einer maskierten Anfrage erzeugt hat, setzt das Gateway auch darin die Originalwerte ein. Das gilt für Textdateien (etwa TXT, CSV, Markdown, JSON), DOCX und XLSX. Andere Formate gibt das Gateway unverändert weiter.
Das Gateway speichert eine Zuordnung nur, wenn die Anfrage Platzhalter enthielt. Es speichert sie verschlüsselt und löscht sie nach Ablauf der Aufbewahrungsdauer automatisch. Die Aufbewahrungsdauer beträgt standardmäßig 30 Tage. Admins Ihrer Organisation ändern sie unter Models → Datenschutz im Feld Mapping-TTL. Eine Zuordnung gilt nur für die Organisation, deren Anfrage sie erzeugt hat.
Mit dem Wert 0 speichert das Gateway keine Zuordnung. Es maskiert dann jede Anfrage für sich: Die Nummerierung der Platzhalter beginnt in jeder Anfrage neu, und Platzhalter aus früheren Antworten im Verlauf übersetzt das Gateway nicht zurück. Auch erzeugte Dateien erhalten beim Herunterladen keine Originalwerte.