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
2026-08-03 07:46:42 +02:00 · 2026-07-15 03:34:24 +08:00
parent 58121f205f
commit 991c981529
409 changed files with 67151 additions and 8076 deletions
@@ -1,31 +1,39 @@
 ---
-description: "Estrai testo dalle immagini usando il riconoscimento ottico dei caratteri basato sull'AI."
-i18n_source_hash: 3d85d423b82c
+description: "Estrai testo dalle immagini localmente con Tesseract integrato o il runtime RapidOCR opzionale ad alta precisione."
+i18n_output_hash: 5c65c73856f7
+i18n_source_hash: 0d453b49db02
 i18n_provenance: human
-i18n_output_hash: 7203514995bd
 ---

 # OCR / Text Extraction {#ocr-text-extraction}

-Estrai testo dalle immagini usando il riconoscimento ottico dei caratteri basato sull'AI. Supporta più lingue e livelli di qualità.
+Estrai testo dalle immagini senza inviare l'immagine a un servizio esterno. Il livello `fast` integrato utilizza Tesseract. I livelli opzionali `balanced` e `best` utilizzano RapidOCR con modelli PP-OCR ONNX bloccati.

+
+<!-- korean-ocr-contract:start -->
+::: info Compatibilità OCR per il coreano
+OCR veloce supporta `auto`, `en`, `de`, `es`, `fr`, `zh` e `ja`, ma non il coreano (`ko`). Il coreano richiede il pacchetto OCR accurato e `balanced` o `best`. Il pacchetto funziona nei container Linux amd64 e arm64 ufficiali, inclusi gli host NVIDIA, dove l’OCR resta sulla CPU. I sistemi non supportati ricevono un errore di compatibilità esplicito e non passano mai silenziosamente a `fast`. Il coreano con `fast` o con l’alias legacy `tesseract` viene rifiutato prima dell’accodamento con `FEATURE_INCOMPATIBLE` e `fast-korean-unsupported`.
+:::
+<!-- korean-ocr-contract:end -->
 ## API Endpoint {#api-endpoint}

 `POST /api/v1/tools/image/ocr`

-**Elaborazione:** Risposta JSON sincrona. Se viene fornito `clientJobId`, l'avanzamento viene riportato anche tramite SSE.
+**Elaborazione:** L’OCR è sempre asincrono. Dopo la convalida e l’accodamento, l’endpoint restituisce immediatamente `202 Accepted` con un `jobId`. Segui il flusso di avanzamento SSE del lavoro fino all’evento terminale `complete` o `failed`; il `result` di un evento riuscito contiene i campi OCR.

-**Bundle del modello:** `ocr` (5-6 GB)
+**Pacchetto OCR accurato:** Runtime `ocr` opzionale (circa 208-234 MiB da scaricare e 409-488 MiB installati, a seconda della destinazione). `fast` non richiede questo pacchetto; l'installatore verifica le dimensioni esatte vincolate dall'indice firmato.

 ## Parameters {#parameters}

 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
-| file | file | Yes | - | File immagine (multipart) |
-| quality | string | No | `"balanced"` | Livello di qualità: `fast` (Tesseract), `balanced` (PaddleOCR v5), `best` (PaddleOCR VL) |
+| file | file | SÌ | - | File immagine (in più parti), fino a 512 MiB codificati e 40 megapixel decodificati; si applica ancora un limite di caricamento da parte dell'operatore inferiore |
+| quality | string | NO | Dinamico | Livello di qualità: `fast` (Tesseract), `balanced` (RapidOCR con i modelli PP-OCRv6 piccoli) o `best` (i modelli PP-OCRv6 medi con precisione più elevata con punteggio delle varianti calibrato) |
 | language | string | No | `"auto"` | Suggerimento sulla lingua: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
-| enhance | boolean | No | `true` | Pre-elabora l'immagine per una migliore accuratezza dell'OCR |
-| engine | string | No | - | Deprecato. Usa `quality` al suo posto. Mappa `tesseract` a `fast`, `paddleocr` a `balanced` |
+| enhance | boolean | NO | Dipendente dal livello | Migliora il contrasto locale prima del riconoscimento. Fast lo applica direttamente; Bilanciato e Migliore mantengono la variante solo quando il punteggio calibrato migliora il risultato. Il valore predefinito è `true` per `best` e `false` per `fast`/`balanced` |
+| engine | string | NO | - | Alias di compatibilità deprecato. Utilizzare invece `quality`. `tesseract` è mappato su `fast`; il valore `paddleocr` legacy viene mappato su `balanced` ma non carica PaddlePaddle |
+
+Quando `quality` e `engine` sono omessi, SnapOtter sceglie il livello migliore disponibile nell’ordine `best`, `balanced`, `fast`. Per il coreano non sceglie mai `fast`: usa `best`, poi `balanced`, oppure restituisce l’errore di installazione o compatibilità del runtime accurato.

 ## Example Request {#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}'
 ```

-## Response (200 OK) {#response-200-ok}
+## Risposta accettata (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
 }
 ```

-### Progress (SSE, optional) {#progress-sse-optional}
+### Avanzamento e risultato (SSE) {#progress-sse-optional}

-Se viene fornito un campo form `clientJobId`, gli eventi di avanzamento vengono trasmessi in streaming:
+Connettiti a `GET /api/v1/jobs/{jobId}/progress` con il `jobId` restituito dalla risposta `202` (o il `clientJobId` fornito). Mantieni aperto il flusso fino all’evento terminale `complete` o `failed`. Un frame terminale riuscito contiene l’output OCR 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}
-```
+
+Gli errori di elaborazione arrivano nel campo `error` dell’evento terminale `failed`; dopo l’accodamento non vengono restituiti come HTTP `422`.

 ## Notes {#notes}

- Richiede l'installazione del bundle del modello `ocr` (5-6 GB).
- L'OCR restituisce direttamente il testo estratto anziché un URL di download dell'immagine.
- Usa una catena di fallback: se un livello di qualità più alto va in crash (ad es. un segfault di PaddleOCR), riprova automaticamente con il livello inferiore successivo.
- Se un livello restituisce testo vuoto senza andare in crash, ricade comunque sul livello successivo.
- I livelli di qualità si mappano sui motori: `fast` = Tesseract, `balanced` = PaddleOCR v5, `best` = PaddleOCR VL.
+- `fast` è sempre disponibile nelle immagini SnapOtter supportate. `balanced` e `best` richiedono il pacchetto OCR accurato opzionale.
+- Tesseract integrato aggiunge circa 25 MiB all'immagine ufficiale. Il pacchetto accurato viene archiviato in `/data/ai`, non inserito nell'immagine.
+- Viene pubblicato il pack accurato per i contenitori ufficiali Linux amd64 e arm64. Utilizza deliberatamente il provider CPU di ONNX Runtime, anche sugli host NVIDIA, quindi non dipende dalle librerie CUDA o dalla compatibilità GPU. Le installazioni bare-metal di origine e predefinite utilizzano OCR veloce a meno che non forniscano il proprio runtime compatibile.
+- Il `result` terminale riuscito include sia il testo estratto in `text` sia un artefatto `.txt` scaricabile in `downloadUrl`.
+- SnapOtter rispetta un livello esplicitamente richiesto. Se `balanced` o `best` non è disponibile, API restituisce `501` con `FEATURE_NOT_INSTALLED` o `FEATURE_INCOMPATIBLE`; non esegue mai il downgrade silenzioso della richiesta a un altro livello.
+- Un risultato vuoto riuscito rimane un risultato vuoto. Gli errori di runtime restituiscono un errore invece di riprovare con un motore di qualità inferiore.
+- Il `result` terminale riuscito riporta sia `requestedQuality` che `actualQuality`, oltre alle versioni del motore, del dispositivo, del provider, del runtime e del modello ed eventuali avvisi.
 - Supporta i formati di input HEIC/HEIF, RAW, TGA, PSD, EXR e HDR tramite decodifica automatica.
+- Gli ingressi codificati sovradimensionati restituiscono `413`. Le immagini superiori a 40 megapixel e le risposte OCR che superano i limiti di output vengono rifiutate invece di essere parzialmente elaborate.
@@ -1,14 +1,20 @@
 ---
-description: "Estrai testo da documenti PDF usando l'OCR basato sull'IA."
-i18n_source_hash: 1431fcba180b
+description: "Estrai testo dai PDF scansionati localmente con Tesseract integrato o il runtime RapidOCR opzionale ad alta precisione."
+i18n_output_hash: cae7ce183801
+i18n_source_hash: a19ba25a1ca8
 i18n_provenance: human
-i18n_output_hash: 123adeee3212
 ---

 # OCR PDF {#pdf-ocr}

-Estrai testo da documenti PDF usando il riconoscimento ottico dei caratteri basato sull'IA. Supporta più livelli di qualità e diverse lingue. Richiede l'installazione del bundle della funzionalità OCR.
+Estrai il testo dai documenti PDF scansionati pagina per pagina senza inviare PDF a un servizio esterno. Il livello `fast` integrato utilizza Tesseract. I livelli opzionali `balanced` e `best` utilizzano RapidOCR con modelli PP-OCR ONNX bloccati.

+
+<!-- korean-ocr-contract:start -->
+::: info Compatibilità OCR per il coreano
+OCR veloce supporta `auto`, `en`, `de`, `es`, `fr`, `zh` e `ja`, ma non il coreano (`ko`). Il coreano richiede il pacchetto OCR accurato e `balanced` o `best`. Il pacchetto funziona nei container Linux amd64 e arm64 ufficiali, inclusi gli host NVIDIA, dove l’OCR resta sulla CPU. I sistemi non supportati ricevono un errore di compatibilità esplicito e non passano mai silenziosamente a `fast`. Il coreano con `fast` o con l’alias legacy `tesseract` viene rifiutato prima dell’accodamento con `FEATURE_INCOMPATIBLE` e `fast-korean-unsupported`.
+:::
+<!-- korean-ocr-contract:end -->
 ## API Endpoint {#api-endpoint}

 `POST /api/v1/tools/pdf/ocr-pdf`
@@ -19,9 +25,14 @@ Accetta dati di form multipart con un file PDF e un campo JSON opzionale `settin

 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
-| quality | string | No | `"balanced"` | Livello di qualità OCR: `fast`, `balanced`, `best` |
+| file | file | SÌ | - | File PDF (multiparte), fino a 512 MiB codificati; si applica ancora un limite di caricamento da parte dell'operatore inferiore |
+| quality | string | NO | Dinamico | Livello di qualità OCR: `fast`, `balanced` o `best` |
 | language | string | No | `"auto"` | Lingua del documento: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
 | pages | string | No | `"all"` | Selezione delle pagine, es. `"all"`, `"1-3"`, `"1,3,5"` |
+| enhance | boolean | NO | Dipendente dal livello | Migliora il contrasto locale prima del riconoscimento. Fast lo applica direttamente; Bilanciato e Migliore mantengono la variante solo quando il punteggio calibrato migliora il risultato. Il valore predefinito è `true` per `best` e `false` per `fast`/`balanced` |
+| engine | string | NO | - | Alias di compatibilità deprecato. Utilizzare invece `quality`. `tesseract` è mappato su `fast`; il valore `paddleocr` legacy viene mappato su `balanced` ma non carica PaddlePaddle |
+
+Quando `quality` e `engine` sono omessi, SnapOtter sceglie il livello migliore disponibile nell’ordine `best`, `balanced`, `fast`. Per il coreano non sceglie mai `fast`: usa `best`, poi `balanced`, oppure restituisce l’errore di installazione o compatibilità del runtime accurato.

 ## Example Request {#example-request}

@@ -29,7 +40,7 @@ Accetta dati di form multipart con un file PDF e un campo JSON opzionale `settin
 curl -X POST http://localhost:1349/api/v1/tools/pdf/ocr-pdf \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@scanned.pdf" \
-  -F 'settings={"quality": "best", "language": "en", "pages": "1-5"}'
+  -F 'settings={"quality": "best", "language": "en", "pages": "1-5", "enhance": true}'
 ```

 ## Example Response {#example-response}
@@ -46,8 +57,11 @@ Restituisce `202 Accepted`. Monitora l'avanzamento tramite SSE su `/api/v1/jobs/
 ## Notes {#notes}

 - Formato di input accettato: `.pdf`.
- Questo è uno strumento IA che richiede l'installazione del **bundle della funzionalità OCR**. Se il bundle non è installato, l'API restituisce `501 Not Implemented`.
- Il livello di qualità `fast` usa un modello più leggero per un'elaborazione più rapida; `best` usa un modello più accurato a scapito della velocità.
- L'impostazione della lingua `auto` tenta di rilevare automaticamente la lingua del documento.
+- `fast` è integrato e aggiunge circa 25 MiB all'immagine ufficiale. `balanced` e `best` richiedono il pacchetto OCR accurato opzionale (circa 208-234 MiB da scaricare e 409-488 MiB installati, a seconda dell'obiettivo).
+- Il pacchetto accurato supporta Linux amd64 e arm64 e utilizza ONNX Runtime su CPU, inclusi gli host NVIDIA.
+- Un livello richiesto esplicitamente non viene mai declassato silenziosamente. Se `balanced` o `best` non è disponibile, API restituisce `501` con `FEATURE_NOT_INSTALLED` o `FEATURE_INCOMPATIBLE`.
+- Le pagine PDF vengono rasterizzate ad alta risoluzione prima di OCR. `best` esegue i modelli PP-OCRv6 medi ad alta precisione e valuta le varianti di orientamento e miglioramento, migliorando il riconoscimento a scapito della velocità.
+- L'impostazione della lingua `auto` consente il riconoscimento attraverso il set di script supportato; un suggerimento esplicito può migliorare i risultati per una lingua di documento conosciuta.
 - Puoi selezionare pagine specifiche usando intervalli (`"1-3"`), elenchi separati da virgole (`"1,3,5"`), o `"all"` per ogni pagina.
+- Una richiesta può elaborare un massimo di 50 pagine. I dati scratch rasterizzati sono limitati a 512 MiB e la risposta aggregata UTF-8 OCR è limitata a 1.000.000 di byte; i lavori con limite eccessivo falliscono anziché restituire testo parziale.
 - Per i PDF che contengono già testo selezionabile, considera l'uso dello strumento più veloce [PDF in testo](./pdf-to-text).