commonforms

CommonForms берёт плоский PDF - отсканированный или экспортированный документ с напечатанными пустыми полями, чекбоксами и строками подписи, но без интерактивных полей - и делает версию, в которую действительно можно вводить текст. Утилита определяет, где должны находиться поля формы, и записывает их обратно в PDF как виджеты AcroForm. В комплекте идут CLI и API для Python, а по умолчанию всё работает на CPU, так что GPU для пробы не потребуется. Распознавание выполняют две открытые модели, FFDNet-S и FFDNet-L, опубликованные вместе со статьёй CommonForms: A Large, Diverse Dataset for Form Field Detection Джо Барроу (Joe Barrow).

Как это устроено

Основная задача - детекция объектов на отрендеренном изображении страницы: по картинке страницы нужно найти bounding box'ы полей и классифицировать каждое как текстовый ввод, чекбокс или подпись. Каждая страница PDF растеризуется в изображение (разрешение для инференса по умолчанию - 1600px по длинной стороне) и передаётся детектору. Каждый прямоугольник с уверенностью выше порога (по умолчанию 0.3) превращается в виджет формы в соответствующем месте выходного PDF.

На HuggingFace выложены модели двух размеров. FFDNet-L используется по умолчанию и работает точнее; FFDNet-S меньше и быстрее. Названия и список зависимостей (rfdetr, ultralytics, torch, transformers) указывают на стандартные backbone-сети детекции - архитектуры RF-DETR и семейства YOLO, - а не на что-то специфичное для PDF. Модели обучались на датасете CommonForms - большой и разнообразной коллекции реальных форм, которую автор также выложил на HuggingFace; в папке dataset/ репозитория лежит код предобработки для его сборки (помечен как work in progress).

Обнаруженные подписи по умолчанию становятся текстовыми полями; отдельный флаг меняет их на полноценные поля подписи. Имеющиеся поля формы во входном файле сбрасываются, если явно не указать сохранить их, поэтому повторный запуск на уже интерактивном PDF по умолчанию не дублирует виджеты.

Использование

Устанавливать лучше в изолированное окружение: набор зависимостей велик и фиксирует свежие версии, поэтому обычный pip install в общее окружение может обновить numpy, pillow и transformers на месте:

uv tool install commonforms
# or
pipx install commonforms

CLI, простейший вариант (CPU, FFDNet-L по умолчанию):

commonforms input.pdf output.pdf

Основные флаги: --model FFDNet-S для меньшей модели или путь к собственному файлу .pt, --device cuda (или индекс устройства) для GPU, --confidence 0.3 для настройки порога уверенности, --image-size 1600 для разрешения инференса, --fast, чтобы пожертвовать точностью ради двукратного ускорения на CPU, --multiline, чтобы распознанные текстовые блоки поддерживали многострочный ввод, --use-signature-fields для создания настоящих полей подписи и --keep-existing-fields для сохранения уже существующих в PDF виджетов.

Python API повторяет CLI: каждый флаг CLI соответствует именованному аргументу в prepare_form:

from commonforms import prepare_form

prepare_form(
    "path/to/input.pdf",
    "path/to/output.pdf",
    model="FFDNet-S",
    device="cpu",
    confidence=0.3,
)

Развёрнутые модели также доступны на detect.semanticdocs.org, если не хочется запускать инференс локально.

Ограничения

Инструмент находит и расставляет виджеты полей; он не читает и не извлекает значения из заполненной формы - это отдельная задача (см. structured-output-benchmark по извлечению данных из документов в JSON с помощью LLM). Качество распознавания ограничено моделями и распределением их обучающих данных, поэтому нестандартную вёрстку или типы полей вне датасета модель может пропустить или сместить, а порог уверенности - слишком грубый инструмент регулировки. Установка получается тяжёлой из-за стека глубокого обучения, а инференс на CPU для больших документов работает медленно, если не использовать --fast или GPU. Код предобработки датасета всё ещё помечен как work in progress. Изменение визуального отображения PDF вместо его содержимого - это ещё одна отдельная задача: её решает veil, инвертируя текст для тёмной темы и не трогая изображения.

Лицензия нестандартная (GitHub определяет её как NOASSERTION); автор просит пользователей не из академической среды связываться по электронной почте, так что перед коммерческим использованием стоит проверить условия в репозитории.

Проект держится на одном авторе и завязан на модели, поэтому он внесён в watchlist в ожидании появления второго мейнтейнера и более понятной лицензии.

Репозиторий: https://github.com/jbarrow/commonforms - 1 189 звёзд, собственная лицензия (NOASSERTION).