zulassung-ocr-compare/README.md

Fahrzeugschein-OCR: lokaler Vergleich

Eine lokale Testoberfläche für zwei unabhängige Wege auf demselben Bild:

A: klassische OCR	B: Vision-Dokumentmodell
PP-OCRv5 mobile, Latin: Textzeilen und Zeilenboxen	PaddleOCR-VL 1.6 mit Layout-Erkennung: Dokumentregionen, Text und Tabellen
Flexible, regelbasierte Feldvorschläge	Feldvorschläge aus gelesenen Layoutblöcken und Tabellen

Die Oberfläche zeigt Rohtext, Feldvorschläge, Bildbelege und Laufzeiten nebeneinander. Die Ecken des Dokuments lassen sich per Maus oder Touch setzen; alternativ wird das ganze Bild verwendet. Besondere Feldcodes: C.1.1 (Name), C.1.2 (Vorname), C.1.3 (Anschrift), B (Erstzulassung), 2.1 (HSN) und 2.2 (TSN). Jeden Vorschlag am Bild prüfen. Unleserliche oder unbelegte Werte bleiben offen. Es werden keine künstlichen Konfidenzwerte angezeigt.

Dieses Repository enthält keine Dokumentbilder, OCR-Ergebnisse, personenbezogenen Testdaten, Modellgewichte, privaten Hostnamen oder Zugangsdaten. Die Tests nutzen erfundene Textzeilen und generierte Bilder. Ein Generator kann lokal synthetische Trainingsbeispiele erzeugen; dieses Repository startet selbst kein Training. Es gibt keine Datenübertragung an externe OCR- oder KI-APIs. Die offiziellen Modellgewichte werden beim Einrichten heruntergeladen; die Inferenz nutzt anschließend explizite lokale Modellverzeichnisse. Der optionale SSH-Modus überträgt das Bild ausschließlich an eine selbst verwaltete Maschine. Das Projekt ist für interne Tests gedacht und enthält keine öffentliche Lizenz.

Voraussetzungen

• Python 3.11 oder 3.12, Git und ausreichend freier Speicherplatz für PaddlePaddle, Abhängigkeiten und Modellgewichte.
• macOS mit Apple Silicon oder Linux x86_64. Für die Vision-Pipeline kann eine eigene NVIDIA-GPU genutzt werden. Auf Apple Silicon läuft der hier genutzte PaddlePaddle-Pfad auf der CPU; Vision kann deutlich länger dauern.
• Ein aktueller Browser. Der Webserver wird nur an 127.0.0.1 gebunden. Für entfernte Nutzung einen SSH-Tunnel verwenden, keinen öffentlichen Port öffnen.
• Installiere entweder paddlepaddle für CPU oder paddlepaddle-gpu passend zu Treiber/CUDA, niemals beide in derselben Umgebung.

Die offizielle PaddleOCR-VL-Anleitung beschreibt die vollständige Pipeline und die Hardwarepfade. Für Apple Silicon gibt es eine eigene Anleitung. Das Repo ist mit PaddleOCR 3.7.0 festgelegt; PaddlePaddle 3.2.1 oder neuer wird getrennt installiert.

In den Beispielen steht python3.12; mit installiertem Python 3.11 kann stattdessen python3.11 verwendet werden.

macOS, Apple Silicon

Im geklonten Repository:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install paddlepaddle==3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
python -m pip install -e '.[vision,test]'
python -m ocr_compare.setup_models --classic --vision --device cpu
OCR_VISION_MODE=local OCR_VISION_DEVICE=cpu python -m uvicorn ocr_compare.server:app --host 127.0.0.1 --port 8092

Dann http://127.0.0.1:8092/ öffnen. Die Modelleinrichtung nutzt ausschließlich ein im Skript erzeugtes Testbild. Die Gewichte liegen im ignorierten Verzeichnis .cache/. Je nach Mac und Bildgröße kann die Vision-Stufe ihr Zeitlimit erreichen; A bleibt dann trotzdem sichtbar.

Linux x86_64, CPU

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install paddlepaddle==3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
python -m pip install -e '.[vision,test]'
python -m ocr_compare.setup_models --classic --vision --device cpu
OCR_VISION_MODE=local OCR_VISION_DEVICE=cpu python -m uvicorn ocr_compare.server:app --host 127.0.0.1 --port 8092

Linux x86_64 mit eigener NVIDIA-GPU

Dieses Beispiel gilt für eine passende CUDA-12.6-Umgebung. Für andere CUDA-Versionen den offiziellen Installationsweg wählen.

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install paddlepaddle-gpu==3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/
python -m pip install -e '.[vision,test]'
python -m ocr_compare.setup_models --classic --vision --device gpu:0
OCR_VISION_MODE=local OCR_VISION_DEVICE=gpu:0 python -m uvicorn ocr_compare.server:app --host 127.0.0.1 --port 8092

Prüfe vorher nvidia-smi und den passenden Treiber. Beide Verfahren laufen lokal, wobei A die CPU und B die konfigurierte GPU nutzt.

Vision auf einer eigenen Linux-Maschine per SSH

Dieser Modus ist optional, wenn der Browser und A auf einem anderen Rechner laufen. Auf dem GPU-Rechner denselben Commit klonen, die obige GPU-Umgebung einrichten und dort python -m ocr_compare.setup_models --vision --device gpu:0 ausführen. Auf dem lokalen Rechner A samt CPU-PaddlePaddle und python -m ocr_compare.setup_models --classic einrichten; die Vision-Zusatzpakete sind dort nicht nötig (python -m pip install -e '.[test]').

Vorhandenen SSH-Zugang mit bereits bekanntem Hostschlüssel verwenden. Auf dem lokalen Rechner die eigenen Werte als Umgebungsvariablen setzen (Beispielnamen sind Platzhalter):

export OCR_VISION_MODE=ssh
export OCR_VISION_SSH_TARGET='user@gpu-host'
export OCR_VISION_REMOTE_DIR='/path/to/clone'
export OCR_VISION_REMOTE_PYTHON='./.venv/bin/python'
export OCR_VISION_REMOTE_DEVICE='gpu:0'
python -m uvicorn ocr_compare.server:app --host 127.0.0.1 --port 8092

Optional: OCR_VISION_SSH_IDENTITY für einen bereits vorhandenen privaten Schlüssel, OCR_VISION_REMOTE_MODEL_HOME für einen abweichenden Cachepfad, OCR_VISION_REMOTE_UNSHARE=1 für Linux-Netzwerk-Isolation, sofern der Zielhost User Namespaces erlaubt. Der entfernte Befehl benötigt GNU timeout. Bilddateien werden dort in einem temporären, nach dem Lauf gelöschten Verzeichnis verarbeitet. Lege echte Dokumente und SSH-Schlüssel nie im Clone ab.

Windows

Mit WSL2/Ubuntu die Linux-Schritte innerhalb von WSL2 ausführen. Native Windows-Installation ist für diesen Stand nicht getestet; die PaddleOCR-Dokumentation ist dafür die Referenz.

Bedienung und Grenzen

1. JPEG oder PNG hochladen (maximal 16 MiB und 24 Megapixel).
2. Bei Bedarf vier äußere Ecken setzen und die Leserichtung wählen.
3. Beide Ergebnisse vergleichen. Ein Fehler bei B unterdrückt A nicht.
4. Rohtext und die markierten Bildbereiche prüfen. Automatische Vorschläge lassen sich verwerfen; erkannte Textzeilen können manuell einem Feld zugeordnet werden.

Die klassische OCR liefert präzisere Zeilenboxen, kann aber Text verlesen. Die Vision-Pipeline erkennt Layout und Tabellen, ihre Belege können ganze Regionen statt einzelner Wörter markieren. Die Zuordnung ist bewusst konservativ und kein amtliches Auslesen. Dieses Repository enthält keine belastbare Erkennungsquote für reale Fahrzeugscheine.

Die App verarbeitet Uploads im Speicher und in kurzlebigen temporären Dateien. Sie schreibt weder Dokumente noch OCR-Ausgaben in ein dauerhaftes Verzeichnis. Browser und eigener Server sehen die Bilddaten; bei SSH-Betrieb auch der eigene SSH-Zielhost. Vor dem Einsatz mit echten Dokumenten sollten Modelle bereits eingerichtet sein. Ein fehlender Cache wird als Fehler angezeigt, statt beim Upload Modellgewichte nachzuladen.

Synthetische Daten und Training

Der Generator erzeugt sichtbar ungültige, erfundene Fahrzeugformulare mit variierter Feldreihenfolge, Schrift, Dichte und Bildstörung. Er liest keine Quelldokumente. Ausgabe und Modellartefakte liegen unter dem von Git ignorierten data/-Verzeichnis. Niemals echte Dokumente, daraus ausgeschnittene Texte oder OCR-Ausgaben in diesen Trainingssatz mischen.

python -m ocr_compare.synthetic --out data/synthetic-v1 --count 100 --seed 20261007
python -m ocr_compare.benchmark_synthetic --dataset data/synthetic-v1

Vor dem Benchmark die klassischen Modelle mit python -m ocr_compare.setup_models --classic lokal einrichten. Der Benchmark verarbeitet standardmäßig nur den nach ganzen Dokumenten getrennten Validierungsteil; --split train und --split all sind für die Fehlersuche gedacht. Er gibt ausschließlich Summen aus: an Wertboxen überlappende OCR-Zeilen, dort vollständig gelesene Werte und korrekt, falsch oder gar nicht zugeordnete Zielfelder. Für eine neue Stichprobe ein neues Ausgabeverzeichnis und einen anderen Seed nehmen. Der Generator überschreibt nichts.

Der Satz enthält rec_train.txt/rec_val.txt mit Bildpfad und Text für die PaddleOCR-Texterkennung sowie det_train.txt/det_val.txt mit Seitenpfad und Zeilenpolygonen für die Texterkennung auf der Seite. ground_truth.jsonl enthält die exakten synthetischen Sollwerte für C.1.1, C.1.2, C.1.3, B, 2.1 und 2.2. Eine Validierung der Labels und des Auswertungscodes ist in den lokalen Tests enthalten; ein Modelltraining und dessen Export sind hier noch nicht getestet.

Für einen Trainingsexperiment zuerst den Fehler nach Stufe messen: Fehlende Textboxen sprechen für den Detektor, falsch gelesene vorhandene Boxen für den Recognizer. Korrekt gelesene Werte mit falschem Feldcode sind ein Zuordnungs- oder Layoutproblem. PaddleOCR-VL ist eine Pipeline aus Layoutanalyse und VLM. Die offizielle SFT-Anleitung unterstützt zurzeit nur das VLM; die ERNIEKit-Beispielkonfiguration wurde auf einer 80-GB-GPU demonstriert. Das ist keine belastbare Zusage für Training auf einer kleineren lokalen GPU. Synthetische Validierung allein beweist keine Verbesserung bei echten Dokumenten: Diese ausschließlich als unveränderten, lokalen Test-Holdout verwenden, nie zum Training.

Prüfen und Fehler eingrenzen

python -m unittest discover -s tests -v
curl -fsS http://127.0.0.1:8092/api/health

Wenn A oder B Modelle fehlen zeigt: Modelleinrichtung in derselben Umgebung und auf dem betroffenen Host ausführen. Für einen anderen privaten Modellcache vor Einrichtung und Serverstart OCR_MODEL_HOME=/path/to/cache setzen. Bei SSH zusätzlich OCR_VISION_REMOTE_MODEL_HOME, falls der entfernte Cache nicht unter .cache/ im Clone liegt. Bei Vision-Konfiguration Ziel, Clonepfad, Pythonpfad und SSH-Erreichbarkeit prüfen. Bei Zeitlimit zunächst ein gut ausgerichtetes, kleineres Bild versuchen; CPU-Vision kann hierfür ungeeignet sein.

config.example.env dokumentiert alle optionalen Variablen. Sie wird nicht automatisch geladen. Lokale Konfigurationen und Modellgewichte gehören nicht ins Git-Repository.

Vor einem Repository-Push

Die .gitignore lässt nur Quellcode, Tests und diese Anleitung zu. Auch damit gilt: keine echten Dokumente, Ergebnisse, Schlüssel, privaten Konfigurationen oder Modellgewichte committen. Nach dem Staging die tatsächlich vorgemerkten Git-Blobs prüfen:

git status --short
python scripts/release_audit.py
git diff --cached --stat

Der Audit nennt bei einem Fund nur Regel und Dateipfad, niemals den gefundenen Inhalt. Er ersetzt keine Codeprüfung. Das Repository für Kollegen privat halten und Zugriffsrechte im eigenen Gitea-Team setzen.