In sintesi: Docling è una libreria Python con licenza MIT, nata in IBM Research e oggi ospitata da LF AI & Data, che converte PDF, file Word, scansioni e oltre 30 altri formati in Markdown o JSON per le pipeline di IA. La versione 2.140.0 (16 ottobre 2026) si installa con un solo comando pip e converte un file in cinque righe di Python.
pip install doclingfrom docling.document_converter import DocumentConverter
converter = DocumentConverter()
result = converter.convert("contract.pdf") # a local path or a URL
print(result.document.export_to_markdown())Nota sulla versione: ogni frammento di codice di questa guida è stato verificato su Docling 2.140.0 (PyPI, rilasciata il 16 ottobre 2026) e sul repository docling-project/docling il 20 ottobre 2026. Docling pubblica nuove versioni a distanza di pochi giorni, quindi fissate la versione in produzione e ricontrollate i nomi delle opzioni a ogni aggiornamento.
Dati principali
- Ultima versione: Docling 2.140.0, pubblicata su PyPI il 16 ottobre 2026 (PyPI, consultato il 20 ott. 2026).
- Python: 3.10 o successivo; il supporto per la 3.9 è stato rimosso nella 2.70.0 (README di Docling, consultato il 20 ott. 2026).
- Licenza e sede: MIT, repository github.com/docling-project/docling, un progetto di LF AI & Data, circa 69.000 stelle su GitHub (GitHub, 20 ott. 2026).
- Motori OCR: un selettore automatico (predefinito), RapidOCR (installato di default), EasyOCR, Tesseract (CLI o tesserocr), macOS Vision, Nemotron OCR e un motore remoto KServe (pipeline_options.py, 2.140.0).
- Arabo: supportato tramite EasyOCR (`ar`), Tesseract (`ara`) e il riconoscitore per la scrittura araba di RapidOCR; le pagine miste in arabo e inglese hanno ancora issue aperte, per esempio #3462 e #3929 (GitHub, consultato il 20 ott. 2026).
- Formati: tra gli altri PDF, DOCX, DOC, RTF, PPTX, XLSX, CSV, HTML, Markdown, AsciiDoc, LaTeX, EPUB, email (EML, MSG), ODF, immagini, audio e video (enum InputFormat, 2.140.0).
Prova HAQQ AI gratis
Sperimenta la redazione e ricerca legale con IA
A cosa serve Docling?
Docling si colloca all'inizio di una pipeline di retrieval o di analisi documentale. Legge un file, esegue il rilevamento del layout, la ricostruzione dell'ordine di lettura, il recupero della struttura delle tabelle e l'OCR dove la pagina non ha un livello di testo, e restituisce un unico oggetto `DoclingDocument`. Da quell'oggetto si esporta Markdown, HTML, testo semplice o JSON senza perdita di informazioni, oppure lo si passa a un chunker che prepara i frammenti per un modello di embedding.
Ci interessa per il lavoro legale perché i contratti sono pieni delle strutture che un'estrazione ingenua del testo da PDF distrugge: clausole numerate, allegati, tabelle dei pagamenti, blocchi di firma e pagine che sono solo la scansione di un originale timbrato. Docling gira in locale, quindi i documenti dei clienti non devono mai uscire dalla vostra infrastruttura per essere analizzati.
Quali formati di file supporta Docling?
La versione 2.140.0 accetta PDF (con testo e scansionati), Word (.docx, .doc), RTF, PowerPoint (.pptx, .ppt), Excel (.xlsx, .xls), CSV, HTML e MHTML, Markdown, AsciiDoc, LaTeX, EPUB, file email (.eml, .msg), OpenDocument (.odt, .ods, .odp), Apple Pages, Numbers e Keynote, immagini (PNG, JPEG, TIFF e altre), WebVTT, e audio e video tramite riconoscimento vocale. `DocumentConverter` rileva il formato da solo, quindi basta passare un percorso o un URL.
Docling esegue l'OCR?
Sì. `PdfPipelineOptions.do_ocr` è `True` per impostazione predefinita, e l'opzione predefinita `OcrAutoOptions` sceglie un motore disponibile all'avvio. Di default l'OCR viene eseguito solo sulle aree prive di un livello di testo utilizzabile (`OcrMode.DEFAULT`, che attualmente corrisponde a `PDF_AWARE_LAYOUT_REGIONS`). Per un file interamente scansionato, impostate `mode=OcrMode.FULL_PAGE`. Il vecchio flag `force_full_page_ocr=True` funziona ancora ma è deprecato.
| Motore | Classe di opzioni | Installazione | Codice per l'arabo |
|---|---|---|---|
| RapidOCR | RapidOcrOptions | incluso in pip install docling | riconoscitore per la scrittura araba (una lingua per esecuzione) |
| EasyOCR | EasyOcrOptions | pip install "docling[easyocr]" | ar (combinabile con en) |
| Tesseract CLI | TesseractCliOcrOptions | Tesseract di sistema più ara.traineddata | ara (combinato come ["ara", "eng"]) |
| Tesseract (tesserocr) | TesseractOcrOptions | pip install "docling[tesserocr]" più Tesseract di sistema | ara |
| macOS Vision | OcrMacOptions | pip install "docling[ocrmac]", solo macOS | dipende dalla versione di macOS |
| Auto | OcrAutoOptions | predefinito | inoltra i tag iso: al motore scelto |
I codici lingua vengono passati al motore così come sono scritti (`ara` per Tesseract, `ar` per EasyOCR), oppure come tag BCP-47 dopo il prefisso `iso:`, per esempio `iso:ar`, che Docling converte nel codice corretto per il motore. Una lingua per cui il motore non ha un modello genera un errore invece di ripiegare silenziosamente su un'altra, ed è proprio ciò che serve in una pipeline legale.
Come si esegue l'OCR di un contratto arabo scansionato con tabelle?
Prendiamo un caso tipico: un contratto di locazione di Dubai scansionato, di 14 pagine, con il corpo del testo in arabo e i termini definiti in inglese, un piano dei canoni in forma di tabella a pagina 3 e una pagina delle firme timbrata. Non c'è un livello di testo, quindi ogni pagina passa per l'OCR, e la tabella dei canoni richiede TableFormer in modalità accurata. Qui usiamo Tesseract perché gestisce arabo e inglese sulla stessa pagina in un solo passaggio.
from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import (
OcrMode,
PdfPipelineOptions,
TableFormerMode,
TableStructureOptions,
TesseractCliOcrOptions,
)
from docling.document_converter import DocumentConverter, PdfFormatOption
pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = True
pipeline_options.ocr_options = TesseractCliOcrOptions(
lang=["ara", "eng"], # Arabic first, English defined terms second
mode=OcrMode.FULL_PAGE, # the scan has no text layer
)
pipeline_options.do_table_structure = True
pipeline_options.table_structure_options = TableStructureOptions(
mode=TableFormerMode.ACCURATE,
do_cell_matching=False, # let the model define cells on a scan
)
converter = DocumentConverter(
format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)}
)
result = converter.convert("lease_dubai_scanned.pdf")
doc = result.document
# Tables come back as structured objects, not flattened text
for table in doc.tables:
df = table.export_to_dataframe(doc=doc)
print(df.head())
with open("lease.md", "w", encoding="utf-8") as f:
f.write(doc.export_to_markdown())Installate prima Tesseract e i suoi dati per l'arabo (`apt install tesseract-ocr tesseract-ocr-ara` su Debian o Ubuntu, oppure il file `ara.traineddata` dal repository tessdata su altri sistemi). La stessa operazione da riga di comando:
docling --ocr-engine tesseract --ocr-lang ara,eng --ocr-mode full_page --table-mode accurate lease_dubai_scanned.pdfPer usare invece EasyOCR, installate `docling[easyocr]` e sostituite le opzioni con `EasyOcrOptions(lang=["ar", "en"], mode=OcrMode.FULL_PAGE)`. EasyOCR usa una GPU quando è presente, il che aiuta con fascicoli lunghi.
Cosa verificare nell'output di un contratto arabo
- Ordine delle parole nelle righe miste. Quando un termine definito in inglese si trova dentro una frase araba, l'ordine dei segmenti di testo può risultare invertito. Il problema è tracciato nella issue #3462 (Mixed Arabic-English PDFs produce incorrect OCR/output text), ancora aperta al 20 ott. 2026.
- Forme di presentazione nei PDF digitali. Alcuni PDF in arabo memorizzano i glifi come forme di presentazione Unicode, il che compromette la ricerca e gli embedding. Una correzione per la normalizzazione è proposta nella pull request #3929, ancora aperta; finché non viene integrata, applicate `unicodedata.normalize("NFKC", text)` al testo esportato.
- Celle delle tabelle. Confrontate a occhio due o tre righe del piano dei canoni con la scansione. Gli importi in cifre arabo-orientali (٠١٢٣) vanno mantenuti come sono scritti e convertiti solo in un passaggio successivo e registrato.
- Timbri e firme. Vengono rilevati come immagini. Non sono testo, quindi non aspettatevi il testo del timbro nel Markdown.
Niente di tutto questo sostituisce la lettura dell'originale da parte di un avvocato. Serve a portare testo, numerazione delle clausole e tabelle in una forma su cui gli strumenti di revisione possono lavorare, e vi indica quali pagine richiedono un secondo controllo umano.
Come si suddividono i documenti in chunk con HybridChunker?
`HybridChunker` divide seguendo la struttura propria del documento (sezioni, clausole, righe di tabella) e poi adatta i frammenti a un budget di token. Nelle versioni attuali il budget di token risiede in un wrapper del tokenizer di `docling-core`, e siete voi a passare quel wrapper al chunker. I tutorial precedenti, compresa la prima versione di questa guida, passavano direttamente a `HybridChunker` un tokenizer `transformers` grezzo e `max_tokens`. Funziona ancora, ma ora genera un `DeprecationWarning`, quindi usate il wrapper.
from docling.chunking import HybridChunker
from docling_core.transforms.chunker.tokenizer.huggingface import HuggingFaceTokenizer
from transformers import AutoTokenizer
EMBED_MODEL_ID = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
tokenizer = HuggingFaceTokenizer(
tokenizer=AutoTokenizer.from_pretrained(EMBED_MODEL_ID),
max_tokens=512, # match your embedding model's limit
)
chunker = HybridChunker(
tokenizer=tokenizer,
merge_peers=True, # merge small neighbouring chunks under the same heading (default)
)
for chunk in chunker.chunk(dl_doc=doc):
text_for_embedding = chunker.contextualize(chunk=chunk) # prepends the heading path
print(chunk.meta.headings, len(text_for_embedding))Calcolate gli embedding sull'output di `contextualize()`, non su `chunk.text`. Per un contratto, il metodo antepone a ogni chunk il percorso dei titoli, così un chunk che dice solo «the Tenant shall pay within 30 days» arriva al modello di embedding come parte di «Article 5, Rent and Payment». Per i contratti in arabo scegliete un modello di embedding multilingue; un modello solo inglese come all-MiniLM-L6-v2 tokenizza male l'arabo. Per i modelli in stile OpenAI, `docling_core.transforms.chunker.tokenizer.openai.OpenAITokenizer` incapsula allo stesso modo una codifica tiktoken.
Da dove proviene ogni chunk?
Ogni chunk porta con sé `chunk.meta`, con `headings` (il percorso della sezione), `doc_items` (i paragrafi o le celle di tabella di origine, ciascuno con numero di pagina e bounding box nel campo `prov`) e `origin` (nome e hash del file di origine). Conservateli. Una risposta legale che cita «pagina 3, piano dei canoni» è verificabile; una che cita «chunk 41» non lo è.
for chunk in chunker.chunk(dl_doc=doc):
pages = sorted({prov.page_no for item in chunk.meta.doc_items for prov in item.prov})
print({
"source": chunk.meta.origin.filename,
"headings": chunk.meta.headings,
"pages": pages,
"text": chunker.contextualize(chunk=chunk)[:80],
})Come si elabora una cartella di contratti?
Create il convertitore una sola volta e riutilizzatelo, perché il caricamento dei modelli è la parte lenta. `convert_all` accetta un iterabile di percorsi e, con `raises_on_error=False`, prosegue oltre un file danneggiato e ne riporta lo stato.
from pathlib import Path
from docling.datamodel.base_models import ConversionStatus
files = sorted(Path("contracts/").glob("*.pdf"))
for res in converter.convert_all(files, raises_on_error=False):
name = res.input.file.name
if res.status == ConversionStatus.SUCCESS:
Path("out", name).with_suffix(".md").write_text(
res.document.export_to_markdown(), encoding="utf-8"
)
else:
print(f"{name}: {res.status}")Per i fascicoli lunghi, impostate `pipeline_options.document_timeout` (la docstring di Docling suggerisce da 90 a 120 secondi) in modo che una scansione difettosa non blocchi un intero lotto, e disattivate le funzioni che non vi servono: `do_table_structure=False` per la corrispondenza, `do_ocr=False` per esportazioni Word nate digitali e convertite in PDF.
Quali formati di esportazione supporta Docling?
Da un `DoclingDocument` potete chiamare `export_to_markdown()`, `export_to_html()`, `export_to_text()` e `export_to_dict()` (JSON senza perdita di informazioni, che potete ricaricare in seguito senza rieseguire l'OCR). Salvate il JSON di tutto ciò che è passato per l'OCR: rieseguire l'OCR a pagina intera su un fascicolo di 200 pagine è il passaggio costoso, e il JSON conserva la provenienza di pagina e bounding box che il Markdown perde.
Docling o Unstructured: quale usare?
Entrambi sono open source ed entrambi girano in locale. I punti di forza di Docling sono l'analisi del layout, il recupero della struttura delle tabelle con TableFormer, un unico modello di documento tipizzato con provenienza a livello di pagina e un chunker che tiene conto della struttura. Unstructured (Apache 2.0, funzioni `partition()`) offre una gamma più ampia di connettori di origine e destinazione e una piattaforma commerciale in hosting. Per una pipeline di contratti in cui contano le tabelle e le citazioni alla pagina, partiamo da Docling; se il vostro problema è estrarre file da molti sistemi SaaS, i connettori di Unstructured potrebbero farvi risparmiare più tempo. Provate entrambi su dieci delle vostre scansioni peggiori prima di decidere, perché sulle scansioni in arabo i risultati variano più da file a file che da libreria a libreria.
Che legame ha con la revisione legale basata sull'IA?
Il parsing è il primo passaggio, ed è quello che determina quanto potrà essere buono tutto ciò che viene dopo. Una clausola che il parser ha spezzato a metà non può essere esaminata come clausola, e una tabella appiattita in una riga di numeri non può essere controllata riga per riga. HAQQ acquisisce i file dei clienti in workspace privati con gli stessi obiettivi (struttura, tabelle e citazioni di pagina mantenute intatte) prima che la revisione dei contratti venga eseguita su di essi, con hosting nell'UE, negli Stati Uniti o in Medio Oriente, oppure sulla vostra infrastruttura.
Cosa fare adesso
- Fissate `docling==2.140.0` (o la versione che state testando) e annotatela accanto ai vostri output.
- Scegliete tre file rappresentativi: un contratto nato digitale, uno arabo scansionato e uno con una tabella fitta. Convertite ciascuno e confrontate il Markdown con l'originale.
- Scegliete il motore OCR per tipo di documento, non a livello globale. Tesseract con `["ara", "eng"]` è un'impostazione predefinita solida per i contratti misti dell'area MENA.
- Suddividete in chunk con un tokenizer adatto al vostro modello di embedding e conservate `chunk.meta` per le citazioni.
Fonti
- Docling su PyPI (cronologia delle versioni)
- docling-project/docling su GitHub
- Release di Docling
- Documentazione di Docling
- Esempio di OCR a pagina intera con Docling
- Esempio di chunking ibrido con Docling
- Issue #3462: PDF misti arabo-inglese
- Pull request #3929: normalizzazione delle forme di presentazione arabe
- Dati linguistici di Tesseract (tessdata)



![Smetti di scrivere [CLIENTE]: come anonimizzare un documento prima di darlo a un'IA](/images/blog-covers/redaction-tools-for-lawyers.webp)