MMOCR помогает находить текстовые области на изображениях, распознавать содержимое строк, объединять детектор и распознаватель в сквозной OCR‑конвейер и выделять ключевые поля в чеках или формах. Пользователь выбирает модель через MMOCRInferencer либо специализированный Inferencer, передаёт файл, массив NumPy или папку и получает координаты, строки, оценки уверенности, JSON‑совместимые результаты и визуализацию с рамками.

Рабочий процесс строится вокруг двух уровней интерфейса. MMOCRInferencer удобен, когда нужно быстро связать детекцию, распознавание и извлечение полей одной командой, а TextDetInferencer, TextRecInferencer, TextSpottingInferencer и KIEInferencer дают более точный контроль над отдельной задачей. Модель можно указать зарегистрированным именем либо загрузить собственную конфигурацию и контрольную точку; устройство вычислений выбирается отдельно для каждого экземпляра.

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

Как устроен рабочий экран и запуск распознавания

У MMOCR нет привычной панели с кнопками Открыть, Распознать и Сохранить. Роль интерфейса выполняют Python API, командная строка, окно визуализации и каталоги результатов. Такая организация сначала кажется сложнее обычной OCR‑утилиты, зато каждое действие можно повторить на сотнях файлов без ручного кликанья. Для разовой проверки достаточно создать Inferencer, передать изображение и включить показ результата; для регулярной обработки те же параметры переносятся в скрипт или задаются аргументами команды.

Новому пользователю удобнее начинать с MMOCRInferencer. Он принимает параметры det, rec и kie и сам выстраивает цепочку в нужном порядке. Если указан только det, возвращаются найденные текстовые области. Пара det и rec запускает полный OCR: сначала изображение размечается полигонами, затем каждая область отправляется распознавателю. KIE становится доступен, когда одновременно заданы детектор и распознаватель, поскольку модулю извлечения полей нужны координаты и текстовые признаки.

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

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

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

В командной строке входной путь указывается первым, а модели передаются через параметры детекции и распознавания. Флаг print-result выводит словарь предсказаний, show открывает визуализатор, а out-dir вместе с save-pred и save-vis сохраняет данные. Для автоматизации лучше не полагаться только на текст в консоли: JSON‑файлы проще сопоставлять с исходными изображениями, проверять программно и повторно использовать в поисковом индексе или системе разметки.

python tools/infer.py scans/page_001.png --det DBNet --rec SAR --print-result --out-dir results --save-pred --save-vis

В Python тот же процесс начинается с создания объекта. Инициализацию следует выполнять один раз, а затем передавать ему все изображения, иначе веса будут повторно загружаться в память и пакетная обработка станет заметно медленнее. Объект можно привязать к cpu или конкретному cuda‑устройству. Когда параметр device не задан, библиотека выбирает доступное устройство автоматически, но в производственном скрипте явное значение упрощает диагностику и распределение задач между несколькими ускорителями.

from mmocr.apis import MMOCRInferencer
ocr = MMOCRInferencer(det='DBNet', rec='SAR', device='cuda:0')
result = ocr('scans', batch_size=4, out_dir='results', save_pred=True, save_vis=True)

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

Подготовка изображений и страниц PDF

MMOCR обрабатывает растровые изображения, а не структуру PDF. Файл PDF нужно предварительно разложить на страницы PNG, JPEG или TIFF внешним конвертером. Для архивного документа желательно сохранить постоянный масштаб и нумерацию: page_0001.png, page_0002.png и далее. Тогда выходной JSON и визуализация наследуют понятное имя, а найденный текст можно без двусмысленности вернуть к исходной странице.

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

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

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

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

Детекция текстовых областей

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

DBNet и DBNet++ часто выбирают как отправную точку для печатного текста и сцен с произвольным расположением надписей. PANet и PSENet используют иной подход к формированию текстовых экземпляров, TextSnake и FCENet ориентированы на сложные и изогнутые формы, а Mask R‑CNN даёт сегментационную постановку. Нельзя считать одну архитектуру универсально лучшей: вывески, чеки, книжные страницы и рукописные формы отличаются масштабом, фоном и геометрией.

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

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

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

Порядок чтения после детекции

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

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

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

Распознавание строк и отдельных слов

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

Семейство распознавателей включает CRNN, SAR, SATRN, SVTR, ABINet, ASTER, MASTER, NRTR и RobustScanner. Они различаются способом извлечения признаков, декодирования последовательности, вниманием и обработкой искажений. CRNN удобен как понятная базовая линия, модели с вниманием лучше справляются с некоторыми нерегулярными строками, а архитектуры с трансформерами требуют иной баланс памяти и скорости. Выбор подтверждают измерением на собственных данных.

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

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

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

Работа с несколькими языками

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

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

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

Сквозной OCR: детектор и распознаватель вместе

Полный OCR в MMOCR строится как последовательность детекции и распознавания. Детектор находит N областей, каждая область преобразуется в изображение строки, распознаватель возвращает N текстов, после чего результаты связываются с исходными полигонами. В объединённом словаре поля det_polygons, det_bboxes, det_scores, rec_texts и rec_scores имеют согласованный порядок. Это позволяет фильтровать строку одновременно по качеству локализации и чтения.

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

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

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

Фильтрация и объединение результата

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

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

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

Извлечение ключевой информации

KIE превращает набор распознанных фрагментов в структурированные поля. Для каждого текстового узла модель предсказывает метку, а для пары узлов — связь. На чеке это могут быть категории названия товара, количества, цены, итога или даты; в форме — вопрос, ответ, заголовок и прочие элементы. Результат содержит kie_labels, kie_scores, kie_edge_labels и kie_edge_scores, поэтому можно отдельно анализировать классификацию узлов и качество связей.

MMOCR использует SDMG‑R как готовую архитектуру для этого класса задач. Она опирается на текстовые и пространственные признаки, поэтому качество входной детекции критично. Неверная рамка меняет координаты и может объединить два поля, а ошибка OCR искажает текстовый признак. При диагностике KIE нужно сохранять три уровня: исходные области, распознанные строки и итоговые метки. Только так видно, на какой стадии возник сбой.

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

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

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

Практический конвейер для чеков и форм

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

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

Форматы входа, выхода и сохранения данных

Стандартные Inferencer принимают путь к изображению, сетевой адрес изображения, массив NumPy, список таких объектов или путь к каталогу. Массив должен быть в порядке каналов BGR. Это важно при интеграции с Pillow и библиотеками, использующими RGB: незаметная перестановка каналов ухудшает распознавание цветных надписей и меняет визуализацию. Перед передачей массива полезно проверить несколько пикселей или сохранить тестовый кадр.

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

По умолчанию результат возвращается словарём с predictions и visualization. Список visualization пуст, пока не включён return_vis. Предсказания приводятся к JSON‑совместимому виду: массивы координат становятся обычными списками, строки и оценки можно сериализовать без знания внутренних классов. Если нужны исходные DataSample, параметр return_datasamples возвращает объекты с более полной структурой, но их сложнее передавать между процессами и хранить длительное время.

При save_pred создаётся JSON для каждого входного изображения, при save_vis — изображение с разметкой. Файлы размещаются в подпапках preds и vis. Имя соответствует исходному имени, а для массива без имени используется последовательный номер. Чтобы избежать коллизий между документами с одинаковыми page_001.png, входные имена должны содержать идентификатор документа либо каждый документ следует обрабатывать в отдельный out_dir.

Тип задачи	Основные поля результата	Практическое применение
Детекция	polygons, bboxes, scores	Кадрирование, разметка страницы, контроль пропусков
Распознавание	text, scores	Чтение подготовленной строки или поля
Сквозной OCR	det_polygons, det_scores, rec_texts, rec_scores	Текст с привязкой к координатам
KIE	labels, scores, edge_labels, edge_scores	Классы полей и отношения между ними
Визуализация	массив изображения либо файл	Ручной аудит и поиск ошибок конвейера

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

Выбор модели и контрольных точек

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

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

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

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

Как сравнивать кандидатов

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

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

Конфигурации и изменение параметров

Конфигурации MMOCR — Python‑файлы с наследованием. Основной файл подключает базовую модель, набор данных, расписание и параметры среды через _base_. Это уменьшает копирование, но требует понимать, откуда пришло значение. Перед изменением полезно распечатать разобранную конфигурацию через MMEngine Config: так видны итоговые dataloader, pipeline, optimizer, hooks и visualizer после всех переопределений.

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

Параметр cfg-options в инструментах обучения и тестирования позволяет временно переопределить значение без создания нового файла. Это удобно для work_dir, размера пакета или пути к данным. Для воспроизводимого эксперимента итоговую команду сохраняют в журнале, а важные изменения всё же переносят в отдельную конфигурацию. Иначе через несколько недель невозможно понять, какие опции применялись поверх файла.

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

Параметры, которые нельзя менять изолированно

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

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

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

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

Inferencer принимает список файлов и каталог, а batch_size задаёт общий размер пакета. В объединённом OCR можно отдельно установить det_batch_size, rec_batch_size и kie_batch_size. Эти стадии имеют разный профиль памяти: детектор обрабатывает целые изображения, распознаватель — множество небольших вырезок, KIE — граф узлов. Один общий размер редко оптимален для всех трёх.

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

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

На CPU можно выполнять вывод и даже обучение, но часть операций отсутствует. Модели с deformable convolution, modulated deformable convolution, ROI pooling или SyncBatchNorm могут завершиться ошибкой. В документации отдельно отмечены варианты DBNet, DBNet++, FCENet с DCN и модели PANet или PSENet. Для процессорного режима выбирают конфигурацию без таких операций и заранее проверяют один полный проход.

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

Обработка больших архивов

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

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

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

Визуализация и аудит качества

MMOCR использует визуализаторы для разных задач: TextDetLocalVisualizer, TextRecogLocalVisualizer, TextSpottingLocalVisualizer и KIELocalVisualizer. Они рисуют предсказания и эталонную разметку с учётом структуры задачи. LocalVisBackend сохраняет данные в каталог, а TensorBoard и WandB можно подключить как другие backend для графиков и изображений. Выбор backend не меняет модель, но определяет, где искать историю эксперимента.

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

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

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

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

Подготовка собственных наборов данных

Dataset Preparer загружает поддерживаемые OCR‑наборы и преобразует их в единый формат. Для ICDAR‑подобного набора команда prepare_dataset.py получает имя и задачу textdet, textrecog, textspotting или kie. После подготовки создаются каталоги изображений и JSON‑аннотации. Если исходный набор уже приведён к поддерживаемому формату, этап загрузки и преобразования можно пропустить.

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

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

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

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

Разметка для детекции

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

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

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

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

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

Разметка для KIE

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

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

Обучение и дообучение моделей

Обучение запускается tools/train.py с конфигурацией. Work-dir содержит журналы и контрольные точки. Параметр resume продолжает процесс с последнего сохранения, amp включает автоматическую смешанную точность, auto-scale-lr помогает масштабировать шаг при изменении эффективного размера пакета, а cfg-options временно переопределяет поля. Перед долгим запуском проверяют, что work-dir новый или намеренно используется для продолжения.

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

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

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

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

Контроль процесса обучения

• Сохраняйте итоговую разобранную конфигурацию рядом с каждой контрольной точкой.
• Фиксируйте seed, версии зависимостей и идентификатор набора данных.
• Проверяйте несколько предсказаний после каждой валидации, а не только число метрики.
• Следите за расхождением train и validation: оно показывает переобучение.
• Не выбирайте модель по тестовой выборке; тест используют после принятия решений.
• Проверяйте восстановление из checkpoint до того, как оно понадобится после сбоя.
• Храните лучшую по метрике и последнюю контрольную точку как разные артефакты.

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

Проверка качества на тестовом наборе

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

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

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

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

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

Как находить слабые группы

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

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

Интеграция MMOCR в прикладной проект

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

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

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

from mmocr.apis import MMOCRInferencer

ocr = MMOCRInferencer(det='DBNet', rec='CRNN')

def recognize(image_path):
    result = ocr(image_path, return_vis=False)
    prediction = result['predictions'][0]
    return {
        'polygons': prediction.get('det_polygons', []),
        'texts': prediction.get('rec_texts', []),
        'scores': prediction.get('rec_scores', [])
    }

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

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

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

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

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

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

Практические сценарии

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

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

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

Фотографии вывесок и упаковок

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

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

Чеки и счета

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

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

Фиксированные формы

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

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

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

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

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

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

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

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

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

Устранение ошибок установки и запуска

Конфликт PyTorch, MMCV и MMDetection

Наиболее частая причина неудачного импорта — несовместимые версии базовых компонентов. Сначала выбирают версию PyTorch под доступную CUDA или CPU, затем устанавливают совместимый MMCV через MIM, после него MMDetection и MMOCR. Проверку выполняют в новом окружении, чтобы старые пакеты не маскировали причину.

Если ошибка упоминает отсутствующий символ, бинарный модуль или несовместимый ABI, переустановка только MMOCR обычно не помогает. Нужно удалить конфликтующую сборку MMCV и поставить вариант, соответствующий PyTorch и CUDA. Версии проверяют непосредственно внутри того интерпретатора, которым запускается скрипт, а не в соседнем окружении.

python -c "import torch, mmcv, mmdet, mmocr; print(torch.__version__); print(mmcv.__version__); print(mmdet.__version__); print(mmocr.__version__)"

Команда должна выполняться тем же Python, который указан в среде разработки, службе или планировщике. Распространённая ситуация — пакет установлен в одном виртуальном окружении, а файл запускается системным Python. Путь к интерпретатору и вывод `python -m pip --version` позволяют быстро обнаружить расхождение.

Не загружается контрольная точка

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

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

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

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

Если список найденных областей пуст, сначала открывают исходное изображение и проверяют его цветовой порядок, размер и диапазон значений. NumPy‑массив ожидается в BGR‑представлении, привычном для OpenCV. Передача RGB без преобразования обычно не вызывает исключения, но меняет цвета и может снизить качество.

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

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

Текст найден, но читается плохо

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

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

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

Нарушен порядок строк

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

Таблицы нельзя надёжно восстановить одной сортировкой центров. Нужно определить строки, столбцы и объединённые ячейки либо использовать специализированный модуль анализа структуры. OCR сообщает текст и координаты; семантическая сетка документа является отдельной задачей.

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

При сообщении out of memory освобождают другие процессы, уменьшают batch size и размер входа, а затем повторяют один файл. Если ошибка остаётся, выбирают более компактную конфигурацию. После аварии CUDA‑контекст процесса может сохранять память, поэтому надёжнее перезапустить процесс, чем многократно продолжать в повреждённом состоянии.

Визуализация не открывается

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

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

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

Программа	Лучше подходит для	Главное ограничение
MMOCR	Исследований, настройки детекции и распознавания, обучения собственных моделей и KIE	Требует Python‑окружения и сборки конвейера
PaddleOCR	Готовых многоязычных OCR‑ и document‑parsing конвейеров	Крупный стек зависимостей и собственная экосистема
Tesseract OCR	Печатного текста, командной обработки и создания текстовых выходных форматов	Слабее справляется со сложным сценическим макетом без подготовки
EasyOCR	Быстрого запуска распознавания множества языков через простой Python API	Меньше инструментов для сложных экспериментов и KIE
docTR	OCR документов с готовой связкой детекции и распознавания	Для нестандартных схем всё равно нужна интеграция и дообучение
PDF Commander	Ручного OCR, редактирования и сборки PDF в графическом интерфейсе	Не предназначен для обучения нейросетевых моделей

MMOCR выбирают, когда нужно менять архитектуры, обучать модели на своих данных, анализировать полигоны и строить программный конвейер. PaddleOCR удобен для более готового набора документных возможностей, EasyOCR — для быстрого прототипа, Tesseract — для стабильной пакетной обработки простого печатного текста, а docTR — для Python‑проекта с документной OCR‑схемой. PDF Commander уместнее, когда результат должен вручную проверить и отредактировать оператор без разработки кода.

Контрольный порядок внедрения

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

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

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

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

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