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

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

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

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

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

Нужны собственная тестовая машина с поддерживаемым Python-окружением или контейнерным runtime и обезличенный PDF, в котором можно заранее переписать заголовки колонок и несколько контрольных строк. Зафиксируйте версию установленного пакета, ОС, способ запуска, выбранные OCR-язык и pipeline; коммит документации сам по себе не фиксирует версию вашего pip-пакета. Для закрытого пилота заранее задайте разрешённые входы, лимиты загрузки, срок хранения результатов, сеть и правила удаления файлов. Настройки сервиса содержат ограничения размера файла, числа страниц и таймаута, но их значения и ресурсы выбирает оператор после пробы. s1 s2 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 s3

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

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

По закреплённому коду GET /health отвечает на проверку жизни приложения, а GET /ready проверяет и готовность загруженных моделей/очереди; сначала запросите http://127.0.0.1:5001/ready и дождитесь успешного ответа. Даже готовность не говорит о правильности распознавания таблицы. При 503 на /ready проверьте логи и подготовку моделей, не отправляя сразу бизнес-документ. s6 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 s6

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

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

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

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

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

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

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

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

Сохраните для собственного теста: хеш и обезличенное описание PDF, версию пакета, настройки, HTTP-статус, status преобразования, ошибки и сравнение контрольных строк с исходником. Решение о передаче результата в 1С принимает человек и правила учёта, а не один ответ OCR; для требований к полям и ошибкам откройте задачу распознавания документов для 1С. Если нужна только пакетная разборка в одном процессе, вернитесь к обычному Docling; альтернативный разборщик MinerU сравнивайте на том же образце. s1 s2

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