Docling, konwersja dokumentów dla modeli językowych

Docling, konwersja dokumentów dla modeli językowych

Docling to biblioteka Pythona, która zamienia PDF, DOCX, prezentacje i skany na jedną strukturę danych opisującą układ strony, tabele oraz kolejność czytania. Bieżąca wersja to 2.121.0 z 20 sierpnia 2026 roku, repozytorium docling-project/docling ma około 65,3 tysiąca gwiazdek, a kod jest wydany na licencji MIT.

Problem, który Docling rozwiązuje

Kiedy budujesz wyszukiwanie po własnych dokumentach, pierwszy krok wygląda niewinnie: wczytaj plik, wyciągnij tekst, potnij na fragmenty, policz wektory. Kłopot zaczyna się przy pierwszym raporcie finansowym albo pierwszej instrukcji technicznej złożonej w dwie szpalty.

Format PDF nie przechowuje akapitów ani tabel. Przechowuje instrukcje rysowania: umieść ten ciąg znaków w tym punkcie strony, tą czcionką, w tym rozmiarze. Kolejność tych instrukcji w pliku bywa dowolna i nie musi mieć nic wspólnego z kolejnością, w jakiej stronę czyta człowiek. Biblioteka wyciągająca sam tekst zwraca ciągi w kolejności zapisu i na tym kończy swoją rolę.

Skutki są przewidywalne i nieprzyjemne. Na stronie dwuszpaltowej zdanie z lewej kolumny sklejone zostaje z początkiem zdania z prawej. W tabeli wyników liczba z kolumny opisanej rokiem trafia obok etykiety z sąsiedniego wiersza, bo obie były rysowane blisko siebie. Żywa pagina i numer strony wchodzą w środek akapitu. Przypis dolny przerywa zdanie w połowie. Fragment, który wyląduje w bazie wektorowej, jest wtedy poprawny znak po znaku i całkowicie fałszywy jako informacja.

Model językowy nie ma jak tego wykryć. Dostaje tekst, który wygląda na spójny, i grzecznie odpowiada na jego podstawie. Błędy tego rodzaju nie zgłaszają się wyjątkiem, tylko cichą, wiarygodnie brzmiącą nieprawdą w odpowiedzi. Dlatego jakość warstwy wczytującej dokumenty decyduje o jakości całego systemu bardziej niż wybór modelu osadzeń czy bazy wektorowej.

Docling atakuje ten problem inaczej niż zwykłe biblioteki do PDF. Zamiast czytać wyłącznie strumień tekstu, uruchamia na obrazie strony model rozpoznawania układu, który wykrywa bloki: nagłówek, akapit, tabela, podpis, przypis, stopka. Dopiero na podstawie tych bloków ustalana jest kolejność czytania, a tabele przechodzą przez osobny model odtwarzający siatkę wierszy i kolumn.

Ta zamiana kolejności działań ma konkretną cenę i konkretny zysk. Cena to czas, bo każda strona przechodzi przez sieć neuronową zamiast przez zwykłe przeglądanie strumienia. Zysk to informacja, której w samym strumieniu po prostu nie ma: świadomość, że dany ciąg znaków jest komórką tabeli, a nie zdaniem, i że stopka strony nie należy do akapitu, który wizualnie ją poprzedza. Bez tej informacji żaden późniejszy krok potoku jej nie odtworzy, bo została utracona już przy wczytaniu pliku.

Co Docling właściwie robi

Przetwarzanie jednego pliku przebiega etapami i warto je rozróżniać, bo każdy da się osobno włączyć albo wyłączyć.

Pierwszy etap to backend, czyli parser konkretnego formatu. Dla PDF wyciąga on komórki tekstowe wraz z ich położeniem na stronie, dla DOCX i PPTX czyta strukturę XML dokumentu. Drugi etap to model układu strony, w domyślnej konfiguracji wariant o nazwie Heron, który dzieli obraz strony na obszary i przypisuje im typy. Trzeci to ustalenie kolejności czytania na podstawie wykrytych obszarów. Czwarty to TableFormer, model odtwarzający strukturę tabeli, z dwoma trybami pracy: fast i accurate, przy czym domyślny jest accurate.

Do tego dochodzi opcjonalny OCR dla dokumentów bez warstwy tekstowej, obsługiwany przez kilka silników: EasyOCR, Tesseract w dwóch wariantach, RapidOCR oraz mechanizm systemowy macOS. Osobno działają wzbogacenia, domyślnie wyłączone: rozpoznawanie bloków kodu, rozpoznawanie wzorów matematycznych z konwersją do LaTeX, klasyfikacja obrazów, opisywanie obrazów przez model wizualny i wyciąganie danych z wykresów.

Wynikiem jest DoclingDocument, czyli model danych oparty na Pydantic, w którym elementy dokumentu mają typ, treść, położenie i miejsce w hierarchii. Z tego obiektu eksportujesz to, czego potrzebujesz: export_to_markdown, export_to_html, export_to_text, export_to_dict oraz export_to_doctags, czyli zapis znacznikowy zaprojektowany pod modele wizualne.

Lista obsługiwanych formatów wejściowych w wersji 2.121.0 jest długa i obejmuje między innymi pdf, docx, doc, pptx, ppt, xlsx, xls, html, md, csv, epub, latex, email, image, audio, video, vtt, pliki OpenDocument odt, ods i odp, a także wyspecjalizowane schematy XML: patenty USPTO, artykuły JATS oraz sprawozdania finansowe XBRL.

Wersja, licencja i stan projektu

Licencja jest deklarowana spójnie, ale sposób pakowania kryje szczegół, który zaskoczy każdy skaner zależności sprawdzający zawartość archiwów.

Plik LICENSE w katalogu głównym repozytorium zawiera tekst licencji MIT z notą „Copyright (c) 2024 International Business Machines". Rejestr PyPI podaje dla pakietu docling pole License-Expression o wartości MIT. Interfejs programistyczny GitHuba raportuje dla repozytorium licencję MIT. Trzy źródła zgodne, sprawa wygląda na zamkniętą.

Zaskoczenie przychodzi przy trzeciej kontroli, czyli otwarciu opublikowanej paczki. Archiwum docling-2.121.0-py3-none-any.whl waży 5177 bajtów i zawiera dokładnie cztery pliki: METADATA, WHEEL, entry_points.txt oraz RECORD. Nie ma w nim ani jednej linii kodu i nie ma żadnego pliku licencyjnego. Archiwum źródłowe też go nie ma, bo składa się z .gitignore, README.md, pyproject.toml i PKG-INFO.

Wyjaśnienie jest proste, choć nieoczywiste. Pakiet docling stał się metapakietem. Jego jedyna zależność obowiązkowa to docling-slim[standard]==2.121.0 i to tam siedzi cały kod. Paczka docling-slim w tej samej wersji zawiera katalog dist-info/licenses/LICENSE z tekstem MIT, podobnie jak docling-core w wersji 2.92.0. Dziesięć dodatków zadeklarowanych przez metapakiet, między innymi vlm, easyocr, rapidocr, tesserocr, ocrmac, asr i xbrl, mapuje się jeden do jednego na dodatki pakietu docling-slim.

Praktyczny wniosek jest taki: jeśli Twój proces zgodności czyta pliki licencyjne z zainstalowanych paczek, pakiet docling pojawi się na liście jako pozycja bez licencji, mimo że deklaruje MIT w metadanych. Wpisz do rejestru zależności również docling-slim i docling-core, bo to one niosą kod i plik licencyjny.

Jest jeszcze zastrzeżenie ważniejsze od poprzedniego, wypisane wprost w dokumentacji projektu: licencja MIT obejmuje kod, a nie modele. Wagi modeli rozpoznawania układu, TableFormer, silników OCR i modeli wizualnych mają własne licencje, opisane przy odpowiednich pakietach i repozytoriach na Hugging Face. Przy wdrożeniu komercyjnym trzeba je sprawdzić osobno, model po modelu, bo z licencji samego Doclinga nic o nich nie wynika.

Warto też wiedzieć, że dwa polecenia dostarczane przez metapakiet, docling oraz docling-tools, są zadeklarowane w jego pliku entry_points.txt, ale wskazują na moduły znajdujące się w pakiecie docling-slim. Instalacja samego metapakietu z pominięciem zależności da więc polecenia, które natychmiast przerwą się błędem importu.

Stan projektu jest zdrowy. Repozytorium nie jest zarchiwizowane, ostatnia zmiana w gałęzi głównej pochodzi z 21 sierpnia 2026 roku, jest 4672 rozgałęzienia i 984 otwarte zgłoszenia. Wersję 2.121.0 opublikowano 20 sierpnia 2026 roku, a w rejestrze widnieje 208 wydań. Projekt wystartował w zespole IBM Research w Zurychu i jest dziś hostowany w fundacji LF AI & Data, co zdejmuje część ryzyka związanego z zależnością od jednej firmy.

Instalacja i pierwsze uruchomienie

Wymagany jest Python w wersji co najmniej 3.10. Wsparcie dla 3.9 zniknęło w wydaniu 2.70.0.

# instalacja podstawowa, ciągnie docling-slim[standard]
pip install docling

# konwersja pliku albo adresu do Markdown w katalogu bieżącym
docling https://arxiv.org/pdf/2206.01062

# wybór formatów wyjściowych i katalogu docelowego
docling raport.pdf --to md --to json --output ./wynik

# szybciej: bez OCR, tryb tabel fast, ograniczenie stron
docling raport.pdf --no-ocr --table-mode fast --page-range 1-20

# dokładniej: rozpoznawanie wzorów i bloków kodu
docling artykul.pdf --enrich-formula --enrich-code

# potok oparty na modelu wizualnym zamiast osobnych modeli
docling raport.pdf --pipeline vlm --vlm-model granite_docling

# karta graficzna, więcej wątków, limit czasu na dokument
docling raport.pdf --device cuda --num-threads 8 --document-timeout 120

Pierwsze uruchomienie pobiera wagi modeli, więc trwa dłużej niż kolejne. Flaga --device przyjmuje wskazanie urządzenia obliczeniowego, --num-threads domyślnie wynosi 4, a --document-timeout ustawia limit sekund na jeden dokument. Ten ostatni parametr jest w produkcji ważniejszy, niż się wydaje, bo pojedynczy patologiczny plik potrafi zająć proces na kwadrans.

Konfiguracja potoku PDF

Z poziomu Pythona sterujesz wszystkim przez obiekt opcji przekazany do konwertera. Nazwy pól poniżej pochodzą wprost z modelu PdfPipelineOptions w wersji 2.121.0.

from docling.datamodel.base_models import InputFormat
from docling.datamodel.accelerator_options import (
    AcceleratorDevice,
    AcceleratorOptions,
)
from docling.datamodel.pipeline_options import (
    PdfPipelineOptions,
    TableFormerMode,
    TableStructureOptions,
)
from docling.document_converter import DocumentConverter, PdfFormatOption

pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = False
pipeline_options.do_table_structure = True
pipeline_options.table_structure_options = TableStructureOptions(
    mode=TableFormerMode.ACCURATE,
    do_cell_matching=True,
)
pipeline_options.do_formula_enrichment = True
pipeline_options.do_code_enrichment = False
pipeline_options.generate_page_images = False
pipeline_options.images_scale = 1.0
pipeline_options.document_timeout = 120.0
pipeline_options.accelerator_options = AcceleratorOptions(
    num_threads=8,
    device=AcceleratorDevice.AUTO,
)

converter = DocumentConverter(
    allowed_formats=[InputFormat.PDF, InputFormat.DOCX],
    format_options={
        InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)
    },
)

result = converter.convert("raport.pdf", max_num_pages=200)
print(result.status)
print(result.document.export_to_markdown())

Kilka rzeczy z tego przykładu wymaga komentarza. Pole do_ocr jest domyślnie ustawione na wartość prawdziwą, więc jeśli przetwarzasz wyłącznie pliki z warstwą tekstową, wyłączenie go jest najtańszym przyspieszeniem, jakie dostaniesz. Pole do_table_structure również domyślnie działa i to ono odpowiada za większość kosztu przy dokumentach z wieloma tabelami. Przełączenie mode na TableFormerMode.FAST obniża jakość odtworzenia siatki, ale bywa wystarczające dla tabel prostych.

Ustawienie do_cell_matching decyduje, skąd bierze się treść komórek. Wartość prawdziwa dopasowuje przewidywania modelu z powrotem do komórek tekstowych z pliku PDF. Wartość fałszywa każe modelowi samodzielnie wyznaczyć komórki i zignorować tekst z pliku. Ta druga opcja ratuje sytuację w tabelach, w których komórki źródłowe są scalone w poprzek kolumn i dopasowanie psuje wynik.

Ograniczenia max_num_pages oraz max_file_size przekazuje się do metody convert, nie do opcji potoku. Ten sam zestaw parametrów przyjmuje convert_all, więc limity ustawia się raz, w miejscu wywołania, a nie w konfiguracji konwertera. Warto o tym pamiętać, bo szukanie tych pól w modelu opcji kończy się bezowocnym przeglądaniem dokumentacji.

Pola generate_page_images oraz images_scale sterują tym, czy obrazy stron zostaną zachowane w wyniku i w jakiej skali. Podniesienie skali poprawia jakość rozpoznawania drobnego druku, ale rośnie razem z nią zużycie pamięci, i to szybciej niż liniowo, bo skala dotyczy obu wymiarów obrazu. Przy przetwarzaniu równoległym to najczęstsza przyczyna wyczerpania pamięci na maszynie roboczej.

DoclingDocument i dzielenie na fragmenty

Eksport do Markdown jest wygodny do podglądu, ale do budowy indeksu lepiej pracować na strukturze. Docling dostarcza dzielniki, które tną dokument po hierarchii nagłówków, a nie po liczbie znaków.

from docling.chunking import HybridChunker
from docling.document_converter import DocumentConverter

converter = DocumentConverter()
doc = converter.convert("raport.pdf").document

chunker = HybridChunker(
    tokenizer="sentence-transformers/all-MiniLM-L6-v2",
    max_tokens=512,
    merge_peers=True,
)

for chunk in chunker.chunk(dl_doc=doc):
    tekst_do_osadzenia = chunker.contextualize(chunk=chunk)
    zrodla = [
        (item.prov[0].page_no if item.prov else None)
        for item in chunk.meta.doc_items
    ]
    print(len(tekst_do_osadzenia), zrodla)

Różnica między HierarchicalChunker a HybridChunker jest istotna. Pierwszy tnie dokument po strukturze i nie patrzy na długość. Drugi dokłada świadomość tokenizatora: dzieli fragmenty przekraczające limit i scala sąsiadujące fragmenty zbyt małe, jeśli mają te same metadane, o ile merge_peers pozostaje włączone.

Metoda contextualize jest najbardziej niedocenianym elementem tego interfejsu. Zwraca treść fragmentu poprzedzoną ścieżką nagłówków, w której fragment się znajduje. Dzięki temu akapit zaczynający się od słów „W drugim kwartale wynik był niższy" trafia do osadzenia razem z informacją, że pochodzi z rozdziału o segmencie chmurowym. To zwykle daje większą poprawę trafności wyszukiwania niż zmiana modelu osadzeń.

Pole meta.doc_items przechowuje odniesienia do elementów źródłowych wraz z informacją o stronie, z której pochodzą. To materiał na przypisy w odpowiedzi, czyli mechanizm, który pozwala użytkownikowi sprawdzić źródło. Gotowe adaptery do LlamaIndex i LangChain korzystają dokładnie z tych struktur, a wynik wkładasz do dowolnej bazy wektorowej, choćby do Chroma.

Praca wsadowa, tryb offline i wydajność

Przy większej liczbie plików liczą się dwie rzeczy: żeby jeden zepsuty dokument nie zatrzymał całości i żeby modele nie musiały być pobierane na maszynie bez dostępu do internetu.

# pobranie wag modeli do wskazanego katalogu, do użycia bez sieci
docling-tools models download layout tableformer code_formula --output-dir ./modele

from pathlib import Path

from docling.datamodel.base_models import ConversionStatus, InputFormat
from docling.datamodel.pipeline_options import PdfPipelineOptions
from docling.document_converter import DocumentConverter, PdfFormatOption

pipeline_options = PdfPipelineOptions()
pipeline_options.artifacts_path = Path("./modele")
pipeline_options.enable_remote_services = False
pipeline_options.document_timeout = 90.0

converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)
    },
)

pliki = sorted(Path("./dokumenty").glob("*.pdf"))
udane, czesciowe, bledne = 0, 0, 0

for result in converter.convert_all(pliki, raises_on_error=False):
    if result.status == ConversionStatus.SUCCESS:
        udane += 1
        Path(f"./wynik/{result.input.file.stem}.md").write_text(
            result.document.export_to_markdown(), encoding="utf-8"
        )
    elif result.status == ConversionStatus.PARTIAL_SUCCESS:
        czesciowe += 1
    else:
        bledne += 1

print(udane, czesciowe, bledne)

Parametr raises_on_error=False zmienia zachowanie zasadniczo: zamiast wyjątku przy pierwszym niepowodzeniu dostajesz obiekt wyniku ze statusem. Wartości statusu to pending, started, success, partial_success, failure i skipped. Status częściowego powodzenia jest tym, który najłatwiej przeoczyć, bo dokument istnieje i wygląda sensownie, choć część stron się nie przetworzyła.

Ustawienie artifacts_path wskazuje katalog z wcześniej pobranymi wagami, a enable_remote_services pozostawione na wartości fałszywej gwarantuje, że żaden etap nie wyśle danych na zewnątrz. To jest właśnie ta przewaga, dla której wiele zespołów sięga po Docling zamiast po usługę chmurową: dokumenty kadrowe, umowy i dokumentacja medyczna nie opuszczają Twojej infrastruktury, bo modele liczą się na miejscu.

Cena tej przewagi jest realna i trzeba ją wypowiedzieć wprost. Przetwarzanie jest wolniejsze niż zwykłe wyciągnięcie tekstu, bo na każdej stronie uruchamiane są modele sieci neuronowych. Zużycie pamięci rośnie razem z rozdzielczością obrazów stron. Na procesorze konwersja dokumentu o kilkuset stronach z włączonym OCR potrafi trwać kilkadziesiąt minut. Jeśli przetwarzasz strony internetowe, a nie dokumenty biurowe, tańszym narzędziem będzie Firecrawl, który do HTML nie potrzebuje modeli wizualnych.

Docling a alternatywy

Wybór jest w gruncie rzeczy rozstrzygnięciem trzech pytań. Czy dokumenty mogą opuścić Twoją sieć? Jeśli nie, usługi chmurowe odpadają niezależnie od jakości. Czy zależy Ci na tabelach i kolejności czytania, czy wystarczy surowy tekst? Jeśli wystarczy tekst z prostych plików, PyMuPDF zrobi to setki razy szybciej, tylko pamiętaj o jego licencji AGPL 3.0 albo o wykupieniu wariantu komercyjnego. Czy zakres formatów wykracza poza PDF? Tu Docling i Unstructured mają wyraźną przewagę nad narzędziami wyspecjalizowanymi w jednym formacie.

Typowe błędy

Pierwszy to pozostawienie domyślnej konfiguracji przy dużym wolumenie. Domyślnie włączone są OCR i pełne odtwarzanie tabel w trybie dokładnym. Dla korpusu złożonego z plików generowanych cyfrowo, w których warstwa tekstowa jest poprawna, wyłączenie do_ocr skraca czas przetwarzania wielokrotnie i niczego nie psuje. Zanim zaczniesz stroić cokolwiek innego, sprawdź na próbce kilkudziesięciu plików, ile z nich w ogóle wymaga rozpoznawania znaków, i rozdziel korpus na dwie kolejki z osobnymi ustawieniami.

Drugi to brak limitu czasu. Bez ustawionego document_timeout jeden plik z tysiącem drobnych obrazów potrafi zablokować proces roboczy na bardzo długo, a w kolejce zadań objawia się to jako zatrzymanie bez żadnego komunikatu o błędzie. W przetwarzaniu wsadowym limit czasu i raises_on_error=False powinny być ustawione od pierwszego dnia, razem z zapisem listy plików, które limit przekroczyły.

Trzeci to traktowanie eksportu do Markdown jako jedynego wyjścia. Markdown gubi położenie elementów na stronie, więc odtworzenie przypisów wskazujących numer strony przestaje być możliwe. Jeśli planujesz cytowanie źródeł, zachowaj obiekt DoclingDocument albo wynik export_to_dict, a Markdown generuj z niego dopiero na końcu, kiedy struktura została już zapisana w trwałej postaci.

Czwarty to dzielenie tekstu po liczbie znaków zaraz po konwersji. Skoro Docling odtworzył hierarchię dokumentu, cięcie co tysiąc znaków wyrzuca tę pracę do kosza i sprowadza całe narzędzie do roli zwykłego czytnika PDF. Użyj HybridChunker i pamiętaj o contextualize, bo bez tej metody fragment traci ścieżkę nagłówków.

Piąty to instalacja bez potrzebnego dodatku. Metapakiet ciągnie wariant standardowy, a silniki OCR i modele wizualne siedzą w dodatkach, między innymi easyocr, rapidocr, tesserocr i vlm. Wywołanie --pipeline vlm bez odpowiedniego dodatku skończy się błędem importu, a nie czytelnym komunikatem o brakującej zależności.

Szósty to założenie, że skoro kod jest na licencji MIT, to całość wdrożenia też. Wagi modeli mają własne warunki i przy zastosowaniu komercyjnym trzeba przejść je pojedynczo. To najczęstsze przeoczenie w audytach zgodności dotyczących narzędzi tej klasy.

Siódmy to pominięcie statusu częściowego powodzenia. Kod sprawdzający wyłącznie równość ze statusem niepowodzenia przepuści dokumenty przetworzone w połowie, które później zasilą indeks dziurawą treścią.

FAQ

Czy Docling wysyła dokumenty do chmury?

Nie, jeśli sam tego nie włączysz. Modele rozpoznawania układu, tabel i OCR działają lokalnie, a pole enable_remote_services pozostawione na wartości fałszywej blokuje etapy sięgające do usług zewnętrznych. Wagi można pobrać wcześniej poleceniem docling-tools models download i wskazać katalog przez artifacts_path, co pozwala pracować w sieci odciętej od internetu.

Jak szybki jest Docling w porównaniu ze zwykłym czytnikiem PDF?

Wyraźnie wolniejszy i tak musi być, bo na każdej stronie uruchamia modele sieci neuronowych. Biblioteka wyciągająca sam strumień tekstu jest o rzędy wielkości szybsza, tylko zwraca zawartość w kolejności zapisu, bez struktury tabel. Największe oszczędności czasu daje wyłączenie do_ocr dla dokumentów cyfrowych i tryb TableFormerMode.FAST dla prostych tabel. Kolejne w kolejności są ograniczenie zakresu stron oraz rezygnacja z zachowywania obrazów stron w wyniku konwersji.

Czy licencja MIT obejmuje też modele?

Nie. Licencja MIT dotyczy kodu Doclinga. Wagi modeli rozpoznawania układu, TableFormer, silników OCR i modeli wizualnych mają własne warunki, opisane przy odpowiednich pakietach i repozytoriach. Przy wdrożeniu komercyjnym trzeba sprawdzić każdy używany model osobno.

Dlaczego paczka docling nie zawiera pliku licencyjnego?

Bo od pewnego wydania jest metapakietem. Archiwum docling-2.121.0-py3-none-any.whl ma 5177 bajtów i zawiera wyłącznie metadane, bez kodu i bez pliku licencyjnego, a jego jedyną zależnością obowiązkową jest docling-slim[standard]==2.121.0. To właśnie docling-slim niesie kod oraz plik LICENSE z tekstem MIT.

Czy Docling zastępuje bazę wektorową albo szkielet aplikacji?

Nie. Docling kończy pracę na strukturze dokumentu i podziale na fragmenty. Osadzenia, indeks i logikę wyszukiwania budujesz osobno, na przykład na LlamaIndex albo LangChain, a fragmenty przechowujesz w wybranej bazie wektorowej.

Kiedy nie warto po niego sięgać?

Kiedy dokumenty są proste i cyfrowe, a liczy się przepustowość. Kiedy źródłem są strony internetowe, bo do HTML modele wizualne są zbędne. Kiedy nie masz zasobów obliczeniowych na przetwarzanie wsadowe, a wolno Ci wysyłać pliki na zewnątrz. W tych trzech przypadkach prostsze albo chmurowe narzędzie da lepszy stosunek kosztu do efektu.

Dokumentację znajdziesz na stronie projektu, kod źródłowy w repozytorium na GitHubie, a opis działania modeli w raporcie technicznym.