HunyuanOCR: установка, настройка и боевые промпты для парсинга документов (2026)

Почему HunyuanOCR, а не очередная китайская поделка?

Tencent — та самая компания, которая запилила WeChat, гипер-зоопарк моделей Hunyuan и внезапно — OCR-модель, которая уделала конкурентов на бенчмарках. HunyuanOCR (версия 1.2, май 2026) — это не очередная китайская поделка, а реальный инструмент, который понимает layout документа, вытаскивает таблицы без костылей и работает с 90+ языками.

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

Проблема: Три дня установки и ноль результата

Первая попытка запустить HunyuanOCR через официальный репозиторий — провал. Зависимости конфликтуют, transformers не той версии, vLLM ругается на CUDA. Вторая попытка — через Docker. Тоже грабли: контейнер падает с OOM на первом же PDF.

Проблема типична для свежих моделей: разработчики тестируют на своих продакшен-серверах, а не на железе обычных смертных. Мы пойдём другим путём — поставим модель через vLLM, который уже умеет загружать HunyuanOCR в формате safetensors.

Решение: Ставим через vLLM — пошагово

1 Подготовка окружения

Создаём свежее окружение Python 3.12 и ставим зависимости. Никаких коллизий — только то, что нужно.

python3.12 -m venv hunyuan_env
source hunyuan_env/bin/activate
pip install torch==2.6.0+cu124 --index-url https://download.pytorch.org/whl/cu124
pip install vllm==0.8.0
pip install pillow pdf2image pypdfium2 # для предобработки

2 Загрузка модели

vLLM умеет сам стягивать веса из Hugging Face. Модель весит 7.8 ГБ, так что приготовьте терпение.

huggingface-cli login  # вставьте токен
huggingface-cli download Tencent/HunyuanOCR-v1.2 --local-dir ./models/hunyuan-ocr

3 Запуск сервера vLLM

Запускаем с поддержкой бакетов (chunked prefill) — это экономит VRAM на длинных документах.

python -m vllm.entrypoints.openai.api_server \
    --model ./models/hunyuan-ocr \
    --task generate \
    --max-model-len 8192 \
    --gpu-memory-utilization 0.9 \
    --enable-chunked-prefill \
    --port 8000

Ждём, пока в логах появится "Uvicorn running on http://0.0.0.0:8000". Это означает, что сервер готов.

Промпты: Как заставить модель читать, а не галлюцинировать

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

Я выделил три основных сценария:

• Чистый текст — для простых сканов без таблиц.
• Таблицы с сохранением структуры — для отчётов и Excel-подобных данных.
• Layout-aware со ссылками — для документов с колонками, сносками, подписями.

Вот проверенные промпты. Верьте — они работают.

Промпт для чистого текста

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

Промпт для таблиц (критически важно!)

prompt = """Распарсите таблицу из документа. Каждая строка — новая строка вывода.
Столбцы разделяйте символом | (pipe).
Если ячейка пустая — ставьте прочерк (-).
Не добавляйте Markdown-форматирование, только raw text."""

Промпт для сложного layout

prompt = """Проанализируйте документ и верните текстовые блоки в порядке чтения.
Для каждого блока укажите:
- тип (заголовок, подзаголовок, абзац, подпись к рисунку, сноска)
- текст блока
- bounding box в формате (x1,y1,x2,y2)
Разделяйте блоки пустой строкой."""

Нюансы и ошибки, которые я встретил

Ещё одна дикая грабля: если на вход подать чёрно-белое изображение (mode 'L' в Pillow), модель может отказаться его обрабатывать. Всегда конвертируйте в RGB:

from PIL import Image
img = Image.open('scan.png').convert('RGB')

Боевой пример: Извлечение таблицы из скан-отчёта

Разберём реальный кейс — нужно распарсить HTML-подобную таблицу в формате строк и столбцов. Вот полный скрипт:

import requests
from PIL import Image
import base64

def image_to_base64(image_path):
    with open(image_path, "rb") as f:
        return base64.b64encode(f.read()).decode("utf-8")

image_b64 = image_to_base64("report_page_2.png")

payload = {
    "model": "Tencent/HunyuanOCR-v1.2",
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{image_b64}"}},
                {"type": "text", "text": "Распарсите таблицу. Столбцы разделяйте |. Строки разделяйте \\n. Пропуски — -."}
            ]
        }
    ],
    "max_tokens": 4096
}

resp = requests.post("http://localhost:8000/v1/chat/completions", json=payload)
table_text = resp.json()["choices"][0]["message"]["content"]
print(table_text)

Результат — сырой текст вида:

Название | Цена | Количество
Товар А | 1500 | 10
Товар Б | 2300 | 5
- | 800 | 2

Достаточно, чтобы запихнуть в Pandas одной строкой:

import pandas as pd
from io import StringIO
df = pd.read_csv(StringIO(table_text), sep='|', header=0)

Сравнение с альтернативами

HunyuanOCR не единственная layout-aware модель на рынке. Я тестировал её в паре с Qianfan-OCR 4B и MinerU-Diffusion. По таблицам Hunyuan выигрывает стабильностью структуры — Qianfan иногда рвёт колонки, а MinerU даёт только Markdown. По рукописному тексту, кстати, HunyuanOCR беспомощен — лучше использовать специализированные решения вроде моделей для индийских языков.

Частые вопросы по промптам (из моего опыта)

Почему модель игнорирует мой промпт?

Потому что промпт слишком общий. Сравните:

• ❌ "Прочитай таблицу" — модель может вернуть описание таблицы, а не данные.
• ✅ "Извлеки все строки таблицы, каждая строка в формате: колонка1 | колонка2 | колонка3" — чёткая инструкция даёт чёткий результат.

Как быть с многоязычными документами?

Укажите языки в промпте: "В документе смесь русского и английского. Сохраняйте оригинальные символы." HunyuanOCR поддерживает 90+ языков, но всегда лучше явно сказать.

Итог: стоит ли овчинка выделки?

HunyuanOCR — лучший open-source вариант для layout-чувствительного OCR на май 2026. Он обходит Tesseract и EasyOCR по качеству структурирования, и не требует гигантских ресурсов как GOT-OCR. Единственный минус — порог входа из-за зависимостей. Но раз вы дочитали до сюда — значит справитесь.

Мой прогноз: к концу 2026 Tencent выпустит модель с нативной поддержкой PDF и уменьшит размер до 4B параметров, а пока используйте связку vLLM + правильные промпты. И не забывайте про конвертацию в RGB — этот баг стоил мне трёх часов дебага.

Если хотите глубже разобраться в архитектуре OCR-пайплайнов — загляните в обзор современных пайплайнов. Там есть сравнение с Surya и DocTR.

Подписаться на канал