DocLayout-YOLO находит на странице заголовки, обычный текст, иллюстрации, таблицы, подписи, сноски и формулы, возвращает для каждого элемента координаты прямоугольника, класс и оценку уверенности, а затем позволяет сохранить наглядную разметку поверх исходного изображения. Для практической работы используются готовые веса, команда demo.py или Python-класс YOLOv10, параметры размера входа и порога уверенности, а при необходимости — отдельное подавление пересекающихся рамок по IoU.

Рабочий процесс строится вокруг одной страницы: сначала PDF переводят в изображение подходящего разрешения либо берут готовый скан, затем загружают весовой файл и передают путь в model.predict. Результат содержит объект boxes с координатами xyxy, номерами классов и confidence; его можно визуализировать методом plot, преобразовать в JSON, отсортировать в предполагаемом порядке чтения или передать в OCR, распознавание таблиц и формул.

В демонстрационном интерфейсе слева выбирают изображение, задают Confidence Threshold и NMS IOU Threshold, запускают Detect и получают справа страницу с цветными областями и подписями классов. Этот экран удобен для быстрой проверки порогов, но массовая обработка, собственные правила постобработки, экспорт координат и обучение выполняются через код; сам детектор не извлекает текст и не открывает PDF напрямую.

Что именно получает пользователь после анализа

Детектор не возвращает готовый отредактированный документ. Его основной результат — набор областей на растровой странице. Для каждой области доступны четыре координаты границ, идентификатор категории и оценка уверенности. Такой формат удобен тем, что не навязывает конкретный способ дальнейшей обработки: рамку таблицы можно передать отдельному модулю распознавания структуры, область формулы — специализированному распознавателю математической записи, а текстовые блоки — OCR с сохранением координат.

Координаты xyxy задаются как левая, верхняя, правая и нижняя границы прямоугольника. Перед сохранением их полезно привести к целым числам, ограничить размерами изображения и дополнить номером страницы. Если PDF был растрирован с известным масштабом, координаты можно пересчитать в пункты PDF: по горизонтали используется отношение ширины страницы в пунктах к ширине изображения в пикселях, по вертикали — аналогичное отношение высот. При обратном переносе следует учитывать, что начало координат в изображениях обычно находится сверху слева, а в PDF — снизу слева.

Оценка уверенности не равна вероятности того, что весь документ обработан правильно. Она относится к отдельной рамке и помогает отфильтровать слабые срабатывания. Для контроля качества полезно сохранять не только итоговые области, но и исходное значение confidence, имя модели, размер входа и выбранный порог. Тогда спорные страницы можно пересчитать с другими настройками без догадок о параметрах первого запуска.

Подготовка страниц перед распознаванием макета

Качество разметки начинается с растрирования. Если страница очень маленькая, тонкие линии таблиц, подписи и отдельные формулы превращаются в несколько пикселей и становятся неотличимыми от фона. Если изображение чрезмерно большое, возрастает расход памяти, а модель всё равно приводит его к заданному imgsz. Практический подход — сохранять пропорции страницы, выбирать разрешение, при котором мелкий текст и графика остаются различимыми, и затем проверять результат на нескольких типичных страницах.

Поворот на 90 или 180 градусов лучше исправлять до детекции. Модель видит геометрию страницы, однако большинство наборов для анализа макета ориентировано на нормально расположенные документы. Небольшой перекос иногда переносится без заметной потери, но сильный наклон делает горизонтальные заголовки и строки похожими на диагональные графические элементы. Для сканов полезно применять deskew, не обрезая поля и номера страниц.

Контраст и шум следует корректировать осторожно. Агрессивная бинаризация способна удалить светлые линии, серые подложки и тонкие рамки, которые помогают отличить таблицу от обычного текста. Одновременно грязный фон, тени у корешка и следы соседней страницы создают ложные прямоугольные структуры. Лучше сохранять цветное или качественное серое изображение, а усиление контраста проверять на контрольной выборке, а не включать автоматически для всех документов.

Запуск через demo.py

Сценарий demo.py предназначен для одиночной страницы и показывает минимальную последовательность действий. Обязательный параметр --model указывает путь к весовому файлу, --image-path — путь к изображению. Папка результата задаётся через --res-path; если её нет, сценарий создаёт каталог. Параметр --imgsz управляет размером, с которым изображение поступает в модель, --conf задаёт порог уверенности, а --line-width и --font-size меняют только вид сохранённой разметки.

Устройство выбирается автоматически: сначала проверяется CUDA, затем MPS, после чего используется CPU. Эта логика удобна для первого запуска, но в производственном коде выбор лучше делать явным. Явное значение предотвращает ситуацию, когда сервер после обновления драйвера внезапно переходит на CPU, а время обработки возрастает. В журнале стоит фиксировать выбранное устройство, время загрузки модели и время инференса каждой страницы.

Имя выходного файла в демонстрационном сценарии формируется заменой окончания .jpg на _res.jpg. Для PNG, TIFF или имён с несколькими точками безопаснее использовать pathlib и формировать имя по stem, иначе замена может не сработать или затронуть не ту часть строки. При пакетной обработке также следует добавлять номер страницы и уникальный идентификатор документа, чтобы результаты разных файлов не перезаписывали друг друга.

Работа через Python SDK

В SDK модель создаётся классом YOLOv10. Весовой файл можно передать локальным путём, загрузить через huggingface_hub или использовать from_pretrained для совместимого репозитория. После загрузки один и тот же объект следует применять ко всем страницам серии: повторное создание модели для каждой страницы тратит время на чтение весов и выделение памяти.

Метод predict принимает путь к изображению, объект PIL, массив NumPy или список входов в зависимости от используемого кода. В официальном примере передаются imgsz, conf и device. Возвращается коллекция результатов; при одиночном изображении обычно берут элемент с индексом ноль. Внутри него boxes.xyxy содержит координаты, boxes.cls — номера категорий, boxes.conf — оценки уверенности.

Результат нужно переносить на CPU перед преобразованием в обычные списки или JSON, если тензоры находятся на видеокарте. Типичная последовательность — detach, cpu, numpy, затем округление координат. Для больших документов лучше сохранять числовые данные отдельно от визуализации: изображение с рамками удобно человеку, но не подходит для точной последующей обработки и не хранит исходные значения confidence без потерь.

Минимальная схема обработки

Загрузите модель один раз, сформируйте список страниц, выполните predict, затем для каждого результата пройдите по boxes. Каждой области присвойте номер страницы, класс, confidence и координаты. После фильтрации запишите JSON и при необходимости создайте копию страницы с рамками. Такой порядок отделяет инференс от представления и позволяет менять правила сортировки без повторного запуска модели.

При обработке нескольких документов полезно хранить статус каждой страницы: успешно, пустой результат, ошибка чтения, нехватка памяти или повреждённое изображение. Тогда процесс можно безопасно продолжить после сбоя, не пересчитывая уже готовые страницы.

Какие категории распознаёт готовая модель DocStructBench

В официальной демонстрации используется десять категорий: title, plain text, abandon, figure, figure_caption, table, table_caption, table_footnote, isolate_formula и formula_caption. Категория abandon предназначена для областей, которые обычно исключают из содержательного потока, например служебных колонтитулов или элементов, не относящихся к основному тексту. Конкретное значение класса всегда следует брать из словаря names загруженной модели, а не копировать список из чужого проекта.

Разделение подписи и самого объекта полезно для построения структуры документа. Подпись к рисунку можно связать с ближайшей рамкой figure, подпись к таблице — с table, а примечание под таблицей — с table_footnote. Связь не создаётся автоматически: её формирует постобработка по расстоянию, расположению и отсутствию конфликтов с другими объектами.

Класс isolate_formula обозначает самостоятельную формулу, но не распознаёт её символы. После детекции область вырезают с небольшим полем и отправляют формульному OCR. Добавление поля важно: слишком тесный кроп может удалить индекс, номер у правого края или знак интеграла, выходящий за основную строку.

Размер входа imgsz и точность на мелких элементах

imgsz задаёт рабочий масштаб модели. В базовом сценарии используется 1024, а демонстрационная страница применяет 1280. Увеличение помогает сохранить мелкие подписи, сноски и тонкие формулы, однако требует больше видеопамяти и времени. Эффект не линейный: после определённого значения дополнительные пиксели дают небольшую прибавку, особенно если исходный скан уже размыт.

Для многостраничного набора разумно сделать тестовую матрицу из нескольких значений imgsz и двух-трёх порогов confidence. Проверять следует не только общее число рамок, но и конкретные ошибки: пропущенные подписи, слияние соседних колонок, дробление одного абзаца и ложные таблицы. Выбранная настройка должна соответствовать наиболее важному типу элемента, а не только среднему показателю.

Если страницы сильно различаются по размеру, можно определить два профиля. Обычные документы обрабатываются стандартным масштабом, а страницы с плакатами, мелкими таблицами или множеством колонок — увеличенным. Предварительный классификатор не обязателен: достаточно простого правила по отношению площади страницы, числу мелких контуров или типу документа.

Порог confidence

Низкий confidence сохраняет больше кандидатов и подходит для этапа, где последующий модуль умеет отбраковывать ошибки. Например, OCR может подтвердить, что рамка содержит текст, а анализ геометрии — что предполагаемая таблица имеет строки и столбцы. Цена низкого порога — множество ложных областей и пересечений.

Высокий порог упрощает результат, но опасен для небольших подписей, сканов плохого качества и нестандартных макетов. В демонстрации начальное значение равно 0,25; в простом сценарии demo.py задано 0,2. Эти числа подходят как отправная точка, но не являются универсальной рекомендацией. Для архивных сканов может потребоваться ниже, для чистых цифровых страниц — выше.

Порог можно задавать по классам. Таблицы и рисунки обычно имеют выраженную геометрию, тогда как подписи и формулы бывают маленькими. Если API не принимает отдельный порог для каждой категории, выполните инференс с общим низким значением, затем отфильтруйте полученные рамки собственным словарём порогов.

NMS и пересекающиеся рамки

Детектор может вернуть несколько близких рамок для одного объекта. Non-Maximum Suppression оставляет более уверенную рамку и удаляет кандидатов с большим пересечением. В официальной демонстрации NMS вызывается через torchvision.ops.nms, а начальный IoU Threshold равен 0,45. Чем ниже значение, тем агрессивнее удаляются пересекающиеся рамки.

Слишком агрессивный NMS способен удалить вложенные элементы. Таблица может находиться внутри крупной области страницы, подпись — рядом с рисунком, а формула — внутри текстового блока. Поэтому NMS следует применять к рамкам одного класса или учитывать допустимые пары классов. Глобальный NMS по всем категориям проще, но может разрушить полезную иерархию.

Если две колонки соприкасаются, их рамки могут иметь небольшое пересечение из-за неточного края. В таком случае высокий IoU Threshold сохраняет обе. Если один абзац распался на несколько почти одинаковых областей, порог можно снизить. Полезно выводить процент пересечения и номера классов для спорных случаев, а не настраивать NMS только по визуальному впечатлению от одной страницы.

Визуализация результата

Метод plot создаёт изображение с прямоугольниками и подписями. В demo.py доступны line_width и font_size, поэтому разметку можно адаптировать к разрешению страницы. На изображениях 3000–5000 пикселей линия шириной один пиксель почти незаметна, а слишком крупный шрифт закрывает соседние объекты. Значения лучше вычислять от ширины страницы или от imgsz.

Демонстрационный интерфейс использует отдельную функцию visualize_bbox. Она создаёт цветовую карту, рисует полупрозрачную заливку, контур и текст вида класс:оценка. Коэффициент alpha управляет прозрачностью. Полупрозрачная заливка удобна для понимания площади рамки, но на плотном тексте может ухудшить читаемость, поэтому для рабочих отчётов иногда оставляют только контуры.

Цвет должен быть стабильно связан с классом. Если палитра меняется между страницами, оператору трудно сравнивать результаты. Сохраняйте словарь class_id — цвет вместе с отчётом и не используйте случайную палитру при каждом запуске.

PDF как входной документ

Модель принимает изображение страницы, а не контейнер PDF. Поэтому документ сначала растрируют. Для цифрового PDF обычно достаточно рендеринга без OCR: текстовые объекты превращаются в пиксели, но визуальная структура сохраняется. Для сканированного PDF рендеринг просто извлекает изображение страницы с учётом поворота и обрезки.

Каждая страница должна иметь стабильное имя, например document_0001.png. Нумерация с ведущими нулями сохраняет правильную сортировку. Вместе с изображением полезно записать ширину, высоту, DPI, размер страницы в пунктах и матрицу поворота. Эти данные понадобятся для переноса координат обратно в PDF или для формирования кликабельных областей.

Перед растрированием проверьте CropBox и MediaBox. Некоторые файлы содержат большой невидимый запас, из-за которого полезное содержимое занимает малую часть изображения. В других документах CropBox обрезает метки на полях. Выберите одну геометрию для всех страниц и используйте её же при обратном пересчёте координат.

Поддерживаемые изображения и цветовые режимы

OpenCV и Pillow читают распространённые PNG и JPEG, а конкретный набор форматов зависит от сборки библиотек. Для архивной обработки предпочтителен PNG: он не добавляет артефакты вокруг букв и линий. JPEG допустим для фотографий и уже сжатых сканов, но повторное сохранение с низким качеством усиливает блочные и кольцевые искажения.

Многостраничный TIFF удобен для хранения, однако перед model.predict страницы лучше развернуть в отдельные изображения. Это упрощает повторный запуск, параллельную обработку и сопоставление ошибок. При чтении TIFF нужно учитывать разные DPI и ориентацию отдельных кадров.

Изображения с альфа-каналом следует свести к обычному RGB на белом фоне. Прозрачный фон может превратиться в чёрный в зависимости от пути чтения, и тогда текстовая страница станет инвертированной. Палитровые PNG также безопаснее переводить в RGB заранее.

Процессор, CUDA и MPS

На CUDA инференс обычно выполняется быстрее, особенно при крупном imgsz и пакетах страниц. Требуется совместимая сборка PyTorch и рабочий драйвер. Наличие команды nvidia-smi ещё не гарантирует, что torch видит устройство; проверять нужно torch.cuda.is_available и фактическое имя устройства.

MPS позволяет использовать графику Apple через PyTorch. Поддержка отдельных операций и числовая стабильность могут отличаться от CUDA, поэтому результаты следует сравнить на контрольных страницах. Если операция не поддерживается, библиотека может перейти на CPU или завершиться ошибкой. В таком случае полезно явно выбрать cpu для воспроизводимости.

CPU подходит для проверки и небольших объёмов. Время зависит от числа ядер, версии PyTorch, размера изображения и фоновой нагрузки. Чтобы не перегрузить сервер, ограничивайте число параллельных процессов: каждый процесс хранит собственную копию модели и может занять значительный объём памяти.

Память и обработка больших страниц

Расход памяти определяется не размером файла JPEG, а развернутым массивом пикселей и промежуточными тензорами. Страница 6000×4000 в RGB занимает десятки мегабайт ещё до преобразования в тензор. При пакетной обработке такие массивы быстро накапливаются, поэтому изображения лучше читать непосредственно перед инференсом и освобождать после сохранения результата.

Ошибка out of memory устраняется уменьшением imgsz, размера пакета или числа одновременно работающих процессов. После исключения Python может сохранить ссылки на тензоры; нужно удалить результат, завершить итерацию и при необходимости вызвать очистку кэша CUDA. Постоянный вызов empty_cache после каждой страницы обычно не ускоряет работу, но помогает при переменном размере входов и фрагментации памяти.

Для плакатов и очень длинных страниц возможна плиточная обработка. Изображение делят на перекрывающиеся окна, выполняют детекцию, переводят координаты в систему всей страницы и затем объединяют рамки. Перекрытие необходимо, иначе объект на границе плитки будет разрезан. После объединения нужен собственный NMS, учитывающий смещение окон.

Пакетный инференс

Модель может принимать список путей, что сокращает накладные расходы и повышает загрузку GPU. Однако пакет должен состоять из страниц сходного размера, иначе выравнивание увеличит объём пустых пикселей. Для смешанного архива полезно группировать страницы по ориентации и диапазону размеров.

Количество элементов в пакете подбирают по видеопамяти. Начните с одного, затем увеличивайте, отслеживая максимальное использование памяти и время на страницу. Оптимальный пакет — не обязательно самый большой: слишком крупный может увеличить задержку первой страницы и ухудшить устойчивость при попадании необычно большого изображения.

Результаты возвращаются в том же порядке, что и входы, но связь лучше фиксировать явным идентификатором. Список путей можно преобразовать в пары id, path, а затем соединить с результатами по позиции. При повторном запуске пропускайте страницы, для которых уже существует валидный JSON и совпадает контрольная сумма входного изображения.

Связка с OCR

DocLayout-YOLO определяет где находится текст, но не сообщает, что написано внутри. После детекции текстовые области вырезают и передают OCR. Кроп следует расширять на несколько пикселей или на долю высоты строки, чтобы не удалить крайние буквы. В то же время слишком большое поле может захватить соседнюю колонку.

Для каждой области сохраняйте координаты кропа и локальные координаты слов. После OCR локальные точки переводятся обратно на страницу добавлением смещения x_min и y_min. Если изображение дополнительно масштабировалось перед распознаванием, нужно учесть коэффициент масштаба.

Не все рамки plain text следует распознавать отдельно. Если модель разбивает длинную колонку на несколько областей, отдельный OCR может потерять переносы. Иногда выгоднее объединить вертикально соседние рамки одного класса, если их горизонтальные границы близки и между ними нет заголовка, рисунка или таблицы.

Порядок чтения

Детектор не гарантирует готовый порядок блоков. Простая сортировка сверху вниз работает только для одной колонки. Для двух колонок сначала определяют колоночные зоны, затем сортируют элементы внутри каждой. Заголовок, пересекающий обе колонки, должен идти до них, а подпись под рисунком — рядом с рисунком.

Практический алгоритм строит граф: вершины — рамки, связи — вероятное следование. Вертикальное расстояние, перекрытие по горизонтали, ширина элемента и класс дают веса. Затем выбирают маршрут без циклов. Для большинства документов достаточно правил, но журнальные развороты, плакаты и презентации требуют отдельного профиля.

Категория abandon помогает исключить номера страниц и служебные элементы, но полагаться только на неё нельзя. Номер страницы может быть размечен как plain text, а важная сноска — как abandon. Правила по расположению на полях должны учитывать повторяемость: если одинаковый блок встречается на многих страницах в одной зоне, вероятно, это колонтитул.

Таблицы, подписи и сноски

Рамка table сообщает границы таблицы, но не восстанавливает строки, столбцы и объединённые ячейки. Для структуры нужен отдельный модуль. Перед передачей таблицы вырежьте её с небольшим полем, сохраните исходный масштаб и проверьте, не попала ли подпись внутрь рамки. Если подпись выделена отдельным классом, её лучше исключить из кропа таблицы.

Связь table_caption с таблицей можно определять по ближайшей таблице по вертикали и значительному перекрытию по горизонтали. Подпись обычно располагается непосредственно над или под объектом, но в разных издательских стилях направление отличается. Если рядом две таблицы, выбирайте связь с минимальным нормированным расстоянием и проверяйте, не пересекает ли линия связи другой объект.

table_footnote часто находится под таблицей и имеет небольшой шрифт. Низкое разрешение и высокий confidence приводят к пропуску. Для документов, где примечания критичны, используйте увеличенный imgsz или второй проход по зоне вокруг найденной таблицы.

Рисунки и подписи к рисункам

Класс figure охватывает фотографию, график, схему или иной визуальный объект. Внутри могут быть текстовые метки, которые общий OCR не увидит, если обрабатываются только plain text. Если подписи на диаграмме важны, выполняйте OCR внутри figure отдельным профилем, не смешивая результат с основным потоком чтения.

figure_caption связывают с ближайшим рисунком, но составные рисунки создают неоднозначность. Один большой рисунок может содержать панели A–D, а модель выделит их отдельно или одной рамкой. Перед экспортом полезно объединять близкие figure, если они имеют общую подпись и выровнены в сетку.

При сохранении иллюстраций не растягивайте кроп до стандартного размера без сохранения пропорций. Для последующего анализа графика важны точные формы. Метаданные должны включать координаты, размер исходной страницы, confidence и ссылку на связанную подпись.

Формулы

isolate_formula предназначен для вынесенных формул, а formula_caption — для их номера или подписи. Встроенного распознавания математических символов нет. Формульный OCR лучше получать из исходного изображения, а не из копии с нарисованной рамкой: цветной контур может попасть в область и превратиться в ложный знак.

Номер формулы часто находится у правого поля и может быть отделён от основной рамки. Если formula_caption не найден, проверьте текстовые блоки на той же строке. При объединении учитывайте вертикальное перекрытие и небольшую ширину номера.

Строчные формулы внутри абзаца обычно не выделяются как isolate_formula, поскольку задача модели — крупные элементы макета. Их распознаёт OCR или математический модуль внутри текстового блока. Это различие важно при оценке полноты: отсутствие рамок вокруг всех формул не означает ошибку, если формулы встроены в строки.

Сложные многоколоночные страницы

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

В журнальном макете цветная подложка или рамка может восприниматься как отдельный рисунок. Если область содержит много текста, OCR подтверждает её содержимое, а геометрический анализ помогает решить, считать её текстовым блоком или иллюстрацией. Не стоит автоматически удалять figure только потому, что внутри найден текст.

На презентации отдельные подписи под картинками могут быть размечены как plain text. Для восстановления структуры полезно объединять изображение и ближайший короткий текстовый блок снизу, если они имеют сходную ширину.

Плохие сканы и нечёткий текст

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

Тени у сгиба создают вертикальную полосу, похожую на границу колонки. Коррекция освещения и удаление фона должны сохранять реальные линии таблиц. Хороший тест — сравнить число и положение рамок до и после предобработки на десяти типичных страницах, а не выбирать вариант по одной красивой картинке.

Если скан содержит две страницы разворота, их лучше разделить до инференса. Иначе модель видит нестандартно широкое изображение, а центральный сгиб влияет на порядок чтения. После разделения сохраняйте связь с исходным номером листа.

Документы на разных языках

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

Названия классов в готовой модели английские, но это не ограничивает содержимое страниц. Для внутреннего JSON можно хранить исходное имя и отдельный перевод, не меняя class_id. Это предотвращает ошибки при сравнении с результатами модели или сторонними инструментами.

Для вертикального письма и нестандартных газетных полос требуется отдельная проверка. Даже если рамки определены правильно, универсальная сортировка сверху вниз и слева направо будет неверной.

Готовые веса и проверка их подлинности

Весовой файл DocStructBench имеет формат PyTorch и загружается в YOLOv10. На странице модели указан размер около 40,7 МБ и контрольная сумма SHA-256. Перед размещением в производственной системе файл следует проверять по сумме и хранить в неизменяемом каталоге. Это защищает от случайной подмены и помогает воспроизводить результаты.

Файлы PyTorch могут содержать pickle-объекты и исполнять код при небезопасной загрузке. Используйте веса из доверенного репозитория, не открывайте случайные файлы и запускайте проверку в изолированной среде. Наличие списка импортов на странице модели — полезный сигнал для аудита, но не заменяет доверие к поставщику.

Имя весов должно записываться в отчёт вместе с SHA-256. Если модель обновили, результаты могут измениться даже при одинаковых порогах. Хранение суммы позволяет отделить изменение данных от изменения модели.

Обучение на собственных данных

Собственное обучение нужно, когда классы готовой модели не совпадают с задачей или документы имеют специфический дизайн. Примеры — бланки с зонами подписи, нотные страницы, патентные чертежи, карточки товаров. Сначала определите чёткий словарь классов и правила разметки; неоднозначная схема снижает качество сильнее, чем небольшой объём данных.

Разметка для детекции хранит прямоугольники и классы. Каждый объект должен быть ограничен последовательно: либо рамка включает подпись всегда, либо подпись размечается отдельным классом. Смешение правил заставляет модель учиться противоречиям.

Набор делят на train и val по документам, а не случайным страницам. Если соседние страницы одной книги попали в обе части, метрики будут завышены из-за одинакового шрифта и шаблона. Отдельный тестовый набор лучше собирать из других издателей и сканеров.

Формат данных YOLO

Подготовленные наборы D4LA и DocLayNet размещаются в layout_data и содержат images, labels и текстовые списки страниц для обучения и проверки. В формате YOLO каждая строка метки хранит номер класса, координаты центра, ширину и высоту, нормированные относительно изображения. Ошибка в нормировании приводит к рамкам за пределами страницы или к объектам нулевого размера.

Проверьте конвертер визуально: нарисуйте метки поверх случайных изображений и убедитесь, что прямоугольники совпадают с объектами. Автоматические проверки должны находить отрицательные координаты, значения больше единицы, неизвестные классы и пустые файлы.

Путь datasets_dir задаётся в настройках Ultralytics. Если обучение не находит изображения, сначала выведите абсолютные пути и содержимое train.txt. Символические ссылки и сетевые каталоги могут вести себя по-разному в контейнере и на хосте.

DocSynth300K и разнообразие макетов

DocSynth300K используется для предварительного обучения на большом числе синтетических страниц. Идея состоит не в генерации случайного шума, а в построении разнообразных реалистичных композиций из элементов документов. Затем модель дообучают на целевом наборе.

Синтетические страницы охватывают одну, две и несколько колонок, газетные, журнальные и научные компоновки. Это помогает модели видеть больше сочетаний размеров и взаимного расположения блоков, чем доступно в одном узком наборе.

Объём набора велик, поэтому его загрузка и преобразование нужно планировать заранее. Форматирование из parquet в YOLO создаёт отдельное хранилище. Перед запуском проверьте свободное место не только для исходных данных, но и для преобразованной копии и временных файлов.

Mesh-candidate BestFit

Mesh-candidate BestFit формирует синтетический макет как задачу двумерной упаковки. Элементы выбираются из пула, для них строятся допустимые сетки размещения, затем алгоритм ищет подходящие пары и итеративно заполняет страницу. Такой подход контролирует пересечения и создаёт разные плотности компоновки.

На этапе подготовки элементы можно подвергать аугментациям: поворотам, изменению масштаба, перспективным искажениям, шуму и другим преобразованиям. Аугментация должна соответствовать реальным документам. Сильные эффекты, которых нет в рабочем потоке, увеличат разнообразие, но ухудшат полезность данных.

Синтетика не заменяет реальные страницы. Она расширяет пространство макетов, а финальное дообучение учит шрифтам, качеству сканирования и правилам конкретного домена.

Архитектурная особенность GL-CRM

Модель построена на базе YOLOv10 и добавляет модуль Global-to-Local Controllable Receptive Module. Его задача — лучше учитывать элементы разных масштабов: от крупных текстовых областей и рисунков до небольших подписей. В коде весов присутствуют компоненты G2L_CRM, DilatedBlock и DilatedBottleneck.

Практический смысл контролируемого рецептивного поля проявляется на страницах, где крупная область должна распознаваться целиком, а мелкая подпись — отдельно. Обычный детектор может терять контекст при малом поле или размывать детали при чрезмерно глобальном представлении.

Из этой особенности не следует, что любой маленький объект будет найден. Итог зависит от разрешения, обучающей разметки, порога и качества входа. Архитектура уменьшает конфликт масштабов, но не отменяет необходимость тестирования.

Оценка качества и метрики

В таблицах проекта используются AP50 и mAP. AP50 считает совпадение при пороге IoU 0,5, а mAP усредняет качество по диапазону порогов. Высокий AP50 при заметно меньшем mAP означает, что модель часто находит объект, но границы не всегда точны.

Для производственной задачи общая mAP не заменяет метрики по классам. Пропуск table_footnote может быть критичнее неточной рамки figure. Считайте precision, recall и распределение IoU отдельно для каждой категории, а также долю полностью корректных страниц.

Проект публикует результаты на D4LA и DocLayNet, а также сравнение скорости и точности на DocStructBench. Эти числа получены в конкретной среде и на заданных наборах. На собственных документах нужно измерять заново, не переносить FPS напрямую на другой процессор или видеокарту.

Интерпретация сравнительных графиков

График скорость–точность показывает компромисс между количеством страниц в секунду и средней точностью. DocLayout-YOLO расположен выше базового YOLOv10 по mAP при меньшей скорости, а мультимодальные модели могут быть медленнее из-за обработки текста и изображения. Для пользователя важна не максимальная точка на графике, а достаточное качество при допустимой задержке.

Радарная диаграмма сравнивает результаты на нескольких типах документов: академических, финансовых, учебниках, маркетинговых материалах и наборах D4LA и DocLayNet. Разброс показывает, что среднее значение скрывает различия между доменами. Перед внедрением собирайте тестовую выборку в тех же пропорциях, что и реальный поток.

Если в архиве 90 процентов простых отчётов и 10 процентов плакатов, средняя метрика может быть высокой при плохой обработке плакатов. Для редких, но важных страниц задайте отдельный минимальный порог качества и маршрут ручной проверки.

Экспорт и развёртывание

В метаданных пакета предусмотрены дополнительные зависимости для ONNX, OpenVINO, CoreML, TensorFlow и TensorFlow.js. Наличие опций экспорта не гарантирует, что конкретная модифицированная архитектура преобразуется без изменений. Перед выбором формата экспортируйте модель и сравните координаты и confidence на контрольном наборе.

ONNX удобен для независимого рантайма, OpenVINO — для оптимизации на поддерживаемых процессорах и ускорителях, CoreML — для экосистемы Apple. После экспорта нужно проверить препроцессинг, порядок каналов, масштабирование, padding и постобработку. Наиболее частая причина расхождения — не веса, а другая подготовка входа.

Для сервиса загрузите модель при старте процесса и ограничьте число одновременных запросов. Длинная очередь лучше, чем параллельные задачи, которые вызывают нехватку памяти и завершают все запросы. Возвращайте координаты и метаданные отдельно от изображения с разметкой.

Интеграция в конвейер извлечения PDF

DocLayout-YOLO используется как этап определения областей. Полный конвейер обычно включает рендеринг PDF, детекцию макета, OCR текста, распознавание таблиц и формул, восстановление порядка чтения и экспорт в Markdown, HTML или JSON. Каждый этап должен сохранять координаты, чтобы результаты можно было связать с исходной страницей.

PDF-Extract-Kit и MinerU показывают пример более широкого применения детектора, но собственный конвейер может быть проще. Если нужны только изображения и таблицы, нет смысла запускать распознавание всех абзацев. Если нужен поиск по тексту, наоборот, требуется OCR и нормализация.

Ошибки следует передавать между этапами. Низкая уверенность детектора может вызвать альтернативный OCR по всей странице. Пустой результат должен считаться отдельным состоянием, а не автоматически успешной страницей.

Диагностика распространённых ошибок

Модуль не импортируется

Проверьте, что команда выполняется в том же окружении, где установлен пакет. Выведите путь python и pip, затем импортируйте doclayout_yolo в коротком тесте. Конфликт возникает, когда pip относится к системному Python, а сценарий запускается из conda или виртуального окружения.

Если установка выполнялась из исходников с pip install -e ., каталог проекта должен оставаться доступным. Для стабильного развёртывания предпочтительнее установить wheel и зафиксировать зависимости.

Весовой файл не загружается

Сверьте размер и SHA-256, убедитесь, что файл не является HTML-страницей ошибки. Сообщение о неизвестном классе часто означает, что вес создан другой версией кода. Установите совместимую библиотеку или используйте официальный вес для выбранного пакета.

Не переименовывайте расширение случайного файла в .pt. Формат определяется содержимым, а не именем.

CUDA недоступна

Проверьте torch.cuda.is_available, версию драйвера и сборку PyTorch. Если установлена CPU-сборка, наличие видеокарты не поможет. После исправления перезапустите процесс, потому что PyTorch определяет устройства при импорте и первом обращении.

Для временной проверки используйте device='cpu'; это отделит проблему окружения от проблемы изображения или модели.

Рамок слишком много

Повышайте confidence, включите NMS и проверьте, не выполняется ли постобработка дважды. Ложные рамки на полях могут исчезнуть после корректного обрезания страницы или удаления теней.

Сравните классы ложных срабатываний. Если проблема сосредоточена в одном классе, примените отдельный порог вместо повышения общего значения.

Рамок слишком мало

Снизьте confidence, увеличьте imgsz и проверьте ориентацию. Если класс отсутствует в словаре модели, изменением порога его не получить — нужен другой вес или дообучение.

Убедитесь, что вход не стал чёрным из-за прозрачности или неправильного преобразования RGB/BGR.

Стабильность и воспроизводимость

Для сравнимых результатов фиксируйте версию пакета, PyTorch, CUDA, модель, SHA-256 весов, imgsz, confidence, IoU и правила постобработки. Одного имени программы недостаточно: даже небольшое изменение NMS может изменить число рамок.

Сохраняйте небольшой набор эталонных страниц и ожидаемый JSON. После обновления окружения запускайте регрессионный тест, сравнивая классы, координаты с допуском и confidence. Изображения с разметкой полезны для ручной проверки, но автоматический тест должен работать с числами.

Случайность важнее при обучении, чем при инференсе. Для обучения фиксируют seed, порядок данных и параметры аугментации, однако полностью идентичный результат на разных GPU не всегда гарантируется.

Лицензия и использование в сервисе

Код пакета распространяется по AGPL-3.0, а отдельные весовые файлы могут иметь собственную лицензию, указанную на странице модели. Перед включением в закрытый сервис необходимо проверить обязанности по предоставлению исходного кода модификаций и условия распространения. Лицензия пакета и лицензия модели оцениваются отдельно.

Зависимости также имеют собственные лицензии. При поставке контейнера составьте перечень пакетов и уведомлений. Для внутреннего эксперимента это кажется избыточным, но при публичном сервисе или передаче клиенту вопрос становится практическим.

Не загружайте конфиденциальные страницы в публичную демонстрацию. Для документов с персональными данными используйте контролируемую среду, ограничение доступа, очистку временных файлов и журналирование без содержимого страницы.

Демонстрационный интерфейс

Экран построен на Gradio. Слева находится поле изображения, кнопки Clear и Detect, ползунок Confidence Threshold с диапазоном от 0 до 1 и шагом 0,05, ползунок NMS IOU Threshold с теми же границами и начальным значением 0,45, а также набор примеров. Справа отображается результат.

При нажатии Detect модель обрабатывает изображение с imgsz 1280, затем берёт boxes.xyxy, boxes.cls и boxes.conf, выполняет torchvision NMS и рисует цветные области. Это важно учитывать при сравнении с demo.py: интерфейс добавляет отдельный NMS, а простой сценарий полагается на результат predict и plot.

Clear очищает вход и выход, но не меняет пороги. Для честного сравнения двух страниц записывайте значения ползунков. Демонстрационный экран предназначен для проверки, а не для хранения проекта: после закрытия сессии вход и результат не следует считать архивом.

Сравнение DocLayout-YOLO с аналогами

Прямые аналоги различаются уровнем готовности конвейера. Одни возвращают только рамки макета, другие одновременно распознают текст, таблицы и порядок чтения. Выбор зависит от того, нужен ли быстрый визуальный детектор или законченная система разбора.

Практический выбор

DocLayout-YOLO подходит, когда нужны координаты областей, высокая скорость и полный контроль над последующими этапами. PP-DocLayout удобен тем, кому важен широкий набор готовых категорий и интеграция с PaddleOCR. LayoutParser выбирают для модульных исследовательских проектов, Surya — когда вместе с макетом нужен OCR и порядок чтения, а Detectron2 с DocLayNet — для глубокой настройки обучения.

PDF Commander не является прямым аналогом детектора макета: он предназначен для ручного редактирования и работы со страницами PDF, а не для выдачи машинных координат структурных областей. Его выбирают, когда задача состоит в изменении документа человеком, а не в автоматической подготовке данных для OCR.

Программа	Лучше подходит для	Главное ограничение
DocLayout-YOLO	Быстрой детекции областей на разнородных страницах и собственной постобработки	Не распознаёт текст и требует отдельного рендеринга PDF
PP-DocLayout	Готовых моделей нескольких размеров и большого набора категорий макета	Зависит от стека PaddlePaddle/PaddleX
LayoutParser	Исследовательских конвейеров с заменяемыми моделями Detectron2 и удобными объектами разметки	Установка моделей Detectron2 может быть сложной
Surya	Единого процесса с OCR, макетом, порядком чтения и таблицами	Требует больше ресурсов, чем отдельный детектор
Detectron2 + DocLayNet	Гибкого обучения и экспериментов с моделями обнаружения на DocLayNet	Нужно самостоятельно собирать инференс и постобработку

Типовые сценарии

Подготовка PDF к поиску

Растрируйте страницы, найдите текстовые блоки, исключите abandon, определите порядок чтения и отправьте кропы в OCR. В итоговом индексе храните текст вместе с номером страницы и координатами, чтобы поиск мог показать фрагмент на оригинале.

Таблицы и формулы индексируйте отдельно: обычный OCR часто искажает их.

Извлечение рисунков

Сохраните figure в отдельные файлы, свяжите с figure_caption и запишите координаты. Для повторяющихся логотипов примените фильтр по положению и сходству изображения, иначе они попадут в коллекцию как содержательные рисунки.

Если рисунок разделён на панели, объединяйте их только при наличии общей подписи и близком расположении.

Контроль шаблонов

Сравнивайте набор классов и относительные координаты с эталоном. Отсутствие заголовка, смещение таблицы или появление лишней области может сигнализировать об изменении формы. Для шаблонного контроля важнее стабильные координаты, чем распознавание текста.

Допуск задавайте в долях ширины и высоты страницы, чтобы правило работало при разных DPI.

Создание обучающего набора

Используйте модель для предварительной разметки, затем исправляйте рамки человеком. Сохраняйте только проверенные метки; автоматический результат без проверки переносит ошибки в новый набор.

Отдельно отбирайте страницы с низкой уверенностью и редкими классами — они дают больше пользы для следующего цикла обучения.

Практическая проверка перед массовым запуском

Соберите 50–100 страниц, включающих обычные отчёты, таблицы, формулы, сканы, плакаты и страницы с необычной ориентацией. Для каждой вручную отметьте критичные элементы. Затем сравните несколько профилей imgsz, confidence и NMS.

Оцените не только качество рамок, но и итоговый бизнес-результат: полноту OCR, правильность порядка чтения, число извлечённых таблиц и долю страниц, требующих ручной проверки. Небольшое ухудшение mAP может быть приемлемо, если скорость увеличилась и важные классы не пострадали.

После выбора профиля заморозьте окружение и эталонный набор. Массовый запуск начинайте с небольшого пакета, контролируя память, время и долю пустых результатов.

Как читать результат на разных типах страниц

На академической статье ожидаются крупные plain text, отдельные figure и table, а также подписи. Если одна колонка разбита на множество коротких рамок, это не всегда ошибка, но усложняет порядок чтения. Объединение выполняют после OCR или по геометрии.

На финансовом отчёте цветные плашки и боковая карточка аналитика могут быть выделены как figure или text. Важно заранее решить, входит ли боковая колонка в основной поток. Таблицу прогнозов следует отделить от примечаний под ней.

На экзаменационном листе формулы и рисунки тесно связаны с вопросами. Простая сортировка может поместить ответ из правой страницы раньше вопроса слева. Для разворота сначала разделите страницы или определите крупные зоны.

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

Ограничения, которые важно учитывать

Модель не редактирует PDF, не распознаёт символы, не восстанавливает таблицы и не строит идеальный порядок чтения без правил. Она решает задачу обнаружения областей. Чем яснее граница ответственности, тем проще диагностировать ошибки: пропущенная таблица относится к детектору, неверный текст внутри найденной рамки — к OCR.

Классы зависят от весов. Установка пакета без весового файла не даёт готового результата. Вес, обученный на DocLayNet, может иметь другой словарь, чем DocStructBench. Всегда проверяйте model.names.

Скорость из публикации нельзя считать гарантией для любого компьютера. Рендеринг PDF, чтение файлов, NMS, визуализация и OCR добавляют задержку, не отражённую в чистом FPS модели.

Качество на нестандартных документах определяется близостью к обучающим данным. Для узкой формы собственное дообучение часто полезнее бесконечной настройки порога.

Итоговый рабочий рецепт

Для первой проверки установите пакет в отдельное окружение, получите доверенный вес, растрируйте несколько страниц в PNG и запустите demo.py с imgsz 1024 и умеренным порогом. Затем откройте изображения с рамками и отметьте систематические ошибки по классам.

После этого перейдите на SDK: загрузите модель один раз, сохраняйте boxes в JSON, добавьте NMS и классовые пороги, свяжите подписи с объектами и подключите OCR только к нужным областям. Для PDF храните параметры растрирования, чтобы координаты можно было вернуть на страницу.

Перед большим архивом проведите регрессионный тест, зафиксируйте контрольные суммы весов и пакетов, настройте повторный запуск после ошибок и отдельную очередь для сложных страниц. Такой конвейер использует сильную сторону DocLayout-YOLO — быстрый поиск структуры — и не пытается заменить им задачи, для которых нужны OCR, анализ таблиц или редактор PDF.

Дополнительные рекомендации по эксплуатации

При построении очереди страниц разделяйте ошибки чтения файла и ошибки инференса. Повреждённый PNG не следует бесконечно повторять, а временная нехватка памяти может исчезнуть после уменьшения пакета. Код состояния и короткое диагностическое сообщение должны записываться рядом с идентификатором страницы.

Контроль пустых результатов обязателен. Пустой список boxes может означать действительно пустую страницу, слишком высокий порог, неверную ориентацию или несовместимый вес. Для решения сравните среднюю яркость, число пикселей с контрастом, размер изображения и результат с более низким confidence.

При параллельной обработке не давайте нескольким процессам писать в один файл. Сначала сохраняйте во временное имя, затем атомарно переименовывайте после успешной записи JSON и изображения. Так оборванный процесс не оставит файл, который выглядит готовым.

Для журналов производительности измеряйте рендеринг, загрузку изображения, инференс, NMS, сериализацию и OCR отдельно. Только раздельные времена показывают, где находится узкое место. Если инференс занимает треть общего времени, увеличение GPU не ускорит весь конвейер втрое.

Сравнивая два веса, используйте одинаковые входы и постобработку. Изменение NMS вместе с моделью делает вывод неоднозначным. Сначала сравните сырые рамки, затем примените единые правила и только после этого оценивайте итоговый документ.

Для ручной проверки создавайте страницу с тонкими контурами и отдельную таблицу объектов. Полупрозрачная заливка хорошо показывает перекрытия, но может скрыть мелкий текст. Таблица с class, confidence и координатами помогает найти рамку, которую трудно рассмотреть.

При переносе координат между изображениями проверяйте не только масштаб, но и padding. Letterbox добавляет поля перед инференсом, а библиотека обычно возвращает координаты в системе исходного изображения. Если используется собственный препроцессинг, нужно явно удалить padding и разделить на коэффициент масштаба.

Для обрезки таблиц и рисунков применяйте разные поля. У таблицы важны внешние линии и примечания, у рисунка — подписи по краям, у формулы — верхние и нижние индексы. Единый отступ в пикселях не масштабируется между страницами разных размеров; лучше задавать процент от высоты рамки с минимальным и максимальным пределом.

Если два блока почти касаются, объединение по расстоянию должно учитывать класс и ширину. Два абзаца в колонке можно соединить, но заголовок и первый абзац лучше оставить раздельными. Таблица и подпись связываются отношением, а не сливаются в одну область.

Для контроля колонтитулов сравнивайте нормированные координаты и текст OCR на нескольких страницах. Повторяющийся блок в верхних пяти процентах страницы вероятнее является колонтитулом, но первая страница главы может содержать уникальный заголовок в той же зоне. Правило должно учитывать частоту, а не только положение.

При дообучении сохраняйте примеры ошибок предыдущей модели в отдельной категории анализа, но в обучающие классы добавляйте только предметные объекты. Класс ошибка не имеет стабильной визуальной семантики и обычно ухудшает детектор.

Разметчики должны видеть инструкции с положительными и отрицательными примерами. Особенно важно согласовать, включать ли номер таблицы в table_caption, как размечать составные рисунки и что относить к abandon. Межэкспертное согласие следует измерить до большой разметки.

Проверяйте баланс классов. Тысячи plain text и десяток formula_caption приводят к слабому редкому классу. Можно добавить реальные страницы с формулами, синтетические варианты и целевые аугментации, но не дублировать один и тот же пример много раз.

При оценке скорости исключите первый прогон: он включает инициализацию и прогрев. Затем измерьте серию одинакового размера и отдельно серию реальных страниц. Пакет из одинаковых изображений показывает верхнюю границу, а смешанный поток — практическое время.

На сервере ограничьте максимальное разрешение входа. Иначе случайная панорама или скан огромного плаката займёт память до того, как модель уменьшит его. Проверка размеров должна выполняться сразу после чтения заголовка изображения.

Сохраняйте исходное изображение без разметки. Рамки можно перерисовать из JSON с другой палитрой и толщиной, но удалить их из единственной сохранённой копии невозможно. Для аудита также нужна версия до предобработки.

При обработке конфиденциальных документов временные кропы лучше хранить в памяти или в защищённом каталоге с автоматическим удалением. Журнал не должен содержать полный OCR-текст, если для диагностики достаточно номера страницы и кода ошибки.

Если визуализация показывает правильные рамки, а JSON пуст, проблема находится в коде сериализации или в обращении к объекту результатов. Если JSON корректен, а рамки смещены, проверяйте преобразование координат и размер изображения, на которое выполняется рисование.

Для теста экспорта сравнивайте не только классы, но и максимальное отклонение координат. Небольшая разница в confidence рядом с порогом может изменить состав рамок; поэтому сначала сравните выходы без финального порога или используйте запас вокруг граничных значений.

После обновления зависимостей проверьте NMS. Разные реализации могут по-разному обрабатывать равные confidence и граничный IoU. Для воспроизводимости фиксируйте версию torchvision или применяйте собственную детерминированную реализацию.

Когда документ содержит вложенные таблицы, глобальный NMS может удалить внутреннюю рамку. Сохраняйте допустимые вложения по классам и применяйте подавление внутри группы. Иерархию лучше хранить отдельными parent_id, а не изменять координаты объектов.

При работе с разворотами определите линию разделения по полю, затем запустите модель на каждой половине. После детекции добавьте смещение координат правой страницы. Это даёт более привычное соотношение сторон и упрощает порядок чтения.

Для тонких вертикальных элементов, например боковых подписей, поворот кропа перед OCR может повысить качество. Сам детектор оставляет координаты на исходной странице, а в метаданных записывается угол преобразования.

Оценка человека должна включать полноту, точность классов и геометрию. Рамка правильного класса, которая обрезала половину таблицы, не является успешной. Для крупных объектов полезна метрика покрытия содержимого, а не только IoU.

Если рамка выходит за границы изображения из-за округления или пользовательской постобработки, ограничьте x значениями от нуля до ширины, y — от нуля до высоты. Пустые или инвертированные прямоугольники после ограничения следует удалить с записью причины.

Для хранения миллионов объектов используйте построчный JSON или колонковый формат, а не один огромный JSON-массив. Страница остаётся независимой единицей, и повреждение одного файла не блокирует весь корпус.

Схема результата должна иметь версию. Добавление reading_order, parent_id или polygon не должно ломать старые потребители. Версия схемы и версия модели — разные поля.

При подготовке данных к RAG сохраняйте тип блока. Заголовок можно использовать для построения разделов, подпись — прикреплять к изображению, таблицу — представлять отдельным структурированным объектом. Если все блоки превратить в обычный текст, преимущество анализа макета теряется.

Не удаляйте область abandon без проверки на конкретном домене. В газетах или формах туда может попасть содержательный боковой блок. Сначала измерьте, какие элементы модель относит к этому классу в вашей выборке.

Для обратной связи разметчику показывайте уверенность и соседние рамки, но не заставляйте его доверять confidence. Низкая уверенность может быть правильной на редком макете, а высокая — ошибочной на повторяющемся декоративном элементе.

При обучении на сканах добавляйте реалистичные искажения: лёгкий наклон, размытие, шум, неравномерное освещение и JPEG-артефакты. Сильные случайные повороты на произвольный угол полезны только если такие страницы реально встречаются.

Планируйте ручную проверку как часть системы. Страницы с низким минимальным confidence, необычным числом рамок или конфликтующим порядком чтения автоматически направляйте оператору. Это надёжнее, чем пытаться одним порогом устранить все редкие ошибки.

Перед массовым запуском сформируйте эталонный набор из страниц каждого типа: научная статья, счёт, презентация, учебник, скан и плакат. Для каждой страницы сохраните ожидаемые классы, приблизительные границы и допустимые исключения. Такой набор быстро выявляет регрессии после смены веса, размера входа или правил NMS.

Порог уверенности полезно выбирать по классам, а не только одним числом. Для крупной таблицы можно требовать более высокий confidence, тогда как небольшая подпись или номер формулы часто получает меньшее значение. Классовые пороги применяют после получения предсказаний, сохраняя исходный confidence для аудита.

При оценке необычного количества объектов нормируйте его на площадь страницы. Двадцать блоков на компактной странице презентации и двадцать блоков на длинном газетном листе означают разные ситуации. Дополнительно сравнивайте долю площади, покрытую рамками: слишком малая доля часто указывает на пропуск, а почти полное перекрытие — на крупную ложную область.

Контроль ориентации должен выполняться до изменения координат. Если страницу повернули на девяносто градусов для инференса, в результате нужно применить обратное преобразование ко всем четырём углам рамки, а затем вычислить новый ограничивающий прямоугольник. Простая перестановка ширины и высоты без учёта направления поворота даёт зеркальные координаты.

Для документов с обрезанными краями добавляйте рамку вокруг страницы до инференса только в том случае, если модель систематически теряет объекты у границы. Размер поля должен быть записан и вычтен при обратном переносе координат. Иначе все кропы будут смещены, хотя визуализация на дополненном изображении покажется правильной.

В контейнере заранее загружайте веса в постоянный каталог и проверяйте их контрольную сумму при старте. Загрузка модели при каждом запросе увеличивает задержку и создаёт лишний сетевой риск. Процесс обработки должен завершаться понятной ошибкой, если вес отсутствует или его хеш не совпадает с ожидаемым.

Модельный сервер лучше отделить от рендеринга PDF и OCR. Тогда каждый компонент можно масштабировать по собственному ресурсу: рендеринг нагружает процессор, детекция — ускоритель, OCR — процессор или другой GPU. Между этапами передавайте идентификатор страницы и путь к защищённому объектному хранилищу, а не дублируйте большие массивы в журнале.

При повторной обработке храните отпечаток входной страницы, веса и параметров. Совпадение только имени файла недостаточно: документ мог быть заменён, а имя осталось прежним. Ключ кэша может включать SHA-256 изображения, идентификатор модели, imgsz, confidence, IoU и версию постобработки.

Для проверки геометрии создайте автоматический тест обратимого преобразования. Возьмите известную рамку, масштабируйте и дополните изображение тем же кодом, что используется перед моделью, затем верните координаты назад. Максимальное отклонение должно укладываться в выбранное округление; тест особенно полезен после замены библиотеки рендеринга.

При экспорте в формат аннотаций не путайте абсолютные и нормированные координаты. В YOLO центр и размеры обычно делятся на ширину и высоту изображения, а в COCO сохраняются абсолютные x, y, width и height. Записывайте размер именно того изображения, к которому относятся рамки, а не размер исходного PDF-листа в пунктах.

Разные страницы одного PDF могут иметь разные размеры и повороты. Нельзя вычислить один коэффициент масштаба для всего документа и применить его ко всем результатам. Метаданные геометрии должны храниться на уровне страницы, включая ширину растра, высоту, DPI, угол и выбранную область PDF.

Если результат используется для поиска, не индексируйте подпись к рисунку дважды: один раз как самостоятельный текст и второй раз внутри объединённого описания рисунка. Лучше сохранить связь caption_id и решить на этапе индексации, какой вариант включить. Это уменьшает повторы в выдаче и не теряет структуру.

Для таблиц полезно сохранять контекст вокруг рамки отдельно от самого кропа. Заголовок раздела над таблицей и предложение перед ней помогают понять смысл, но мешают распознаванию сетки. Поэтому структурный модуль получает чистую таблицу, а поисковый индекс — таблицу вместе с ближайшим заголовком и подписью.

При обнаружении пересекающихся рамок разных классов не выбирайте победителя только по confidence. Таблица может законно содержать формулу, а рисунок — текстовые метки. Решение зависит от допустимой иерархии классов: вложение сохраняется, если оно предметно оправдано, а конкурирующие рамки одного уровня проходят NMS или правило приоритета.

Систему наблюдения стройте на распределениях, а не на единичных ошибках. Полезны медиана числа объектов, доля каждого класса, площадь крупнейшей рамки, средняя уверенность и время на страницу. Резкий сдвиг этих показателей после поступления нового источника документов сигнализирует о доменном дрейфе.

Для выборочного контроля берите не только случайные страницы. Добавляйте страницы с минимальной уверенностью, максимальным числом объектов, редкими классами и сильным отличием от обычной геометрии. Комбинация случайной и риск-ориентированной выборки лучше показывает реальное качество конвейера.

При хранении визуализаций используйте цветовую легенду, устойчивую между запусками. Если цвет класса меняется, сравнение двух результатов становится труднее. Вместе с изображением сохраняйте перечень class_id, названий и цветов, чтобы старые кадры оставались понятными после изменения конфигурации.

Веб-интерфейс для операторов должен показывать исходную страницу и редактируемые рамки, но исправления следует сохранять отдельно от машинного результата. Тогда можно оценить исходную модель, восстановить историю правок и использовать подтверждённые исправления для дообучения без потери первоначальных данных.

При удалении ложной рамки фиксируйте причину: неверный класс, лишний объект, плохая геометрия или дубликат. Одной отметки ошибка недостаточно для анализа. Статистика причин подсказывает, что улучшать — разметку, модель, пороги, NMS или правила порядка чтения.

Перед передачей результата следующему модулю валидируйте схему: обязательные поля, числовые типы, допустимые классы, границы координат и уникальность идентификаторов. Невалидную страницу лучше поместить в отдельную очередь, чем позволить ей вызвать ошибку в середине большого объединённого документа.

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