OCR lato server con modelli vision per i documenti scansionati

Perché i documenti scansionati rompono l'estrazione del testo

Chiedete a un estrattore di testo di leggere un PDF scansionato e otterrete quasi nulla. Un PDF prodotto da un elaboratore di testi porta con sé uno strato di testo - i caratteri sono memorizzati come testo, e l'estrazione è banale. Un PDF prodotto da uno scanner è invece una busta di immagini di pagina: non c'è nessuno strato di testo, solo pixel. Il parser del collector può estrarre solo ciò che esiste davvero, così le pagine di sole immagini tornano vuote o quasi, e un documento che in un visualizzatore appare perfettamente leggibile non contribuisce affatto alla base di conoscenza.

Simmetric Chat lo gestisce sul server, prima che un documento raggiunga la fase di chunking ed embedding. Quando l'ingestion rileva un PDF povero di testo, la piattaforma lo instrada in una pipeline OCR dedicata il cui motore non è una libreria OCR classica a riconoscimento di pattern, ma un modello linguistico con capacità di visione servito localmente tramite Ollama. Il risultato è Markdown estratto che preserva titoli, elenchi e struttura delle tabelle molto meglio di un OCR a livello di carattere - e tutto gira interamente nella vostra infrastruttura. Nessun documento lascia mai la rete per essere letto.

Questo articolo descrive come funziona la pipeline, quali controlli espone e il passo di approvazione umana che impedisce a un modello che legge male di inquinare in silenzio una base di conoscenza.

Dai pixel al Markdown: la pipeline

L'OCR in Simmetric Chat è una pipeline server-side basata su job. Un upload il cui testo estratto non supera il precheck - per impostazione predefinita, meno di circa 200 caratteri estraibili marcano un documento come scansionato - diventa un job OCR, e uno scheduler di polling riprende i job ogni 10 secondi con un limite di concorrenza globale, così un lotto di upload non può saturare la macchina. Un singolo documento attraversa poi cinque fasi:

1. Caricamento. pdfjs-dist apre il PDF lato server ed enumera le pagine, con un tetto di 50 pagine per job come limite di sicurezza contro elaborazioni fuori controllo.
2. Rendering. Ogni pagina viene renderizzata in un'immagine PNG a una scala ingrandita - 2x per impostazione predefinita - così anche la stampa piccola di una scansione di qualità fax arriva al modello con una risoluzione leggibile.
3. Riconoscimento. Ogni immagine di pagina viene inviata al modello vision di Ollama configurato come immagine base64, e il modello trascrive la pagina come testo Markdown.
4. Protezione. La trascrizione grezza attraversa una guardia anti-allucinazione e un passo di pulizia del grounding. I modelli vision a volte annotano l'output con marcatori di grounding, o inventano contenuti plausibili quando una pagina è davvero illeggibile - entrambi i casi vengono intercettati qui invece di essere salvati.
5. Punteggio e assemblaggio. Ogni pagina riceve un punteggio di qualità, le pagine vengono concatenate in un unico documento, e il job si conclude con un riepilogo veritiero: le pagine fallite sono contate e riportate come pagine fallite, mai assorbite in silenzio in un risultato "completato" pulito.

Ogni passaggio di questo elenco avviene sul server. Il browser non esegue mai l'OCR, e non viene chiamata nessuna API OCR di terze parti - l'unico salto di rete va dal vostro server alla vostra istanza Ollama.

Scelta del modello

Il modello vision è configurabile, e la pipeline include un piccolo registry di modelli che sa come dialogare con ciascuna famiglia supportata:

• glm-ocr - il predefinito (OCR_MODEL=glm-ocr:latest), un modello vision specializzato in OCR. Il registry lo instrada attraverso l'endpoint chat di Ollama, che per questa famiglia di modelli rileva la fine della trascrizione in modo più affidabile.
• deepseek-ocr - una seconda famiglia ottimizzata per l'OCR che usa token di grounding; il registry le invia immagini a pagina singola e rimuove i marcatori di grounding durante la pulizia.
• Qualsiasi modello vision generico - i modelli che il registry non riconosce ricadono su un prompt generico attraverso l'endpoint generate di Ollama, così anche un modello multimodale che già eseguite in locale funziona.

I parametri legati al modello sono variabili d'ambiente, documentate insieme al resto della superficie di configurazione:

# OCR vision lato server
OCR_MODEL=glm-ocr:latest   # modello vision (supporta model:version)
OCR_TIMEOUT=600000         # 10 minuti - i modelli vision sono lenti
OCR_NUM_PREDICT=8192       # token di output massimi per pagina

Un endpoint di prewarm consente a un amministratore di caricare il modello in memoria prima del primo job, così il primo upload scansionato della giornata non paga il costo di avvio a freddo del modello.

L'umano nel ciclo: approva o rifiuta

La qualità della trascrizione varia con la qualità della scansione, e una base di conoscenza è il posto sbagliato per scoprire che un modello ha letto male una pagina. Per questo la pipeline tratta l'output OCR come una bozza, non come un fatto. Ogni job produce un artefatto revisionabile: l'anteprima mantiene il testo estratto vincolato alla stessa porzione di pagina del pannello con l'immagine, così un revisore può verificare qualsiasi pagina confrontandola con la scansione da cui proviene.

Dal pannello impostazioni OCR un amministratore vede il catalogo dei modelli, l'elenco dei job con punteggi di qualità e credibilità per pagina, e il flusso di lavoro stesso:

• Approva - le pagine estratte vengono accettate e proseguono: un job d'archivio approvato materializza le pagine nella base di conoscenza, e dall'esito approvato può essere avviata un'esecuzione di sintesi.
• Rifiuta - l'output viene scartato e la decisione viene registrata sul job.

L'automazione è disponibile senza rinunciare al varco. Un hook di auto-approvazione guidato dagli eventi può finalizzare i job i cui segnali di qualità sono puliti, e preserva deliberatamente il flusso di approvazione manuale ovunque la decisione umana sia il contratto - un import esplicitamente instradato verso una base di conoscenza non viene mai auto-approvato in silenzio. In ogni caso, i riepiloghi dei job restano veritieri sulla salute delle pagine: un job concluso con tre pagine fallite lo dichiara nel suo risultato e nei log.

Il senso del ceremonial è un unico invariant: il testo entra nel vostro indice RAG solo dopo un passaggio di qualità pulito o dopo che un umano l'ha esaminato.

Dove finisce il testo estratto

L'output OCR approvato rientra nel normale flusso di ingestion. Per i documenti caricati, il Markdown estratto sostituisce lo strato di testo mancante alla scansione, e il documento prosegue con chunking, embedding e indicizzazione per la ricerca ibrida esattamente come un PDF nativo. Per gli archivi, le pagine approvate diventano parte della base di conoscenza curata del workspace, dove wikilink, backlink e la pipeline di sintesi possono operare su di esse come su qualunque altra pagina.

Poiché la pipeline è lato server, si compone con le garanzie del resto della piattaforma: i filtri DLP continuano a scansionare i contenuti prima che escano dalla rete, l'RBAC continua a decidere chi può avviare job e approvare risultati, e nessun punto del percorso OCR richiede una connessione in uscita verso un servizio OCR nel cloud.

Impostazioni pratiche

La maggior parte dei deployment richiede solo tre decisioni:

• Abilitarlo. OCR_ENABLED e OCR_PRECHECK_CHARS - la soglia di caratteri che instrada un PDF nella pipeline - sono gestiti nelle impostazioni di amministrazione.
• Scegliere il modello. glm-ocr:latest è un predefinito sensato; il catalogo dei modelli elenca ciò che il registry riconosce, la scelta del modello per singolo job è disponibile dal pannello impostazioni, e istruzioni personalizzate possono affinare il comportamento della trascrizione per il vostro dominio documentale.
• Budgettare il tempo. L'OCR vision scambia velocità con fedeltà. Il timeout predefinito di 10 minuti e il tetto di 50 pagine esistono perché una scansione patologica degradi in un fallimento visibile invece che in un worker bloccato.

Se il vostro corpus è fatto soprattutto di PDF nativi, noterete raramente la pipeline: gli strati di testo sani bypassano del tutto l'OCR. Nel momento in cui arriva un documento scansionato, passa per rendering, modello vision e vostra approvazione - e finisce ricercabile invece che invisibile.

Leggi la guida completa nella documentazione →