Chi prova a costruire un sistema RAG sopra il proprio archivio documentale conosce bene il momento in cui l’entusiasmo iniziale si scontra con la realtà: i PDF. Da tempo il formato di Adobe ha occupato una sorta di muro invisibile fra i dati strutturati e i modelli linguistici, capace di trasformare una pipeline elegante in una sequenza di workaround poco eleganti.
Tabelle disallineate, colonne che diventano un flusso di testo confuso, formule matematiche ridotte a sequenze incomprensibili: ogni documento sembra avere una geometria a sé. Docling nasce per affrontare questo problema in modo strutturale. Sviluppato da IBM Research e rilasciato come progetto open source alla fine del 2024, è una libreria Python pensata per convertire documenti complessi (non solo PDF, ma anche DOCX, PPTX, HTML, XLSX e immagini) in un formato coerente, pronto per essere ingerito da un LLM, da un sistema di ricerca semantica o da un knowledge graph.
A differenza dei classici parser basati su euristiche o sul testo grezzo estratto da PyPDF2, Docling adotta un approccio multi-modello che combina rilevamento del layout, comprensione gerarchica delle tabelle e OCR opzionale per i documenti scannerizzati. Il risultato è un Markdown ordinato, una struttura JSON gerarchica oppure un grafo di blocchi, sempre con riferimenti ai bounding box originali. Per chi lavora a RAG, automatizza report o vuole portare la propria libreria personale dentro un assistente AI in locale, Docling è uno dei tasselli più interessanti emersi negli ultimi tempi.
Perché IBM ha rilasciato Docling come open source
Docling è il frutto del gruppo IBM Research Zurich, lo stesso che da anni si occupa di document understanding per i clienti enterprise della casa madre. Per molto tempo questa tecnologia è rimasta dietro il portale Watson, accessibile solo via API e a pagamento.
La scelta di liberarne il cuore con licenza MIT, alla fine del 2024, va letta nel contesto della guerra in corso sui modelli aperti: senza una pipeline solida di preprocessing, anche il miglior LLM rimane limitato dalla qualità del testo che riceve in ingresso. A tal proposito, IBM ha rilasciato in parallelo i modelli specializzati su cui Docling si appoggia, distribuiti su Hugging Face e utilizzabili in totale autonomia. Inoltre, la libreria si integra in modo trasparente con LangChain, LlamaIndex, Haystack e diversi orchestratori agentici, riducendo l’attrito per chi adotta lo stack di fatto del momento.
La differenza rispetto a librerie storiche come pdfplumber, pdfminer.six o PyMuPDF è netta. Quei tool restano ottimi per estrarre testo lineare, ma non comprendono la struttura logica del documento. Docling, invece, distingue intestazioni, paragrafi, didascalie, note a piè di pagina, tabelle multilivello e blocchi di codice. Di conseguenza, quando il documento viene chunkato per essere embeddato in un vector store, i confini semantici vengono rispettati e la retrieval ne beneficia in modo misurabile.
I modelli che lavorano su Docling
L’architettura di Docling si regge su due modelli specializzati, entrambi rilasciati pubblicamente. Il primo è un layout analyzer basato su una variante di RT-DETR addestrato su DocLayNet, il dataset interno IBM che copre 80.863 pagine annotate manualmente su sei categorie documentali (articoli scientifici, manuali, brevetti, bilanci, leggi e moduli amministrativi).
DocLayNet è stato pensato proprio per coprire la varietà del mondo reale, con undici classi semantiche e una distribuzione bilanciata fra domini. Il secondo modello è TableFormer, una rete che ricostruisce la matrice logica delle tabelle, comprese quelle con celle unite, header su più righe e gerarchie complesse, proprio i casi in cui i tool tradizionali falliscono.
Per chi vuole numeri di throughput, il Docling Technical Report misura su una RTX 3090 una media di 1,27 secondi per pagina in modalità fast e 3,7 secondi in modalità accurate. Su CPU (un Intel Xeon Platinum 8580) si scende a 5,4 secondi/pagina in fast e oltre 14 secondi in accurate. Su una RTX 4070 consumer, un documento di 30 pagine processato con pipeline completa (layout, tabelle, OCR disattivato) gira in circa 22-25 secondi, contro i 45-50 secondi della stessa pipeline su un MacBook Pro M3 Pro in modalità CPU-only. In tempo reale conviene la GPU, ma per lavori batch notturni anche un mini-PC diventa un’opzione valida.
Sopra questi due modelli, Docling orchestra una pipeline modulare. Si possono attivare o disattivare OCR (EasyOCR e Tesseract sono entrambi supportati), classificazione delle figure, equazioni LaTeX, esportazione gerarchica e persino estrazione dei metadati. La possibilità di scegliere quali fasi caricare significa controllare esattamente VRAM, tempo di esecuzione e qualità del risultato. A partire dalla versione 2 è stato introdotto anche SmolDocling, un modello vision-language compatto da 256M parametri pensato per girare su hardware modesto, mentre su CPU i tempi salgono in modo sensibile, lasciando il flusso utilizzabile solo per archivi non in tempo reale.
Integrarlo in una pipeline RAG senza riscrivere lo stack
L’approccio più immediato è installare il pacchetto con pip install docling e ottenere subito un convertitore funzionante. Una manciata di righe basta per trasformare un PDF in Markdown, JSON o nel formato nativo DoclingDocument, che conserva struttura, posizioni e relazioni gerarchiche.
from docling.document_converter import DocumentConverter
converter = DocumentConverter()
result = converter.convert("manuale_tecnico.pdf")
print(result.document.export_to_markdown())Quando carichi un documento in un sistema RAG (recupero + LLM), devi spezzare il testo in pezzi più piccoli (chunk) per poterli cercare nel vector store. Il guaio è che se tagli il testo in modo ingenuo — ogni N caratteri, o ogni N parole — rischi di spezzare a metà un concetto, una tabella, un elenco puntato. Il chunk risultante non ha senso da solo.
Docling capisce già la struttura del documento (titoli, paragrafi, tabelle, ecc.). HybridChunker sfrutta questa conoscenza per tagliare il testo nei punti giusti, cioè rispettando i confini logici: finisce un paragrafo → taglia lì, non nel mezzo.
Fa anche due cose in più:
- Controlla la lunghezza in token — non in caratteri, ma nei “pezzi” che l’LLM effettivamente legge — così il chunk non supera mai il limite del modello.
- Aggiunge il contesto della sezione — se un chunk viene da un paragrafo sotto il titolo “Installazione > Requisiti”, questa informazione viene allegata al chunk. Così anche fuori contesto si capisce di cosa parla.
Quando l’LLM riceve un chunk recuperato dal vector store, non gli arriva un pezzetto di testo strappato a caso dal mezzo di un documento. Gli arriva un blocco che ha senso da solo, con il titolo della sezione di appartenenza e i confini rispettati. Questo migliora molto la qualità delle risposte.
Il lettore di base funziona, ma ti dà solo il testo. Se invece esporti il documento in formato JSON (con metadati), Docling ti restituisce molto di più (metadati): per ogni pezzo di testo sai a che pagina si trova, se è un titolo o un paragrafo o una tabella, a che livello gerarchico appartiene.
Se usi LlamaIndex o LangChain per costruire un sistema RAG, di solito carichi i PDF con un lettore generico. Docling offre un suo lettore ufficiale (DoclingReader) che si sostituisce a quello standard con pochissimo codice — due righe, appunto.
from llama_index.readers.docling import DoclingReader
reader = DoclingReader()
docs = reader.load_data(file_path="documento.pdf")Se invece vuoi l’export in JSON (per avere i metadati di cui parlavamo sopra):
from llama_index.readers.docling import DoclingReader
reader = DoclingReader(export_type=DoclingReader.ExportType.JSON)
docs = reader.load_data(file_path="documento.pdf")E a questo punto, se aggiungi anche il DoclingNodeParser, LlamaIndex capisce la struttura Docling e crea i nodi già arricchiti con metadati come numero di pagina e bounding box:
from llama_index.readers.docling import DoclingReader
from llama_index.node_parser.docling import DoclingNodeParser
reader = DoclingReader(export_type=DoclingReader.ExportType.JSON)
node_parser = DoclingNodeParser()
index = VectorStoreIndex.from_documents(
documents=reader.load_data("documento.pdf"),
transformations=[node_parser],
)Senza filtering, il vector store recupera i chunk più simili semanticamente, ma magari prende roba sparsa e poco pertinente. Con il filtering arrivi al contesto giusto con più precisione, e l’LLM risponde meglio perché riceve informazioni più mirate. In breve: l’integrazione base ti fa risparmiare tempo, ma i metadati personalizzati ti faranno guadagnare qualità nelle risposte.
Docling alla prova: end-to-end con 500 paper, Qdrant e Ollama
Per capire come si comporta lo stack messo davvero alla prova, vale la pena ricostruire un flusso end-to-end su un caso plausibile, ovvero un ricercatore che vuole interrogare in linguaggio naturale una libreria di 500 paper scientifici in PDF. Il setup è minimale, con una macchina dotata di RTX 4070 (12 GB), 32 GB di RAM, Ollama per l’inferenza locale, Qdrant come vector store e un piccolo script che orchestra il tutto.
La pipeline di ingest si divide in tre fasi. Nella prima, Docling viene fatto girare sull’intero corpus con modalità accurate attivata e OCR disattivato (i paper sono digitali nativi). Il tempo medio è di circa 2,8 secondi per pagina su GPU, quindi su una media di 12 pagine per paper si ottiene un throughput totale di circa cinque ore per l’intero archivio. È un batch che gira tranquillamente in una notte senza supervisione.
Nella seconda fase entra in gioco l’HybridChunker, configurato sul tokenizer di BAAI/bge-m3, un embedding model multilingue da 567M parametri che gira bene sulla stessa GPU. Ogni paper produce in media 45 chunk semanticamente coerenti, per un totale di circa 22.500 vettori generati a una velocità di 160 chunk/secondo in batch da 32. I metadati salvati includono titolo del paper, sezione, numero pagina e bounding box, informazioni preziose per filtri mirati e per fornire citazioni esatte all’LLM.
Nella terza fase, Qdrant viene avviato in container con storage su SSD NVMe e configurato con indice HNSW. L’intero database, comprese le payload, occupa circa 180 MB su disco, una dimensione gestibile anche su una macchina modesta. La fase di query usa Qwen3.6-35b-a3b servito da Ollama o LMStudio, che con offload parziale su CPU produce risposte in circa 12 secondi per una domanda complessa, oppure Qwen2.5 14B completamente su GPU per latenze sotto i 6 secondi.
Il risultato pratico è una knowledge base personale completamente locale, capace di rispondere a domande del tipo “quali paper degli ultimi due anni discutono di sparse attention?“, citando direttamente sezione e pagina. Il costo marginale è zero, la privacy assoluta, e l’intera pipeline può essere ricostruita su una macchina secondaria in poche ore.
Limiti reali e alternative da conoscere
Sarebbe scorretto presentare Docling come una soluzione universale. La libreria ha ancora qualche fragilità sui documenti con formattazione molto creativa (riviste, magazine, layout editoriali multicolonna con riquadri sovrapposti), dove l’analisi del layout fa fatica a stabilire l’ordine di lettura. Su scansioni di pessima qualità, il risultato dell’OCR resta vincolato a EasyOCR o Tesseract, e nessuno dei due raggiunge la qualità dei modelli proprietari di Google Document AI o Azure Document Intelligence.
Marker, sviluppato da Vik Paruchuri, è probabilmente il principale concorrente diretto, perché privilegia velocità ed eleganza dell’output Markdown ed eccelle su paper accademici. MinerU, progetto cinese basato su PDF-Extract-Kit, ha un approccio simile a Docling ma con modelli più pesanti e qualità superiore su tabelle e formule. Per casi più semplici, infine, unstructured.io rimane una scelta valida come orchestratore generale.
La scelta dipende da cosa stai costruendo. Se ti serve un parser che funzioni out of the box su un parco documenti eterogeneo, gestisca DOCX, PPTX e HTML oltre ai PDF, e si integri senza attrito nel tuo stack RAG, Docling è oggi il punto di equilibrio migliore. Se invece il tuo dominio è ristretto e omogeneo, potresti trovare in Marker o MinerU una qualità superiore. Conviene sempre testare su una decina di documenti campione del tuo corpus prima di committare l’intera pipeline.
Un tassello che cambia la qualità del tuo stack AI locale
Se hai una libreria di paper, manuali, schede tecniche o bilanci, puoi costruire un knowledge base privato e interrogabile in linguaggio naturale, abbinando Docling a un’istanza locale di Ollama o LM Studio. Poi se devi automatizzare report aziendali, puoi trasformare il flusso PDF verso dati strutturati in qualcosa di affidabile, senza la fragilità delle regex sul testo estratto. Infine se gestisci documenti per un team, puoi alimentare un sistema di ricerca semantica che restituisce risposte ancorate al documento originale, con tanto di citazione della pagina e del blocco.
Il consiglio è di trattarlo come qualunque altro strumento, dedicandogli mezza giornata di sperimentazione, costruendo una piccola pipeline di valutazione sui tuoi documenti , e confrontando i chunk prodotti con quelli del tuo workflow attuale. È probabile che non tornerai indietro. In uno stack AI personale, Docling non è la stella, ma è uno di quei tasselli silenziosi che spostano la qualità complessiva di parecchi punti percentuali.
Segui Gomoot
Le nostre recensioni e notizie, dove le cerchi già.
1 commento
Per il corpus da 500 paper aggiungerei ai metadati anche un identificatore della versione del PDF, per esempio il suo hash. Se arriva una revisione dello stesso articolo, titolo e pagina da soli non bastano: i vecchi chunk possono restare in Qdrant e mescolarsi con quelli nuovi. La prova sui dieci documenti suggerita alla fine dovrebbe includere almeno un PDF a due colonne e uno con tabelle, controllando anche le citazioni recuperate.
Sono l’autore di PDF to MD: per preparare manualmente qualche PDF testuale offro una conversione gratuita in Markdown nel browser, con elaborazione locale. Non sostituisce l’ingestione automatica descritta qui; l’OCR opzionale è invece un servizio cloud a pagamento che richiede l’upload.