DeepSeek-OCR in locale: leggere i propri PDF scansionati

#Perché DeepSeek-OCR invece di un OCR classico

Un PDF scansionato non contiene testo, ma solo immagini di testo. Un motore OCR classico come Tesseract ne ricava righe grezze: non sa che un blocco è un titolo, rompe le tabelle e perde l'ordine di lettura di una pagina su due colonne. DeepSeek-OCR affronta il problema in modo diverso. È un modello di visione-linguaggio: osserva l'intera pagina, poi genera direttamente Markdown con titoli, elenchi, tabelle e formule.

Il modello è stato pubblicato da DeepSeek nell'autunno del 2025 insieme a un articolo intitolato « Contexts Optical Compression ». L'idea centrale è rappresentare una pagina con un numero ridotto di token visivi, tra 64 e 400 a seconda della modalità di risoluzione, invece delle migliaia di token testuali che conterrebbe. L'editore dichiara una precisione di decodifica di circa il 97% quando il rapporto di compressione rimane inferiore a dieci. Questo è il suo dato, misurato sui propri set di dati, non il nostro: tenete soprattutto presente che il modello è leggero e veloce per ciò che fa.

Per un uso locale, contano tre cose. Il modello entra in una scheda grafica di fascia bassa. Produce Markdown che si può indicizzare così com'è in una pipeline RAG. Ed è disponibile nella libreria Ollama, evitando così di installare PyTorch, Flash Attention e vLLM come richiesto dal repository ufficiale. Le specifiche complete sono nella scheda del modello: https://quelllm.fr/modele/deepseek-ocr

#Prerequisiti e memoria da prevedere

La scheda del modello sul sito fornisce i riferimenti sulla VRAM per precisione: circa 2 GB in Q4, 4 GB in Q8 e 6 GB in FP16, per un contesto di 8 192 token. Il peso effettivo da scaricare dipende da ciò che Ollama ha impacchettato nel tag; la pagina dei tag della libreria mostra la dimensione del file, ed è quella a fare fede. A ciò va aggiunta la memoria del contesto: una pagina densa convertita in Markdown può produrre diverse migliaia di token in output.

GPU NVIDIA

Qualsiasi scheda da 8 GB o più è sufficiente. Una RTX 3060 da 12 GB o una RTX 4070 da 12 GB fanno funzionare il modello in FP16 lasciando margine per il contesto.

Mac Apple Silicon

Ollama usa la memoria unificata. Un Mac con 16 GB è sufficiente per il solo modello; calcolate 24 GB se volete tenere caricato accanto un modello di chat per il RAG.

Senza GPU

Possibile, ma la codifica dell'immagine e la generazione del Markdown vengono eseguite sul processore. Per poche pagine è tollerabile; per un lotto di cento pagine, aspettatevi diversi minuti per pagina a seconda della macchina.

Software

Ollama aggiornato, poppler-utils per suddividere i PDF e Python 3 con la libreria ollama se volete automatizzare l'elaborazione in batch.

#Passaggio 1: verificare Ollama e recuperare il tag corretto

DeepSeek-OCR è arrivato nella libreria Ollama alla fine del 2025, dopo l'uscita del modello. Si basa su un particolare encoder visivo, DeepEncoder, che combina un modulo per le finestre locali e un modulo di attenzione globale. Ollama ha dovuto aggiungere il supporto per questa architettura al proprio motore: un runtime precedente scarica i pesi ma si rifiuta di caricarli, mostrando un messaggio che indica che il modello richiede una versione più recente. La pagina della libreria mostra la versione minima richiesta, quando applicabile.

# Version installée (comparez avec la version minimale affichée sur ollama.com/library/deepseek-ocr)
ollama -v

# Récupérer le modèle (le tag 3b est celui référencé par la fiche modèle)
ollama pull deepseek-ocr:3b

# Vérifier l'architecture, le contexte et la quantification empaquetée
ollama show deepseek-ocr:3b

Il comando show è l'unica fonte affidabile per sapere cosa hai appena scaricato: indica la famiglia del modello, il numero di parametri, la lunghezza del contesto e il livello di quantizzazione. Se il tag latest e il tag 3b puntano allo stesso digest, non importa quale usi; la guida impiega 3b per rimanere esplicita.

#Passaggio 2: preparare le pagine del PDF

Ollama non apre PDF. Accetta immagini PNG o JPEG, una per richiesta. La prima operazione consiste quindi nel rasterizzare il documento, pagina per pagina. Lo strumento più semplice è pdftoppm, fornito con poppler-utils, disponibile su tutte le distribuzioni Linux e tramite Homebrew su macOS.

# Debian/Ubuntu : sudo apt install poppler-utils
# macOS : brew install poppler
# Arch : sudo pacman -S poppler

mkdir -p pages
pdftoppm -r 200 -png scan.pdf pages/page
ls pages
# pages/page-1.png  pages/page-2.png  ...  (numérotation complétée par des zéros selon le nombre de pages)

La risoluzione merita un minuto di riflessione. DeepSeek-OCR lavora a risoluzioni fisse: 512, 640, 1024 o 1280 pixel per lato a seconda della modalità, più una modalità dinamica chiamata Gundam che suddivide la pagina in riquadri da 640 pixel attorno a una vista globale di 1024. Una pagina A4 rasterizzata a 200 punti per pollice misura circa 1 650 per 2 340 pixel; Ollama la ridimensiona prima di inviarla all'encoder. Passare a 300 punti per pollice non apporta nulla al modello e aumenta inutilmente le dimensioni dei file. Scendere a 100 fa perdere i caratteri piccoli delle note a piè di pagina prima ancora che il modello li veda.

Se la scansione è storta o molto contrastata, il modello se la cava generalmente meglio di un OCR riga per riga, ma una correzione preliminare dell'inclinazione resta utile. La guida a Tesseract del sito illustra i pretrattamenti utili, che si applicano anche qui: https://quelllm.fr/guide/tesseract-ocr-guide-local

#Passaggio 3: ottenere Markdown con deepseek ocr

Il repository ufficiale documenta diverse istruzioni, ognuna delle quali attiva un comportamento diverso del modello. Le due principali sono « Convert the document to markdown. » per una conversione strutturata e « Free OCR. » per una trascrizione grezza senza formattazione. Le istruzioni sono in inglese nell'addestramento; lasciatele così come sono, il testo riconosciuto viene prodotto nella lingua del documento. Con il client da riga di comando, il percorso dell'immagine viene inserito direttamente nel prompt.

# Conversion structurée (titres, listes, tableaux)
ollama run deepseek-ocr:3b "Convert the document to markdown. ./pages/page-1.png"

# Transcription brute, sans structure
ollama run deepseek-ocr:3b "Free OCR. ./pages/page-1.png"

La stessa operazione tramite l'API locale, che ascolta per impostazione predefinita su http://localhost:11434, codifica l'immagine in base64 nel campo images. È la strada da preferire non appena concatenि più pagine o chiami il modello da un altro programma.

# Linux (GNU coreutils). Sur macOS, remplacez base64 -w0 par base64 -i pages/page-1.png
curl http://localhost:11434/api/generate -d "{
  \"model\": \"deepseek-ocr:3b\",
  \"prompt\": \"Convert the document to markdown.\",
  \"images\": [\"$(base64 -w0 pages/page-1.png)\"],
  \"stream\": false,
  \"options\": { \"num_ctx\": 8192, \"temperature\": 0 }
}"

Due opzioni meritano di essere impostate. La temperatura a zero rende l'output riproducibile, come ci si aspetta da un OCR. Il contesto di 8 192 token corrisponde al limite del modello; al di sotto, una pagina densa può essere troncata nel bel mezzo di una cella della tabella. Il repository ufficiale menziona anche istruzioni dedicate per descrivere una figura o localizzare il testo con coordinate; sono poco utili per un semplice PDF da indicizzare.

#Passaggio 4: elaborare un PDF intero

Per un documento di diverse decine di pagine basta uno script Python di poche righe. Scorre le immagini in ordine numerico, chiama Ollama pagina dopo pagina, rimuove i tag di localizzazione che il modello può inserire e concatena il tutto in un unico file Markdown con un marcatore per pagina. Il marcatore è poi utile per ritrovare la pagina sorgente di un passaggio citato dal tuo RAG.

pip install ollama

import pathlib
import re
import ollama

MODEL = "deepseek-ocr:3b"
PROMPT = "Convert the document to markdown."

# Tri numérique : page-2 avant page-10
pages = sorted(
    pathlib.Path("pages").glob("page-*.png"),
    key=lambda p: int(re.search(r"(\d+)", p.stem).group(1)),
)

parts = []
for page in pages:
    r = ollama.generate(
        model=MODEL,
        prompt=PROMPT,
        images=[str(page)],
        options={"num_ctx": 8192, "temperature": 0},
    )
    md = r["response"]
    # Balises de localisation éventuelles : on garde le texte, on jette les coordonnées
    md = re.sub(r"<\|ref\|>(.*?)<\|/ref\|><\|det\|>.*?<\|/det\|>", r"\1", md, flags=re.S)
    parts.append(f"<!-- {page.name} -->\n{md.strip()}\n")
    print(f"{page.name} : {len(md)} caractères")

pathlib.Path("scan.md").write_text("\n\n".join(parts), encoding="utf-8")

Ogni chiamata è indipendente: il modello non conserva alcuna memoria della pagina precedente. È un limite per le tabelle che si estendono su due pagine e un vantaggio per la robustezza, poiché una pagina problematica non ne contamina un'altra. Ollama carica il modello una volta e lo mantiene in memoria tra le chiamate, in base al valore della variabile OLLAMA_KEEP_ALIVE; paghi il tempo di caricamento solo all'inizio del lotto.

Se disponete di una scheda con margine, l'opzione OLLAMA_NUM_PARALLEL permette di elaborare più pagine contemporaneamente, al prezzo di ulteriore VRAM per ogni contesto. Su una scheda da 12 GB, due richieste parallele restano ragionevoli con un modello di queste dimensioni; verificate con nvidia-smi di non eccedere nella memoria di sistema, perché in tal caso il rallentamento è drastico.

#Passaggio 5: pulire e controllare l'output

Il Markdown prodotto è facile da leggere, ma non necessariamente da indicizzare così com'è. Prima di inviarlo a un database vettoriale, esaminate tre punti.

1. 01
   I tag residui

   Con l'istruzione di conversione, il modello viene addestrato con un token di localizzazione e può restituire coordinate tra i tag ref e det. Lo script qui sopra li rimuove. Verifica che non rimangano neppure tag image o frammenti di istruzioni all'inizio del file.
2. 02
   I numeri e le tabelle

   Un modello di visione-linguaggio genera testo; può quindi inventare un valore plausibile in una cella illeggibile, laddove un OCR classico avrebbe lasciato un carattere anomalo. Apri le tabelle finanziarie o tecniche affiancate alla scansione e confronta una riga su dieci. Per le fatture, la guida dedicata del sito spiega come effettuare un controllo incrociato con i totali: https://quelllm.fr/guide/extraction-factures-ocr-llm
3. 03
   Le intestazioni e i piè di pagina

   Numeri di pagina, nome del documento, note legali ripetute: compaiono su ogni pagina e inquinano la suddivisione in segmenti. In genere basta un'espressione regolare sulle righe identiche presenti in più della metà delle pagine per rimuoverli.
4. 04
   Gli accenti e la tipografia francese

   L'editor dichiara un addestramento su un centinaio di lingue. Controlla comunque le lettere accentate, le virgolette francesi e gli spazi inseparabili prima dei segni doppi su un campione: è lì che si annidano gli errori discreti che poi falsano una ricerca lessicale.

Una volta ripulito il file, entra in una pipeline RAG come qualsiasi Markdown: suddivisione per titoli, embeddings, database vettoriale. L'introduzione al RAG locale del sito riprende questi passaggi: https://quelllm.fr/guide/rag-local-introduction

#Limiti e risoluzione dei problemi

Il modello risponde senza guardare l'immagine

O Ollama è troppo vecchio per questa architettura, oppure l'immagine non è stata trasmessa. Dalla riga di comando, il percorso deve essere assoluto o relativo alla directory corrente, senza virgolette attorno al percorso stesso. Tramite l'API, verifica che il campo images contenga effettivamente base64 senza ritorni a capo.

Output interrotto a metà di una tabella

Il contesto è troppo breve per la pagina. Imposta num_ctx su 8192 se non l'avevi già fatto. Se la pagina è ancora troppo grande, dividila in due immagini, parte superiore e inferiore, con una sovrapposizione di alcune righe.

Pagina letta nell'ordine sbagliato

Con un'impaginazione su tre colonne o un modulo a caselle, il modello può mescolare i blocchi. Prova l'istruzione Free OCR, che segue più semplicemente l'ordine spaziale, oppure passa da Docling, la cui analisi dell'impaginazione è esplicita.

Lentezza anomala

Verificate con ollama ps che il modello sia effettivamente caricato sulla GPU e non parzialmente sul processore. Un contesto troppo grande o un secondo modello caricato possono farlo sconfinare nella memoria di sistema.

Testo manoscritto

DeepSeek-OCR è addestrato su documenti stampati e rappresentazioni di pagine. Con la scrittura manoscritta, i risultati variano notevolmente; non fateci affidamento senza una prova preliminare.

Documenti lunghi e contesto tra le pagine

Ogni pagina viene elaborata in modo isolato. Una tabella che continua nella pagina successiva perde le intestazioni; è necessario reinserirle manualmente o con una regola di post-elaborazione.

#Quando PaddleOCR, Docling o Tesseract sono sufficienti

DeepSeek-OCR non è la risposta a tutte le scansioni. Dà il meglio quando la pagina ha una struttura da preservare e volete ottenere Markdown senza assemblare una pipeline. In molti casi comuni, uno strumento più semplice o più specializzato offre risultati altrettanto buoni, con meno risorse e minore rischio di invenzioni.

Tesseract

Testo pulito, stampato, su sfondo bianco, in grande quantità, e vi serve soltanto il testo. Funziona sul processore, non genera nulla e quindi non inventa nulla. Guida: https://quelllm.fr/guide/tesseract-ocr-guide-local

PaddleOCR

Testo posizionato in qualsiasi punto della pagina, scansioni inclinate, tabelle da ricostruire con una fase di rilevamento esplicita prima della lettura. Anche la sua variante VL è un modello di visione, più piccolo di DeepSeek-OCR. Guida: https://quelllm.fr/guide/paddleocr-vl-ocr-local

Docling

PDF nativi, DOCX, presentazioni: documenti che contengono già del testo e per i quali occorre soprattutto recuperare l'impaginazione e le tabelle. Docling può chiamare un motore OCR per le pagine immagine, ma il suo nucleo è l'analisi della struttura. Guida: https://quelllm.fr/guide/docling-conversion-documents-ia

DeepSeek-OCR

Scansioni o foto di pagine con titoli, elenchi, tabelle o formule, e la necessità di ottenere Markdown pronto per l'indicizzazione in un unico passaggio, su una scheda grafica modesta.

Spesso un criterio è decisivo: se un errore in una cifra ha conseguenze, preferisci uno strumento che riconosce senza generare, oppure raddoppia la lettura con un secondo motore e confronta i risultati. Se la priorità è rendere leggibile e interrogabile una raccolta di documenti eterogenei, il Markdown di DeepSeek-OCR fa risparmiare tempo a ogni fase successiva.

#Per approfondire

Scheda del modello DeepSeek-OCR

Parametri, VRAM per precisione, licenza e comando di installazione. https://quelllm.fr/modele/deepseek-ocr

Installare Ollama

L'installazione su Windows, macOS e Linux, i comandi di base e la risoluzione dei problemi. https://quelllm.fr/guide/installer-ollama

RAG locale senza scrivere codice

Collegate il Markdown ottenuto a Open WebUI o AnythingLLM per interrogare i documenti. https://quelllm.fr/guide/rag-local-ollama-sans-coder

Fonti ufficiali

Repository GitHub deepseek-ai/DeepSeek-OCR (codice, istruzioni, script vLLM per PDF), pagina Hugging Face deepseek-ai/DeepSeek-OCR (pesi e licenza MIT), pagina Ollama ollama.com/library/deepseek-ocr (tag, dimensioni e versione minima).