Docling Python: praktický průvodce zpracováním souborů v roce 2026

pip install docling

from docling.document_converter import DocumentConverter

converter = DocumentConverter()
result = converter.convert("contract.pdf")  # a local path or a URL
print(result.document.export_to_markdown())

Klíčová fakta

• Nejnovější vydání: Docling 2.140.0, zveřejněno na PyPI 16. října 2026 (PyPI, přečteno 20. 10. 2026).
• Python: 3.10 nebo novější; podpora verze 3.9 byla ukončena ve verzi 2.70.0 (README Doclingu, přečteno 20. 10. 2026).
• Licence a domov: MIT, repozitář github.com/docling-project/docling, projekt LF AI & Data, asi 69 000 hvězdiček na GitHubu (GitHub, 20. 10. 2026).
• OCR enginy: automatický výběr (výchozí), RapidOCR (nainstalován ve výchozím stavu), EasyOCR, Tesseract (CLI nebo tesserocr), macOS Vision, Nemotron OCR a vzdálený engine KServe (pipeline_options.py, 2.140.0).
• Arabština: podporována přes EasyOCR (`ar`), Tesseract (`ara`) a rozpoznávač arabského písma v RapidOCR; stránky se smíšenou arabštinou a angličtinou mají stále otevřené problémy, například #3462 a #3929 (GitHub, přečteno 20. 10. 2026).
• Formáty: mimo jiné PDF, DOCX, DOC, RTF, PPTX, XLSX, CSV, HTML, Markdown, AsciiDoc, LaTeX, EPUB, e-maily (EML, MSG), ODF, obrázky, audio a video (výčet InputFormat, 2.140.0).

K čemu se Docling používá?

Docling stojí na začátku pipeline pro vyhledávání nebo analýzu dokumentů. Načte soubor, provede detekci rozvržení, rekonstrukci pořadí čtení, obnovu struktury tabulek a OCR tam, kde stránka nemá textovou vrstvu, a vrátí jediný objekt `DoclingDocument`. Z tohoto objektu exportujete Markdown, HTML, prostý text nebo bezeztrátové JSON, nebo ho předáte chunkeru, který připraví části pro embedding model.

Pro právní práci nám na něm záleží, protože smlouvy jsou plné struktur, které naivní extrakce textu z PDF ničí: číslovaná ustanovení, přílohy, platební tabulky, podpisové bloky a stránky, které jsou jen skenem orazítkovaného originálu. Docling běží lokálně, takže dokumenty klientů kvůli zpracování nikdy nemusí opustit vaši infrastrukturu.

Jaké formáty souborů Docling podporuje?

Vydání 2.140.0 přijímá PDF (textové i skenované), Word (.docx, .doc), RTF, PowerPoint (.pptx, .ppt), Excel (.xlsx, .xls), CSV, HTML a MHTML, Markdown, AsciiDoc, LaTeX, EPUB, e-mailové soubory (.eml, .msg), OpenDocument (.odt, .ods, .odp), Apple Pages, Numbers a Keynote, obrázky (PNG, JPEG, TIFF a další), WebVTT a audio a video prostřednictvím rozpoznávání řeči. `DocumentConverter` formát rozpozná sám, takže předáte jen cestu nebo URL a nic dalšího.

Umí Docling OCR?

Ano. `PdfPipelineOptions.do_ocr` je ve výchozím stavu `True` a výchozí `OcrAutoOptions` vybere při spuštění dostupný engine. Ve výchozím stavu OCR běží jen na oblastech bez použitelné textové vrstvy (`OcrMode.DEFAULT`, což se aktuálně mapuje na `PDF_AWARE_LAYOUT_REGIONS`). U zcela skenovaného souboru nastavte `mode=OcrMode.FULL_PAGE`. Starší příznak `force_full_page_ocr=True` stále funguje, ale je zastaralý.

Kódy jazyků se enginu předávají tak, jak jsou napsány (`ara` pro Tesseract, `ar` pro EasyOCR), nebo jako značka BCP-47 s předponou `iso:`, například `iso:ar`, kterou Docling převede na správný kód enginu. Jazyk, pro který engine nemá model, vyvolá chybu místo tichého záložního řešení, což je v právní pipeline přesně to, co chcete.

Jak provést OCR skenované arabské smlouvy s tabulkami?

Vezměme typický případ: 14stránková skenovaná nájemní smlouva z Dubaje, arabský text s anglickými definovanými pojmy, tabulka nájemného na straně 3 a orazítkovaná podpisová strana. Textová vrstva chybí, takže každá stránka prochází OCR a tabulka nájemného potřebuje TableFormer v přesném režimu. Použijeme zde Tesseract, protože zvládá arabštinu i angličtinu na jedné stránce v jednom průchodu.

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())

Nejprve nainstalujte Tesseract a jeho arabská data (`apt install tesseract-ocr tesseract-ocr-ara` na Debianu nebo Ubuntu, na jiných systémech soubor `ara.traineddata` z repozitáře tessdata). Tatáž úloha z příkazového řádku:

docling --ocr-engine tesseract --ocr-lang ara,eng --ocr-mode full_page --table-mode accurate lease_dubai_scanned.pdf

Chcete-li místo toho použít EasyOCR, nainstalujte `docling[easyocr]` a dosaďte `EasyOcrOptions(lang=["ar", "en"], mode=OcrMode.FULL_PAGE)`. EasyOCR využije GPU, je-li k dispozici, což pomáhá u dlouhých balíků dokumentů.

Co zkontrolovat ve výstupu arabské smlouvy

• Pořadí slov na smíšených řádcích. Když je anglický definovaný pojem uvnitř arabské věty, může se pořadí úseků vrátit obráceně. Problém je evidován jako issue #3462 (Mixed Arabic-English PDFs produce incorrect OCR/output text) a k 20. 10. 2026 je otevřený.
• Prezentační formy v digitálních PDF. Některá arabská PDF ukládají glyfy jako prezentační formy Unicode, což rozbíjí vyhledávání a embeddingy. Oprava normalizace je navržena v pull requestu #3929, který je stále otevřený; dokud nebude sloučen, spusťte na exportovaném textu `unicodedata.normalize("NFKC", text)`.
• Buňky tabulek. Porovnejte dva nebo tři řádky tabulky nájemného se skenem pohledem. Částky ve východních arabských číslicích (٠١٢٣) ponechte tak, jak jsou napsány, a převádějte je až v pozdějším, zaznamenaném kroku.
• Razítka a podpisy. Detekují se jako obrázky. Nejsou to text, proto nečekejte znění razítka v Markdownu.

Nic z toho nenahrazuje právníka, který čte originál. Převede text, číslování ustanovení a tabulky do podoby, se kterou mohou pracovat nástroje pro revizi, a ukáže, které stránky potřebují druhý pohled člověka.

Jak dělit dokumenty na chunky pomocí HybridChunker?

`HybridChunker` dělí podle vlastní struktury dokumentu (oddíly, ustanovení, řádky tabulek) a poté části přizpůsobí rozpočtu tokenů. V aktuálních vydáních je rozpočet tokenů součástí obalu tokenizeru z `docling-core` a tento obal předáváte chunkeru. Starší návody, včetně první verze tohoto, předávaly přímo `HybridChunker` surový tokenizer z `transformers` a `max_tokens`. To stále běží, ale nyní to vyvolá `DeprecationWarning`, proto použijte obal.

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))

Embedujte výstup `contextualize()`, ne `chunk.text`. U smlouvy se před každý chunk přidá cesta nadpisů, takže chunk, který říká jen „nájemce zaplatí do 30 dnů“, dorazí do embedding modelu jako součást „Článek 5, Nájemné a platba“. Pro arabské smlouvy zvolte vícejazyčný embedding model; model jen pro angličtinu, například all-MiniLM-L6-v2, bude arabštinu tokenizovat špatně. Pro modely ve stylu OpenAI obalí kódování tiktoken stejným způsobem `docling_core.transforms.chunker.tokenizer.openai.OpenAITokenizer`.

Odkud každý chunk pochází?

Každý chunk nese `chunk.meta` s položkami `headings` (cesta oddílů), `doc_items` (zdrojové odstavce nebo buňky tabulky, každá s číslem stránky a ohraničujícím rámečkem v poli `prov`) a `origin` (název a hash zdrojového souboru). Ponechte si je. Právní odpověď, která cituje „stranu 3, tabulku nájemného“, lze ověřit; ta, která cituje „chunk 41“, ne.

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],
    })

Jak zpracovat složku smluv?

Vytvořte konvertor jednou a používejte ho opakovaně, protože pomalé je načítání modelů. `convert_all` přijímá iterovatelný seznam cest a s `raises_on_error=False` pokračuje i po poškozeném souboru a nahlásí jeho stav.

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}")

U dlouhých balíků nastavte `pipeline_options.document_timeout` (docstring Doclingu doporučuje 90 až 120 sekund), aby jeden špatný sken nemohl zastavit celou dávku, a vypněte funkce, které nepotřebujete: `do_table_structure=False` u korespondence, `do_ocr=False` u nativně digitálních exportů z Wordu převedených do PDF.

Jaké exportní formáty Docling podporuje?

Z objektu `DoclingDocument` můžete volat `export_to_markdown()`, `export_to_html()`, `export_to_text()` a `export_to_dict()` (bezeztrátové JSON, které později načtete bez nového spuštění OCR). JSON uložte pro vše, na čem jste provedli OCR: opakované OCR celých stránek u 200stránkového balíku je nákladný krok a JSON uchovává původ stránek a ohraničujících rámečků, který Markdown zahazuje.

Docling vs Unstructured: co mám použít?

Oba jsou open source a oba běží lokálně. Silnými stránkami Doclingu jsou analýza rozvržení, obnova struktury tabulek pomocí TableFormer, jediný typovaný model dokumentu s původem na úrovni stránek a chunker respektující strukturu. Unstructured (Apache 2.0, funkce `partition()`) má širší sadu zdrojových a cílových konektorů a hostovanou komerční platformu. Pro pipeline smluv, kde záleží na tabulkách a odkazech na stránky, začínáme s Doclingem; pokud je vaším problémem stahování souborů z mnoha SaaS systémů, mohou vám konektory Unstructured ušetřit víc času. Před rozhodnutím spusťte oba na deseti svých nejhorších skenech, protože výsledky u arabských skenů se liší více podle souboru než podle knihovny.

Jak to souvisí s revizí pomocí Legal AI?

Parsování je první krok a ten rozhoduje o tom, jak dobré může být vše po něm. Ustanovení rozdělené napůl parserem nelze posoudit jako ustanovení a tabulku zploštěnou do řádku čísel nelze zkontrolovat řádek po řádku. HAQQ nahrává soubory klientů do soukromých pracovních prostorů se stejnými cíli (zachovaná struktura, tabulky a citace stránek) předtím, než na nich proběhne revize smluv, s hostingem v EU, USA nebo na Blízkém východě, případně na vaší vlastní infrastruktuře.

Co dělat dál

• Připněte `docling==2.140.0` (nebo jakékoli vydání, které testujete) a zaznamenejte ho vedle svých výstupů.
• Vyberte tři reprezentativní soubory: nativně digitální smlouvu, skenovanou arabskou a jednu s hustou tabulkou. Každý převeďte a přečtěte Markdown proti originálu.
• OCR engine volte podle typu dokumentu, ne globálně. Tesseract s `["ara", "eng"]` je rozumná výchozí volba pro smíšené smlouvy z regionu MENA.
• Dělte na chunky tokenizerem, který odpovídá vašemu embedding modelu, a ponechte `chunk.meta` pro citace.

Zdroje

• Docling na PyPI (historie vydání)
• docling-project/docling na GitHubu
• Vydání Doclingu
• Dokumentace Doclingu
• Příklad OCR celých stránek v Doclingu
• Příklad hybridního dělení na chunky v Doclingu
• Issue #3462: Smíšená arabsko-anglická PDF
• Pull request #3929: normalizace arabských prezentačních forem
• Jazyková data Tesseractu (tessdata)

Související čtení

• context engineering pro spolehlivou Legal AI
• tabulková revize dokumentů pro Legal AI
• průvodce legal engineeringem pracovními postupy s AI