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

OptionOhne AngabeBedeutung
modelpreprocessing.pii_model des BetreibersDetektormodell, nicht das Hauptinferenzmodell
entitiesAlle acht Kategorienperson, address, email, phone, iban, identifier, date_of_birth, organization
threshold0.5Konfidenzschwelle des nativen Detektors zwischen null und eins; niedrigere Werte akzeptieren mehr gemeldete Fundstellen, holen aber keine ungemeldete Fundstelle nach
restoretrueErlaubt 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.

SignalEinordnung
Direkter Endpunkt meldet für den Wert keine FundstelleKein 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 PlatzhalterErkennung und direkte Transformation haben bei dieser Anfrage funktioniert; das allein belegt noch nicht den Chat-Providerbody
Erfasste Inferenzanfrage enthält den PlatzhalterDie Transformation fand vor der Inferenz statt
Inferenzantwort enthält diesen Platzhalter, Clientantwort dessen OriginalBei 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

LageVerhalten
Kein Detektor eingerichtet501 feature_unavailable, nicht wiederholbar und ohne Retry-After; eine Wiederholung kann ihn nicht einrichten
Keine Route erfüllt die Regeln einschließlich ZDRKein unzulässiger Detektoraufruf; Feldhinweise und remedy_hint prüfen
Detektorfehler oder unbrauchbare AusgabeZulässiger Fallback oder Fehler; Pflichtschwärzung darf nicht still in unmaskierte Inferenz übergehen
Optionale native Erkennung mit vom Betreiber freigegebenem fail_openEin Erkennungsfehler darf Originaltext zur Inferenz durchlassen; restore: false schaltet diese Ausnahme nicht ab
Spätere Inferenz scheitertBereits 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.