PaddleOCR PP-Structure разбирает PDF и изображения на смысловые области, распознаёт текст, таблицы, формулы, печати и диаграммы, восстанавливает порядок чтения и сохраняет результат в Markdown, JSON, DOCX, HTML или XLSX. Пользователь может обработать одну страницу, многостраничный документ или каталог изображений, включить коррекцию поворота и геометрических искажений, заменить модели для нужного языка и получить координаты блоков, строк, слов и ячеек для дальнейшей автоматизации.

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

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

Как устроен конвейер обработки документов

PP-Structure рассматривает страницу не как сплошную картинку, а как набор областей с разными правилами обработки. Сначала система определяет ориентацию листа и при необходимости исправляет поворот на 90, 180 или 270 градусов. Затем модуль выравнивания может устранить перспективное и волнообразное искривление, характерное для фотографии книги, страницы у корешка или кадра, снятого под углом. После подготовки запускается детектор макета, который отмечает заголовки, обычный текст, таблицы, изображения, подписи, формулы, колонтитулы, номера страниц, сноски, списки, печати и другие типы блоков.

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

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

Какие входные данные подходят для разбора

В командной строке вход задаётся параметром -i, а в Python — аргументом input метода predict(). Поддерживается путь к изображению или PDF, объект numpy.ndarray, список допустимых объектов и каталог с изображениями. Для каталога действует важное ограничение: PDF внутри него не обходятся как обычные картинки, поэтому многостраничные файлы следует передавать точным путём. Это предотвращает неявную обработку больших архивов, но требует заранее разделить очередь на изображения и PDF.

Для сервисного вызова файл передают как Base64 или как адрес, доступный серверу. Тип можно указать явно: PDF и изображение кодируются разными значениями поля fileType. Многостраничный TIFF разворачивается по страницам. В типовой конфигурации служба ограничивает число страниц для одного запроса, поэтому длинные документы нужно либо разрешить в конфигурации, либо делить на части, чтобы не получить тайм-аут и резкий рост памяти.

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

Установка компонентов и проверка среды

Для функций структурного разбора используется группа зависимостей doc-parser. Базовая команда выглядит так: python -m pip install "paddleocr[doc-parser]". Отдельно требуется движок инференса. Выбор зависит от процессора, видеокарты, версии CUDA и задач: для стандартного запуска применяется Paddle, для части моделей доступны Transformers и ONNX Runtime. Смешивать случайные сборки движка и CUDA нежелательно, поскольку несовместимость проявляется уже при загрузке весов или создании первого тензора.

Надёжная схема начинается с новой виртуальной среды. Сначала проверяют версию Python, затем обновляют pip, устанавливают выбранный движок и только после этого пакет с группой doc-parser. Отдельная среда защищает проект от конфликтов NumPy, OpenCV, токенизаторов и библиотек ускорения. Для обучения и экспорта моделей нужен дополнительный набор зависимостей; его не следует устанавливать в среду простого распознавания, если обучение не планируется.

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

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

Минимальная команда состоит из имени конвейера и входного файла: paddleocr pp_structurev3 -i document.pdf. Без пути сохранения результат выводится в терминал, но файлы не создаются. Для практической работы задают --save_path output, чтобы собрать машинные результаты и визуализации в отдельной папке. Каталог лучше делать новым для каждого задания: одинаковые имена страниц и вложенных изображений иначе могут затруднить сравнение прогонов.

Команда удобна для диагностики. Параметр --device выбирает устройство, например CPU или конкретный GPU. Переключатели --use_doc_orientation_classify, --use_doc_unwarping и --use_textline_orientation включают коррекцию ориентации листа, геометрии и направления строк. Отдельно управляются распознавание таблиц, формул, печатей и диаграмм. Отключение ненужного модуля сокращает загрузку весов, потребление памяти и время страницы.

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

Интеграция через Python и объект результата

В коде создают объект PPStructureV3, затем вызывают predict(). Метод возвращает последовательность результатов: для изображения обычно один элемент, для PDF — элемент на каждую обработанную страницу. Базовый шаблон включает цикл, в котором вызываются print(), save_to_json(), save_to_markdown(), save_to_word() или save_to_img(). Разделение по страницам удобно для контроля памяти и позволяет повторно обработать только сбойный лист.

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

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

Форматы результата и назначение каждого из них

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

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

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

Разбор многостраничных PDF

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

Для единого Markdown собирают словари markdown из каждого результата, передают список в concatenate_markdown_pages(), а изображения из всех страниц сохраняют по относительным путям. Имена вложений должны оставаться уникальными. При повторном запуске в ту же папку лучше очищать старые изображения, иначе документ может ссылаться на файл от предыдущей конфигурации.

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

Определение областей и настройка порогов макета

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

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

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

Восстановление порядка чтения

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

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

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

OCR текста и выбор языковой модели

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

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

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

Коррекция поворота, перспективы и направления строк

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

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

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

Таблицы: от рамки до структуры ячеек

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

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

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

Распознавание формул

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

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

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

Диаграммы и преобразование графика в таблицу

Модуль диаграмм пытается превратить визуальные значения в структурированную таблицу. Он рассчитан на столбчатые, линейные, круговые и другие распространённые графики, где легенда, подписи осей и отметки образуют данные. Это отличается от обычного OCR: требуется связать цвет или серию с конкретным числом и восстановить порядок категорий.

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

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

Печати, штампы и нестандартные текстовые области

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

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

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

Markdown для RAG и поисковых систем

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

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

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

JSON и координаты для собственных приложений

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

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

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

Конфигурация YAML и замена моделей

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

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

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

Производительность, память и выбор устройства

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

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

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

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

Параллельная обработка и пакетные задания

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

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

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

Развёртывание как HTTP-службы

Конвейер можно опубликовать как службу с операцией разбора макета. Запрос отправляется методом POST и содержит JSON. В поле file передают Base64 или доступный службе файл, а переключатели управляют ориентацией, выравниванием, таблицами, формулами, диаграммами, печатями и визуализациями. Ответ содержит идентификатор запроса, код ошибки и массив результатов страниц.

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

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

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

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

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

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

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

Ошибка импорта после установки обычно означает конфликт среды или отсутствие группы doc-parser. Проверьте, что команда и Python относятся к одному виртуальному окружению. Запуск python -m pip предпочтительнее отдельного pip, потому что явно использует выбранный интерпретатор. После обновления зависимости перезапустите процесс, чтобы он не держал старые библиотеки в памяти.

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

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

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

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

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

Практические сценарии использования

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

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

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

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

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

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

У PP-Structure нет привычного окна с кнопками, страницами и панелью инструментов. Основные способы управления — командная строка, Python и HTTP. Это даёт гибкость разработчику, но для оператора без технической подготовки потребуется оболочка: форма загрузки, очередь, просмотр визуализаций и экспорт результатов.

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

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

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

Сравнение PaddleOCR PP-Structure с аналогами

Программа	Лучше подходит для	Главное ограничение
PaddleOCR PP-Structure	Подробного структурного разбора PDF и изображений с координатами, таблицами, формулами, диаграммами и настраиваемыми модулями	Требует настройки Python, моделей и вычислительной среды
PDF Commander	Ручного редактирования, распознавания, сборки и оформления PDF в понятном графическом интерфейсе	Не формирует детальный JSON-конвейер для RAG и программной разметки макета
Docling	Унифицированного преобразования большого числа офисных и публикационных форматов в структурное представление	Набор моделей и геометрических полей отличается, поэтому миграция постпроцессоров требует адаптации
MinerU	Преобразования научных и сложных документов в Markdown и JSON с акцентом на формулы и макет	Тяжёлые конфигурации предъявляют высокие требования к ресурсам и качеству входа
Unstructured	Ингеста документов разных типов, выделения элементов и подготовки фрагментов для LLM-конвейеров	Точная реконструкция сложных таблиц и формул зависит от выбранной стратегии и дополнительных компонентов
Mathpix	Облачного преобразования STEM-документов, формул и таблиц в Markdown, LaTeX и офисные форматы	Обработка зависит от внешнего сервиса и условий коммерческого доступа

Выбор зависит от следующего шага. Для ручной правки и выпуска PDF разумнее PDF Commander. Для программного конвейера с точными координатами и заменяемыми модулями подходит PP-Structure. Docling удобен при множестве входных офисных форматов, MinerU — при насыщенных научных публикациях, Unstructured — при построении широкой системы ингеста и чанкинга, Mathpix — когда приоритетом является готовое облачное преобразование математики и химии.

Как выбрать конфигурацию под документ

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

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

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

Ответы на практические вопросы

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

Почему в выходной папке нет файлов? Путь сохранения должен быть указан явно, либо в Python нужно вызвать соответствующий метод save_to_*. Вывод print() показывает структуру в терминале, но не создаёт документ автоматически.

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

Можно ли отключить таблицы или формулы? Да. Переключатели передаются при создании объекта, вызове predict() или в конфигурации. Отключение уменьшает затраты и число ложных срабатываний на документах без таких объектов.

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

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

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

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

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

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

Проектирование папок и имён результатов

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

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

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

Логирование и наблюдаемость

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

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

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

Постобработка текста без потери доказательств

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

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

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

Работа с низкой уверенностью

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

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

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

Безопасное обновление рабочего окружения

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

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

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

Параметры запуска: постоянная конфигурация и разовые изменения

Параметры удобно разделить на две группы. Имена моделей и каталоги весов обычно задают при создании PPStructureV3, потому что они определяют состав конвейера на всё время жизни объекта. К этой группе относятся layout_detection_model_name, text_detection_model_name, text_recognition_model_name, каталоги моделей таблиц, формул, диаграмм, печатей, ориентации и выравнивания. Значение None означает выбор модели из стандартной конфигурации; если локальный каталог не указан, нужные файлы загружаются автоматически. В производственном процессе каталоги лучше фиксировать явно, чтобы повторный запуск не зависел от состояния общего кэша и доступности сети.

Переключатели, которые зависят от конкретного документа, можно передавать в predict(). Параметры use_doc_orientation_classify, use_doc_unwarping и use_textline_orientation включают исправление ориентации листа, геометрии страницы и направления строк. Аналогично управляются use_table_recognition, use_formula_recognition, use_seal_recognition, use_chart_recognition и use_region_detection. Такой способ позволяет один раз загрузить модели и затем запускать быстрый профиль для простых отчётов либо полный профиль для сложных научных и архивных страниц.

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

Точная настройка детектора макета

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

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

При наложении областей параметр layout_merge_bboxes_mode выбирает, какую геометрию сохранить. Режим large оставляет большую рамку, small — меньшую, а union формирует объединение. Словарь позволяет применять разные правила к разным классам. Для рисунка с подписью большая область может быть удобна как единый объект, а для формулы внутри текстового блока требуется сохранить точную меньшую рамку, чтобы общий OCR не повторил математическую запись. Универсального режима нет: решение принимают по тому, как последующий экспорт должен представлять вложенные элементы.

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

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

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

text_rec_score_thresh фильтрует распознанные строки по уверенности. Нулевой порог сохраняет всё и удобен для диагностики; высокий порог делает результат чище, но способен удалить редкое имя, номер детали или строку на печати. Для автоматизации безопаснее оставить низкоуверенный текст в JSON и пометить его для проверки, чем безвозвратно исключать. Отдельно проверяйте выбор языковой модели: стандартная китайско-английская модель не является оптимальной для каждого языка. Язык меняют на уровне модели распознавания, после чего повторно оценивают не только символы, но и разбиение строк.

Расширенная обработка таблиц

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

Флаги use_wired_table_cells_trans_to_html и use_wireless_table_cells_trans_to_html управляют использованием найденных ячеек при построении HTML. use_ocr_results_with_table_cells подключает OCR-результаты к сопоставлению содержимого и ячеек. Параметры use_e2e_wired_table_rec_model и use_e2e_wireless_table_rec_model позволяют задействовать сквозные модели соответствующего типа. Менять сразу все переключатели не следует: сначала определите, неверно ли найдены границы, структура или текст. Иначе улучшение одного этапа будет скрыто ошибкой другого.

После экспорта в HTML или XLSX проверяйте не только внешний вид. Сравните число строк и столбцов, координаты объединений, порядок заголовков и привязку текста к ячейкам. Числовые столбцы контролируют по допустимому типу и суммам, даты — по формату и диапазону, единицы измерения — по заголовку. Если таблица используется в расчётах, сохраните ссылку на страницу и координаты исходной области. Это позволит открыть соответствующий фрагмент при спорном значении и не превращать распознавание в необъяснимый импорт.

Сборка многостраничного Markdown

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

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

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

Контракт HTTP-службы и размер ответа

В запросе к развёрнутой службе поле file принимает Base64-содержимое либо адрес файла, доступный серверу. fileType позволяет явно указать PDF или изображение; явное значение надёжнее автоматического определения, когда адрес не содержит расширения. Переключатели модулей передаются в camelCase, например useTableRecognition, useFormulaRecognition и useDocUnwarping. Пороговые параметры также доступны в запросе, поэтому клиент может выбрать профиль без создания отдельной службы для каждого типа документа.

Ответ содержит массив layoutParsingResults: один элемент для изображения и по одному элементу на обработанную страницу PDF. Внутри находятся упрощённый prunedResult, объект markdown, входное изображение, визуализации и дополнительные экспорты, если они запрошены. Поле outputFormats в сервисном контракте используют для дополнительных форматов; поддерживаемый вариант следует сверять с документацией развёрнутой службы. Клиент обязан терпимо обрабатывать отсутствие необязательных полей, поскольку возврат изображений и экспортов зависит от настроек.

Бинарные поля по умолчанию могут приходить как Base64, а при настройке хранилища — как подписанные временные адреса. Base64 увеличивает JSON и память клиента, особенно для многостраничного PDF с визуализациями. Параметр visualize и настройка returnMarkdownImages позволяют отказаться от ненужных изображений. Для внешнего доступа задайте ограничение размера запроса, числа страниц, времени обработки и частоты вызовов. Не передавайте секреты в теле документационного запроса и не журналируйте Base64 исходника.

Диагностика по этапам конвейера

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

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

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

Подготовка результата для RAG и семантического поиска

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

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

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

Приёмочное тестирование и регрессионный набор

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

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

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

Чек-лист перед массовой обработкой

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

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

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

Итоговый рабочий порядок

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

Храните исходный JSON, итоговый Markdown и сведения о конфигурации. DOCX, HTML и XLSX создавайте как пользовательские представления, а не как единственный источник данных. При обновлении среды прогоняйте тот же набор страниц и сравнивайте метрики и изображения. Такой процесс превращает распознавание из разовой команды в воспроизводимый конвейер, где результат можно проверить, объяснить и безопасно использовать в поиске, аналитике и автоматизации документов.