fix: make OCR portable and reliable across AMD64 and ARM64 (#519)

* fix: make OCR portable and reliable

* fix: harden OCR installation portability

* fix: pin OCR partials across downloads

* fix: make OCR execution reliably asynchronous

* fix: harden OCR portability and docs routes

* fix: preserve decoder and docs safeguards

apps/docs/de/tools/image/ocr.md

@@ -1,31 +1,39 @@
 ---
-description: "Extrahiere Text aus Bildern mit KI-gestützter optischer Zeichenerkennung."
-i18n_source_hash: 3d85d423b82c
+description: "Extrahieren Sie Text lokal aus Bildern mit dem integrierten Tesseract oder der optionalen hochpräzisen RapidOCR-Laufzeitumgebung."
+i18n_output_hash: 7455d3e3f8ff
+i18n_source_hash: 0d453b49db02
 i18n_provenance: human
-i18n_output_hash: b3aac06f2306
 ---
 
 # OCR / Textextraktion {#ocr-text-extraction}
 
-Extrahiere Text aus Bildern mit KI-gestützter optischer Zeichenerkennung. Unterstützt mehrere Sprachen und Qualitätsstufen.
+Extrahieren Sie Text aus Bildern, ohne das Bild an einen externen Dienst zu senden. Die integrierte `fast`-Stufe verwendet Tesseract. Die optionalen Ebenen `balanced` und `best` verwenden RapidOCR mit angehefteten PP-OCR ONNX-Modellen.
 
+
+<!-- korean-ocr-contract:start -->
+::: info Kompatibilität für koreanische OCR
+Fast OCR unterstützt `auto`, `en`, `de`, `es`, `fr`, `zh` und `ja`, aber kein Koreanisch (`ko`). Koreanisch benötigt das genaue OCR-Paket und `balanced` oder `best`. Das Paket läuft in offiziellen Linux-amd64- und arm64-Containern, auch auf NVIDIA-Hosts weiterhin auf der CPU. Nicht unterstützte Systeme erhalten einen eindeutigen Kompatibilitätsfehler und keinen stillen Rückfall auf `fast`. Koreanisch mit `fast` oder dem alten Alias `tesseract` wird vor dem Einreihen mit `FEATURE_INCOMPATIBLE` und `fast-korean-unsupported` abgelehnt.
+:::
+<!-- korean-ocr-contract:end -->
 ## API-Endpunkt {#api-endpoint}
 
 `POST /api/v1/tools/image/ocr`
 
-**Verarbeitung:** Synchrone JSON-Antwort. Wenn `clientJobId` angegeben ist, wird der Fortschritt zusätzlich über SSE gemeldet.
+**Verarbeitung:** OCR wird immer asynchron ausgeführt. Nach Validierung und Einreihung gibt der Endpunkt sofort `202 Accepted` mit einer `jobId` zurück. Verfolgen Sie den SSE-Fortschrittsstrom des Jobs bis zum abschließenden Ereignis `complete` oder `failed`; bei Erfolg enthält dessen `result` die OCR-Felder.
 
-**Modell-Bundle:** `ocr` (5-6 GB)
+**Genaues OCR-Paket:** Optionale `ocr`-Laufzeit (ca. 208–234 MiB zum Herunterladen und 409–488 MiB installiert, je nach Ziel). Für `fast` ist dieses Paket nicht erforderlich. Das Installationsprogramm überprüft die genauen Größen, die durch den signierten Index gebunden sind.
 
 ## Parameter {#parameters}
 
 | Parameter | Typ | Erforderlich | Standard | Beschreibung |
 |-----------|------|----------|---------|-------------|
-| file | file | Ja | - | Bilddatei (multipart) |
-| quality | string | Nein | `"balanced"` | Qualitätsstufe: `fast` (Tesseract), `balanced` (PaddleOCR v5), `best` (PaddleOCR VL) |
+| file | file | Ja | - | Bilddatei (mehrteilig), bis zu 512 MiB kodiert und 40 Megapixel dekodiert; Es gilt weiterhin ein niedrigeres Upload-Limit des Betreibers |
+| quality | string | NEIN | Dynamisch | Qualitätsstufe: `fast` (Tesseract), `balanced` (RapidOCR mit den kleinen PP-OCRv6-Modellen) oder `best` (die höhergenauen mittleren PP-OCRv6-Modelle mit kalibrierter Variantenbewertung) |
 | language | string | Nein | `"auto"` | Sprachhinweis: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
-| enhance | boolean | Nein | `true` | Bild für bessere OCR-Genauigkeit vorverarbeiten |
-| engine | string | Nein | - | Veraltet. Verwende stattdessen `quality`. Bildet `tesseract` auf `fast` und `paddleocr` auf `balanced` ab |
+| enhance | boolean | NEIN | Tierabhängig | Verbessern Sie den lokalen Kontrast vor der Erkennung. Fast wendet es direkt an; „Balanced“ und „Best“ behalten die Variante nur dann bei, wenn die kalibrierte Bewertung das Ergebnis verbessert. Standardmäßig ist `true` für `best` und `false` für `fast`/`balanced` |
+| engine | string | NEIN | - | Veralteter Kompatibilitätsalias. Verwenden Sie stattdessen `quality`. `tesseract` wird auf `fast` abgebildet; Der alte Wert `paddleocr` wird `balanced` zugeordnet, lädt PaddlePaddle jedoch nicht |
+
+Wenn `quality` und `engine` fehlen, wählt SnapOtter die höchste verfügbare Stufe in dieser Reihenfolge: `best`, `balanced`, `fast`. Für Koreanisch wird `fast` nie gewählt; es wird `best`, dann `balanced` verwendet oder ein Installations- bzw. Kompatibilitätsfehler der genauen Laufzeit zurückgegeben.
 
 ## Beispielanfrage {#example-request}
 
@@ -35,31 +43,55 @@ curl -X POST http://localhost:1349/api/v1/tools/image/ocr \
   -F 'settings={"quality":"best","language":"en","enhance":true}'
 ```
 
-## Antwort (200 OK) {#response-200-ok}
+## Angenommene Antwort (202) {#accepted-response-202}
 
 ```json
 {
   "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-  "filename": "document.png",
-  "text": "Extracted text content from the image...",
-  "engine": "paddleocr-vl"
+  "async": true
 }
 ```
 
-### Fortschritt (SSE, optional) {#progress-sse-optional}
+### Fortschritt und Ergebnis (SSE) {#progress-sse-optional}
 
-Wenn ein Formularfeld `clientJobId` angegeben ist, werden Fortschrittsereignisse gestreamt:
+Verbinden Sie sich mit `GET /api/v1/jobs/{jobId}/progress` und verwenden Sie die `jobId` aus der `202`-Antwort (oder die übergebene `clientJobId`). Halten Sie den Stream bis zum abschließenden Ereignis `complete` oder `failed` offen. Ein erfolgreiches Terminal-Frame enthält die OCR-Ausgabe in `result`:
 
+```json
+{
+  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "type": "single",
+  "phase": "complete",
+  "stage": "complete",
+  "percent": 100,
+  "result": {
+    "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+    "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/document_ocr.txt",
+    "originalSize": 12345,
+    "processedSize": 47,
+    "text": "Extracted text content from the image...",
+    "engine": "rapidocr-onnx",
+    "requestedQuality": "best",
+    "actualQuality": "best",
+    "device": "cpu",
+    "provider": "CPUExecutionProvider",
+    "degraded": false,
+    "warnings": [],
+    "runtimeVersion": "2.1.0",
+    "modelVersion": "PP-OCRv6-best-v1-medium"
+  }
+}
 ```
-event: progress
-data: {"phase":"processing","stage":"Recognizing text...","percent":50}
-```
+
+Verarbeitungsfehler werden im Feld `error` des abschließenden Ereignisses `failed` übertragen; nach dem Einreihen werden sie nicht als HTTP `422` zurückgegeben.
 
 ## Hinweise {#notes}
 
-- Erfordert das installierte Modell-Bundle `ocr` (5-6 GB).
-- OCR gibt den extrahierten Text direkt zurück statt einer Download-URL für ein Bild.
-- Verwendet eine Fallback-Kette: Wenn eine höhere Qualitätsstufe abstürzt (z. B. PaddleOCR-Segfault), wird automatisch mit der nächstniedrigeren Stufe erneut versucht.
-- Wenn eine Stufe leeren Text ohne Absturz zurückgibt, wird ebenfalls auf die nächste Stufe zurückgegriffen.
-- Qualitätsstufen werden auf Engines abgebildet: `fast` = Tesseract, `balanced` = PaddleOCR v5, `best` = PaddleOCR VL.
+- `fast` ist immer in unterstützten SnapOtter-Images verfügbar. `balanced` und `best` erfordern das optionale genaue OCR-Paket.
+- Das integrierte Tesseract fügt dem offiziellen Bild etwa 25 MiB hinzu. Das genaue Paket wird in `/data/ai` gespeichert und nicht in das Bild eingebrannt.
+- Das genaue Paket wird für die offiziellen Container Linux amd64 und arm64 veröffentlicht. Es verwendet bewusst den CPU-Anbieter von ONNX Runtime, auch auf NVIDIA-Hosts, sodass es nicht auf CUDA-Bibliotheken oder GPU-Kompatibilität angewiesen ist. Quelle und vorgefertigt bare-metal Installationen verwenden Fast OCR es sei denn, sie stellen ihre eigene kompatible Laufzeit bereit.
+- Das erfolgreiche Terminal-`result` enthält sowohl den extrahierten Text in `text` als auch ein herunterladbares `.txt`-Artefakt in `downloadUrl`.
+– SnapOtter berücksichtigt eine explizit angeforderte Stufe. Wenn `balanced` oder `best` nicht verfügbar ist, der API gibt `501` mit `FEATURE_NOT_INSTALLED` oder `FEATURE_INCOMPATIBLE` zurück; Die Anfrage wird niemals stillschweigend auf eine andere Ebene herabgestuft.
+- Ein erfolgreiches leeres Ergebnis bleibt ein leeres Ergebnis. Laufzeitfehler geben einen Fehler zurück, anstatt es erneut mit einer Engine mit geringerer Qualität zu versuchen.
+– Das erfolgreiche Terminal-`result` meldet sowohl `requestedQuality` als auch `actualQuality` sowie die Engine-, Geräte-, Anbieter-, Laufzeit- und Modellversionen sowie etwaige Warnungen.
 - Unterstützt die Eingabeformate HEIC/HEIF, RAW, TGA, PSD, EXR und HDR durch automatische Dekodierung.
+– Übergroße codierte Eingaben geben `413` zurück. Bilder über 40 Megapixel und OCR-Antworten, die ihre begrenzten Ausgabegrenzen überschreiten, werden abgelehnt, anstatt teilweise verarbeitet zu werden.