# Docling Serve: локальный API для PDF и проверка таблиц

Источник: https://modelium.tech/zhurnal/docling-serve-lokalno/

Docling Serve предоставляет HTTP API для преобразования PDF и других документов с помощью Docling. Для пробного разбора на собственной машине привяжите сервер к 127.0.0.1, отправьте тестовый PDF в /v1/convert/file и сверьте извлечённую таблицу с оригиналом. Локальная установка сама по себе не означает закрытый контур: сетевой адрес, доступ к API, источники URL и выбранные модели требуют отдельной проверки.

**Версия и границы:** исходный код и документация закреплены на коммите Docling Serve `07b1d3d` от 1 октября 2026 года; текст проверен 5 октября 2026 года. Команды ниже — протокол для вашего стенда. Modelium не запускал сервер, не загружал ваши документы и не измерял точность. [s1](#src-s1) [s6](#src-s6)

## Когда нужен именно Docling Serve, а не обычный Docling?

Если нескольким внутренним приложениям нужен единый HTTP-вход для разбора PDF, Docling Serve оборачивает Docling в API. Если вы обрабатываете файлы в одном Python-процессе, отдельный сервис добавляет сетевую поверхность и операционные обязанности без обязательной пользы; сначала посмотрите [обычный путь Docling](/zhurnal/docling/). Здесь результат — ответ API по одному разрешённому тестовому PDF и проверенная вручную таблица, а не обещание безошибочного OCR. [s1](#src-s1) [s2](#src-s2) [s3](#src-s3)

Цепочка выбора: **документ с известной таблицей → Docling и его компоненты OCR/раскладки → CPU либо совместимое ускорение на вашем устройстве → Docling Serve → ответ в Markdown → ручное сравнение с PDF**. Документация предлагает как Python-пакет, так и контейнерные варианты; размеры образов и примеры GPU-развёртывания не являются минимальными требованиями RAM/VRAM к вашей конфигурации. Точность зависит от входа и настроек, а не следует из названия API. [s1](#src-s1) [s2](#src-s2) [s4](#src-s4)

## Что подготовить перед запуском локального API?

Нужны собственная тестовая машина с поддерживаемым Python-окружением или контейнерным runtime и **обезличенный** PDF, в котором можно заранее переписать заголовки колонок и несколько контрольных строк. Зафиксируйте версию установленного пакета, ОС, способ запуска, выбранные OCR-язык и pipeline; коммит документации сам по себе **не фиксирует версию вашего pip-пакета**. Для закрытого пилота заранее задайте разрешённые входы, лимиты загрузки, срок хранения результатов, сеть и правила удаления файлов. Настройки сервиса содержат ограничения размера файла, числа страниц и таймаута, но их значения и ресурсы выбирает оператор после пробы. [s1](#src-s1) [s2](#src-s2) [s3](#src-s3)

Для воспроизводимого теста на одной машине установите пакет в отдельное окружение командой `python -m pip install docling-serve`; затем запустите `docling-serve run --host 127.0.0.1 --port 5001`. README показывает установку через pip и команду `run`, а конфигурация подтверждает `--host`/`--port`. **Адрес **`**0.0.0.0**`** является значением по умолчанию для **`**run**`, поэтому явно оставьте `127.0.0.1`: это ограничивает слушающий интерфейс, но не доказывает отсутствия исходящих соединений. Загрузка весов при первом старте может зависеть от сети; заранее подготовленные артефакты задаются `DOCLING_SERVE_ARTIFACTS_PATH`. [s1](#src-s1) [s3](#src-s3)

Контейнер из README публикует порт как `-p 5001:5001`; не копируйте эту публикацию буквально для частных документов без проверки интерфейса привязки и сетевых правил контейнера/хоста. При нескольких workers настройки, переданные только CLI, документация не гарантирует: для такого режима используйте переменные среды и повторно проверяйте фактический адрес. Возможности CPU/GPU и зависимости Docker-профиля смотрите в официальных примерах, а не угадывайте требуемую память по размеру образа. [s1](#src-s1) [s3](#src-s3) [s4](#src-s4)

## Как передать PDF и понять, что сервер готов?

По закреплённому коду `GET /health` отвечает на проверку жизни приложения, а `GET /ready` проверяет и готовность загруженных моделей/очереди; сначала запросите `http://127.0.0.1:5001/ready` и дождитесь успешного ответа. Даже готовность не говорит о правильности распознавания таблицы. При 503 на `/ready` проверьте логи и подготовку моделей, не отправляя сразу бизнес-документ. [s6](#src-s6) [s3](#src-s3)

Для файла используйте `**POST /v1/convert/file**` с `multipart/form-data`, полем `files` и тестовым `sample.pdf`; в документации есть пример `curl -F 'files=@sample.pdf;type=application/pdf' -F 'from_formats=pdf' -F 'to_formats=md' http://127.0.0.1:5001/v1/convert/file`. Здесь `sample.pdf` — файл **на вашей машине**, а не опубликованный документ Modelium; подставьте реальное имя. Не выставляйте `Content-Type: multipart/form-data` вручную без boundary: пусть его сформирует клиент. В варианте для одного файла результат по документации имеет `status`, `document.md_content` и `errors`; запишите статус и обезличенный вывод, затем сопоставьте заголовок, колонки, объединённые ячейки, строки и числа с оригинальным PDF. Код подтверждает маршрут и приём `files`. [s2](#src-s2) [s6](#src-s6)

В `options`/форме доступны `do_ocr`, `ocr_lang`, `do_table_structure` и `table_mode`; документация описывает извлечение структуры таблиц и предупреждает, что сопоставление ячеек может ломаться на объединённых колонках. Сначала зафиксируйте настройки по умолчанию и результат на одном входе, а потом меняйте по одной настройке и повторяйте сравнение. Ошибку в сумме или пропущенную строку нельзя маскировать «успешным HTTP 200»: это статус транспорта, не приёмка данных. [s2](#src-s2)

## Почему запрос по URL требует отдельной политики безопасности?

Вторая ветка, `POST /v1/convert/source`, принимает массив `sources`, в том числе объект `{"kind":"http","url":"https://..."}`: сервер скачивает переданный адрес. **Для частного пилота предпочтите загрузку файла и ограничьте или изолируйте доступ к URL-входу на уровне сетевого периметра и политики входов**, иначе доступ клиента к API может превратиться в исходящий запрос сервера к нежелательному адресу. Это модель угроз, а не сообщение о выполненной атаке. Переменная `DOCLING_SERVE_ENABLE_REMOTE_SERVICES=false` относится, согласно документации, к удалённым компонентам обработки, например VLM API, и **не является доказательством запрета HTTP-источников**. Проверьте фактический исходящий трафик. [s3](#src-s3) [s5](#src-s5) [s6](#src-s6)

Осторожно со старыми примерами: в `docs/usage.md` того же коммита местами остались `http_sources`/`file_sources`, тогда как **специальный migration guide и README используют v1 **`**sources**`** + **`**kind**`. Для нового клиента не переносите старый JSON вслепую; сверяйте установленную версию и её `/openapi.json` в доверенном тестовом окружении. Это отмеченное расхождение двух официальных файлов, а не универсальная обратная совместимость. [s1](#src-s1) [s2](#src-s2) [s5](#src-s5) [s6](#src-s6)

## Достаточно ли API-ключа для закрытого контура?

Нет. При заданном `DOCLING_SERVE_API_KEY` защищённые маршруты требуют `X-Api-Key`; код авторизации возвращает 401 при отсутствующем или неверном ключе. Без заданного ключа эта проверка не является ограничителем доступа. Храните значение вне статьи, истории команд и логов; перед подключением рабочих клиентов проверьте тестом отказ без ключа и доступ с ключом **без публикации самого секрета**. Защиту URL-входа, TLS, пользователей, журналов, файлов и исходящего трафика надо проектировать отдельно. [s3](#src-s3) [s6](#src-s6) [s7](#src-s7)

`/health` и `/ready` реализованы отдельно от защищённых convert-маршрутов. Конфигурация также включает по умолчанию документацию API, `/v1/capabilities`, `/version`, метрики Prometheus и широкий CORS; часть этих маршрутов доступна без ключа или регулируется отдельными переключателями. Не рассчитывайте, что `DOCLING_SERVE_API_KEY` делает **каждый** URL закрытым. Уберите ненужные публичные возможности, изолируйте порт, зафиксируйте сетевую политику и отдельно проведите проверку [офлайн-контура](/zhurnal/proverka-offline-kontura-ii/); CORS сам по себе не firewall. [s3](#src-s3) [s6](#src-s6) [s7](#src-s7)

## Как принять результат и когда выбрать другой путь?

Сохраните для собственного теста: хеш и обезличенное описание PDF, версию пакета, настройки, HTTP-статус, `status` преобразования, ошибки и сравнение контрольных строк с исходником. Решение о передаче результата в 1С принимает человек и правила учёта, а не один ответ OCR; для требований к полям и ошибкам откройте [задачу распознавания документов для 1С](/zadachi/raspoznavanie-dokumentov-1s/). Если нужна только пакетная разборка в одном процессе, вернитесь к [обычному Docling](/zhurnal/docling/); альтернативный разборщик [MinerU](/zhurnal/mineru-lokalno/) сравнивайте на **том же** образце. [s1](#src-s1) [s2](#src-s2)

После эксперимента остановите тестовый сервер, удалите временные копии конфиденциальных файлов по правилам вашей организации и проверьте отсутствие открытого слушающего порта. **Основной следующий шаг:** [подготовить контрольный PDF и простой путь Docling](/zhurnal/docling/), а Docling Serve подключать только если действительно нужен общий локальный API. Ни точность, ни отсутствие сетевого выхода Modelium на вашем стенде не проверял. [s1](#src-s1) [s3](#src-s3)

## Источники

1. [Docling Serve README: запуск, v1 endpoint и назначение проекта](https://github.com/docling-project/docling-serve/blob/07b1d3d3b515afd9196148e0353d54ea38de2a37/README.md) — получено 2026-10-05
2. [Docling Serve Usage: параметры файлового API, OCR и структура ответа](https://github.com/docling-project/docling-serve/blob/07b1d3d3b515afd9196148e0353d54ea38de2a37/docs/usage.md) — получено 2026-10-05
3. [Docling Serve Configuration: host, port, API key, UI и удалённые сервисы](https://github.com/docling-project/docling-serve/blob/07b1d3d3b515afd9196148e0353d54ea38de2a37/docs/configuration.md) — получено 2026-10-05
4. [Docling Serve Deployment: локальные и защищённые примеры](https://github.com/docling-project/docling-serve/blob/07b1d3d3b515afd9196148e0353d54ea38de2a37/docs/deployment.md) — получено 2026-10-05
5. [Docling Serve: переход от v1alpha к v1 и формат sources](https://github.com/docling-project/docling-serve/blob/07b1d3d3b515afd9196148e0353d54ea38de2a37/docs/v1_migration.md) — получено 2026-10-05
6. [Docling Serve app.py: маршруты health/ready/convert и проверка ключа](https://github.com/docling-project/docling-serve/blob/07b1d3d3b515afd9196148e0353d54ea38de2a37/docling_serve/app.py) — получено 2026-10-05
7. [Docling Serve auth.py: проверка X-Api-Key и HTTP 401](https://github.com/docling-project/docling-serve/blob/07b1d3d3b515afd9196148e0353d54ea38de2a37/docling_serve/auth.py) — получено 2026-10-05