Surya OCR распознаёт текст на страницах PDF и изображениях, находит строки и смысловые блоки, восстанавливает порядок чтения, выделяет таблицы и возвращает результат с координатами, метками структуры и HTML-разметкой. Инструменты командной строки и Python API позволяют обрабатывать один файл, выбранные страницы или целую папку, сохранять наглядные наложения и передавать структурированный JSON в поисковый индекс, систему извлечения данных или собственный конвертер документов.

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

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

Как устроен рабочий процесс

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

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

Команда `surya_ocr` запускает полный конвейер. Ключ `--output_dir` отделяет результаты от исходников, `--page_range` ограничивает страницы, а `--images` включает сохранение визуализаций. Параметр `--keep_server` полезен при серии запусков: backend остаётся активным между заданиями, поэтому не приходится заново загружать модель перед каждым небольшим пакетом.

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

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

1. Возьмите по одной странице каждого типа: обычный текст, две колонки, таблица, форма, страница с рисунком и мелкими сносками.
2. Запустите распознавание с визуализациями и отдельным выходным каталогом, чтобы исходники не смешались с результатами.
3. Сравните рамки строк, метки блоков и нумерацию порядка чтения с визуальной логикой страницы.
4. Проверьте JSON: координаты должны соответствовать изображению, а HTML — содержать ожидаемую структуру абзацев, заголовков и таблиц.
5. Изменяйте разрешение и пороги только после того, как определено, на какой стадии появляется ошибка.
6. После контрольного прогона обработайте весь каталог и сохраните параметры запуска вместе с результатами для воспроизводимости.

Установка и первый запуск

Пакет устанавливается из Python Package Index командой `pip install surya-ocr`. Для изоляции зависимостей лучше создать отдельное виртуальное окружение с подходящей версией Python, активировать его и только затем устанавливать пакет. Это снижает риск конфликтов между библиотеками машинного обучения, версиями NumPy, средствами работы с PDF и уже существующими проектами.

После установки проверьте доступность команд через справку, например `surya_ocr --help`. Если оболочка не находит исполняемый файл, причиной обычно является неактивное виртуальное окружение или каталог scripts/bin, отсутствующий в PATH. В таком случае активируйте окружение заново, убедитесь, что `python` и `pip` указывают на один и тот же каталог, и повторите проверку.

Полное распознавание, анализ макета и восстановление таблиц используют inference-бэкенд. Для видеокарт NVIDIA предусмотрен вариант на базе vLLM; он требует совместимой среды контейнеров и NVIDIA Container Toolkit. Для процессора и Apple Silicon применяется сервер llama.cpp. Детектор строк остаётся отдельной моделью на PyTorch, поэтому режим поиска строк можно использовать независимо от VLM-бэкенда.

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

Минимальная проверка после установки

• Справка CLI открывается без ошибки импорта.
• Тестовое изображение читается из указанного пути.
• Выходной каталог создаётся и содержит JSON.
• При включённых визуализациях появляется PNG с рамками или подписями.
• Backend отвечает, если запущена операция полного OCR, макета или таблиц.
• Кодировка терминала корректно показывает русские имена файлов и сообщения.

Распознавание текста в PDF

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

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

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

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

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

Работа с отдельными изображениями

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

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

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

При пакетной обработке папки сортируйте изображения естественным образом и заранее исключайте дубликаты. Имена `page1`, `page2`, `page10` некоторые файловые операции располагают лексикографически, поэтому надёжнее использовать нули: `page001`, `page002`. Порядок файлов не заменяет порядок чтения внутри страницы, но влияет на сборку итогового многостраничного результата.

Поиск строк и областей текста

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

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

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

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

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

Признаки ошибки сегментации

• Одна рамка пересекает две колонки.
• Номер страницы объединён с нижней строкой.
• Фрагменты формулы разбиты на десятки мелких областей.
• Вертикальная линия таблицы распознана как текст.
• Бледная сноска не получила рамку.
• Поворот страницы привёл к диагональным или пустым областям.

Анализ макета страницы

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

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

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

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

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

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

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

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

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

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

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

Распознавание форм и анкет

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

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

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

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

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

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

Восстановление таблиц

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

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

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

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

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

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

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

Структура JSON и координаты

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

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

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

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

Рекомендуемая модель хранения

Поле	Назначение	Что проверить
document_id	Связь результата с исходником	Не меняется при повторном прогоне
page_index	Положение страницы	Совпадает с выбранным диапазоном
page_width, page_height	Масштаб координат	Сохранены до ресайза превью
label	Тип структурного блока	Входит в ожидаемый набор меток
reading_order	Последовательность чтения	Нет необъяснимых скачков
polygon, bbox	Геометрия области	Точки лежат внутри страницы
html	Распознанное содержимое	Очищено перед публикацией
confidence	Оценка уверенности	Используется как сигнал, а не абсолютная истина
skipped, error	Состояние обработки	Ошибки не заменены пустым текстом

HTML-разметка, формулы и специальный контент

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

Математические выражения могут оформляться тегом `math` с LaTeX-совместимым содержимым для отображения через KaTeX. Проверять формулы нужно посимвольно: индекс, степень, греческая буква или знак отношения меняют смысл даже при внешне небольшом расхождении. Для критичных публикаций автоматическое OCR формул следует дополнять ручной верификацией или проверкой по исходным данным.

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

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

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

Python API для встраивания в проект

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

Не связывайте прикладную модель данных напрямую со всеми внутренними полями ответа. Создайте слой преобразования, который принимает результат Surya и выдаёт стабильную структуру вашего проекта. Тогда изменение необязательного поля или добавление новой метки не потребует переписывать бизнес-логику. Неизвестные метки лучше сохранять как `other`, но не удалять бесследно.

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

Исключения нужно разделять по происхождению. Ошибка чтения файла, нехватка памяти, недоступность inference-сервера и некорректный ответ требуют разных действий. Для временной сетевой ошибки допустим повтор с задержкой, для повреждённого PDF нужен карантин, а при нехватке памяти — меньший пакет или разрешение. Универсальный бесконечный retry скрывает проблему и расходует ресурсы.

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

Каркас надёжной интеграции

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

Графический интерфейс на Streamlit

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

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

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

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

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

Выбор и настройка inference-бэкенда

Полное OCR, анализ макета и таблиц выполняются через VLM-бэкенд. Для NVIDIA предусмотрен vLLM, ориентированный на ускоренный инференс на видеокарте. Для CPU и Apple Silicon применяется llama.cpp с сервером `llama-server`. Выбор определяется не только наличием оборудования, но и объёмом документов, требуемой задержкой, доступной памятью и способом развёртывания.

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

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

Параметр `SURYA_INFERENCE_KEEP_ALIVE` управляет временем сохранения модели в памяти, а `--keep_server` предотвращает завершение сервера после команды. Для серии коротких заданий это экономит время загрузки. На общей машине длительное удержание модели может мешать другим задачам, поэтому режим следует согласовать с планировщиком ресурсов.

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

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

Метрика	Зачем нужна	Как интерпретировать
Время первой страницы	Учитывает загрузку модели	Высокое значение нормально при холодном старте
Среднее время страницы	Показывает рабочую скорость	Считать после прогрева
Пиковая память	Определяет устойчивый пакет	Оставлять резерв для системы
Ошибки на 100 страниц	Показывает надёжность	Разделять сеть, память и входные файлы
Доля ручной проверки	Отражает полезное качество	Измерять по типам документов
Пропускная способность	Помогает планировать очередь	Сравнивать при одинаковом разрешении

Память, скорость и масштаб изображения

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

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

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

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

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

Многоязычные документы

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

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

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

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

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

Формулы, цифры и знаки

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

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

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

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

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

Пакетная обработка каталогов

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

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

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

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

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

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

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

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

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

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

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

Минимальный протокол приёмки

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

Контроль качества без эталонной расшифровки

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

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

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

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

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

Предварительная обработка сканов

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

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

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

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

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

Ошибки запуска и способы устранения

Команда не найдена

Проверьте, что виртуальное окружение активировано и установка выполнялась тем же интерпретатором. Команды `python -m pip --version` и путь к `python` должны указывать на одно окружение. В Windows исполняемые сценарии находятся в каталоге Scripts, в Unix-подобных системах — в bin. Не добавляйте случайные каталоги глобально, если достаточно активировать окружение.

Ошибка импорта библиотеки

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

Backend недоступен

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

Нехватка памяти

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

Пустой или почти пустой результат

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

Текст читается, но порядок неверен

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

Таблица превращается в обычный текст

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

Визуализации не сохранились

Проверьте ключ `--images`, права на выходной каталог и свободное место. Убедитесь, что смотрите каталог, указанный через `--output_dir`, а не папку исходника. В пакетной обработке имена могут находиться во вложенных каталогах, поэтому ищите по манифесту задания.

Разметка форм и порядок полей

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

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

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

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

Экспорт и дальнейшее использование

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

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

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

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

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

Безопасность и конфиденциальность

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

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

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

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

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

Практические ограничения

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

Для полного OCR, макета и таблиц нужен отдельный inference-бэкенд. Это усложняет первый запуск по сравнению с утилитой, которая полностью работает одним процессом. Зато сервер можно держать прогретым и разделять между клиентами. В эксплуатационной инструкции следует явно описать запуск, адрес, проверку здоровья и остановку backend.

Готового редактора результата и универсального офисного экспорта нет. Пользователь получает JSON, HTML и визуализации, а исправление и сборка DOCX требуют собственного интерфейса или стороннего инструмента. Если задача состоит в ручном открытии PDF, правке страницы и сохранении, удобнее выбрать визуальный PDF-редактор.

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

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

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

Оцифровка технической документации

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

Извлечение данных из форм

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

Поиск по архиву PDF

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

Разбор финансовых таблиц

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

Подготовка датасета

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

Сравнение Surya OCR с аналогами

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

Программа	Лучше подходит для	Главное ограничение
Surya OCR	Структурного OCR, макета, порядка чтения и таблиц в собственном конвейере	Требует настройки inference-бэкенда и экспорта
PaddleOCR	Многоязычного OCR и готовых модулей анализа документов	Большой набор компонентов усложняет выбор конфигурации
Tesseract OCR	Классического распознавания печатного текста и встраивания в лёгкие процессы	Сам по себе слабее восстанавливает сложный макет и таблицы
EasyOCR	Быстрого распознавания строк на изображениях через простой Python API	Не ориентирован на полноценную структуру многостраничных документов
OCRmyPDF	Добавления поискового текстового слоя к сканированным PDF	Не заменяет детальный JSON макета и таблиц
PDF Commander	Ручного редактирования, сборки и преобразования PDF в понятном интерфейсе	Не предназначен для серверного OCR-конвейера с координатами блоков

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

EasyOCR удобен для короткого Python-сценария, который читает надписи и строки на изображениях, но не заменяет полноценную модель документа. OCRmyPDF лучше выбирать, когда конечная цель — получить поисковый PDF с сохранением исходных страниц, а не разобрать документ в структурированный JSON. PDF Commander подходит пользователю, которому важнее вручную открыть, изменить, объединить или экспортировать PDF, чем строить программную очередь распознавания.

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

Как выбрать параметры для конкретного документа

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

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

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

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

Чек-лист перед массовым распознаванием

1. Подготовлена репрезентативная выборка всех шаблонов и уровней качества.
2. Проверены строки, макет, порядок чтения и таблицы на соответствующих страницах.
3. Выбран масштаб, который сохраняет мелкие символы без избыточного расхода памяти.
4. Настроен и защищён inference-бэкенд, проверена его доступность.
5. Параллелизм измерен на реальной нагрузке, а не на одном простом изображении.
6. Выходные каталоги отделены от исходников и защищены от перезаписи.
7. Манифест содержит хэши, число страниц и состояния обработки.
8. Ошибки разделены на временные, ресурсные и повреждённые входы.
9. Определены правила очистки HTML, нормализации Unicode и числовых значений.
10. Настроена очередь ручной проверки для критичных и низкоуверенных полей.
11. Визуализации сохраняются для спорных страниц и выборочного аудита.
12. Измеряется полнота: у каждого файла и каждой страницы есть конечный статус.

Чек-лист проверки одной страницы

• Ориентация страницы правильная, поля не обрезаны.
• Все смысловые строки получили рамки.
• Рамки не пересекают независимые колонки.
• Заголовки, подписи, таблицы и рисунки получили подходящие метки.
• Порядок чтения сохраняет связность абзацев.
• Колонтитулы не попали в середину текста.
• Формулы и специальные символы визуально совпадают с оригиналом.
• Таблица сохраняет число колонок и объединённые ячейки.
• Координаты накладываются на страницу без сдвига.
• Поля error и skipped обработаны явно.
• HTML очищен перед отображением.
• Критичные числа прошли предметную валидацию.

Организация ручной проверки

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

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

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

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

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

Воспроизводимость и обновление рабочего процесса

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

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

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

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

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

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

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

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

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