Docling: структурный импорт документов

Docling — сервис разбора документов, который сохраняет при импорте в базу знаний структуру исходного файла: заголовки, таблицы, списки и изображения на своих местах. Docling работает как отдельный контейнер рядом с платформой и включается двумя переменными среды приложения, а время ожидания разбора вы задаёте в разделе Администрирование → Знания и поиск → Импорт документов. Docling читает документы с текстовым слоем и не распознаёт растр: сканы, фотографии и рукописный текст обрабатывает отдельный контур AI-импорта. Если сервис недоступен, импорт не прерывается — платформа достраивает документ упрощённым разбором и отмечает результат предупреждением.

Что вам понадобится

• доступ администратора платформы к разделу Администрирование → Знания и поиск → Импорт документов;
• доступ к серверу инсталляции: запуск контейнеров и правка переменных среды приложения;
• сервис docling в контуре инсталляции — он входит в состав платформы и поднимается вместе с остальными сервисами;
• включённая функция AI-импорт документов в разделе Администрирование → Доступ → Функции — если рабочим пространствам нужно распознавание сканов.

Что Docling даёт при импорте

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

Разбор через Docling получают документы с текстовым слоем: PDF, из которого текст можно выделить и скопировать, и DOCX. Книги Excel разбирает отдельный конвейер, который не зависит от Docling. Остальные форматы платформа читает текстовым парсером.

Как включить Docling в инсталляции

Docling включается двумя переменными среды приложения. Пока DOCLING_ENABLED не равна строке true, платформа не обращается к сервису и разбирает все файлы упрощённым способом — промежуточных состояний нет.

Отдельного файла конфигурации у Docling нет.

Запустите или перезапустите один сервис на сервере инсталляции, не трогая остальной контур:

docker compose up -d docling

Контейнер поднимается под именем docling, поэтому команды диагностики адресуются к этому имени: docker logs docling, docker stats docling.

Важно. В контуре инсталляции порт Docling наружу не публикуется: сервис доступен только внутри сети платформы по адресу http://docling:5001, и DOCLING_API_URL указывает именно на него.

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

Модели разбора Docling скачивает при первом запуске и хранит в именованном томе docling_models. Проверка готовности контейнера начинается через 120 секунд после старта — этот запас и покрывает загрузку моделей. Удаление тома приводит к повторной загрузке при следующем старте.

Как задать таймаут разбора

Время ожидания разбора задаётся в разделе Администрирование → Знания и поиск → Импорт документов, карточка Обработка файлов перед импортом, поле Таймаут, минут. По умолчанию — 30 минут, допустимый диапазон — 5–120 минут. Значение общее для инсталляции и применяется к следующим заданиям импорта без перезапуска приложения.

1. Откройте Администрирование → Знания и поиск → Импорт документов.
2. Укажите в поле Таймаут, минут целое число минут.
3. Нажмите Сохранить.

Платформа подтверждает сохранение сообщением «Таймаут Docling обновлён». Кнопка Сбросить по умолчанию возвращает поле к значению 30 минут, но изменение вступает в силу только после сохранения.

Таймаут ограничивает ожидание платформы, а не работу Docling. По его истечении задание не падает: платформа переключается на упрощённый разбор и завершает импорт со статусом предупреждения.

Как проверить, что Docling работает

Платформа опрашивает адрес /health сервиса и кэширует результат на минуту, поэтому изменения в контуре видны в импорте не мгновенно. Проверять доступность удобнее напрямую с сервера инсталляции, а результат разбора — на пробном файле.

Проверьте доступность сервиса с сервера инсталляции:

docker compose exec docling curl -f http://localhost:5001/health

Сервис отвечает кодом 200. Отказ означает, что контейнер не запущен или ещё загружает модели.

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

Примечание. Признак использованного конвейера остаётся в серверных логах: платформа намеренно вычищает из пользовательских сообщений технические слова, включая название сервиса.

Как платформа выбирает конвейер импорта

Конвейер определяется типом файла и режимом импорта, а не настройками пространства. Платформа принимает решение один раз при постановке задания и переключается на запасной конвейер только при отказе основного.

Импорт идёт асинхронно: платформа ставит задачу в Docling, опрашивает её состояние и забирает результат. Пока задание выполняется, в базе знаний у файла меняются подписи фазы — В очереди, Подготовка, Анализ, Сохранение, Завершение — и завершается на Готово или С ошибками. Сбой до старта конвейера платформа повторяет: задание получает до трёх попыток с нарастающей паузой, и только затем помечается как неудачное.

Отказ Docling переводит задание на упрощённый разбор. Импорт завершается статусом completed_with_warnings и сообщением «Импорт завершён с предупреждениями. Для лучшего качества обратитесь к администратору» — документ в базе знаний появляется, но без структуры.

Как импортировать сканы и фотографии

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

Фаза разбора видна в списке файлов базы знаний, пока задание не завершится.

Кнопка доступна пространствам, которым администратор включил функцию AI-импорт документов в разделе Администрирование → Доступ → Функции. По умолчанию функция выключена для всех пространств.

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

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

Частые вопросы

Импорт проходит, но структуры в документе нет

Платформа не обратилась к Docling или получила отказ и перешла на упрощённый разбор. Проверьте:

• переменная DOCLING_ENABLED равна строке true, а приложение перезапущено после правки;
• DOCLING_API_URL указывает на адрес сервиса внутри сети инсталляции;
• контейнер docling запущен и отвечает на /health;
• исходный PDF содержит текстовый слой, а не скан.

Импорт большого файла завершается со статусом С ошибками

Разбор не уложился в отведённое время. Увеличьте значение поля Таймаут, минут в разделе Администрирование → Знания и поиск → Импорт документов и повторите загрузку. Если это повторяется на файлах обычного размера, проверьте загрузку сервера: при DOCLING_SERVE_CONCURRENCY равном 1 одновременные загрузки обрабатываются по очереди.

В сообщении об ошибке нет ни одного технического слова

Платформа вычищает из пользовательских сообщений названия внутренних конвейеров и оставляет короткие причины вида «Таймаут» или «Ошибка сети». Развёрнутая диагностика — в серверных логах приложения, там же остаётся код причины перехода на запасной конвейер.

Сканированный PDF импортировался пустым

В файле нет текстового слоя. Платформа сообщает об этом прямо: «Импорт завершён: документ не содержит индексируемого текста. Похоже на скан без текстового слоя — включите AI-импорт (OCR) в настройках пространства и повторите загрузку». Включите пространству функцию AI-импорт документов и повторите загрузку через кнопку AI импорт.

Изменения параметров контейнера не применились

Окружение контейнер читает при создании, а не при перезапуске. Пересоздайте сервис командой docker compose up -d --force-recreate docling и проверьте применённые значения командой docker exec docling env.

Что дальше

• Docling на локальном стенде — поднять сервис на машине разработчика и проверить разбор.
• Администрирование знаний — лимиты загрузки файлов и настройки индексации.
• Доступ, пользователи и пространства — включить пространствам AI-импорт документов.
• Базы знаний — как выглядит импорт со стороны читателя.