Table Transformer находит таблицы на страницах PDF и изображениях, определяет строки, столбцы, заголовки и объединённые ячейки, а затем формирует структурированное представление для экспорта в HTML или CSV. Пользователь управляет обработкой через Python-сценарии: выбирает режим обнаружения, распознавания структуры или полного извлечения, подключает координаты слов и сохраняет визуализации границ.

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

Для единичной страницы удобно запускать готовый сценарий inference.py, а для конвейера документов — создавать объект TableExtractionPipeline в собственном коде. Результат можно оставить в виде объектов с координатами, получить список ячеек, сохранить отдельные фрагменты таблиц, построить диагностический рисунок либо преобразовать содержимое в HTML и CSV. Качество итогового текста зависит не только от модели, но и от точности координат слов, полученных из PDF или OCR.

Что именно распознаёт Table Transformer

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

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

Само распознавание структуры не заменяет извлечение текста. Сеть возвращает границы объектов и оценки уверенности. Текст появляется в ячейках только после сопоставления этих границ со списком слов, где для каждого токена известны координаты. Для электронного PDF такой список обычно получают напрямую из текстового слоя; для скана или фотографии нужен отдельный OCR. Если передать изображение без токенов, геометрия и визуализация сохранятся, но HTML и CSV будут содержать пустые либо неполные ячейки.

Интерфейс командной строки и три режима обработки

Основной пользовательский интерфейс проекта — аргументы сценария inference.py. Обязательные пути задают каталог изображений, каталог результатов и файлы конфигурации с весами моделей. Параметр mode принимает три значения: detect, recognize и extract. Остальные флаги определяют, какие представления сохранить: объекты, вырезанные таблицы, ячейки, HTML, CSV и диагностические изображения. Устройства для двух моделей выбираются отдельно, поэтому, например, детектор можно оставить на GPU, а распознавание структуры временно перевести на CPU.

Режим detect

В режиме detect обрабатывается целая страница или другое изображение, где таблица находится среди остального содержимого. Результатом являются объекты класса table и table rotated с координатами и оценками уверенности. Флаг crops сохраняет вырезанные области; crop_padding задаёт запас вокруг каждой границы и по умолчанию равен десяти пикселям. Небольшое поле полезно, потому что крайняя линия, подпись внутри рамки или часть крайнего столбца не должны быть обрезаны до передачи следующей модели.

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

Режим recognize

Режим recognize применяют к изображению одной таблицы. Сценарий не ищет её на странице, а сразу запускает структурную модель. Это сокращает время и исключает ошибку детектора, если область уже получена из другой системы, выделена вручную или экспортирована из PDF по известным координатам. В таком режиме особенно важно, чтобы в кадр не попадали подпись к таблице, номер страницы и соседний абзац: структурная модель может принять длинную текстовую строку за дополнительный ряд.

Вывод recognize может включать исходные объекты rows, columns, headers и spanning cells, либо уже согласованный список ячеек. Второй вариант удобнее для прикладной обработки, потому что постобработка выравнивает все строки по общей ширине, все столбцы по общей высоте, формирует пересечения и объединяет подячейки, попавшие внутрь spanning cell. При необходимости оба представления сохраняют одновременно: исходные объекты помогают отлаживать пороги, а ячейки используются для экспорта.

Режим extract

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

python inference.py \
  --mode extract \
  --image_dir input_pages \
  --words_dir page_words \
  --out_dir results \
  --detection_config_path detection_config.json \
  --detection_model_path detection_model.pth \
  --structure_config_path structure_config.json \
  --structure_model_path structure_model.pth \
  --objects --cells --html --csv --visualize

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

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

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

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

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

Формат слов и связь геометрии с текстом

Каталог words_dir должен содержать JSON-файл для каждого JPG. Имя строится заменой расширения .jpg на _words.json. Код принимает либо непосредственно список токенов, либо объект с ключом words. У каждого токена нужен прямоугольник bbox в координатах изображения; для устойчивого порядка полезны поля block_num, line_num и span_num. Если этих полей нет, сценарий подставляет нули для блока и строки, а span_num назначает по текущему порядку элементов списка.

Порядок токенов влияет на объединение текста внутри ячейки. Когда PDF-библиотека возвращает слова в непредсказуемой последовательности, содержимое CSV может перемешаться даже при правильных границах. Перед сохранением JSON следует сортировать токены по блоку, строке и позиции слева направо, отдельно обрабатывая вертикальный текст. Номер страницы в имени файла не должен конфликтовать с заменой расширения: основной сценарий ожидает JPG и формирует путь буквально, поэтому PNG лучше либо конвертировать, либо адаптировать логику именования.

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

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

{
  "words": [
    {
      "text": "Показатель",
      "bbox": [112.4, 84.1, 236.8, 107.7],
      "block_num": 0,
      "line_num": 0,
      "span_num": 0
    }
  ]
}

Как формируются строки, столбцы и ячейки

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

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

Объединённая ячейка определяется классом table spanning cell. Постобработка выясняет, какие базовые пересечения строк и столбцов покрыты её прямоугольником более чем наполовину, собирает номера этих строк и столбцов и заменяет подячейки одной сущностью. Для проекционного заголовка строки применяется тот же механизм, но сохраняется отдельный признак projected row header. Он нужен, когда текст в первой строке группы относится к нескольким последующим строкам и визуально выполняет роль ключа.

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

Порог уверенности и отладка ложных объектов

В готовом inference.py базовый порог для обычной и повёрнутой таблицы равен 0,5. Такой же порог задан для строк, столбцов, заголовка столбцов, проекционного заголовка строки и объединённой ячейки. Это стартовые значения, а не гарантированно оптимальная настройка для каждого корпуса. В одних документах снижение порога возвращает пропущенные тонкие строки, в других создаёт множество дублей и ложных spanning cells.

Настраивать пороги следует по классам, а не одним глобальным числом. Если детектор уверенно находит области, но структура теряет объединённые заголовки, менять threshold для table бессмысленно — нужен отдельный анализ table spanning cell. Если в таблице появляются лишние строки из-за подчёркивания текста или полосатой заливки, корректируют порог table row и сравнивают ячейки после постобработки. Каждое изменение оценивают на отложенном наборе, а не на одном удачном примере.

Флаг objects сохраняет исходные объекты и помогает отличить ошибку сети от ошибки постобработки. Если нужной строки нет уже среди объектов, проблема связана с моделью, качеством изображения или порогом. Если строка присутствует, но исчезает после выравнивания, следует изучить перекрытия, размеры токенов и правила refine_rows. Аналогично, неправильно объединённая шапка может быть вызвана неверным spanning cell или тем, что базовые строки и столбцы построены с ошибкой.

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

Экспорт в HTML

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

Выходной HTML не является копией оформления исходного PDF. Он передаёт логику ячеек, а не шрифты, толщину линий, цвет заливки и точные размеры. Поэтому его используют как промежуточное структурированное представление. Стили добавляют отдельно, ориентируясь на роли header и data. Если требуется воспроизвести внешний вид документа, координатная модель должна быть дополнена сведениями о шрифтах, линиях и цветах из PDF или анализа изображения.

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

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

Экспорт в CSV и ограничения плоского формата

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

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

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

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

Визуальная проверка результата

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

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

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

Работа через библиотеку Transformers

Модели доступны через классы AutoImageProcessor и AutoModelForObjectDetection. Такой способ удобен, когда приложение уже использует экосистему Transformers и требуется только получить сырые детекции. Процессор подготавливает изображение, модель возвращает логиты классов и нормализованные рамки, а метод post_process_object_detection переводит их в координаты исходного размера. Для полноценного HTML или CSV всё равно потребуется логика формирования структуры и сопоставления текста, представленная в официальном inference.py.

Для первой стадии используют идентификатор microsoft/table-transformer-detection, для распознавания структуры — microsoft/table-transformer-structure-recognition либо одну из моделей v1.1. Структурные варианты обучены на разных наборах: PubTables-1M, согласованном FinTabNet и их объединении. Выбор делают по домену документов. Научные статьи ближе к PubTables-1M, финансовая отчётность — к FinTabNet, а смешанный вариант обычно лучше переносится между этими типами, хотя собственная проверка обязательна.

Высокоуровневый pipeline object-detection быстро показывает рамки, но не выполняет весь двухступенчатый процесс автоматически. Он не извлекает слова из PDF, не строит ячейки и не принимает решение о flattening заголовков. Поэтому демонстрационный код с одним вызовом нельзя считать готовым табличным конвертером. В прикладном решении явно организуют рендеринг, детекцию, обрезку, распознавание структуры, текстовые токены и экспорт.

from transformers import AutoImageProcessor, AutoModelForObjectDetection

processor = AutoImageProcessor.from_pretrained(
    "microsoft/table-transformer-detection"
)
model = AutoModelForObjectDetection.from_pretrained(
    "microsoft/table-transformer-detection"
)

inputs = processor(images=page_image, return_tensors="pt")
outputs = model(**inputs)
results = processor.post_process_object_detection(
    outputs,
    target_sizes=[page_image.size[::-1]],
    threshold=0.5
)[0]

Пакетная обработка больших документов

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

Детектор и структурная модель загружаются один раз при создании конвейера. Их нельзя инициализировать заново для каждой страницы: загрузка весов и перенос на устройство займут больше времени, чем сама инференс-операция. При многопроцессной обработке следует учитывать видеопамять; несколько процессов с отдельной копией модели могут быстро исчерпать её. Часто эффективнее один процесс на GPU с очередью изображений и отдельный пул CPU для рендеринга, OCR и записи файлов.

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

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

Производительность на CPU и GPU

По умолчанию аргументы detection_device и structure_device имеют значение cuda. Для запуска без совместимого GPU оба параметра задают как cpu. Это функционально поддерживается, но время обработки возрастает, особенно на страницах высокого разрешения. Разделение устройств позволяет измерить, какой этап ограничивает скорость. Если на странице мало таблиц, детектор обрабатывает большой кадр, а структурная модель — несколько небольших фрагментов; при множестве таблиц нагрузка второй стадии растёт.

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

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

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

Совместимость и подготовка окружения

Официальный файл environment.yml описывает воспроизводимое окружение на базе Python 3.10.9, PyTorch 1.13.1 и Torchvision 0.14.1. Создание через Conda снижает риск несовместимости бинарных зависимостей. Современный стек Transformers может использовать опубликованные модели через собственный API, но официальный сценарий опирается на структуру исходного репозитория и его конфигурационные файлы. Смешивать код одной ревизии с конфигом и весами другой следует только после проверки ключей state_dict.

Для GPU требуется сборка PyTorch, соответствующая драйверу и поддерживаемой версии CUDA. Ошибка вида CUDA unavailable обычно означает, что установлена CPU-сборка, драйвер не видит устройство либо процесс запущен в контейнере без доступа к GPU. Быстрая проверка — вывести torch.cuda.is_available(), имя устройства и выполнить небольшой тензорный расчёт до загрузки модели. Если GPU недоступен, оба device-параметра явно переключают на cpu, а не оставляют значение по умолчанию.

Проект использует PIL для изображений, NumPy и PyTorch для вычислений, matplotlib для визуализаций и вспомогательный код DETR. При обновлении отдельных библиотек наиболее типичны изменения сигнатур, предупреждения о загрузке весов и несовпадение форматов препроцессора. Поэтому обновление выполняют в копии окружения и прогоняют фиксированный набор страниц, сравнивая не только отсутствие исключений, но и координаты объектов.

conda env create -f environment.yml
conda activate tables-detr

python inference.py --help

Обучение и тонкая настройка

Репозиторий содержит обучение для двух типов данных: detection и structure. В обоих случаях основной сценарий main.py получает путь к набору и JSON-конфигурацию гиперпараметров. Для детекции разметка описывает страницы и рамки таблиц. Для структуры используются вырезанные изображения таблиц с рамками строк, столбцов, заголовков и объединённых ячеек. Набор должен соблюдать те же определения объектов, что и постобработка, иначе модель будет получать противоречивые сигналы.

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

Для продолжения прерванного обучения передают model_load_path с сохранённым состоянием оптимизатора. Для запуска новой тонкой настройки от checkpoint добавляют load_weights_only, чтобы не наследовать старое состояние оптимизатора. Скорость обучения, learning rate, число эпох и аугментации задаются конфигурацией или переопределяются аргументами. Менять сразу много параметров нецелесообразно: невозможно понять, что именно улучшило или ухудшило результат.

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

PubTables-1M и перенос на собственные документы

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

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

Оценивать перенос нужно на уровне конечной задачи. Для поиска всех таблиц важны precision и recall детектора. Для экспорта данных — правильность ячеек, заголовков и текста. Иногда модель слегка ошибается в границе строки, но все слова попадают в правильные ячейки; такая ошибка почти не влияет на CSV. В другом случае рамки выглядят аккуратно, но spanning cell выбрана неверно и смысл столбцов потерян. Метрики и ручная проверка должны отражать эти различия.

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

Оценка качества с помощью AP и GriTS

Для детекции и структурных объектов используются стандартные показатели object detection: AP, AP50, AP75 и recall. Они измеряют совпадение рамок и классов, но не полностью отражают качество итоговой сетки. Несколько небольших ошибок рамок могут снизить AP, хотя ячейки остаются логически правильными; наоборот, высокий AP отдельных строк и столбцов не гарантирует правильное объединение в таблицу.

GriTS оценивает таблицу как двумерную сетку. Вариант GriTS Top сравнивает топологию ячеек, GriTS Loc учитывает их расположение, GriTS Con — текстовое содержимое. Подход ищет наиболее похожую двумерную подструктуру между предсказанием и эталоном, поэтому частично правильная таблица получает частичный балл, а одна пропущенная строка не обнуляет все последующие соответствия. Это делает метрику полезной для диагностики сложных структур.

Точная метрика содержимого требует корректных токенов. Если OCR ошибается в словах, GriTS Con смешивает качество структуры и распознавания текста. Для сравнения моделей структуры разумно смотреть GriTS Top и GriTS Loc отдельно, а затем оценивать содержимое в полном конвейере. При тонкой настройке также важно использовать эталон с теми же каноническими правилами, иначе метрика будет наказывать допустимую, но иначе размеченную структуру.

Официальный eval-режим для structure может сохранять подробные метрики и визуализации. Параметры batch_size, eval_pool_size и eval_step управляют вычислением и параллельной обработкой GriTS. Для быстрой проверки test_max_size ограничивает число образцов. Небольшая выборка подходит для проверки, что код запускается, но не для окончательного сравнения: редкие сложные таблицы могут полностью изменить вывод.

Типовые ошибки запуска и способы исправления

Модель не загружает веса

Сообщение о missing keys или unexpected keys означает, что архитектура из конфигурации не совпадает с checkpoint. Проверяют, для какой задачи предназначены веса: detection и structure имеют разные классы. Затем сопоставляют конфигурацию, код DETR и формат сохранённого словаря. Если файл скачан неполностью, сравнивают размер и контрольную сумму. Не следует переименовывать структурный checkpoint в детекторный путь только ради прохождения проверки расширения.

Каталог words найден, но текст пуст

Сценарий строит имя токенов из имени JPG. Если изображения имеют PNG, имя содержит дополнительные точки или JSON назван иначе, файл не будет найден либо откроется не тот набор. Проверяют точное соответствие, ключ words и наличие bbox. Затем накладывают несколько прямоугольников токенов на изображение. Если они смещены или перевёрнуты по Y, исправляют преобразование координат PDF в пиксели.

Появляются лишние строки

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

Пропадают столбцы без вертикальных линий

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

Объединённые ячейки создаются ошибочно

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

CSV сдвигает значения

Сдвиг почти всегда начинается раньше экспорта. Сравнивают список ячеек, их row_nums и column_nums, затем проверяют пустые ячейки и spanning cells. Если геометрия правильна, исследуют разделитель и кавычки: значение с запятой без корректного экранирования выглядит как дополнительный столбец уже при импорте. Для контроля CSV разбирают стандартным парсером, а не делят строки вручную.

Обработка останавливается на одном изображении

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

Сложные структуры и практические ограничения

Таблицы с вложенными подтаблицами, диагональными заголовками и произвольными линиями не укладываются в простую прямоугольную сетку. Table Transformer всё равно пытается представить их строками, столбцами и spanning cells, поэтому часть визуальной семантики теряется. В таких случаях результат используют как основу и дополняют специальными правилами либо сохраняют координатную разметку вместо немедленного CSV.

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

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

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

Рукописные значения не являются задачей структурной модели. Она может правильно выделить строки и столбцы формы, но содержимое зависит от отдельного распознавателя рукописи. То же относится к формулам, символам и сложной математической нотации. Успешная визуализация ячеек не гарантирует, что текст внутри пригоден для аналитики; контроль OCR проводят отдельно.

Практические сценарии применения

Извлечение таблиц из научных статей

Страницы рендерят, текст получают из PDF, затем detect находит таблицы вместе с возможным поворотом. После recognize заголовки и spanning cells сохраняют в HTML, потому что CSV может потерять иерархию. Подпись и сноски извлекают отдельно. Для контроля проверяют номера таблиц, число колонок и несколько значений из разных строк. Такой процесс подходит для наполнения поискового индекса и создания структурированного корпуса.

Финансовая отчётность

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

Поток сканированных документов

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

Подготовка данных для поиска и RAG

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

Контроль качества разметки

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

Сравнение Table Transformer с аналогами

Программа	Лучше подходит для	Главное ограничение
Table Transformer	Точного контроля детекции и структуры таблиц, обучения на своих данных и получения координат ячеек	Текст и готовый интерфейс извлечения нужно организовать отдельным конвейером
PaddleOCR PP-StructureV3	Комплексного OCR и разбора документов с таблицами, формулами и макетом	Большой набор моделей и зависимостей усложняет развёртывание и настройку
Docling	Преобразования PDF и офисных документов в структурированные представления для дальнейшей обработки	Меньше низкоуровневого контроля над отдельными объектами строк и столбцов
LayoutParser	Экспериментов с моделями макета и объединения детекторов с собственным OCR	Для HTML или CSV таблицы требуется дополнительная логика структуры
Camelot	Извлечения таблиц из текстовых PDF по линиям или расстояниям между словами	Не рассчитан на сканы без OCR и сложные визуальные структуры
Tabula	Ручного или полуавтоматического выделения таблиц в обычных текстовых PDF	Сканированные страницы и нестандартные таблицы требуют других инструментов

Table Transformer выбирают, когда важны координаты, отдельные классы структуры, воспроизводимое обучение и возможность встроить модель в собственный Python-конвейер. PaddleOCR PP-StructureV3 и Docling удобнее для широкого разбора документов, где таблица — лишь один из элементов. LayoutParser подходит как конструктор исследовательского процесса. Camelot и Tabula проще для электронных PDF с предсказуемыми таблицами, но хуже переносятся на изображения и сложные шапки.

Как выбрать модель структуры

Базовая structure-recognition обучена на PubTables-1M и хорошо соответствует научным публикациям. Вариант v1.1-pub сохраняет ориентацию на этот корпус с согласованной обработкой. Вариант v1.1-fin обучен на исправленном FinTabNet и полезен для финансовых таблиц. Вариант v1.1-all объединяет оба набора и отмечен в официальной коллекции как наиболее сильная общая модель структуры. Но выбор по названию домена не заменяет испытание на собственных документах.

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

Модель detection обычно остаётся отдельной от структуры. Замена только структурных весов не исправит пропущенные области на странице. Если документы уже содержат координаты таблиц или области выделяет другой макетный анализатор, detection можно не использовать. Это полезно при интеграции с системой, которая одновременно находит заголовки, рисунки и текстовые блоки.

Контрольный процесс от страницы до проверенного результата

1. Отрендерить страницу и сохранить параметры масштаба, чтобы координаты PDF и пиксели можно было взаимно преобразовать.
2. Получить слова с bbox из текстового слоя или OCR, привести их к порядку чтения и визуально проверить несколько прямоугольников.
3. Запустить detect, сохранить объекты и фрагменты, проверить полноту таблиц и отсутствие лишних подписей.
4. Запустить recognize для каждого фрагмента, сохранить исходные объекты и согласованные ячейки.
5. Построить визуализацию, проверить строки, столбцы, заголовки и объединённые области.
6. Сформировать HTML и CSV, затем валидировать прямоугольность, число полей и уникальность заголовков.
7. Применить доменные правила к числам, датам, единицам и группам строк, не меняя исходное представление без журнала.
8. Сохранить страницу, координаты, версии весов и конфигурацию, чтобы каждое значение можно было проследить до источника.

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

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

Имена выходных файлов следует формировать без простого replace для произвольных расширений. Надёжнее использовать объект пути, отделять stem и добавлять суффикс результата. Это исключает случайную замену последовательности .jpg внутри длинного имени и поддерживает PNG или TIFF после небольшой адаптации сценария. Для каждого файла сохраняют JSON-манифест с исходным путём, размером, режимом и статусом.

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

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

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

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

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

Координаты объектов и интерпретация результатов

Каждый найденный объект описывается меткой, оценкой и прямоугольником в формате x1, y1, x2, y2. После выхода модели рамки переводятся из нормализованного представления относительно размера входного тензора в пиксели исходного изображения. При сохранении результатов полезно не округлять координаты слишком рано: целые значения удобны для рисования, но дробная точность позволяет стабильнее пересчитать рамку при изменении масштаба или вернуть её в систему PDF.

Координаты вырезанной таблицы и координаты ячеек находятся в разных системах. Детектор сообщает положение относительно страницы, а структурная модель — относительно crop. Чтобы получить абсолютную рамку ячейки на странице, к её x и y добавляют начало области таблицы с учётом padding и возможного поворота. Для table rotated преобразование выполняют в обратном порядке: сначала возвращают координаты из повёрнутого фрагмента, затем добавляют смещение crop. Без этого трассировка ячейки к PDF будет неверной.

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

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

Настройка поля вокруг найденной таблицы

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

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

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

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

Проверка многоуровневых заголовков

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

Проекционный заголовок строки отличается от обычного объединения. Он обычно занимает несколько столбцов или всю ширину и вводит группу последующих строк. В аналитическом представлении его текст часто нужно распространять вниз как ключ группы, но в визуальном HTML достаточно сохранить rowspan или отдельную строку. Решение принимают после распознавания, не изменяя исходный признак projected row header.

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

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

Подготовка собственных обучающих данных

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

Для structure изображение уже представляет одну таблицу. Аннотация включает общий объект table, каждую строку, каждый столбец, область column header, spanning cells и projected row headers. Базовые строки и столбцы должны образовывать полную прямоугольную сетку, включая пустые позиции. Пропуск пустого столбца изменяет топологию, хотя визуально таблица может выглядеть почти одинаково.

Разделение на train, validation и test выполняют по документам, а не по отдельным таблицам из одного PDF. Иначе одинаковый шаблон, шрифт и содержание попадут одновременно в обучение и оценку, создавая завышенный результат. Для форм и отчётов дополнительно разделяют по периоду или организации, чтобы тест отражал реальный перенос на новые документы.

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

Перед запуском обучения полезен валидатор разметки: рамки находятся внутри изображения, x2 больше x1, y2 больше y1, каждая строка пересекает таблицу, каждый столбец пересекает таблицу, spanning cell покрывает целое число базовых ячеек, а header соответствует верхним строкам. Ошибки разметки лучше остановить до загрузки в DataLoader, иначе они проявятся как нестабильный loss или ухудшение метрик без понятной причины.

Регрессионный набор для обновлений

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

Сравнение по одному итоговому баллу скрывает регрессии. Отчёт должен показывать добавленные и удалённые детекции, изменение класса поворота, число строк и столбцов, spanning cells, GriTS по трём вариантам и различия текста по ячейкам. Улучшение среднего GriTS не считается достаточным, если критичный шаблон отчёта перестал извлекаться полностью.

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

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

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

Нормализация текста после распределения по ячейкам

Текст нормализуют только после того, как токены распределены по структуре. Раннее удаление пробелов, дефисов или знаков способно изменить координатные боксы и порядок. На первом этапе сохраняют исходную строку и список токенов. Затем создают отдельное нормализованное поле для поиска, числового анализа или сравнения. Это обеспечивает обратимость и позволяет показать пользователю точный фрагмент документа.

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

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

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

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

Интеграция официального сценария и API Transformers

Официальный сценарий удобен тем, что содержит полный набор постобработки: вырезание таблиц, поворот, согласование строк и столбцов, построение ячеек, HTML, CSV и визуализации. API Transformers удобнее для стандартной загрузки моделей, кэширования и работы с современным кодом приложения. На практике часто объединяют оба подхода: модель и препроцессор загружают через Transformers, а алгоритмы формирования структуры адаптируют из inference.py.

При такой интеграции проверяют соответствие id2label. Числовые классы должны точно отображаться в table, table rotated либо набор структурных меток. Ошибка в словаре не вызывает сбоя вычислений, но превращает строки в столбцы или заголовки в spanning cells. Словарь сохраняют вместе с моделью и тестируют на изображении, где ожидаемые классы очевидны.

Различия препроцессинга также существенны. Размер, нормализация, padding и порядок каналов должны соответствовать модели. Если рамки после перехода к другому процессору систематически смещаются, проверяют target_sizes и преобразование cxcywh в xyxy. Сравнение выполняют на одном изображении с фиксированным порогом, выводя сырые логиты и координаты до постобработки.

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

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

Итоговая оценка возможностей

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

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

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