Docling — интеллектуальный импорт документов

Версия: 1.62

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

Установка на локальную машину: пошаговая инструкция для разработчика — Docling: установка на локальную машину.

Что даёт Docling

Без Docling импорт файлов работает в режиме плоского текста — изображения, таблицы и структура теряются.

С Docling при импорте сохраняется:

Элемент	Без Docling	С Docling
Заголовки H1–H3	❌ плоский текст	✅
Таблицы	❌	✅
Списки (маркированные, нумерованные)	❌	✅
Изображения на нужных позициях	❌ в конце	✅
Зоны ключ-значение (квитанции, формы)	❌ построчно	✅ таблица 2 колонки
Жирный/курсив (если PDF поддерживает)	❌	✅

Поддерживаемые форматы

Docling обрабатывает следующие форматы файлов:

PDF — включая сканы (через OCR)
DOCX — Microsoft Word 2007+

Остальные форматы (TXT, HTML и др.) обрабатываются стандартным текстовым парсером без Docling.

Развёртывание Docling

Docling запускается как отдельный Docker-контейнер. Конфигурационный файл: docker-compose.docling.yml.

Запуск

docker compose -f docker-compose.docling.yml up -d

Обновление

docker compose -f docker-compose.docling.yml pull
docker compose -f docker-compose.docling.yml up -d --force-recreate

Остановка

docker compose -f docker-compose.docling.yml down

Параметры docker-compose

version: "3.9"

services:
  docling:
    image: ghcr.io/docling-project/docling-serve:latest
    container_name: docling-serve
    ports:
      - "5001:5001"
    environment:
      DOCLING_SERVE_HOST: "0.0.0.0"
      DOCLING_SERVE_CONCURRENCY: "2"
      DOCLING_SERVE_ENABLE_UI: "1"
      DOCLING_SERVE_MAX_SYNC_WAIT: "600"
    volumes:
      - docling_models:/root/.cache/docling
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5001/health"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 120s
    restart: unless-stopped

volumes:
  docling_models:

Описание параметров

`ports: "5001:5001"`

Порт, на котором доступен Docling API. Левая часть — порт на хосте, правая — внутри контейнера.

Должен совпадать с DOCLING_API_URL в .env приложения (по умолчанию http://localhost:5001).

`DOCLING_SERVE_HOST: "0.0.0.0"`

Адрес, на котором Docling принимает входящие соединения внутри контейнера. Значение 0.0.0.0 означает «принимать со всех интерфейсов» — это стандарт для Docker.

Не меняйте это значение без необходимости.

`DOCLING_SERVE_CONCURRENCY: "2"`

Количество документов, которые Docling обрабатывает одновременно.

Значение	Применение
`1`	Минимальная нагрузка, сервер с ограниченными ресурсами
`2`	Рекомендуется по умолчанию
`4+`	Высоконагруженные инсталляции (нужно ≥16 ГБ RAM)

Каждый параллельный поток обработки потребляет значительный объём памяти (особенно при OCR). Увеличивайте осторожно.

`DOCLING_SERVE_ENABLE_UI: "1"`

Включает веб-интерфейс Docling для ручного тестирования конвертации документов.

"1" — UI доступен по адресу http://<host>:5001
"0" — UI отключён (только API)

Рекомендуется оставить включённым для диагностики.

`DOCLING_SERVE_MAX_SYNC_WAIT: "600"`

Максимальное время (в секундах), которое Docling ждёт завершения конвертации одного документа, прежде чем вернуть ошибку.

Значение	Применение
`120`	Значение по умолчанию в оригинальном образе (мало для больших файлов)
`600`	Рекомендуемое — 10 минут, покрывает большинство документов
`900+`	Очень большие или насыщенные изображениями PDF

Важно: Это серверный лимит самого Docling. Таймаут клиента в приложении (.env) должен быть меньше этого значения, иначе приложение прервёт ожидание раньше, чем Docling вернёт ошибку.

`volumes: docling_models`

Именованный том для кэша ML-моделей Docling. При первом запуске Docling скачивает модели (~2–4 ГБ). Том сохраняет их между перезапусками контейнера.

Не удаляйте том без необходимости — иначе модели загрузятся заново при следующем старте (займёт несколько минут).

`healthcheck`

Периодическая проверка доступности Docling. Параметры:

Параметр	Значение	Описание
`interval`	`30s`	Как часто проверять
`timeout`	`10s`	Таймаут одной проверки
`retries`	`5`	Сколько неудач подряд считать проблемой
`start_period`	`120s`	Сколько ждать после старта до первой проверки

start_period: 120s задан потому, что при первом запуске Docling загружает модели — это занимает время.

Переменные среды приложения

В файле .env основного приложения необходимо указать:

# URL контейнера Docling (должен совпадать с портом в docker-compose)
DOCLING_API_URL=http://localhost:5001

# Включить/выключить Docling для импорта
DOCLING_ENABLED=true

Переменная	Значение	Описание
`DOCLING_API_URL`	`http://localhost:5001`	Адрес Docling API. Если Docling в отдельной сети Docker — укажите IP или имя сервиса.
`DOCLING_ENABLED`	`true` / `false`	Глобальный включатель. При `false` все импорты идут через стандартный парсер без структуры.

После изменения .env необходимо перезапустить приложение.

Проверка работоспособности

1. Проверка через healthcheck

curl http://localhost:5001/health

Ожидаемый ответ: {"status":"ok"} или аналогичный JSON со статусом 200.

2. Проверка через UI

Откройте в браузере: http://<host>:5001

Если DOCLING_SERVE_ENABLE_UI=1, откроется веб-интерфейс Docling, где можно загрузить документ и увидеть результат конвертации.

3. Проверка через логи приложения

При успешном импорте в логах будет:

INFO: Docling conversion succeeded — filename=..., pageCount=..., textsCount=...
INFO: import-file: completed — importSource=docling

При недоступности Docling:

WARN: Docling unavailable (health-check failed), using fallback
INFO: import-file: completed — importSource=pdfjs

Влияние на импорт документов

Что происходит при включённом Docling

При загрузке PDF или DOCX в базу знаний запрос отправляется в Docling.
Docling возвращает структурированный JSON с элементами документа.
Приложение конвертирует их в блоки BlockNote (заголовки, параграфы, таблицы, изображения).
Для PDF дополнительно извлекаются данные шрифтов для определения жирного/курсивного текста.

Что происходит при недоступном Docling

Если Docling недоступен или вернул ошибку, приложение автоматически переключается на fallback-режим:

Текст извлекается плоским (без структуры)
Изображения добавляются в конец документа
importSource: pdfjs в логах

Fallback работает без перебоев — пользователь увидит документ, но без форматирования.

Параметр	Минимум	Рекомендуется
CPU	2 ядра	4+ ядра
RAM	4 ГБ	8–16 ГБ
Диск (для моделей)	5 ГБ	10 ГБ

Частые проблемы

Импорт идёт без структуры (плоский текст)

Симптомы: Нет заголовков, все изображения в конце, importSource: pdfjs в логах.

Причины и решения:

DOCLING_ENABLED=false в .env → установите true и перезапустите приложение.
Docling не запущен → docker compose -f docker-compose.docling.yml up -d.
DOCLING_API_URL указывает на неверный адрес → проверьте значение в .env.
Docling недоступен из-за сети → проверьте curl http://localhost:5001/health.

Импорт зависает или работает очень долго

Симптомы: Загрузка файла не завершается.

Причины:

Большой файл (100+ страниц с изображениями)
Недостаточно RAM для обработки

Решения:

Подождать: для больших файлов обработка может занимать 5–10 минут.
Проверить память контейнера: docker stats docling-serve.
При нехватке RAM — увеличить память сервера или уменьшить DOCLING_SERVE_CONCURRENCY до 1.

Ошибка "Conversion is taking too long"

Симптомы: В логах: "Conversion is taking too long. The maximum wait time is configured as DOCLING_SERVE_MAX_SYNC_WAIT=120".

Причина: Значение DOCLING_SERVE_MAX_SYNC_WAIT слишком мало для данного документа.

Решение: Увеличьте DOCLING_SERVE_MAX_SYNC_WAIT в docker-compose.docling.yml и пересоздайте контейнер:

docker compose -f docker-compose.docling.yml up -d --force-recreate

Контейнер не запускается / падает

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

Решение:

Проверьте логи: docker logs docling-serve --tail 50
Убедитесь в наличии ≥4 ГБ свободной RAM
При первом запуске подождите 2–3 минуты — Docling скачивает модели

После изменения параметров изменения не применились

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