flemming-it
3e018f528a
Some checks failed
CI / Linux x86_64 (Forgejo) (push) Failing after 1m20s
NER anonymization of German legal texts (plain text + DOCX) via the JuraNER model by Harshil Darji (MIT). The transformer model runs in the judge-ner host service; this module forwards documents over loopback HTTP and maps responses onto the capability contract.
103 lines
3.6 KiB
Markdown
103 lines
3.6 KiB
Markdown
# text.anonymize.legal-de
|
||
|
||
NER-basierte Anonymisierung deutscher juristischer Texte (JuraNER).
|
||
Brückenmodul: das Transformers-Modell läuft im **judge-ner
|
||
Host-Service** (`fai_judge/host_services/judge-ner/`); dieses
|
||
WASM-Modul reicht das Dokument per Loopback-HTTP weiter und bildet
|
||
die Antwort auf den Capability-Contract ab.
|
||
|
||
## Capability
|
||
|
||
- `text.anonymize.legal-de@0.1.0`
|
||
|
||
## Eingaben
|
||
|
||
| Name | Typ | Beschreibung |
|
||
| ---------- | ----- | ------------ |
|
||
| `request` | json | `{"mode":"text"\|"docx","options":{...}}` — siehe unten. |
|
||
| `document` | bytes | UTF-8-Klartext (mode=text) oder eine DOCX-Datei (mode=docx). |
|
||
| `endpoint` | text | Optionale judge-ner-Basis-URL. Default `http://127.0.0.1:8756`. |
|
||
|
||
### `request.options` (alle optional)
|
||
|
||
| Schlüssel | Default | Bedeutung |
|
||
| --------- | ------- | --------- |
|
||
| `importance_levels` | `["High"]` | Zu anonymisierende Entitätsklassen (`High`/`Mid`/`Low`). |
|
||
| `confidence_threshold` | `0.8` | Minimale NER-Konfidenz (0.0–1.0). |
|
||
| `manual_phrases` | `[]` | Zusätzlich zu schwärzende Phrasen (Label `RED`). |
|
||
| `maintain_consistency` | `true` | Gleiche Oberflächenform erhält überall dasselbe ⟦TYPE#⟧-Token. |
|
||
| `remove_rubrum` | `false` | Rubrum-Block erkennen und durch Platzhalter ersetzen. |
|
||
|
||
## Ausgaben
|
||
|
||
| Name | Typ | Beschreibung |
|
||
| ---------- | ----- | ------------ |
|
||
| `result` | json | `{"replacements": [...], "text": "..."}` — `text` (der anonymisierte Text) nur bei mode=text. `statistics` und `rubrum` werden vom Service durchgereicht, wenn vorhanden. |
|
||
| `document` | bytes | Das anonymisierte Dokument: UTF-8-Text (`text/plain`) bei mode=text, das umgeschriebene DOCX bei mode=docx. |
|
||
|
||
Jeder `replacements`-Eintrag:
|
||
`{text, label, label_description, start, end, score, line_number,
|
||
anonymized}`; im DOCX-Modus zusätzlich `run_id_start`,
|
||
`char_in_start`, `run_id_end`, `char_in_end` zur Adressierung der
|
||
exakten `w:t`-Knoten des Originaldokuments. Einträge mit
|
||
`"anonymized": null` wurden erkannt, aber nicht ersetzt
|
||
(Importance-Level nicht ausgewählt).
|
||
|
||
## Berechtigungen & benötigte Services
|
||
|
||
```yaml
|
||
permissions:
|
||
- "net: localhost"
|
||
- "net: 127.0.0.1"
|
||
requires_services:
|
||
- judge-ner
|
||
```
|
||
|
||
Der Hub führt Steps mit diesem Modul nur aus, wenn der Operator einen
|
||
`judge-ner`-Service-Endpunkt in `~/.chain/config.yaml` (`services:`)
|
||
deklariert hat. Beachte: Der erste judge-ner-Start lädt das
|
||
JuraNER-Modell von HuggingFace — bis dahin antwortet der Service mit
|
||
503 und dieses Modul schlägt mit einer klaren „NER model not
|
||
available"-Meldung fehl.
|
||
|
||
## Einrichtung des judge-ner-Host-Services
|
||
|
||
Das NER-Modell (JuraNER von Harshil Darji, MIT — transformers + torch)
|
||
kann nicht in der WASM-Sandbox laufen; es läuft als Host-Service.
|
||
|
||
```bash
|
||
# 1. Service starten (Docker; ~1 GB Modell-Download beim ersten Start,
|
||
# persistiert im Named Volume — spätere Starts sind offline-fähig)
|
||
docker run -d --name judge-ner \
|
||
-p 8756:8756 \
|
||
-v judge-ner-models:/models \
|
||
judge-ner
|
||
|
||
# 2. Beim Hub registrieren (~/.chain/config.yaml)
|
||
# services:
|
||
# judge-ner:
|
||
# endpoint: http://127.0.0.1:8756
|
||
# health_check:
|
||
# url: http://127.0.0.1:8756/health
|
||
|
||
# 3. Prüfen
|
||
curl -s localhost:8756/health # {"status":"ok","model_loaded":true}
|
||
chain service status judge-ner
|
||
```
|
||
|
||
Quellcode und Image-Build: `fai_judge/host_services/judge-ner/`
|
||
(`docker build -t judge-ner .`).
|
||
|
||
## Fehler
|
||
|
||
- Fehlerhafte `request`, Nicht-UTF-8-Textdokument oder 4xx vom
|
||
Service → `invalid input: ...`
|
||
- Service nicht erreichbar, 5xx, fehlerhafte Service-Antwort →
|
||
`internal error: judge-ner at <url> ...`
|
||
|
||
## Build
|
||
|
||
```bash
|
||
cargo test
|
||
cargo build --release --target wasm32-wasip2
|
||
```
|