# 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](https://tokenlane.de/docs/guides/pii-redaction.md?lang=de).

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
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

```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

```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

```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](https://tokenlane.de/docs/guides/pii-redaction.md?lang=de).

## Modell wählen
[PII-Modelle](https://tokenlane.de/models?category=pii&sovereign=0) 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:

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

Im [Plugin](https://tokenlane.de/docs/guides/pii-redaction.md?lang=de) lautet die Auswahl:

```json
{ "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`, `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](https://tokenlane.de/docs/guides/pdf-parser.md?lang=de) und [OCR](https://tokenlane.de/docs/guides/ocr.md?lang=de).

## 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](https://tokenlane.de/docs/gateway/post-L3BpaS9yZWRhY3Q.md?lang=de) und den aktuellen [PII-Katalog](https://tokenlane.de/models?category=pii&sovereign=0) nutzen. Explizite Modell-IDs machen die Routenauswahl nachvollziehbar. Chat Completions nicht als Ersatz aufrufen und vorgeschriebene Schwärzung nach einem Anbieterfehler nicht deaktivieren.
