Docling превращает PDF, офисные документы, веб-страницы, изображения и другие файлы в структурированный материал: распознаёт текст на сканах, восстанавливает порядок чтения, выделяет заголовки, списки, таблицы, формулы, код и рисунки, а затем сохраняет результат в Markdown, HTML, обычный текст, JSON или формат фрагментов для поисковых и RAG-систем. Работу можно выполнить одной командой, настроить через Python API или вынести в очередь Docling Serve, выбирая OCR-движок, точность разбора таблиц, способ сохранения изображений и ограничения по размеру документа.

Базовый рабочий процесс строится вокруг конвертера: ему передают путь к одному файлу, папке или допустимому удалённому документу, после чего конвейер выбирает обработчик формата, извлекает содержимое и собирает единый объект DoclingDocument. Вместо плоской строки пользователь получает дерево элементов с привязкой к страницам и координатам, поэтому заголовки остаются заголовками, ячейки — ячейками, а подписи и изображения можно обрабатывать отдельно. Для быстрой проверки достаточно вывести Markdown, а для последующей программной обработки целесообразно сохранить JSON без потери структуры.

Главные настройки находятся не в привычной панели PDF-редактора, а в параметрах команды и объектах конфигурации. Они определяют, запускать ли OCR, какой движок использовать, включать ли распознавание таблиц и формул, применять ли визуально-языковую модель, куда записывать результаты и модели, как поступать с ошибками в пакетной задаче и сколько ресурсов разрешено занять. Такой подход требует аккуратной первоначальной настройки, зато один проверенный профиль затем одинаково обрабатывает сотни документов и выдаёт предсказуемую структуру для хранилища, поиска, аналитики или генеративного ИИ.

Как устроена обработка документов

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

Обработка не сводится к одному универсальному алгоритму. Для PDF применяется специализированный конвейер с анализом макета и структуры таблиц; для DOCX, PPTX, XLSX, HTML, EPUB, Markdown и других форматов используются соответствующие обработчики. Изображения проходят через распознавание, а аудио и видео требуют отдельного набора зависимостей для расшифровки речи. Все ветви сходятся в DoclingDocument, поэтому следующий этап программы не обязан знать, из какого исходного формата пришёл текст. Это особенно удобно в смешанной коллекции, где рядом лежат отчёты PDF, презентации, электронные письма и таблицы.

Результат конвертации представлен объектом ConversionResult. Успешный результат содержит документ и служебные сведения о ходе преобразования; при пакетной обработке статус нужно проверять до обращения к содержимому. Такой контроль важен для повреждённых, защищённых или слишком больших файлов: задача может вернуть неполный результат либо ошибку, и без проверки программа запишет пустой Markdown как будто это нормальный документ. Практичный сценарий сохраняет исходное имя, статус, время обработки и диагностическое сообщение в отдельный журнал.

Что происходит с PDF по шагам

1. Открывается файл или поток и проверяется, может ли выбранный обработчик прочитать его страницы.
2. Из текстового слоя извлекаются символы и геометрия; для сканов либо заданных областей запускается OCR.
3. Модель макета находит текстовые блоки, заголовки, списки, таблицы, рисунки, подписи, формулы и другие типы областей.
4. Модель таблиц восстанавливает строки, столбцы, объединённые ячейки и сопоставляет предсказанные ячейки с текстом страницы.
5. Постобработка определяет порядок чтения, связывает подписи и изображения, формирует группы и иерархию разделов.
6. Сериализатор превращает DoclingDocument в выбранное представление, не изменяя исходный PDF.

Последний пункт принципиален: Docling извлекает и преобразует содержимое, но не предназначен для ручного исправления исходной страницы, перемещения текста мышью, удаления листов, добавления подписи или сохранения правок обратно в тот же PDF. Исправления выполняют в полученном Markdown, HTML или структурированном JSON либо передают исходник в PDF-редактор. Благодаря этому граница рабочего процесса ясна: Docling отвечает за машинно-читаемую структуру, а визуальное редактирование и верстка остаются задачей других инструментов.

Установка и первая проверка

Для запуска нужен Python 3.10 или новее. На Windows, Linux и macOS удобнее создать отдельное виртуальное окружение, чтобы версии PyTorch, OCR-библиотек и вспомогательных пакетов не конфликтовали с другими проектами. После активации окружения устанавливают пакет Docling, затем вызывают справку команды. Если оболочка не находит команду, обычно пакет попал в другой интерпретатор: следует сравнить пути, которые показывают команды python и pip, либо запускать установку как модуль выбранного Python.

python -m venv .venv
# Активируйте окружение способом вашей оболочки
python -m pip install --upgrade pip
python -m pip install docling
docling --help

Первая обработка PDF может занять заметно больше времени, чем последующие: необходимые модели загружаются в пользовательский кэш. Это нормальное поведение, а не зависание установщика. В корпоративной сети загрузку иногда блокирует прокси или проверка сертификатов; тогда модели заранее получают на машине с доступом к сети и указывают каталог через параметр artifacts_path либо переменную DOCLING_ARTIFACTS_PATH. Для воспроизводимой среды полезно сохранить перечень установленных пакетов и отдельно зафиксировать набор моделей, иначе два сервера могут дать немного различающийся результат после обновления весов.

Минимальная проверка должна использовать небольшой локальный PDF с обычным текстовым слоем. Так легче отделить проблемы установки от сложностей OCR. Команда по умолчанию формирует Markdown в текущем каталоге; параметр вывода лучше задавать явно, чтобы результат не потерялся среди исходников. После выполнения проверьте не только наличие файла, но и порядок заголовков, таблиц и абзацев. Успешное завершение процесса ещё не гарантирует, что конкретная сложная верстка разобрана без ошибок.

mkdir result
docling convert sample.pdf --to md --output result
docling convert sample.pdf --to json --output result

В некоторых инструкциях встречается короткая форма без подкоманды convert. При автоматизации лучше использовать синтаксис, который показывает установленная команда docling --help, поскольку интерфейс командной строки развивается. Скрипт развёртывания должен проверять код возврата и не считать предупреждения о модели безусловной ошибкой. Одновременно следует избегать молчаливого обновления всех зависимостей на рабочем сервере: особенно чувствительны сочетания Python, PyTorch, драйвера GPU и дополнительных OCR-пакетов.

Особенности установки на разных системах

На машине без совместимого GPU имеет смысл использовать сборку PyTorch для CPU, чтобы не подтягивать лишние компоненты ускорения. На Intel Mac совместимость ограничивает доступные сборки PyTorch, поэтому перед установкой проверяют версию Python и рекомендованную комбинацию зависимостей. На Apple Silicon доступно ускорение MPS, но не каждый оператор и не каждая модель одинаково эффективно выполняются на нём; при нестабильности временно переключаются на CPU. На NVIDIA требуется не просто установленный драйвер, а согласованная сборка PyTorch с нужной версией CUDA.

Дополнительные возможности подключаются extras-наборами. ASR нужен для аудио и видео, VLM — для визуально-языковых конвейеров, EasyOCR, RapidOCR, tesserocr и ocrmac — для соответствующих движков, htmlrender — для рендеринга страниц HTML, XBRL — для специализированной обработки финансовой разметки. Не стоит устанавливать все extras без необходимости: окружение станет тяжелее, увеличится число нативных библиотек и вероятность конфликта. Надёжнее начать с базового профиля, затем добавить один требуемый движок и провести контрольный прогон.

Командная строка и пакетная конвертация

Интерфейс командной строки подходит для разовых преобразований, задач планировщика и конвейеров сборки данных. На вход можно передать файл, каталог или поддерживаемый адрес документа. Для каталога параметр from ограничивает допустимые расширения, а повторяемый параметр to создаёт несколько представлений за один проход. Это экономит время: анализ макета и OCR не нужно выполнять отдельно ради Markdown и JSON. Каталог вывода следует отделять от входного, иначе следующий пакетный запуск может попытаться обработать уже созданные файлы.

docling convert incoming --from pdf --from docx   --to md --to json --output converted

Параметр abort-on-error полезен в проверочных заданиях, где любой сбой делает весь набор непригодным. Для длительной миграции фонда чаще выгоднее продолжить обработку остальных документов и собрать список неудач. Выбор зависит от смысла результата: при подготовке юридического комплекта пропущенный файл критичен, а при индексации миллионного фонда разумнее изолировать несколько повреждённых объектов. В обоих случаях лог должен содержать имя исходника, статус, длительность и путь к результату.

Уровень подробности регулируется флагами verbose. Обычный информационный журнал показывает этапы и загрузку моделей; отладочный помогает выяснить, на каком обработчике или шаге возникла ошибка. Постоянно хранить максимально подробный вывод в производственной задаче невыгодно: журнал быстро растёт и может содержать имена файлов или фрагменты диагностируемого документа. Практичный профиль пишет краткое событие для каждого файла, а полный журнал включает только при повторном запуске проблемного экземпляра.

Форматы вывода указывают повторением параметра to. Помимо Markdown и JSON доступны HTML, разбитый по страницам HTML, YAML, обычный текст, DocTags, WebVTT, DocLang, пакет DocLang и chunks. Не все варианты равноценны. Markdown удобен человеку и большинству загрузчиков, JSON сохраняет модель без потерь, text подходит для простого полнотекстового индекса, а chunks сразу подготавливает строки JSONL для последующего встраивания. Выбор нескольких форматов не означает, что между ними можно без потерь конвертировать обратно: главным сохранным представлением остаётся DoclingDocument в JSON.

docling convert report.pdf   --to md --to html --to json --to chunks   --chunks-type hybrid --output report-result

При пакетной работе имена файлов могут совпадать после нормализации или находиться в разных подпапках. Перед запуском продумайте правило назначения результата: сохранять структуру каталогов, добавлять идентификатор или использовать отдельную папку на каждый исходник. Иначе два документа report.pdf из разных отделов перезапишут друг друга. Даже если CLI предотвращает часть конфликтов, внешний скрипт должен считать путь результата частью уникального ключа.

Ограничение входных форматов

Параметр from снижает риск случайно обработать служебные файлы, временные копии и предыдущие результаты. Например, каталог с презентациями может содержать эскизы PNG; без фильтра они тоже станут отдельными документами. Для Office-файлов различайте современные DOCX, XLSX, PPTX и старые бинарные DOC, XLS, PPT. Последние требуют LibreOffice, поскольку прямой обработчик рассчитывает на предварительное преобразование. Если LibreOffice отсутствует или недоступен из PATH, ошибка касается не всего Docling, а только этой ветви входа.

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

Поддерживаемые входные документы

Наиболее полно раскрывается обработка PDF: она включает анализ страниц, порядок чтения, таблицы, код, формулы и изображения. DOCX, PPTX и XLSX поступают через обработчики Office Open XML; структура таких файлов обычно чище, чем у PDF, но итог зависит от того, насколько исходный документ использует реальные заголовки, таблицы и текстовые блоки, а не визуальную имитацию. Для ODT, ODS и ODP предусмотрена обработка OpenDocument. Старые DOC, XLS и PPT требуют установленного LibreOffice и поэтому должны тестироваться отдельно.

HTML и XHTML подходят для сохранённых веб-страниц, однако внешний вид страницы может зависеть от скриптов, стилей и ресурсов, которые отсутствуют в локальной копии. Дополнение htmlrender устанавливает зависимости для рендеринга, когда простой разбор разметки не даёт нужного результата. Markdown, AsciiDoc, LaTeX и обычный текст уже несут явную структуру, поэтому задача состоит главным образом в унификации элементов. CSV превращается в табличное содержание, а не в визуальную страницу электронной таблицы.

Изображения PNG, JPEG, TIFF, BMP и WEBP рассматриваются как документы, для которых текст извлекается через OCR и формируется структура страницы. Многостраничный TIFF требует проверки всех кадров. Слишком низкое разрешение, сильное сжатие JPEG, тень у корешка или наклон снижают качество распознавания независимо от движка. Перед массовой обработкой полезно измерить реальное разрешение текста и выбрать тестовые страницы с мелким шрифтом, таблицами и печатями.

Аудиоформаты WAV, MP3, M4A, AAC, OGG и FLAC требуют ASR-зависимостей. Видео MP4, AVI и MOV обрабатывается с извлечением и расшифровкой звуковой дорожки; для этого нужен ffmpeg. Результат также помещается в DoclingDocument, что позволяет затем экспортировать расшифровку или передать её в поиск. Однако качество речи, шум, акценты и разделение говорящих относятся уже к ограничениям модели ASR, а не к PDF-конвейеру.

Специализированные XML-форматы обрабатываются по схеме: DocLang, патентный USPTO XML, журнальный JATS и финансовый XBRL. DocLang поддерживает обычный XML и пакет DCLX с изображениями страниц. JSON, ранее сохранённый из DoclingDocument, можно загрузить обратно без повторного распознавания. Такая загрузка особенно важна, когда нужно экспериментировать с сериализацией и разбиением на фрагменты, не тратя время на повторный анализ исходника.

Как выбрать тестовый набор

• Добавьте PDF с цифровым текстом, двухколоночной версткой и колонтитулами.
• Добавьте скан на русском языке с наклоном, печатью и таблицей.
• Проверьте документ с объединёнными ячейками и многострочными заголовками.
• Включите презентацию с диаграммой, подписью и текстом внутри фигуры.
• Проверьте DOCX, в котором заголовки заданы стилями, и документ с ручным форматированием.
• Добавьте повреждённый либо защищённый PDF, чтобы проверить обработку ошибок.
• Сравните короткий и очень длинный файл, чтобы оценить память и время.

Оценивать следует не только процент распознанных символов. Для поиска важны правильные границы разделов; для таблиц — координаты строк и столбцов; для RAG — отсутствие смешивания колонтитулов с основным текстом; для хранилища — стабильность имён и возможность восстановить происхождение каждого элемента. Один и тот же результат может быть приемлем для полнотекстового поиска и непригоден для автоматического извлечения чисел.

Python API: минимальный и надёжный сценарий

Главной точкой входа служит DocumentConverter. Метод convert принимает входной объект и возвращает ConversionResult, внутри которого находится DoclingDocument. Минимальный пример умещается в несколько строк, однако производственный код должен проверить статус, перехватить исключение, ограничить вход и сохранить результат атомарно. Сначала лучше писать во временный файл, а после успешной сериализации переименовывать его: тогда внезапное завершение не оставит полупустой JSON с окончательным именем.

from pathlib import Path
from docling.document_converter import DocumentConverter

source = Path("report.pdf")
target = Path("report.md")

converter = DocumentConverter()
result = converter.convert(source)
markdown = result.document.export_to_markdown()

temp = target.with_suffix(".md.tmp")
temp.write_text(markdown, encoding="utf-8")
temp.replace(target)

Один экземпляр конвертера разумно переиспользовать для серии документов с одинаковой конфигурацией. Создание нового объекта на каждый файл может повторно инициализировать тяжёлые компоненты. При этом не следует без проверки разделять один экземпляр между потоками: потокобезопасность зависит от выбранных моделей и обработчиков. Для параллелизма обычно надёжнее несколько рабочих процессов с контролируемым числом задач и отдельным лимитом памяти.

Методы convert_all или пакетная логика вокруг convert помогают обрабатывать коллекцию. Генераторный подход позволяет записывать каждый результат сразу, не удерживая все документы в памяти. Если бизнес-правило требует полной транзакции, сначала сохраняют результаты во временный каталог и публикуют набор только после успешного завершения. Для индексации чаще подходит частичная публикация с очередью повторной обработки ошибок.

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

Конфигурация форматов

Разные правила задаются через format_options. Для PDF создают PdfPipelineOptions и передают их в PdfFormatOption; другие форматы могут иметь собственные параметры обработчика. allowed_formats ограничивает список входов на уровне конвертера. Это полезнее, чем проверка расширения только во внешнем коде: нежелательный формат не будет случайно принят после переименования или изменения маршрута.

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

pdf_options = PdfPipelineOptions()
pdf_options.do_ocr = True
pdf_options.do_table_structure = True

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

Конфигурацию следует создавать явно в одном модуле и покрывать контрольными документами. Разрозненные изменения параметров в разных функциях приводят к труднообъяснимым расхождениям. Полезно сохранять рядом с результатом краткую запись профиля: использованный OCR, режим таблиц, масштаб изображений, включённые обогащения и идентификатор набора моделей. Сам JSON документа не всегда достаточно ясно объясняет, почему конкретный блок был распознан именно так.

DoclingDocument и сохранение структуры

DoclingDocument — не просто контейнер для текста. Он хранит элементы тела, группы, таблицы, рисунки, текстовые узлы и сведения о происхождении. Иерархия позволяет представить раздел с заголовком и вложенными абзацами, список с отдельными пунктами или таблицу как самостоятельный объект. Ссылки между элементами нужны, чтобы не дублировать содержимое и сохранять отношения. Геометрическая информация связывает элемент с номером страницы и прямоугольником в координатах документа.

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

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

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

При сохранении в JSON DoclingDocument сериализуется без потери существенной структуры. Этот файл обычно больше Markdown, зато позволяет менять формат вывода, разбиение и фильтры без повторной конвертации. Для долгосрочного хранения JSON следует сопровождать версией схемы и тестом чтения после обновления библиотеки. Если хранилище рассчитано на годы, полезно также сохранять исходник и простой Markdown как человекочитаемый резерв.

Работа с отдельными элементами

Таблицы можно извлекать как матрицу или преобразовывать в DataFrame, если доступен соответствующий метод объекта таблицы. Но перед аналитикой нужно проверить заголовки, объединённые ячейки и числа с переносами. Рисунок можно экспортировать, описать моделью или связать с подписью. Формулы и код имеют собственные типы, что позволяет не смешивать их с обычным абзацем. Списки сохраняют последовательность и маркеры, однако сложные многоуровневые списки стоит проверять на исходной странице.

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

Экспорт в Markdown, HTML, JSON и текст

Markdown подходит для чтения, систем контроля версий и большинства загрузчиков знаний. Заголовки превращаются в маркеры уровней, списки — в пункты, таблицы — в табличную разметку, а изображения могут быть встроены, заменены маркерами или сохранены рядом. Ограничение Markdown состоит в том, что он не способен без потерь представить всю геометрию и сложные объединения ячеек. Если результат будет повторно анализироваться программно, параллельно сохраняйте JSON.

HTML лучше передаёт таблицы и позволяет встроить изображения как данные либо сослаться на файлы. Разбитый по страницам вариант удобен для просмотра и сопоставления с исходником, но не обязательно подходит для семантического поиска: граница страницы может разорвать предложение или раздел. Перед публикацией HTML нужно отдельно очищать и стилизовать; экспорт предназначен для представления документа, а не автоматически безопасной вставки неизвестного содержимого в сайт.

Обычный текст удаляет большую часть декоративной разметки. Он полезен для классического полнотекстового индекса, сравнения и простых утилит, но теряет уровни заголовков и богатые таблицы. WebVTT сохраняет временную структуру для расшифровок. DocTags и DocLang предназначены для более специализированного представления структуры и характеристик макета. DCLX объединяет DocLang с изображениями страниц в одном пакете.

JSON является каноническим вариантом для повторной загрузки. Он сохраняет дерево, элементы, ссылки и provenance. Минус — объём и зависимость потребителя от схемы. Не следует индексировать весь JSON как строку: координаты, идентификаторы и служебные поля создадут шум. Сначала пройдите структуру, сформируйте осмысленный текст и метаданные, затем отправляйте их в поисковый индекс.

Chunks создаёт JSONL с фрагментами для RAG. Параметры chunks-type, chunks-max-tokens и chunks-tokenizer определяют способ разбиения и допустимый размер. Даже готовый экспорт нужно проверить на целевой модели эмбеддингов: токенизаторы считают длину по-разному, а большой заголовок или таблица могут превысить предел. Контекст раздела следует хранить в метаданных, чтобы найденный абзац не выглядел оторванным от темы.

docling convert handbook.pdf   --to chunks   --chunks-type hybrid   --chunks-max-tokens 450   --output chunks-result

При сохранении изображений различают встроенный, ссылочный и placeholder-подход. Встроенные данные упрощают перенос одного HTML, но сильно увеличивают его размер. Ссылочные файлы удобнее для сайта и хранилища, зато каталог результата нужно переносить целиком. Placeholder оставляет место без графики и подходит, если изображения будут обработаны отдельно. Стратегию выбирают до массового запуска, иначе смена режима потребует повторной сериализации или конвертации.

OCR для сканов и изображений

OCR включают, когда PDF состоит из изображений либо его текстовый слой пуст, повреждён или содержит неверную кодировку. Для цифрового PDF повторное распознавание всей страницы часто ухудшает результат: модель может ошибиться там, где исходные символы уже доступны точно. Поэтому сначала определяют состояние текстового слоя, затем выбирают режим обработки областей. Параметр force_full_page_ocr оправдан для скана с бесполезным скрытым слоем, но не должен становиться безусловным стандартом.

Docling поддерживает несколько движков: RapidOCR, EasyOCR, Tesseract через командную строку или tesserocr, OcrMac, Nemotron OCR и подключаемые плагины вроде OnnxTR. Они различаются зависимостями, языками, скоростью, требованиями к GPU и поведением на сложной верстке. Один движок нельзя объявить лучшим для всех документов. Контрольный корпус должен включать реальные языки, шрифты, печати, таблицы, низкоконтрастные страницы и повороты.

EasyOCR устанавливается отдельным extra-набором и поддерживает много языков; языковые коды задаются в EasyOcrOptions. Набор языков влияет на скорость и вероятность смешения похожих символов, поэтому не нужно включать десятки вариантов на всякий случай. Для русско-английского документа выбирают оба требуемых языка и проверяют имена, номера и сокращения. Порог уверенности фильтрует слабые распознавания: слишком высокий порог теряет бледный текст, слишком низкий пропускает мусор.

RapidOCR может работать через разные бэкенды, включая ONNX Runtime. Он удобен, когда нужен сравнительно лёгкий профиль, но конкретные языковые контрольные точки следует загрузить заранее. Tesseract требует системной установки и языковых данных; переменная TESSDATA_PREFIX должна указывать на каталог tessdata. Ошибка поиска traineddata не исправляется переустановкой Docling: необходимо установить нужный языковой пакет и проверить путь.

OcrMac использует возможности macOS и доступен только на соответствующей системе. Nemotron OCR предъявляет узкие требования к Linux x86_64, Python, CUDA и специальным сборкам PyTorch, поэтому его целесообразно выносить в отдельное окружение. Если дополнительный движок ломает базовую установку, не смешивайте профили: создайте отдельный образ или виртуальное окружение для документов, которым он действительно нужен.

from docling.datamodel.pipeline_options import (
    EasyOcrOptions,
    PdfPipelineOptions,
)

options = PdfPipelineOptions()
options.do_ocr = True
options.ocr_options = EasyOcrOptions(
    lang=["ru", "en"],
    force_full_page_ocr=False,
    confidence_threshold=0.35,
)

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

OCR-ошибки следует оценивать по контексту задачи. Для поиска допустима отдельная опечатка, если ключевые термины находятся; для бухгалтерских чисел одна неверная цифра критична. В последнем случае извлечённые значения проверяют правилами диапазона, контрольными суммами, сопоставлением итогов или ручной верификацией. Docling предоставляет структурированный материал, но не заменяет предметный контроль достоверности.

Когда отключать OCR

• В PDF уже есть корректный выбираемый текст и нет растровых вставок с важными надписями.
• Нужна максимально быстрая черновая конвертация цифрового фонда.
• Дополнительный движок недоступен в изолированной среде, а документы не являются сканами.
• Повторное распознавание систематически портит формулы, код или редкие символы.
• Текстовый слой получен надёжным корпоративным OCR и уже прошёл проверку.

Отключение OCR не выключает анализ макета и таблиц. Конвейер продолжает использовать текстовый слой и геометрию PDF. Поэтому тестировать нужно отдельно: один профиль без OCR для цифровых документов и второй для сканов. Автоматический маршрутизатор может оценить долю страниц без текста и отправить файл в нужную очередь, но смешанные документы требуют проверки каждой страницы или гибридного режима.

Распознавание таблиц

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

Параметр do_table_structure включает структурное распознавание. TableFormer предлагает режимы FAST и ACCURATE: быстрый полезен для большого потока простых таблиц, точный — для сложных шапок и объединений. Режим не следует выбирать только по времени на одной странице. Измерьте точность на таблицах, которые затем участвуют в вычислениях; небольшое замедление может окупиться отсутствием ручной правки.

По умолчанию распознанная структура сопоставляется с текстовыми ячейками PDF. Если несколько колонок ошибочно сливаются, параметр do_cell_matching можно отключить, чтобы использовать текст, предсказанный моделью структуры. Это не универсальное улучшение: на чистом цифровом PDF исходные символы часто точнее OCR-предсказания. Сравните оба варианта на конкретном шаблоне и зафиксируйте профиль для данного шаблона.

from docling.datamodel.pipeline_options import (
    PdfPipelineOptions,
    TableFormerMode,
)

options = PdfPipelineOptions(do_table_structure=True)
options.table_structure_options.mode = TableFormerMode.ACCURATE
options.table_structure_options.do_cell_matching = True

После экспорта в Markdown объединённые ячейки неизбежно упрощаются, потому что синтаксис Markdown не выражает сложную геометрию. Для аналитики используйте объект таблицы или JSON, а HTML оставьте для визуального представления. Перед загрузкой в DataFrame нормализуйте многострочные заголовки, удалите повтор шапки на каждой странице и осторожно преобразуйте числа: пробел может быть разделителем тысяч, запятая — десятичным знаком, а дефис — отсутствующим значением.

Многостраничная таблица может быть распознана как несколько объектов. Автоматическое объединение требует бизнес-правила: совпадение заголовков, близкая ширина столбцов, последовательные страницы и отсутствие нового раздела между ними. Склеивать все соседние таблицы опасно. В отчёте могут идти две таблицы одинаковой ширины, но с разными показателями.

Качество таблицы удобно проверять инвариантами. В каждой строке ожидается одинаковое число колонок, итог должен совпадать с суммой, дата — соответствовать периоду, а заголовки — входить в известный словарь. Нарушение отправляет объект на повторную обработку в точном режиме или на ручную проверку. Такой контроль эффективнее визуального просмотра каждого Markdown-файла.

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

Макет, порядок чтения и колонтитулы

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

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

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

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

Рисунки, подписи и визуальное обогащение

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

Классификатор рисунков помогает отличать диаграммы, фотографии и другие типы. Описание изображения можно получить визуально-языковой моделью, однако это отдельный этап с дополнительными требованиями к памяти и лицензии модели. Описание не следует считать точной расшифровкой чисел на графике. Для аналитики диаграмм предпочтительно извлекать данные специализированным режимом и проверять оси, легенду и единицы.

Удалённая модель описания изображения требует явного разрешения enable_remote_services. Без него Docling блокирует отправку данных и выдаёт OperationNotAllowed. Это защитное поведение важно для конфиденциальных документов. Включая удалённый вызов, необходимо понимать, какие фрагменты страницы уходят поставщику, где они хранятся и какие ограничения действуют на объём и частоту.

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

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

При экспорте изображений контролируйте масштаб. Высокий image_scale улучшает OCR мелких подписей и качество описания, но увеличивает память и размер файлов. Для страницы формата A0 или скана с очень высоким DPI необдуманный масштаб способен исчерпать память. Устанавливайте предел пикселей и уменьшайте только рабочую копию, сохраняя оригинал для аудита.

Фрагментация для RAG и поиска

Прямое деление Markdown каждые несколько тысяч символов разрушает структуру: заголовок отделяется от абзаца, таблица разрезается посередине, а подпись уходит от рисунка. Docling использует сведения DoclingDocument, чтобы формировать фрагменты с учётом иерархии. HierarchicalChunker следует структуре документа, а HybridChunker дополнительно учитывает токенизацию и объединение соседних элементов.

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

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

Таблица требует особой стратегии. Маленькую таблицу целесообразно хранить целиком вместе с подписью; большую можно разделять по группам строк, повторяя заголовки столбцов. Нельзя резать строку между ячейками или отделять единицы измерения. Для вопросно-ответной системы иногда создают два представления: Markdown-таблицу для модели и нормализованные записи для точного фильтра или вычисления.

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

Качество RAG оценивают не по красоте одного ответа. Нужен набор вопросов с ожидаемыми страницами и фрагментами, измерение полноты поиска и анализ ложных совпадений. Ошибка может возникнуть на любом этапе: OCR исказил термин, макет смешал колонки, chunker отделил заголовок, эмбеддинг не уловил число, а генератор придумал вывод. Docling улучшает подготовку документа, но не отменяет сквозную проверку системы.

Пример программной фрагментации

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

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

for item in chunker.chunk(document):
    text = item.text
    meta = item.meta
    # Передайте text и нужные поля meta в индекс

Точные имена полей метаданных следует брать из объекта установленной версии, а не предполагать по примеру. Перед отправкой в индекс сериализуйте только нужные и стабильные значения. Внутренние объекты Python могут не преобразоваться в JSON напрямую. Отдельно сохраните идентификатор исходного DoclingDocument, чтобы при изменении стратегии фрагменты можно было пересоздать.

Docling Serve: форма, API и очередь задач

Docling Serve предоставляет HTTP API и веб-интерфейс поверх тех же возможностей конвертации. На форме пользователь выбирает файл или вводит допустимый адрес, отмечает выходные форматы и параметры конвейера, затем получает результат. Такой интерфейс удобен для сотрудников, которым не нужен Python-код, и для централизованного сервера с общим кэшем моделей. Он не превращает Docling в ручной PDF-редактор: форма запускает обработку и показывает экспорт.

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

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

Конвертация выполняется как задача. Асинхронная модель предотвращает длительное удержание одного HTTP-запроса и позволяет опрашивать статус. Клиент должен обрабатывать состояния ожидания, выполнения, успеха и ошибки, устанавливать общий тайм-аут и не создавать повторную задачу после каждого сетевого сбоя. Идемпотентный ключ запроса или внешний идентификатор документа помогает избежать дубликатов.

Для сервера особенно важны ограничения. Пользователь может отправить чрезмерно крупный PDF с тысячами страниц, изображение огромного размера или адрес бесконечного потока. До очереди проверяют Content-Length, фактически прочитанный объём, тип, расширение, число страниц и разрешённые домены. После постановки задания ограничивают время, память и число одновременных конвертаций. Один тяжёлый VLM-процесс не должен блокировать все простые PDF.

Модели лучше прогреть до приёма трафика. Первый пользователь не должен ждать загрузки нескольких наборов и компиляции бэкенда. В изолированной среде каталог артефактов монтируют только для чтения, а временные файлы — в отдельный том с квотой и очисткой. Если несколько реплик одновременно скачивают модели, возможны гонки и лишний трафик; централизованная подготовка образа делает запуск предсказуемее.

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

Производительность и использование ресурсов

Скорость зависит от числа страниц, разрешения, наличия OCR, сложности таблиц, включённых обогащений и выбранного устройства. Цифровой PDF с простым текстом обрабатывается значительно легче скана, где каждую страницу нужно растеризовать и распознать. Поэтому среднее время по смешанной коллекции малоинформативно. Разделите корпус на классы и измеряйте для каждого медиану, высокий процентиль, пиковую память и долю ошибок.

На CPU можно выполнять стандартный конвейер, но массовые задачи выигрывают от GPU. Для NVIDIA требуется совместимая сборка PyTorch и рабочий драйвер; сам факт наличия CUDA Toolkit не доказывает, что PyTorch видит устройство. Сначала проверьте доступность ускорителя в Python, затем запустите короткий документ и сравните журнал. Если процесс незаметно откатился на CPU, время вырастет, но результат может остаться корректным.

Apple Silicon использует MPS там, где операции поддерживаются. Отдельные модели или версии библиотек могут выполнять часть шагов на CPU. На Intel Mac действуют ограничения сборок PyTorch, поэтому попытка установить самые новые пакеты без совместимой матрицы приводит к ошибке разрешения зависимостей. В серверной среде лучше закрепить образ, прошедший тест на целевом железе, чем собирать окружение при каждом запуске.

Растеризация страниц создаёт крупные изображения. Увеличение image_scale полезно для мелкого текста и картинок, но расход памяти растёт примерно с площадью. Двукратное увеличение каждой стороны даёт примерно в четыре раза больше пикселей. Для больших листов устанавливают предел, иначе одна страница способна завершить процесс по нехватке памяти. Если важна только часть страницы, предварительное кадрирование уменьшает нагрузку.

Кэш моделей ускоряет повторные запуски и должен находиться на быстром диске. В контейнере без постоянного тома модели будут скачиваться при каждом старте. На нескольких узлах общий сетевой каталог упрощает управление, но может стать узким местом при одновременной загрузке. Часто надёжнее включить проверенный набор в образ либо разложить его на локальные диски при развёртывании.

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

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

Модели, автономная работа и конфиденциальность

При первом использовании Docling по умолчанию может загрузить необходимые модели. Для изолированной сети их заранее получают командой docling-tools models download. Утилита умеет выбирать конкретные группы: макет, TableFormer, распознавание кода и формул, классификатор рисунков, RapidOCR, EasyOCR и визуально-языковые модели. Загрузка всего набора без необходимости увеличивает образ и усложняет проверку лицензий.

docling-tools models download layout tableformer rapidocr   --output-dir models

docling convert confidential.pdf   --artifacts-path models   --to json --output result

Локальные модели не отправляют содержимое документа внешнему поставщику. Но это утверждение перестаёт быть полным, если включены удалённые OCR или VLM, входной файл загружается из сети, результаты отправляются в облачный индекс либо журналы уходят во внешнюю систему. Карта потоков данных должна учитывать весь конвейер. Docling специально требует явного enable_remote_services для моделей, которые передают данные наружу.

Загрузка весов и отправка пользовательского документа — разные операции. Запрет enable_remote_services блокирует удалённую обработку содержимого, но не является универсальным выключателем скачивания моделей. Для полностью автономного режима предварительно заполняют каталог артефактов, отключают загрузку в настройках движков и блокируют исходящий трафик на уровне окружения. Такой двойной контроль защищает от случайной зависимости после обновления.

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

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

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

Типовые ошибки и способы исправления

Команда docling не найдена

Причина обычно в неактивном виртуальном окружении или установке пакета другим интерпретатором. Выполните python -m pip show docling, проверьте путь Python и каталог скриптов окружения. В автоматическом задании активировать оболочку необязательно: можно вызывать исполняемый файл Python из окружения напрямую. Переустановка глобально с правами администратора маскирует проблему и создаёт новый конфликт.

Не загружаются модели

Проверьте доступ к хранилищу, сертификаты, прокси, свободное место и права на каталог кэша. Если сеть закрыта, используйте docling-tools models download на разрешённой машине и перенесите каталог целиком. После переноса задайте artifacts_path и повторите тест без сети. Если ошибка называет конкретную модель, не удаляйте весь кэш сразу: сначала сравните наличие файлов и права.

PyTorch не видит GPU

Сверьте драйвер, сборку PyTorch и доступность устройства внутри контейнера. Команда системного драйвера может видеть GPU, а Python — нет, если установлен CPU-вариант PyTorch. После исправления проверьте небольшим выражением доступности CUDA или MPS. Не начинайте диагностику с Docling, пока базовая библиотека не подтверждает ускоритель.

Процесс завершается по нехватке памяти

Уменьшите число параллельных работников, масштаб изображений и число одновременно обрабатываемых страниц. Отключите неиспользуемые VLM-обогащения, разделите очень длинный PDF и установите ограничения размера. На GPU освободите память от других процессов. Повторный запуск без изменения профиля обычно приводит к той же ошибке в другом месте.

Русский текст распознаётся с ошибками

Убедитесь, что выбранный OCR имеет русскую модель и язык явно включён. Проверьте разрешение, наклон и контраст исходника. Не включайте force_full_page_ocr для PDF с хорошим текстовым слоем. Сравните два движка на одинаковой выборке и измерьте не только слова, но и цифры, инициалы, номера и символы валют.

Колонки перемешаны

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

Ячейки таблицы объединены неверно

Переключите TableFormer в ACCURATE и сравните do_cell_matching в двух состояниях. Проверьте качество рендеринга и наклон. Для таблицы без линий важна точность расположения текста; для скана с сеткой — сохранность границ. После изменения сравнивайте структурированный JSON или DataFrame, а не только внешний вид Markdown.

Tesseract не находит языковые данные

Установите системный пакет нужного языка и задайте TESSDATA_PREFIX на каталог tessdata с завершающим разделителем, если этого требует окружение. Проверьте запуск Tesseract отдельно. Ошибка сборки tesserocr относится к нативной привязке; временно можно выбрать Tesseract CLI или другой OCR, не меняя весь конвейер.

Старые DOC, XLS или PPT не открываются

Для бинарных форматов Office требуется LibreOffice. Установите его, проверьте доступность исполняемого файла и права на временный каталог. В минимальном контейнере могут отсутствовать шрифты, из-за чего преобразованный документ отличается. Если формат входа контролируется, надёжнее предварительно перевести его в DOCX, XLSX или PPTX и сохранить исходник для аудита.

OperationNotAllowed при описании изображения

Выбранная функция пытается обратиться к удалённой модели, а явное разрешение не включено. Это не сбой сети. Решите, допустима ли передача данных, настройте поставщика и только затем установите enable_remote_services. Для закрытых документов используйте локальную модель либо отключите описание рисунков.

HTML выглядит иначе, чем веб-страница

Сохранённый HTML может зависеть от JavaScript, CSS, шрифтов и внешних ресурсов. Установите htmlrender, если нужен рендеринг, и передавайте полный комплект ресурсов. Динамическую страницу лучше заранее сохранить в стабильный вид. Не ожидайте, что разбор разметки воспроизведёт интерактивные виджеты или данные, подгружаемые после открытия.

Результат обрывается на большом документе

Проверьте лимиты страниц, размера и времени в конвертере, внешнем прокси и очереди. Ошибка может быть не в Docling, а в тайм-ауте HTTP или очистке временного файла. Для API используйте асинхронное задание, а не один длинный запрос. Сохраняйте статус каждой части, если документ разделяется.

JSON не читается после обновления

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

Сравнение Docling с аналогами

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

Программа	Лучше подходит для	Главное ограничение
Docling	Структурного разбора PDF и разных документов, OCR, таблиц и подготовки данных для RAG	Требует настройки Python, моделей и параметров конвейера
PDF Commander	Ручного редактирования, сборки, аннотирования и повседневной работы с PDF	Не предназначен для программного построения DoclingDocument и RAG-конвейеров
PyMuPDF4LLM	Быстрого извлечения PDF в Markdown, JSON и фрагменты на базе PyMuPDF	Меньше акцент на универсальной модели разных форматов и сменных AI-конвейерах
Unstructured	Разделения множества типов документов и подключения к конвейерам загрузки данных	Расширенная конфигурация и зависимости могут усложнить развёртывание
Marker	Преобразования PDF и изображений в Markdown или JSON с упором на формулы и таблицы	Модельный профиль требователен к ресурсам и ориентирован прежде всего на конвертацию
Apache Tika	Широкого извлечения текста и метаданных из множества форматов через Java или сервер	Глубина восстановления макета и сложных таблиц ниже, чем у специализированных моделей

Docling выбирают, когда требуется единая структурированная модель, подробный разбор PDF, настраиваемый OCR и дальнейшая работа через Python. PDF Commander практичнее, если человек должен визуально изменить страницы, подпись, порядок листов или текст. PyMuPDF4LLM подходит для более прямого и быстрого PDF-потока, где возможностей PyMuPDF достаточно. Unstructured удобен в инфраструктуре загрузчиков и коннекторов, Marker — при приоритете качественного Markdown для сложных научных материалов, Apache Tika — для массового извлечения текста и метаданных из очень широкого набора форматов.

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

Практические сценарии

Сканированный договор

Сначала определяют язык и качество страниц, выбирают OCR и запрещают удалённые модели. После конвертации сохраняют JSON и Markdown, проверяют стороны, даты, суммы, номера пунктов и приложения. Provenance прикрепляют к каждому фрагменту, чтобы найденное условие можно было показать на странице. Таблицы платежей проходят отдельную числовую проверку. Исходный PDF не изменяется и остаётся контрольным экземпляром.

Научная статья

Включают точный режим таблиц, выделение формул и рисунков. Markdown используют для чтения и загрузки в модель, JSON — для связи заголовков, подписей и страниц. Ссылки и сноски не удаляют без анализа. Большие таблицы делят по строкам с повтором шапки, а формулы сохраняют в отдельном элементе. Ответы RAG показывают страницу и рамку исходной страницы.

Корпоративный фонд документов

Файлы предварительно классифицируют по формату и наличию текста. Цифровые PDF идут без принудительного OCR, сканы — через языковой профиль, старые Office-файлы — через узел с LibreOffice. Результат записывают в каталог по устойчивому идентификатору, а журнал содержит хэш исходника и статус. Неудачи поступают в отдельную очередь, не блокируя весь фонд.

Отчёты с финансовыми таблицами

Для PDF проверяют режим TableFormer и cell matching на типовых шаблонах. Для XBRL настраивают доступ к таксономии и решают, разрешены ли удалённые ресурсы. Числа нормализуют с учётом локали, единиц и скобок для отрицательных значений. Итоги и подытоги сверяют математически. Извлечённая таблица без проверки не должна автоматически попадать в финансовое решение.

База инструкций

DOCX, PDF, HTML и презентации приводят к DoclingDocument, затем HybridChunker формирует фрагменты с путём заголовков. Колонтитулы и повторяющиеся предупреждения фильтруют осторожно. В индекс отправляют версию документа, продукт, раздел и страницу. При обновлении инструкции старые фрагменты удаляют по идентификатору документа, а не пытаются найти их по тексту.

Сервис конвертации для команды

Docling Serve размещают за аутентификацией и очередью. Ограничивают размер, типы, домены удалённых адресов, число задач и время. Модели прогревают, временные файлы изолируют, а результаты удаляют по сроку. В интерфейсе показывают статус, краткую ошибку и доступные форматы. Полный журнал доступен только администратору и не содержит распознанного текста.

Обработка аудио и видео

Устанавливают ASR-зависимости и ffmpeg, проверяют язык, качество дорожки и допустимый размер. Видео даёт расшифровку и репрезентативные кадры; это не покадровый анализ всего изображения. Временные метки сохраняют в WebVTT или метаданных. Имена говорящих и специальные термины требуют проверки, особенно если запись используется как протокол.

Повторная сериализация без исходника

После дорогой конвертации сохраняют Docling JSON. Из него можно заново сформировать Markdown, HTML или фрагменты с другими параметрами, не повторяя OCR и анализ страниц. Такой подход ускоряет эксперименты с chunker и индексом. Однако исходный PDF всё равно хранят, поскольку новая модель или исправление конвейера может потребовать повторного разбора.

Как проверить результат перед массовым запуском

1. Зафиксируйте окружение, выбранные extras, модельные артефакты и профиль параметров.
2. Соберите контрольный корпус из реальных документов, включая плохие и пограничные случаи.
3. Определите метрики для текста, порядка чтения, таблиц, формул, рисунков и времени.
4. Сохраните эталонные страницы и ожидаемые структурные элементы.
5. Запустите конвертацию в JSON и человекочитаемый формат.
6. Автоматически проверьте пустые страницы, число элементов, таблицы и обязательные строки.
7. Вручную просмотрите выборку с наихудшими оценками и несколько случайных успешных файлов.
8. Измерьте память и высокие процентили времени на целевом оборудовании.
9. Проверьте поведение при повреждённом файле, тайм-ауте, отсутствии модели и заполненном диске.
10. Только после этого увеличивайте параллелизм и объём очереди.

Контрольный корпус нужно хранить вместе с ожидаемыми результатами и запускать после обновления Python, Docling, PyTorch, OCR или моделей. Полное совпадение JSON байт в байт может быть слишком строгим из-за служебных полей, поэтому сравнивают значимые признаки: текст, типы, порядок, таблицы и координаты с допуском. Любое улучшение на одном классе проверяют на остальных, чтобы не получить регрессию.

Для ручной проверки удобно сформировать HTML и рядом показать исходную страницу. Рецензент отмечает смешение колонок, пропущенные подписи, неверные таблицы и OCR. Эти отметки превращаются в воспроизводимые тесты или правила маршрутизации. Без такого цикла качество остаётся субъективным и зависит от последнего просмотренного файла.

Итоговый рабочий подход

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

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

Для единичного файла достаточно команды с явным каталогом и форматом вывода. Для повторяющейся задачи лучше Python API с фиксированной конфигурацией, журналом статусов и сохранением JSON. Для команды или нескольких приложений подходит Docling Serve с очередью, ограничениями и контролем доступа. Во всех вариантах исходный документ остаётся эталоном, а provenance позволяет объяснить, откуда взят каждый фрагмент.

Если требуется исправлять страницы вручную, менять их порядок, добавлять подпись или редактировать текст в самом PDF, нужен визуальный PDF-редактор. Если цель — превратить неоднородные документы в структурированные данные для поиска, аналитики, хранилища или RAG, Docling предоставляет детальную модель, сменные OCR и конвейеры, несколько сериализаций и средства пакетной автоматизации. Результат становится устойчивым тогда, когда выбранный профиль подтверждён контрольным корпусом и автоматическими проверками.