Docling в Docker, полное руководство по развертке на своем VPS/VDS сервере с Docker

Это руководство поможет вам развернуть Docling — сервер для парсинга документов (PDF, DOCX, PPTX, HTML и других форматов) в контейнере Docker. Данные остаются на вашем сервере и не передаются третьим лицам .

1. Системные требования

Компонент	Требование
ОС	Linux (локальный или облачный сервер)
Архитектура	amd64 (x86_64) или arm64 (aarch64)
Docker	Установленный Docker Engine
ОЗУ	~2 ГБ свободной памяти (для CPU-инференса)
Диск	~4 ГБ для Docker-образа
Интернет	Требуется только для загрузки документов по URL; модели уже встроены в образ

Для GPU-ускорения (NVIDIA CUDA) дополнительно потребуется:

• NVIDIA GPU с Compute Capability 6.0+
• Драйвер NVIDIA 575.57.08+ (Linux) или 576.57+ (Windows)
• Установленный NVIDIA Container Toolkit
• Образ :cuda поддерживает только linux/amd64 

2. Проверка окружения

Убедитесь, что Docker установлен и работает:

bash

docker --version
docker compose version

3. Выбор образа

Доступны два основных репозитория:

Вариант A: hwdsl2/docling-server — легковесный образ с API и опциональным веб-интерфейсом :

bash

# CPU-версия
docker pull hwdsl2/docling-server

# GPU-версия (CUDA)
docker pull hwdsl2/docling-server:cuda

Вариант B: quay.io/docling-project/docling-serve — официальный образ с веб-интерфейсом :

bash

docker pull quay.io/docling-project/docling-serve:v1.9.0

4. Быстрый старт (docker run)

CPU-версия :

bash

docker run \
    --name docling \
    --restart=always \
    -v docling-data:/var/lib/docling \
    -p 5001:5001 \
    -d hwdsl2/docling-server

GPU-версия (NVIDIA CUDA) :

bash

docker run \
    --name docling \
    --restart=always \
    --gpus=all \
    -v docling-data:/var/lib/docling \
    -p 5001:5001 \
    -d hwdsl2/docling-server:cuda

С включенным веб-интерфейсом (официальный образ) :

bash

docker run -d \
    --restart unless-stopped \
    --name docling-serve \
    -p 5300:5001 \
    -e DOCLING_SERVE_ENABLE_UI=1 \
    -e GRADIO_MCP_SERVER=True \
    quay.io/docling-project/docling-serve:v1.9.0

После запуска проверьте логи:

bash

docker logs docling

Дождитесь сообщения "Docling document parsing server is ready" .

5. Развертывание через Docker Compose

Создайте директорию и файл docker-compose.yaml :

bash

mkdir -p /data/docling && cd /data/docling

Базовый docker-compose.yaml :

yaml

services:
  docling:
    image: hwdsl2/docling-server
    container_name: docling
    restart: always
    ports:
      - "5001:5001/tcp"
    volumes:
      - docling-data:/var/lib/docling

volumes:
  docling-data:
    name: docling-data

С включенным UI и MCP (официальный образ) :

yaml

version: '3'
services:
  docling-serve:
    image: quay.io/docling-project/docling-serve:v1.9.0
    container_name: docling-serve
    restart: always
    ports:
      - "5300:5001"
    environment:
      - DOCLING_SERVE_ENABLE_UI=1
      - GRADIO_MCP_SERVER=True

Для GPU (NVIDIA CUDA) создайте docker-compose.cuda.yml :

yaml

services:
  docling:
    image: hwdsl2/docling-server:cuda
    container_name: docling
    restart: always
    ports:
      - "5001:5001/tcp"
    volumes:
      - docling-data:/var/lib/docling
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

volumes:
  docling-data:
    name: docling-data

Запуск через Compose:

bash

docker compose up -d
# или для GPU:
docker compose -f docker-compose.cuda.yml up -d

6. Настройка переменных окружения

Для гибкой настройки используйте файл .env :

bash

# Создайте файл docling.env
DOCLING_ENABLE_UI='true'
DOCLING_LOG_LEVEL='INFO'
DOCLING_MAX_FILE_SIZE='50000000'    # ~50 MB
DOCLING_API_KEY='your-secure-api-key'

Переменная	Описание	Значение по умолчанию
DOCLING_PORT	Порт API	5001
DOCLING_API_KEY	API-ключ для аутентификации	автогенерация
DOCLING_ENABLE_UI	Включить веб-интерфейс (true/false)	false
DOCLING_LOG_LEVEL	Уровень логирования	INFO
DOCLING_WORKERS	Количество Uvicorn-воркеров	1
DOCLING_DEVICE	Устройство: cpu, cuda, auto	cpu
DOCLING_LOCAL_ONLY	Отключить загрузку моделей (офлайн-режим)	не задано
DOCLING_MAX_PAGES	Максимальное число страниц	безлимит
DOCLING_MAX_FILE_SIZE	Максимальный размер файла (байт)	безлимит

Важно: При использовании более одного воркера (UVICORN_WORKERS > 1) с docling-serve возможна ошибка Task Not Found (404). Рекомендуется оставлять UVICORN_WORKERS=1 .

7. Проверка работы

Доступ к веб-интерфейсу :

text

http://<IP_сервера>:5300/ui   # для официального образа
# или
http://<IP_сервера>:5001/ui   # при DOCLING_ENABLE_UI=true

API-запрос на конвертацию :

bash

curl -X POST http://<IP_сервера>:5001/v1/convert/source \
    -H "Content-Type: application/json" \
    -d '{"sources": [{"kind": "http", "url": "https://arxiv.org/pdf/2501.17887"}]}'

Если установлен API-ключ, добавьте заголовок:

bash

-H "X-Api-Key: your-secure-api-key"

8. Важные замечания

1. Безопасность: Для публичного доступа обязательно используйте HTTPS через reverse proxy (например, nginx). В целях безопасности настройте привязку порта только к локальному интерфейсу: -p 127.0.0.1:5001:5001 .
2. Постоянное хранение: Том docling-data сохраняет модели и настройки при перезапуске контейнера.
3. Офлайн-режим: Если задать DOCLING_LOCAL_ONLY=true, контейнер не будет пытаться загружать модели из HuggingFace — полезно для изолированных сред .
4. GPU: Для использования GPU укажите образ с тегом :cuda, добавьте --gpus=all и установите DOCLING_DEVICE=cuda .