# TrOCR ONNX Runtime

## Uebersicht

TrOCR (Transformer-based OCR) kann sowohl mit PyTorch als auch mit ONNX Runtime betrieben werden. ONNX bietet deutlich reduzierten RAM-Verbrauch und schnellere Inferenz — ideal fuer den Offline-Betrieb auf Hardware Tier 2 (8 GB RAM).

## Export-Prozess

### Voraussetzungen

- Python 3.10+
- `optimum>=1.17.0` (Apache-2.0)
- `onnxruntime` (bereits installiert via RapidOCR)

### Export ausfuehren

```bash
python scripts/export-trocr-onnx.py --model both
```

Dies exportiert:
- `models/onnx/trocr-base-printed/` (~85 MB fp32 → ~25 MB int8)
- `models/onnx/trocr-base-handwritten/` (~85 MB fp32 → ~25 MB int8)

### Quantisierung

Int8-Quantisierung reduziert Modellgroesse um ~70% mit weniger als 2% Genauigkeitsverlust.

## Runtime-Konfiguration

### Umgebungsvariablen

| Variable | Default | Beschreibung |
|----------|---------|--------------|
| `TROCR_BACKEND` | `auto` | Backend-Auswahl: `auto`, `pytorch`, `onnx` |
| `TROCR_ONNX_DIR` | (siehe unten) | Pfad zu ONNX-Modellen |

### Backend-Modi

- **auto** (empfohlen): ONNX wenn verfuegbar, sonst PyTorch Fallback
- **pytorch**: Erzwingt PyTorch (hoeherer RAM, aber bewaehrt)
- **onnx**: Erzwingt ONNX (Fehler wenn Modell nicht vorhanden)

### Modell-Pfade (Suchpfade)

1. `$TROCR_ONNX_DIR/trocr-base-{variant}/`
2. `/root/.cache/huggingface/onnx/trocr-base-{variant}/` (Docker)
3. `models/onnx/trocr-base-{variant}/` (lokale Entwicklung)

## Hardware-Anforderungen

| Metrik | PyTorch float32 | ONNX int8 |
|--------|-----------------|-----------|
| Modell-Groesse | ~340 MB | ~50 MB |
| RAM (Printed) | ~1.1 GB | ~300 MB |
| RAM (Handwritten) | ~1.1 GB | ~300 MB |
| Inferenz/Zeile | ~120 ms | ~40 ms |
| Mindest-RAM | 4 GB | 2 GB |

## Benchmark

```bash
# PyTorch Baseline (Sprint 1)
python scripts/benchmark-trocr.py > benchmark-baseline.json

# ONNX Benchmark
python scripts/benchmark-trocr.py --backend onnx > benchmark-onnx.json
```

Benchmark-Vergleiche koennen im Admin unter `/ai/model-management` eingesehen werden.

## Verifikation

Der Export-Script verifiziert automatisch, dass ONNX-Output weniger als 2% von PyTorch abweicht. Manuelle Verifikation:

```python
# Im Container
python -c "
from services.trocr_onnx_service import is_onnx_available, get_onnx_model_status
print('Available:', is_onnx_available())
print('Status:', get_onnx_model_status())
"
```