PII-Schwärzung
Erkannte personenbezogene Angaben ersetzen, bevor eine Anfrage eine Inferenzroute erreicht.
Die Grenze verstehen
Das Plugin pii-redact lässt unterstützten Text beim freigegebenen Detektor prüfen. Das Gateway ersetzt validierte Treffer durch typisierte Platzhalter, bevor es den Text an die Inferenzroute sendet.
- Der Detektor erhält Originaltext. Die Schwärzung verbirgt ihn nicht vor diesem Anbieter.
- Nur gemeldete und akzeptierte Fundstellen werden ersetzt. Übersehene Angaben und ausgeschlossene Kategorien bleiben unverändert und können die Inferenz erreichen.
- Das ist kein Nachweis einer Anonymisierung und erfasst nicht beliebige binäre Anhänge.
Nur Daten nutzen, die die eigene Anwendung verarbeiten darf.
Schwärzung ausdrücklich anfordern
Das Beispiel verwendet eine synthetische reservierte E-Mail-Adresse, fordert email an und schaltet mit restore: false die Rückübersetzung durch das Gateway aus.
curl
curl --request POST \
--url 'https://api.tokenlane.de/v1/chat/completions' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "deepseek/deepseek-v4-flash-0731",
"messages": [
{
"role": "user",
"content": "Summarize this contact: lena@example.invalid"
}
],
"max_tokens": 400,
"plugins": [
{
"id": "pii-redact",
"entities": [
"email"
],
"threshold": 0.5,
"restore": false
}
]
}'
node
import OpenAI from 'openai';
const client = new OpenAI({ baseURL: "https://api.tokenlane.de/v1", apiKey: process.env.TOKENLANE_API_KEY });
const response = await client.chat.completions.create({
"model": "deepseek/deepseek-v4-flash-0731",
"messages": [
{
"role": "user",
"content": "Summarize this contact: lena@example.invalid"
}
],
"max_tokens": 400,
"plugins": [
{
"id": "pii-redact",
"entities": [
"email"
],
"threshold": 0.5,
"restore": false
}
]
}, {});
console.log(response);
python
import os
import json
from openai import OpenAI
client = OpenAI(base_url="https://api.tokenlane.de/v1", api_key=os.environ["TOKENLANE_API_KEY"])
body = json.loads(r'''{
"model": "deepseek/deepseek-v4-flash-0731",
"messages": [
{
"role": "user",
"content": "Summarize this contact: lena@example.invalid"
}
],
"max_tokens": 400,
"plugins": [
{
"id": "pii-redact",
"entities": [
"email"
],
"threshold": 0.5,
"restore": false
}
]
}''')
response = client.chat.completions.create(
model=body["model"],
messages=body["messages"],
max_tokens=body["max_tokens"],
extra_body=json.loads(r'''{
"plugins": [
{
"id": "pii-redact",
"entities": [
"email"
],
"threshold": 0.5,
"restore": false
}
]
}''')
)
print(response)
vercel
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText } from 'ai';
const tokenlane = createOpenAICompatible({ name: 'tokenlane', baseURL: "https://api.tokenlane.de/v1", apiKey: process.env.TOKENLANE_API_KEY, includeUsage: true });
const result = await generateText({
model: tokenlane("deepseek/deepseek-v4-flash-0731"),
messages: [
{
"role": "user",
"content": "Summarize this contact: lena@example.invalid"
}
],
maxOutputTokens: 400,
providerOptions: { tokenlane: {
"plugins": [
{
"id": "pii-redact",
"entities": [
"email"
],
"threshold": 0.5,
"restore": false
}
]
} },
});
console.log(result.text);
Voreinstellungen und Kategorien
| Option | Ohne Angabe | Bedeutung |
|---|---|---|
model | preprocessing.pii_model des Betreibers | Detektormodell, nicht das Hauptinferenzmodell |
entities | Alle acht Kategorien | person, address, email, phone, iban, identifier, date_of_birth, organization |
threshold | 0.5 | Konfidenzschwelle des nativen Detektors zwischen null und eins; niedrigere Werte akzeptieren mehr gemeldete Fundstellen, holen aber keine ungemeldete Fundstelle nach |
restore | true | Erlaubt dem Gateway, erkannte Platzhalter in der Antwort durch ihre Originale zu ersetzen, soweit erzwungene Regeln dies zulassen |
Die Auswahl nur von email fordert beispielsweise keine Telefonnummernerkennung an. Modellqualität, Sprache und Kontext beeinflussen die Treffer. LLM-Fundstellen haben keine kalibrierte Konfidenz; threshold ist dafür keine Qualitätsgarantie.
Was restore:false bewirkt
Mit restore: false übersetzt das Gateway erkannte Werte aus seiner Ersetzungstabelle weder in JSON- noch in SSE-Antworten zurück. Die Inferenzanfrage wird genauso maskiert wie bei restore: true; Rückübersetzung ändert den Antwortpfad, nicht die Erkennung.
Das ist kein PII-Ausgabefilter. Eine Adresse in der Antwort kann vom Detektor übersehen, durch die Kategorieauswahl ausgeschlossen oder vom Inferenzmodell unabhängig erzeugt worden sein. Ihr Auftreten allein belegt weder eine Gateway-Rückübersetzung noch den Inhalt der Inferenzanfrage. Umgekehrt kann ein Modell Platzhalter verändern oder weglassen; auch restore: true garantiert daher keine vollständige Rückübersetzung.
Erzwungene Regeln erhalten
Organisations- und Key-Regeln können Schwärzung unabhängig vom Plugin verlangen. Anfragen können diese Regeln nicht abschalten, ihre Kategorien einschränken, ihre Konfidenzschwelle anheben oder eine verbotene Rückübersetzung einschalten. Bedingungen werden für jede tatsächlich ausführende Inferenzroute einschließlich Fallback ausgewertet; eine ausdrücklich ausgenommene Route darf Originaltext erhalten.
Der Detektor hat eine eigene geroutete Anfrage. Modell-, Anbieter-, Länder-, Rechtsraum-, Preis- und Zero-Data-Retention-Regeln gelten auch für den Detektor, der die Originale erhält. Eine maskierte Inferenzanfrage nimmt die Erkennung nicht von diesen Anforderungen aus.
Sichtbare Originalwerte einordnen
Für die Prüfung des Datenpfads synthetische lokale Eingaben und einen kontrollierten Inferenzendpunkt nutzen. Keine echten personenbezogenen Daten oder Ersetzungstabellen protokollieren.
| Signal | Einordnung |
|---|---|
| Direkter Endpunkt meldet für den Wert keine Fundstelle | Kein akzeptierter Treffer; unveränderter Text ist erwartbar und kein Beleg für Rückübersetzung |
Direkter Endpunkt meldet eine Fundstelle und masked enthält den Platzhalter | Erkennung und direkte Transformation haben bei dieser Anfrage funktioniert; das allein belegt noch nicht den Chat-Providerbody |
| Erfasste Inferenzanfrage enthält den Platzhalter | Die Transformation fand vor der Inferenz statt |
| Inferenzantwort enthält diesen Platzhalter, Clientantwort dessen Original | Bei erlaubter Rückübersetzung erklärbar; mit restore: false untersuchungsbedürftig |
Für Vergleiche denselben Text, dasselbe Modell, dieselben Kategorien und dieselbe Schwelle verwenden. Routing und Detektorausgabe können zwischen getrennten Anfragen abweichen. Der direkte PII-Endpunkt liefert masked und validierte Fundstellen ohne Hauptinferenz; bei LLM-Erkennung selbst finden dennoch Modellaufrufe statt.
Detektorfehler und Kosten
| Lage | Verhalten |
|---|---|
| Kein Detektor eingerichtet | 501 feature_unavailable, nicht wiederholbar und ohne Retry-After; eine Wiederholung kann ihn nicht einrichten |
| Keine Route erfüllt die Regeln einschließlich ZDR | Kein unzulässiger Detektoraufruf; Feldhinweise und remedy_hint prüfen |
| Detektorfehler oder unbrauchbare Ausgabe | Zulässiger Fallback oder Fehler; Pflichtschwärzung darf nicht still in unmaskierte Inferenz übergehen |
Optionale native Erkennung mit vom Betreiber freigegebenem fail_open | Ein Erkennungsfehler darf Originaltext zur Inferenz durchlassen; restore: false schaltet diese Ausnahme nicht ab |
| Spätere Inferenz scheitert | Bereits angefallene Erkennungskosten können bestehen bleiben |
Der direkte Endpunkt scheitert immer geschlossen. LLM-Erkennung kann fail_open nicht einschalten. Eine Pflichtregel setzt natives Fail-open außer Kraft, macht aus einer erfolgreichen leeren Erkennung aber keinen Nachweis, dass der Text keine personenbezogenen Angaben enthält.
Die Erkennung verursacht zusätzliche Verarbeitungszeit und Kosten neben der Hauptinferenz. Native Modelle nutzen ihren Zeichentarif. Freigegebene LLM-Aufträge nutzen tatsächliche Tokenpreise und können mehrere aufeinanderfolgende Aufrufe über überlappende Fenster ausführen; Überlappungen werden gegebenenfalls erneut verarbeitet. Belege erhalten bezahlte Versuche, Fallback-Arbeit und Erkennungskosten auch dann, wenn spätere Verarbeitung scheitert. Fehlende bestätigte Nutzung bedeutet keine kostenlose Erkennung.
Detektormodell
Der direkte Endpunkt und das Plugin akzeptieren eine Modell-ID. Ein Chatmodell kommt nur mit einem ausdrücklich freigegebenen strukturierten PII-Auftrag infrage, nicht allein aufgrund seiner Chatfähigkeit:
{ "id": "pii-redact", "model": "<freigegebenes-modell>", "restore": false }
Das ist ein Platzhalter, kein verfügbares Modell. Ohne model gilt die eingerichtete Voreinstellung; null und leere Namen wählen diese nicht aus.
LLM-Aufträge liefern Fundstellen, niemals Ersetzungstext. Exakte Zitate und Unicode-Skalarpositionen werden geprüft; ungültige Einträge werden gezählt, vollständig ungültige nichtleere Ausgaben scheitern oder nutzen Fallback. Die Eingabe ist auf 65.536 UTF-8-Bytes mit begrenzt überlappenden Fenstern beschränkt. Grenzen, Belegfelder und native beziehungsweise LLM-Preise stehen im PII-Leitfaden.