Direkte PII-Schwärzung

Personenbezogene Daten mit einem normalen gerouteten PII-Modell erkennen und maskieren.

Wann nutzen

Der direkte Schwärzungsendpunkt liefert maskierten Text und erkannte Spannen ohne Inferenzantwort. Für die automatische Prüfung von Chat-Eingaben dient das PII-Schwärzungsplugin.

Der gewählte Anbieter verarbeitet dabei den Originaltext. Die Erkennung belegt keine Anonymisierung.

Minimalbeispiel

Diese Anfrage verwendet eine synthetische reservierte E-Mail-Adresse und fordert nur die Erkennung von E-Mail-Adressen an.

curl

curl --request POST \
  --url 'https://api.tokenlane.de/v1/pii/redact' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "grunden/gliner-multi-pii",
  "text": "Contact lena@example.invalid",
  "entities": [
    "email"
  ],
  "threshold": 0.5
}'

node

const response = await fetch("https://api.tokenlane.de/v1/pii/redact", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "model": "grunden/gliner-multi-pii",
  "text": "Contact lena@example.invalid",
  "entities": [
    "email"
  ],
  "threshold": 0.5
}`,
});
console.log(await response.text());

python

import os
import urllib.request

body = (r'''{
  "model": "grunden/gliner-multi-pii",
  "text": "Contact lena@example.invalid",
  "entities": [
    "email"
  ],
  "threshold": 0.5
}''').encode("utf-8")

request = urllib.request.Request(
    "https://api.tokenlane.de/v1/pii/redact",
    method="POST",
    headers={
        "Authorization": "Bearer " + os.environ["TOKENLANE_API_KEY"],
        "Content-Type": "application/json",
    },
    data=body,
)

with urllib.request.urlopen(request) as response:
    print(response.read().decode("utf-8"))

vercel

// This operation uses HTTP directly.
const response = await fetch("https://api.tokenlane.de/v1/pii/redact", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "model": "grunden/gliner-multi-pii",
  "text": "Contact lena@example.invalid",
  "entities": [
    "email"
  ],
  "threshold": 0.5
}`,
});
console.log(await response.text());

Anfrageformat

JSON an POST /v1/pii/redact senden, mit text und einem aktuellen PII-model. Die Antwort enthält maskierten Text und Spannen.

FeldWert
textDer zu prüfende Text
modelEin PII-Modell; ohne Angabe gilt der vom Betreiber konfigurierte Standard
entitiesOptional; begrenzt die angefragten Kategorien
thresholdOptional; steuert die Erkennungsschwelle

Ohne entities werden alle acht Kategorien angefordert: person, address, email, phone, iban, identifier, date_of_birth und organization. Die native Konfidenzschwelle beträgt voreingestellt 0.5 und erlaubt Werte zwischen null und eins. Niedrigere Werte akzeptieren mehr gemeldete Fundstellen, holen aber keine vom Detektor ungemeldete Fundstelle nach.

Das Antwortfeld masked enthält den transformierten Text. entities enthält validierte Kategorien und Quellpositionen, keine Originalzitate oder Rückübersetzungstabelle. Ohne akzeptierte Fundstellen bleibt masked unverändert. Eine erfolgreiche leere Erkennung beweist nicht, dass die Eingabe keine personenbezogenen Angaben enthält.

Der direkte Endpunkt übersetzt Werte nicht zurück. Im Chat ist Rückübersetzung mit true voreingestellt; restore: false schaltet die Gateway-Rückübersetzung aus der Ersetzungstabelle in JSON und SSE aus, nicht die Erkennung oder beliebige PII-Erzeugung in der Antwort. Vor der Zuordnung sichtbarer Originalwerte zur Rückübersetzung hilft die Diagnose des Plugin-Datenpfads.

Modell wählen

PII-Modelle haben gewöhnliche Anbieterrouten und Fallback. Anbieter-, Modell-, Länder-, Rechtsraum- und Preisregeln gelten auch im Plugin.

Die Erkennung erhält immer die personenbezogenen Rohdaten; das Schwärzen schützt nicht vor dem Erkennungsanbieter.

Spezialisiertes PII-ModellChatmodell (LLM)
AbrechnungZeichentarif, keine zusätzlichen Prompt- und Ausgabetokenstatsächliche Tokenpreise
Abdeckungdie Kategorien des Detektorskann andere Erkennungsqualitäten und Sprachen abdecken
Aufrufeeine Erkennungstrukturierte Aufträge, gegebenenfalls mehrere sequenzielle Aufrufe

Qualität und Latenz sind modellabhängig, nicht garantiert. Beide Wege können personenbezogene Daten übersehen.

Chatmodell nutzen

Als Gateway-Erweiterung kann model auch ein normales Chatmodell auswählen, wenn der Betreiber dafür ausdrücklich eine pii.llm-Ausführung mit Klartextfreigabe eingerichtet hat. Eine Chatroute allein reicht nicht: Erforderlich sind JSON-Schema-Ausgabe oder erzwungene Tools, unverändert weitergeleitete Kontrollfelder sowie begrenzte Kontext- und Ausgabetokens.

Der direkte Endpunkt akzeptiert dann:

{
  "model": "<freigegebenes-chatmodell>",
  "text": "Contact lena@example.invalid",
  "entities": ["email"]
}

Im Plugin lautet die Auswahl:

{ "id": "pii-redact", "model": "<freigegebenes-chatmodell>", "restore": false }

Modell-IDs sind aus dem tatsächlich eingerichteten Katalog zu wählen; die Platzhalter sind keine verfügbaren Modellnamen.

LLM-Grenzen

Der versionierte Auftrag enthält Prompt, Schema, Abschnittsgröße, Überlappung, Aufruflimit, Ausgabetokens und Antwortbytegrenze. Betreiber dürfen innerhalb der validierten Grenzen eigene versionierte Auftragsdaten konfigurieren. Die mitgelieferte Revision verwendet:

GrenzeWert
Abschnitt8.192 Unicode-Skalarwerte
Überlappung512
Abschnittehöchstens 16
Ausgabetokens8.192
Fundstellenausgabe128 KiB
Gesamte Eingabe65.536 UTF-8-Bytes

Wie LLM-Fundstellen angewendet werden

  • Das LLM liefert ausschließlich label, start, end und text.
  • Nur exakte Originalzitate mit gültigen Unicode-Skalarpositionen und erlaubten Kategorien werden angewendet.
  • Ungültige Einträge werden verworfen und gezählt; eine vollständig ungültige nichtleere Ausgabe ist ein Fehler.
  • Gültige Überschneidungen werden konservativ vereinigt, doppelte Treffer nur einmal maskiert.
  • Insgesamt sind höchstens 256 gemeldete Fundstellen erlaubt, einschließlich Duplikaten aus überlappenden Abschnitten; eine Überschreitung führt zu einem Fehler statt zu stiller Kürzung.
  • Die vorhandenen kollisionssicheren Platzhalter ändern den Text, nicht das LLM.
  • LLM-Fundstellen liefern keine kalibrierte Konfidenz; threshold bleibt die native Detektorschwelle.
  • Ein LLM-Auftrag darf nicht mit fail_open konfiguriert werden.

OCR

OCR-Anbieter erhalten ursprüngliche Dokumentinhalte, so wie PII-Detektoren den Originaltext erhalten; der PII-Anschluss und seine Datenschutzgrenze ändern sich dadurch nicht. Modellwahl, Grenzen und Tokenabrechnung der Dokumentextraktion stehen unter PDF-Parser und OCR.

Kosten

Der Zeichentarif ist von Tokenpreisen unabhängig. Die Einheit zählt Unicode-Skalarwerte des übermittelten Textes, nicht UTF-8-Bytes.

Die preprocessing-Einträge des Belegs nennen unit: "character", Menge, Modell, Anbieter und EUR-Kosten. Soweit vorhanden bleiben die ursprüngliche Anbieterwährung und der Wechselkursstand erhalten. Unbekannte Gebühren werden nicht als kostenlose Verarbeitung dargestellt.

Abrechnung beim LLM

Beim LLM bleibt unit: "character" die gescannte Arbeitsmenge, einschließlich erneut gescannten Überlappungen. Sie ist nicht die Preisbasis.

  • execution: "llm_span_extract", task_version, rejected_count und token_usage mit tatsächlichen Input-, Output- und Cachetokens dokumentieren die Tokenabrechnung.
  • token_usage.costs bewahrt die ursprünglichen, Kunden- und Einkaufskosten nach Preisbestandteil.
  • Der Parent-Aufruf reserviert Geld und Tokens vor dem Senden und schließt gemeinsam mit dem Plugin ab.
  • Bezahlte ungültige Antworten und Fallbacks bleiben im Beleg erhalten; fehlende bestätigte Nutzung ist keine kostenlose Erkennung.

Häufige Fehler

Unbekannte Modelle, fehlende zulässige Anbieter, nicht unterstützte Erkennungsoptionen und nicht verfügbare Detektoren haben eigene Fehler. error.metadata.issues und remedy_hint prüfen.

Ist Schwärzung vorgeschrieben und kein zulässiger Detektor verfügbar, muss die Anfrage sicher scheitern. Das gilt auch in Plugins.

Bewährte Praxis

  • Nur zur Verarbeitung freigegebene Informationen senden.
  • Die veröffentlichten Textgrenzen einhalten.
  • Weder Eingabetext noch erkannte Spannen protokollieren.
  • Maskierte Ausgaben weiter als sensibel behandeln, solange die Anwendung keine stärkere Datenschutzgarantie belegt hat.

Für KI-Agenten

Die Referenz des direkten PII-Endpunkts und den aktuellen PII-Katalog nutzen. Explizite Modell-IDs machen die Routenauswahl nachvollziehbar. Chat Completions nicht als Ersatz aufrufen und vorgeschriebene Schwärzung nach einem Anbieterfehler nicht deaktivieren.