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

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

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

• доступ администратора платформы к разделу Администрирование → Знания и поиск → Импорт документов;
• доступ к серверу инсталляции: запуск контейнеров и правка переменных среды приложения;
• сервис docling в контуре инсталляции — он входит в состав платформы и поднимается вместе с остальными сервисами;

Загружаем изображение…

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

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

Docling разбирает PDF с текстовым слоем: текст берётся из файла дословно, таблицы и уровни заголовков восстанавливаются по раскладке страницы. Сканы и PDF без текстового слоя распознаёт vision-модель OCR-провайдера. Если Docling недоступен, PDF с текстовым слоем тоже распознаёт модель, и документ получает отметку об упрощённом способе обработки. DOCX платформа разбирает сама: читает разметку Word напрямую и переносит выравнивание абзацев, жирный, курсив, подчёркивание и цвет текста, заголовки по стилям, списки, таблицы и картинки на своих местах; через Docling идёт только DOCX, который собственный разбор не смог открыть. Книги Excel разбирает отдельный конвейер, а презентации PPTX — собственный парсер платформы; они в Docling не уходят. DOC и RTF платформа читает текстовым парсером, документы ODT сохраняет без индексации.

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

Docling включается двумя переменными среды приложения. Пока DOCLING_ENABLED не равна строке true, платформа к сервису не обращается: DOCX она разбирает сама, PDF с текстовым слоем распознаёт vision-модель с меткой Использован упрощённый способ обработки, а документ, которому нужен именно Docling, получает состояние Требуется действие с причиной Расширенное распознавание временно недоступно и ждёт включения сервиса.

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

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

docker compose up -d docling

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

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

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

Переменную DOCLING_SERVE_CONCURRENCY, которая задана в поставке, сервис не читает: параллельность определяет только DOCLING_SERVE_ENG_LOC_NUM_WORKERS.

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

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

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

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

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

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

На том же экране есть карточка «Улучшение структуры документа» с переключателем «Восстанавливать структуру при импорте», включённым в поставке. Он распознаёт заголовки по повторяющейся нумерации, склеивает разорванные абзацы и разворачивает таблицы-обёртки; если регулярная структура не найдена, документ сохраняется без изменений. Это общий этап подготовки содержимого для всех документов, кроме книг Excel и расшифровок речи; отказ структуризатора не прерывает импорт и помечает документ Оглавление не построено. На этом же этапе и независимо от переключателя платформа собирает слова, разорванные переносом строки, и убирает мягкие переносы, так что поиск находит слово целиком, а не два обрывка. Склейку получают новые документы. Уже загруженные получают её при повторной загрузке файла, переиндексация базы их текст не меняет. Блок «Лимиты загрузки файлов» описан в главе Администрирование знаний.

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

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

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

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

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

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

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

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

Конвейер определяется типом файла, а не настройками пространства.

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

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

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

Сканы, фотографии и рукописный текст принимает общая область загрузки базы знаний: Выбрать файлы или Импорт с сайта. Платформа сама определяет растр и направляет его на распознавание; при обычном разборе текстового слоя Docling работает без распознавания растра.

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

Загружаем изображение…

Если распознавание в контуре не настроено, PDF переходит на текстовый маршрут с меткой Использован упрощённый способ обработки, изображение сохраняется без индексации, а там, где запасного пути нет, показывается причина Распознавание сканов не настроено — обратитесь к администратору. При частичном распознавании появляется одна метка Часть страниц пропущена. Настройка распознавания описана в главе Распознавание документов и речи.

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

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

Если Docling недоступен, PDF с текстовым слоем распознаёт vision-модель: документ появляется с меткой Использован упрощённый способ обработки, но без изображений. Документ, которому нужен именно Docling, стоит в состоянии Требуется действие. Проверьте:

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

Импорт большого файла завершается со статусом «Не удалось обработать»

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

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

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

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

В файле нет индексируемого текста. Платформа показывает причину В документе не нашлось текста для индексации. Скан распознаётся сам, если распознавание настроено; иначе проверьте главу Распознавание документов и речи.

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

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

Что дальше

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