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.
| Feld | Wert |
|---|---|
text | Der zu prüfende Text |
model | Ein PII-Modell; ohne Angabe gilt der vom Betreiber konfigurierte Standard |
entities | Optional; begrenzt die angefragten Kategorien |
threshold | Optional; 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-Modell | Chatmodell (LLM) | |
|---|---|---|
| Abrechnung | Zeichentarif, keine zusätzlichen Prompt- und Ausgabetokens | tatsächliche Tokenpreise |
| Abdeckung | die Kategorien des Detektors | kann andere Erkennungsqualitäten und Sprachen abdecken |
| Aufrufe | eine Erkennung | strukturierte 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:
| Grenze | Wert |
|---|---|
| Abschnitt | 8.192 Unicode-Skalarwerte |
| Überlappung | 512 |
| Abschnitte | höchstens 16 |
| Ausgabetokens | 8.192 |
| Fundstellenausgabe | 128 KiB |
| Gesamte Eingabe | 65.536 UTF-8-Bytes |
Wie LLM-Fundstellen angewendet werden
- Das LLM liefert ausschließlich
label,start,endundtext. - 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;
thresholdbleibt die native Detektorschwelle. - Ein LLM-Auftrag darf nicht mit
fail_openkonfiguriert 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_countundtoken_usagemit tatsächlichen Input-, Output- und Cachetokens dokumentieren die Tokenabrechnung.token_usage.costsbewahrt 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.