Docling: PDF, OCR и документы для RAG и ИИ-агентов

Docling превращает PDF, сканы и офисные документы в данные, с которыми может работать ИИ. Он извлекает текст и таблицы, сохраняет заголовки и порядок чтения. Результат можно использовать для поиска по документам, базы знаний или ИИ-агента. Библиотека написана на Python, появилась в IBM Research Zurich и развивается в LF AI & Data Foundation.

Представьте папку с инструкциями, отчётами и презентациями. Чтобы агент отвечал по этим файлам, сначала нужно извлечь их содержимое. В сложном PDF текст разбит на колонки, числа спрятаны в таблицах, а подпись стоит под рисунком. Docling разбирает эти части и собирает документ в понятном порядке.

Docling готовит документы для RAG: поиска, при котором ИИ сначала находит подходящие фрагменты, а затем отвечает по ним. Сам поиск, хранение данных и генерацию ответа подключают отдельно.

Включайте обработку под свои документы. Для договоров обычно нужны текст и таблицы. Для научных статей пригодятся формулы и рисунки. Дополнительные модели требуют больше времени и памяти.

Docling читает PDF, Word, презентации, таблицы, изображения, почту и записи. Для части форматов нужны дополнительные пакеты или программы. Например, старые DOC, XLS и PPT обрабатываются через LibreOffice.

Markdown удобно открыть и прочитать. JSON подходит для приложения: в нём остаются отдельные элементы документа и связи между ними. Если строите базу знаний, сохраняйте оба файла.

В Python документ передают в DocumentConverter. Он выбирает способ обработки для нужного формата и возвращает результат. Внутри находится DoclingDocument: из него получают Markdown, JSON, таблицы и фрагменты для поиска.

DoclingDocument хранит текст, таблицы, рисунки и вложенные разделы. Колонтитулы отделены от основного текста. Когда исходный формат это позволяет, у элементов остаются номер страницы и координаты. Модель построена на Pydantic, поэтому с ней удобно работать в Python.

1. Файл или ссылка: Docling определяет формат.
2. Обработка: извлекает текст, таблицы и структуру.
3. Результат: сохраняет данные или разбивает их на фрагменты.
4. Поиск: ваше приложение находит нужный фрагмент и показывает источник.

Привязка к странице помогает показать источник ответа. Пользователь может открыть документ и найти место, из которого агент взял цитату. Набор таких данных зависит от формата файла.

Docling пригодится там, где нужно искать информацию в документах или передавать её ИИ. Вот несколько рабочих задач.

База знаний для сотрудников

Соберите инструкции и регламенты в базу знаний для сотрудников. Docling извлечёт содержимое, а система поиска найдёт нужный фрагмент. Сохраняйте версию документа: после обновления инструкции старые ответы не должны оставаться в базе.

Документы с таблицами и показателями

Извлеките таблицы из отчётов и прайс-листов, чтобы передать их в аналитику или другой сервис. При этом важно сохранить связь числа с названием строки, периодом и единицей измерения.

Технические статьи и исследования

В технических статьях важны разделы, формулы и подписи к рисункам. Docling помогает сохранить эту структуру для поиска по содержимому статьи.

Агент с доступом к новым файлам

Агент может получить новый файл и вызвать Docling через MCP. Например, разобрать присланную инструкцию или подготовить краткий отчёт по документу.

Для Docling нужен Python 3.10 или новее. Библиотека работает на Windows, Linux и macOS. Начните с отдельного виртуального окружения, чтобы её пакеты не смешивались с другими проектами.

python -m venv .venv

# Linux / macOS
source .venv/bin/activate

# Windows PowerShell: вместо команды выше
# .\.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install docling

docling --help

При первом запуске Docling скачивает нужные модели. Поэтому первая обработка может занять больше времени. После загрузки модели остаются на диске.

Через командную строку можно быстро получить Markdown или JSON из своего PDF. Вторая команда ниже обрабатывает сразу папку документов и складывает результат в выбранный каталог.

docling ./report.pdf --to md --to json --output ./converted

# Несколько документов из каталога
docling ./corpus --to md --output ./converted

При обработке папки следите за ошибками: отдельный файл может не пройти конвертацию. Журнал заданий поможет найти такие документы и запустить их повторно.

Команды установки и конвертации работают из подготовленного окружения. В Windows PowerShell для HTTP-запросов используйте curl.exe, если curl занят алиасом. Примеры Python сохраните в файлы .py.

В этом примере PDF разбирается один раз. Затем программа сохраняет текст в Markdown и структуру документа в JSON. Вместо локального пути DocumentConverter также принимает поддерживаемый URL.

import json
from pathlib import Path

from docling.document_converter import DocumentConverter

source = Path("report.pdf")
output = Path("converted")
output.mkdir(parents=True, exist_ok=True)

result = DocumentConverter().convert(source)
document = result.document

(output / "report.md").write_text(
    document.export_to_markdown(),
    encoding="utf-8",
)
(output / "report.json").write_text(
    json.dumps(document.export_to_dict(), ensure_ascii=False, indent=2),
    encoding="utf-8",
)

print(f"Результат сохранён в {output.resolve()}")

Файлы report.md и report.json появятся в папке converted. Для обработки нескольких документов задайте каждому свой выходной путь.

OCR распознаёт текст на сканах и фотографиях. В Docling можно выбрать RapidOCR, EasyOCR, Tesseract CLI, tesserocr, ocrmac или Nemotron-OCR. Язык указывают в формате выбранного движка либо через тег с префиксом iso:.

Пример ниже распознаёт русский и английский текст через Tesseract CLI. Сначала установите Tesseract, добавьте его в PATH и загрузите языковые файлы rus и eng.

from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import (
    OcrMode,
    PdfPipelineOptions,
    TableStructureOptions,
    TesseractCliOcrOptions,
)
from docling.document_converter import DocumentConverter, PdfFormatOption

options = PdfPipelineOptions()
options.do_ocr = True
options.do_table_structure = True
options.table_structure_options = TableStructureOptions(do_cell_matching=True)
options.ocr_options = TesseractCliOcrOptions(
    lang=["rus", "eng"],
    mode=OcrMode.FULL_PAGE,
)

converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(pipeline_options=options)
    }
)
document = converter.convert("scan.pdf").document
print(document.export_to_markdown())

Docling хранит найденные таблицы в document.tables. Каждую можно превратить в pandas DataFrame и сохранить в CSV. Для примера установите pandas в то же окружение.

python -m pip install pandas

from pathlib import Path

from docling.document_converter import DocumentConverter

target = Path("tables")
target.mkdir(parents=True, exist_ok=True)
document = DocumentConverter().convert("report.pdf").document

for number, table in enumerate(document.tables, start=1):
    frame = table.export_to_dataframe(doc=document)
    frame.to_csv(
        target / f"table-{number}.csv",
        index=False,
        encoding="utf-8-sig",
    )

print(f"Найдено таблиц: {len(document.tables)}")

Каждая таблица сохранится в отдельный CSV. Перед загрузкой в учётную систему проверьте объединённые ячейки, заголовки, единицы измерения и числа. Ошибка распознавания одного знака может изменить сумму.

DocumentExtractor извлекает отдельные поля по заданной схеме. Например, номер счёта и итоговую сумму. Схему можно описать словарём или Pydantic-моделью. Этот способ работает с PDF и изображениями; данные возвращаются отдельно для каждой страницы.

Вместо полного текста приложение получает нужные значения. Для примера ниже установите поддержку VLM, моделей, которые читают изображение документа.

python -m pip install "docling[vlm]"

from pydantic import BaseModel

from docling.datamodel.base_models import InputFormat
from docling.document_extractor import DocumentExtractor


class InvoiceFields(BaseModel):
    invoice_number: str | None = None
    total: float | None = None


extractor = DocumentExtractor(
    allowed_formats=[InputFormat.PDF, InputFormat.IMAGE]
)
result = extractor.extract(source="invoice.pdf", template=InvoiceFields)

for page in result.pages:
    if page.errors:
        print(f"Страница {page.page_no}: {page.errors}")
        continue
    fields = InvoiceFields.model_validate(page.extracted_data)
    print(fields.model_dump_json(indent=2))

В примере отсутствующее поле получает значение null. Проверка Pydantic проверяет типы данных. Суммы и реквизиты перед загрузкой в рабочую систему нужно сверить с документом.

Для RAG большой документ разбивают на небольшие фрагменты, чанки. HybridChunker учитывает заголовки, таблицы и размер текста. Слишком большие части разделяет, а маленькие соседние части с одинаковым контекстом может объединить. Метод contextualize() добавляет к фрагменту доступный контекст, например заголовок раздела.

import json
from pathlib import Path

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

document = DocumentConverter().convert("handbook.pdf").document
chunker = HybridChunker()

with Path("chunks.jsonl").open("w", encoding="utf-8") as output:
    for number, chunk in enumerate(chunker.chunk(dl_doc=document)):
        record = {
            "id": f"handbook-{number}",
            "text": chunker.contextualize(chunk=chunk),
            "metadata": chunk.meta.model_dump(mode="json"),
        }
        output.write(json.dumps(record, ensure_ascii=False) + "\n")

Результат сохраняется в chunks.jsonl. Затем из фрагментов создают эмбеддинги, числовые представления для смыслового поиска, и загружают их в хранилище. В рабочем проекте согласуйте размер фрагмента и токенизатор с моделью эмбеддингов.

Если таблица занимает несколько фрагментов, HybridChunker умеет повторять её заголовок в каждом. Так название колонки остаётся рядом с числами. Для широких таблиц можно настроить поведение при превышении лимита токенов.

Docling Serve запускает Docling как отдельный HTTP-сервис. К нему может обращаться сайт, бот или приложение на любом языке. Веб-интерфейс позволяет загрузить файл вручную, а REST API подходит для автоматической обработки.

python -m pip install docling-serve
docling-serve run --enable-ui

После запуска откройте http://localhost:5001/ui для загрузки файла или http://localhost:5001/docs для просмотра API. Сервис также можно запустить в Docker. В примере контейнер доступен только с этой машины.

docker run --rm -p 127.0.0.1:5001:5001 \
  -e DOCLING_SERVE_ENABLE_UI=1 \
  quay.io/docling-project/docling-serve

curl --request POST http://localhost:5001/v1/convert/file \
  --form 'files=@report.pdf;type=application/pdf' \
  --form 'to_formats=md' \
  --form 'do_ocr=true'

Для длинных документов есть асинхронные запросы: сервис принимает задание, а приложение получает статус и готовый результат позже. Если сервер защищён через DOCLING_SERVE_API_KEY, передавайте ключ в заголовке X-Api-Key. Полный список параметров доступен в /docs.

Docling подключается к LangChain, LlamaIndex, Haystack, CrewAI и другим инструментам для ИИ. Он подготавливает документы, а выбранный фреймворк отвечает за поиск и работу с моделью.

В Open WebUI Docling можно выбрать как обработчик загружаемых файлов. После этого документы будут проходить через Docling Serve перед добавлением в базу знаний.

Подключение Docling к Open WebUI

1. Запустите Docling Serve и сначала проверьте загрузку своего файла в его интерфейсе /ui.
2. В Open WebUI откройте Settings → Admin Settings → Documents и выберите Docling в Default content extraction engine.
3. Укажите Docling Server URL. Для приложений на одной машине без контейнеров: http://localhost:5001. Для Docker адрес должен быть доступен из контейнера Open WebUI: имя сервиса в общей сети либо доступный адрес хоста.
4. При защищённом Docling Serve задайте соответствующий API Key, сохраните настройки и загрузите документ в базу знаний Open WebUI.

Внутри Docker адрес localhost указывает на сам контейнер. Для связи Open WebUI с Docling Serve используйте имя сервиса в общей сети или доступный адрес хоста.

1. Сначала проверить извлечение на типичных документах без чат-интерфейса.
2. Подключить обработчик к выбранному RAG-фреймворку или интерфейсу.
3. Сохранить происхождение, версию документа и ограничения доступа в метаданных.
4. Проверить поиск и ответы по таблицам, сканам и обновлённым документам.

MCP позволяет ИИ-агенту вызывать Docling как инструмент: передать документ и получить его содержимое. Для обработки на своей машине установите docling-mcp[local] и выберите DOCLING_MCP_CONVERSION_MODE=local. Ниже показана готовая конфигурация.

{
  "mcpServers": {
    "docling": {
      "command": "uvx",
      "args": [
        "--from",
        "docling-mcp[local]",
        "docling-mcp-server"
      ],
      "env": {
        "DOCLING_MCP_CONVERSION_MODE": "local"
      }
    }
  }
}

Для команды из примера нужен uvx. Добавьте блок docling в настройки MCP вашего клиента. Если хотите использовать отдельный сервер, задайте адрес сервиса и ключ доступа.

Агенту нужен доступ к файлам, которые он обрабатывает. Выберите нужные папки и настройте права в своём приложении.

VLM читает изображение страницы. Такой способ обработки подходит для документов, где важен внешний вид: расположение текста, формул и рисунков. Docling поддерживает Granite Docling и другие визуальные модели.

docling ./technical-paper.pdf --pipeline vlm \
  --vlm-model granite_docling --to md --output ./converted

Дополнительная обработка умеет распознавать формулы в LaTeX, разбирать блоки кода, классифицировать рисунки и создавать их описания. Нужные функции включаются отдельно.

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

options = PdfPipelineOptions()
options.do_code_enrichment = True
options.do_formula_enrichment = True

converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(pipeline_options=options)
    }
)
document = converter.convert("technical-paper.pdf").document
print(document.export_to_markdown())

VLM и обработка рисунков расходуют больше ресурсов. Начните со стандартного режима и подключайте их для страниц, с которыми он не справляется.

Диаграммы и графики

Docling умеет обрабатывать столбчатые, круговые и линейные диаграммы: представлять их в виде таблиц или кода и добавлять описания.

Docling расшифровывает аудио и видео в текст. Для видео также выбирает кадры и может разделять реплики по говорящим. Для обработки нужен FFmpeg, установленный в системе и доступный через PATH.

# Транскрибация аудио
python -m pip install "docling[asr]"

# Отдельный extra для видеоконвейера, кадров и диаризации
python -m pip install "docling-slim[format-video]"

Кадры можно брать через заданный интервал или при смене сцены. Они сохраняются вместе с расшифровкой в DoclingDocument. Разделение говорящих включается отдельно.

Записи обучения и встреч можно добавить в ту же базу знаний, что и документы. Сохраняйте время каждого фрагмента: по найденной цитате будет проще открыть нужное место записи.

Docling запускается на своей машине, в Python-приложении или как отдельный сервис. Для управляемого и частного развёртывания есть варианты через IBM watsonx.

Для работы без интернета заранее скачайте нужные модели. Затем укажите папку через artifacts-path или переменную DOCLING_ARTIFACTS_PATH. Для OCR, видео и VLM подготовьте также их зависимости.

docling-tools models download

# Укажите каталог, в который скачаны нужные модели
docling ./report.pdf --artifacts-path ./models --to md

Если выбран удалённый OCR или внешний сервис описания изображений, данные отправляются этому сервису. Для такого подключения нужно enable_remote_services=True. При локальной обработке модели работают на вашем оборудовании.

Что измерять перед внедрением

• Время первого запуска отдельно от обработки после загрузки моделей.
• Скорость на своих типах файлов: текстовый PDF, скан, презентация, таблицы.
• Пиковое потребление RAM и, если используется ускоритель, VRAM.
• Количество неудачных или частичных конвертаций при пакетной загрузке.
• Качество чтения и таблиц при выбранных OCR и enrichment-настройках.

Потребление памяти и скорость зависят от документов и выбранных моделей. Для большого архива настройте очередь: она позволит ограничить одновременную обработку и повторять неудачные задания.

Код Docling распространяется по MIT. У моделей и дополнительных пакетов могут быть собственные лицензии. Учитывайте их, если используете Docling в коммерческом проекте.

На сложных сканах возможны ошибки: перепутанные буквы, потерянные строки таблицы, неверный порядок текста. Особенно внимательно проверяйте документы с числами и реквизитами.

Docling подходит для базы знаний из разных файлов, обработки сканов и извлечения таблиц. Его удобно встроить в Python-приложение или подключить как сервис к сайту и ИИ-агенту.

Если работаете со сложными PDF, посмотрите также MinerU. Он извлекает содержимое документов в Markdown и JSON для ИИ. Для чистых PDF без таблиц и сканов бывает достаточно более простого извлечения текста.

1. Отберите 15–30 типичных файлов, включая неудобные примеры.
2. Опишите ожидаемые результаты: порядок текста, таблицы, источник фрагмента.
3. Проверьте стандартный конвейер, затем добавляйте OCR и enrichments по необходимости.
4. Сравните качество, время и ресурсы с альтернативой на одном наборе.
5. Зафиксируйте версии и настройки, затем подключайте индексацию и агента.

Начните с небольшой папки своих документов. Если текст, таблицы и источники сохраняются как нужно, подключайте поиск и агента.

• Docling на GitHub
• Официальный сайт Docling
• Документация Docling
• Документация Open WebUI