UnicaДокументацияНа сайт

Docling на локальном стенде

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

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

  • установленные и запущенные Docker и Docker Compose;
  • локальная копия репозитория платформы и работающее приложение с базой данных и объектным хранилищем;
  • файл .env приложения, доступный на запись;
  • свободное место на диске под кэш моделей разбора;
  • PDF с заголовками и таблицей для проверки.

Как поднять контейнер Docling

Сервис docling объявлен в docker-compose.yml платформы, поэтому поднимается той же командой, что и остальные контейнеры стенда. Отдельного compose-файла для Docling нет.

Запустите сервис из корня репозитория:

docker compose up -d docling

Первый запуск занимает несколько минут: Docling скачивает модели разбора и кладёт их в именованный том docling_models. Повторные запуски проходят быстро — модели остаются в томе.

Убедитесь, что контейнер поднялся и прошёл проверку готовности:

docker compose ps docling

В колонке STATUS должно появиться healthy. Значение starting в колонке STATUS означает, что контейнер ещё не прошёл проверку готовности: первую проверку Docker делает через 120 секунд после старта, и этот запас покрывает загрузку моделей.

Как связать приложение с Docling

Приложение обращается к Docling по адресу из переменной DOCLING_API_URL и делает это, только когда DOCLING_ENABLED равна строке true. Адрес зависит от того, где работает само приложение: в контейнере или на машине разработчика.

Где запущено приложениеЗначение DOCLING_API_URLЧто нужно дополнительно
В контейнере вместе с остальным стендомhttp://docling:5001Ничего: сервисы видят друг друга по именам внутри общей сети
На машине разработчика командой npm run devhttp://localhost:5001Опубликованный порт контейнера

В поставке порт Docling наружу не публикуется. Если приложение работает на машине разработчика, поднимите сервис отдельной командой с публикацией порта вместо docker compose up -d docling:

docker run -d --name docling -p 5001:5001 -v docling_models:/opt/app-root/src/.cache/docling/models -e DOCLING_SERVE_HOST=0.0.0.0 ghcr.io/docling-project/docling-serve:v1.13.1

Пропишите в .env приложения обе переменные:

DOCLING_ENABLED=true
DOCLING_API_URL=http://localhost:5001

Перезапустите приложение: переменные среды читаются при старте процесса.

Важно. Значение DOCLING_ENABLED сравнивается со строкой true буквально — True, 1 и yes оставят Docling выключенным.

Как проверить разбор

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

Запросите состояние сервиса с той же машины, где работает приложение:

curl http://localhost:5001/health

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

Затем проверьте разбор на реальном файле:

  1. Откройте в платформе любую базу знаний.
  2. Загрузите подготовленный PDF.
  3. Дождитесь завершения импорта.
  4. Откройте импортированный документ.

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

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

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

Контейнер Docling живёт независимо от остального стенда, поэтому его можно останавливать и обновлять отдельно. Том с моделями при этом сохраняется, и повторная загрузка не потребуется. Если Docling поднят командой docker run, останавливайте контейнер командой docker stop docling, а обновляйте удалением через docker rm docling и повторным запуском.

Остановите сервис:

docker compose stop docling

Скачайте свежий образ:

docker compose pull docling

Пересоздайте контейнер на скачанном образе:

docker compose up -d --force-recreate docling

Пересоздание нужно и после правки окружения контейнера: переменные среды применяются при создании контейнера, а не при перезапуске.

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

Порт 5001 занят другим процессом

Опубликуйте контейнер на свободном порту машины, оставив внутренний порт прежним, и укажите выбранный порт машины в DOCLING_API_URL. Внутри контейнера Docling всегда слушает 5001, меняется только внешняя часть сопоставления портов.

Импорт идёт без структуры, хотя контейнер запущен

Приложение не видит сервис или не обращается к нему. Проверьте по порядку:

  • DOCLING_ENABLED=true в .env, приложение перезапущено после правки;
  • DOCLING_API_URL соответствует способу запуска приложения из таблицы выше;
  • curl к /health отвечает кодом 200 с той же машины, где работает приложение;
  • загружаемый PDF содержит текстовый слой, а не скан.

Первый запуск идёт очень долго

Загружаются модели разбора. Дождитесь состояния healthy в выводе docker compose ps docling и следите за ходом загрузки в логах: docker logs docling --tail 100.

Что дальше