Всем привет! Меня зовут Артем, я Data Scientist в компании Raft Digital Solutions. В этой статье расскажу про свой опыт работы с HunyuanOCR end-to-end моделью от Tencent для распознавания текста на 1B параметров. Несмотря на громкие заявления о «SOTA-результатах» и компактности, в публичных обзорах практически не описано, как эта модель ведет себя в реальных задачах: с чем приходится столкнуться при настройке окружения, почему она может уйти в бесконечное зацикливание и как заставить её эффективно парсить сложные таблицы на обычном «железе».

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

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

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

Особенно это заметно при запуске через vLLM. Формально это один из самых удобных способов развертывания, но на практике именно здесь чаще всего проявляются проблемы совместимости. В моём случае только на то, чтобы добиться первой корректной генерации без ошибок, ушло около 1–2 часов.

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

Промпт и поведение модели

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

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

Вот эволюция моего подхода к промптам:

1. Первый тест (базовый):

請嚴格提取圖片中的所有文字，按原文順序輸出。
不要翻譯，不要總結，不要改寫，不要糾錯，不要補全。
盡量保留原始換行、段落、標點和閱讀順序。如果有表格，只按原樣輸出表格內容，不要生成多余空表格，不要擴展內容。
如果無法確定某部分內容，請留空或跳過，不要猜測。輸出只包含識別結果。

2. Вариант от разработчиков:

請提取圖片中正文的所有信息，並按閱讀順序輸出為 Markdown。
頁眉和頁腳請忽略。表格請輸出為 HTML。
不要翻譯，不要總結，不要改寫，不要糾錯，不要補全。
不要生成空表格，不要重復同一內容。輸出只包含識別結果。

3. Мой универсальный промпт (для текста и таблиц):

請完整提取圖片中的所有文字，嚴格按原文輸出。
不要翻譯，不要總結，不要改寫，不要糾錯。
盡量保持原始排版、段落、換行、標點和閱讀順序。

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

Скорость и поведение генерации

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

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

1. Либо модель зациклилась (генерирует повторяющиеся токены).

2. Либо на странице действительно очень большой объём текста.

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

temperature=0.0
repetition_penalty=1.0
no_repeat_ngram_size=3
max_new_tokens = 2048

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

Качество на документах и таблицах

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

Важно понимать, что HunyuanOCR это не инструмент для стерильной транскрипции.
Модель периодически допускает мелкие ошибки в словах или неточности в символах, однако для прикладных задач (таких как анализ документа, извлечение ключевых данных или создание чек-листа) это редко является критичным.
По моему опыту, около 70% документов обрабатываются стабильно и пригодны для использования без какой-либо ручной правки.

Совершенно иначе ситуация обстоит с таблицами:

• Распознавание текста: внутри ячеек модель справляется отлично.

• Структура: здесь случаются промахи. Иногда модель плывет в координатах, путая ячейки между собой (например, вместо исходного порядка данных  A−B,1−2 вы можете получить перемешанный результат в стиле  A−2,B−1

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

Например на таком документе

Иногда модель генерирует практически идеальную структуру таблицы

Пункт 4.1 бюллетеня
Выполнение запланированных работ на 2023 год по текущему ремонту общего имущества в домах ЖСК-1
| № п/п | Наименование работ | План тыс. руб | Факт тыс. руб |
|-------|-------------------|---------------|---------------|
| 1 | Выборочный косметический ремонт поэтажных льфтовых холлов с окраской тамбура выхода на переходную лоджию и заменой светильников на светодиодные до 25 этажей. Выборочний косметических ремонтов приквартирных холлов заменой сетевых до 10 этажев. | 800,00 | 781,00 |
| 2 | Выборчный косметический ремент черных лестниц до 10этажей Выполнен силами штатных рабочих | 100,00 |0 |
| 3 | Плановый поэтапный ремон тсистемы канализации в подвалах домов с заменой забитых участков трубопроводов. | 175,00 |255,00 |
4 | Плано-предупредительный рем онорудования поэтачных электроцитов, 121 цит с материалами (регламентные работы, один раз в 2 года). | 80,00 |52,00 |
5 | Настил керамической плитки в приквартилых холлах согласно плана на 2022 год в доме и 1-3 парадных дома 69 (1 этап) | 2 200,00 |1 978,00 |
6 | Монтаж жестяных козырьков и отливов на 2-х этажах переходных лоджий дома с 1-1 пар и дом с 1 по 3 пар. для предотвращения затопления переходных домов 2 этажи во время дождей. | 100.00 |110,00 |
7 | Текущий ремон кровли. | 85,00 |109,00 |
8 | Текуй ремонк крылев входной группы с укреплением отделочных плит и проведение противоскользящей окраски. | 50,00 |67,00 |

Или менее удачной и с привлекательной структурой

9 Строительство приемка (входа) в подвал дома со стороны пр. Просвещения для обеспечения доступа для замены теплотрассы в ходе её капитального ремонта. Перенесён на след. год.
10 Герметизация стыков по заявкам жителей.
11 Выборочная замена напольного покрытия в лифтах.
12 Продление договора аренды помещения Правления ЖКС на следующие 10 лет, проведение в нём косметического ремонтата с укладкой напольной плитки и заменой деревянной входной двери на металлическую
13 Гидроизоляция (бетонирование) участков пола подвального помещения для исключения избыточной влажности и с целью исключения конденсата на стальных конструкциях и электрооборудовании в подвале дома.
14 Продолжение работ по плановой замене забитых отложениями крестовин на стояках холодного водоснабжения.
15 Проведение экспертизы и освидетельствования состояния лифтов перед предстоящей заменой лифтового оборудования согласно плановом регионального Оператора капиталиного ремона.
| | | | | |
|---|---|---|---|--|
| | | 750,00 | 0 |
| | |250,00 |255,00 |
| |  | 50,00 |50,00 |
 | | | 360,00 |568,00 |
  | | |210,00 |186,00 |
   | | |85,00 |130,0 |
  |  | |200,00 |198,00 |
    | | |5 495,00 |4 739,00 |
Итоговая экономия достигнута по причине проведения конкурсных процедур при подборе подрядчиков, выполнения работ силами штатных сотрудников и переноса строительства входа в подваль на 2024г. Перерасход по отдельным статьям получился по причине выбора более качественных материалов и увеличения объемов проведённых работ. Остаток средств 756,0 т. руб. запланированных работ сохранян на расчетном счете ЖКС-Председатель ЖКС

Потери информации и особенности страниц

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

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

Рукописный текст и точность

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

Например такой текст

В первом задании (где только цифры) результат в целом похож на исходный
Но без ошибок не обходится: вместо 1905–1907 модель выдает 1905–1904

### 1.Напиши даты событий:

1) Начало и окончание первой русской революции - 1905 - 1904
2) Манифест 17 октября - 14.10.1905
3) Работа I Государственной думы - 1906
4) Ра-бота II Государ-ственной думы - 1907
5) Издание указа, положившего начало аграрной реформе Столыпина П.А. - 1908
6) Первая мировая война - 1914 - 1918

### 2.Расположи события в хронологическом порядке.

6 - 4 - 5 - 1 - 3 - 2

А вот во второй части, где текста намного больше, мы получили бред.
Большую часть модель либо проигнорировала, либо как-то переписала.

3. Дай определения терминам.
Отруб - урока здесь, где помогите
крестьяницы
Антанта
Временное правительство - все ограничения, которые
Совет Народных Комиссаров - опасные права, которые
4. Дай развернутые ответы на вопросы.
1) Дайте характеристику реформаторской деятельности П.А.Столыпина. Опишите цели,
содержание, результаты и последствия аграрной реформы.

Метрики оценки

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

Чтобы объективно оценить способности модели, я провел тест на трех классах данных: печатных документах (doc_case), рукописном русском тексте (handwritten_ru_case) и таблицах со сложной структурой (table_case) 

Основные метрики:

• Similarity (mean/median) — совпадение символов с эталоном

• Word (mean/median) — доля корректно распознанных слов

• Local mean — сохранение локального порядка слов в контексте

Mem

Что значат эти цифры:

• Таблицы (table_case) — главная ниша:
  Модель показывает лучшие результаты (Word accuracy ~85%). Показатель Local mean на уровне 0.65 подтверждает, что HunyuanOCR видит геометрию таблицы и удерживает контекст данных, что критически важно при парсинге сложных документов.

• Печатный текст (doc_case) — уверенная база:
  Word accuracy ~76% вполне достаточно для задач автоматизации, где не требуется 100% точность в каждом символе (например, для индексации или поиска). Мелкие ошибки в Similarity не препятствуют чтению документа человеком.

• Русская рукопись — не профиль:
  Результаты в 11–18% предсказуемы для 1B-модели, не обучавшейся специально под задачи распознавания курсива. Она может распознать отдельные цифры или печатные пометки поверх изображения, но не более того.

Краткий итог: Модель оптимальна для автоматизированного парсинга таблиц и печатных документов. Её точность в 75–85% на данных типа word accuracy делает её надежным фундаментом для построения чек-листов и систем классификации, где первичная обработка массива данных важнее, чем идеальное распознавание каждого рукописного символа.

Общий вывод

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

Почему HunyuanOCR стоит внедрять в свои проекты:

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

• Эффективность на слабом железе: Модель позволяет развернуть полноценный OCR-движок там, где раньше требовались тяжелые API или огромные вычислительные мощности.

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

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

На что важно настроиться при внедрении:

• Работа с промптами: Качество результата напрямую зависит от того, как вы просите модель работать. Удачно подобранный промпт (часто на китайском языке) это ключ к тому, чтобы модель перестала галлюцинировать и начала выдавать предсказуемый результат.

• Контроль параметров генерации: Модель требует узды в виде параметров temperature, repetition_penalty и жестких лимитов на длину генерации. Без этого она склонна уходить в бесконечные повторы, особенно если генерация выходит за пределы распознаваемого участка изображения.

В конечном итоге, HunyuanOCR хороший выбор для тех, кто хочет быстро запустить OCR на своем GPU без облачных API. Модель реально шустрая, понимает кучу языков и неплохо тянет сложные таблицы. Да, промпты и параметры надо подкрутить под себя— и дальше работает стабильно в пайплайне.