請求書の認識、表の抽出、古典書籍スキャン、契約書解析といった OCR タスクに取り組んでいるなら、従来の OCR パイプラインの「検出→認識→レイアウト→構造化」という4点セットに悩まされた経験がある確率は高いでしょう。Tencent Hunyuan が 2026-07-07 にオープンソースした HunyuanOCR-1.5（リポジトリでは HyOCR-1.5 とも呼ばれます）は、よりクリーンな道を示しました。上記すべての能力を 1B パラメータの視覚言語モデル（VLM） 1つに詰め込み、エンドツーエンドで一度に結果を出し、さらに speculative decoding によって長文ドキュメントのデコード速度を約6.37倍に引き上げます。

この記事では公式リポジトリを実際に動かす手順を、重みのダウンロードからバッチ推論で Markdown を出力するまで解説し、vLLM サービスと llama.cpp ローカルデプロイという最もよく使う2つの経路もカバーします。すべてのコマンドは公式 Tencent-Hunyuan/HunyuanOCR リポジトリ由来で、独自に作ったものはありません。

始める前の準備

• ハードウェア：vLLM 経路では 16 GB 以上の VRAMを持つ GPU が1枚必要（A10/4090/3090 いずれでも動作）。llama.cpp 経路は CPU またはコンシューマー GPU で動きます
• アカウント：Hugging Face アカウント（重みの取得用。重みは公開されています）
• コードと論文：
  • リポジトリ：https://github.com/Tencent-Hunyuan/HunyuanOCR
  • 技術レポート：https://arxiv.org/abs/2607.04884
  • オンラインデモ：https://hunyuanocr.org/
• 所要時間：環境構築後、単一画像の推論は秒単位で結果が出ます

💡 ヒント：公式は、vLLM（AR / DFlash）とネイティブ transformers の3つの推論環境が互いに非互換であることを明確に説明しています。transformers のバージョンが衝突するため、必ず別々に環境を構築してください。下記の経路 A/B/C からどれか1つを選べばよく、混用しないでください。

具体的な手順

ステップ1：モデル重みをダウンロード

重みは Hugging Face の tencent/HunyuanOCR にホストされており、ダウンロードには base モデルと DFlash の draft モデルの両方が含まれます。

pip install -U "huggingface_hub[cli]"
huggingface-cli download tencent/HunyuanOCR \
    --local-dir ./HunyuanOCR --exclude "v1.0/*"

--exclude "v1.0/*" は、旧世代の 1.0 の重みまで一緒に取得してしまうのを避け、ディスク容量を節約するためです。

ステップ2：推論経路を選ぶ

公式は inference/ 配下に互いに独立した3つの環境と、llama.cpp の PC 向け方案を用意しています：

以下では**経路 A（最もよく使われる vLLM 単一 GPU）**で一通り実行します。高速化だけが目的なら、経路 B の README に従って serve.sh を serve_dflash.sh に置き換えるだけで OK です。

ステップ3：vLLM サービスを起動

まず inference/vllm_0_18_1/requirements.txt に従って依存関係をインストールし、その後 OpenAI 互換のサーバーを起動します：

MODEL_PATH=./HunyuanOCR GPU=0 PORT=8000 \
    bash inference/vllm_0_18_1/serve.sh

# ヘルスチェック
curl -sf http://127.0.0.1:8000/v1/models

サービスはモデルを tencent/HunyuanOCR として公開し、--max-model-len はデフォルトで 131072（128K コンテキスト、訓練での最大構成に対応）まで引き上げられます。

ステップ4：単一画像のドキュメント解析

公式はタスクタイプを12個の --task-type に固定し（--list-tasks で全件確認）、うっかり自作の prompt でモデルを悪路に導かないようにしています。サンプリングパラメータ（temperature=0.0、top_p=1.0、repetition_penalty=1.08）と末尾繰り返しの早期停止は、すべてクライアント側に組み込み済みです。

python inference/vllm_0_18_1/infer_vllm_client.py \
    --image /path/to/document.png \
    --task-type doc_parse \
    --model tencent/HunyuanOCR \
    --port 8000 --max-tokens 32768

よく使う task-type は次のとおりです。doc_parse（ページ全体を構造化テキストへ解析）、text_spotting（純粋なテキストの検出と認識）、information_extraction（指示に従ってフィールドを抽出）、text_image_translation（画像テキスト翻訳）。1枚の画像から Markdown か JSON のどちらかが出力されます。

ステップ5：バッチ推論

大量のスキャンファイルに対しては、公式の batch_infer.py を使います。複数エンドポイントへの並列処理と中断再開が組み込まれています：

python inference/vllm_0_18_1/batch_infer.py \
    --image-dir /path/to/images \
    --out-dir /path/to/output \
    --ports 8000 \
    --task-type doc_parse \
    --max-tokens 32768 \
    --concurrency 16

GPU が複数ある場合は serve.sh インスタンスを複数起動し、ポートリストを --ports に渡せば、スループットは線形に伸びます。

ノート PC で動かす：llama.cpp 経路

GPU がなくても使えます。HunyuanOCR-1.5 は GGUF 変換済み checkpoint と OpenAI 互換の llama-server を提供しており、コミュニティ版 llama.cpp が base モデルをサポートします。DFlash 高速化には適応済み fork（wendadawen/llama.cpp @ dflash-adapt-hunyuanocr-hunyuanstyle）が必要です。

最小構成の流れ（コミュニティ版、DFlash なし）：

# 1. llama.cpp をビルド
git clone https://github.com/ggml-org/llama.cpp.git && cd llama.cpp
cmake -B build -DLLAMA_BUILD_EXAMPLES=ON   # NVIDIA GPU の場合は -DGGML_CUDA=ON を追加
cmake --build ./build --config Release -j

# 2. GGUF へ変換（base + mmproj）
python3 convert_hf_to_gguf.py --outfile ./HunyuanOCR/hyocr-f16.gguf        --outtype f16 ./HunyuanOCR
python3 convert_hf_to_gguf.py --outfile ./HunyuanOCR/mmproj-hyocr-f16.gguf --outtype f16 --mmproj ./HunyuanOCR

# 3. OpenAI 互換サービスを起動
build/bin/llama-server \
    --model  ./HunyuanOCR/hyocr-f16.gguf \
    --mmproj ./HunyuanOCR/mmproj-hyocr-f16.gguf \
    --host 0.0.0.0 --port 8080 --alias HYVL \
    --ctx-size 10240 --n-predict 4096

完全な DFlash 適応版、draft 重みの変換、そして26枚のサンプル画像でのスモークテストスクリプトは、すべて公式 docs/llama_cpp.md にあります。

1.5 へ切り替える価値がある理由

「速くて良い」を説明する2つの核心的な変更があります：

• DFlash speculative decoding：長い自己回帰デコードはエンドツーエンド OCR の最大のボトルネックです（高密度ドキュメント、表、数式は簡単に数千 token に及びます）。HunyuanOCR-1.5 は軽量な block-diffusion draft モデルで複数の候補 token を並行して起草し、目標モデルが一度に検証します。長い構造化出力のデコード遅延が大幅に低下し、同時に目標モデルの出力分布を変えません（ロスレス高速化）。OCR タスクでの公式の測速声明は docs/benchmark.md を参照してください。
• Agentic Data Flow + 訓練レシピの強化：データ側では agent 駆動のデータ構築システムを導入し、モデルの弱点を実行可能なデータ要件へ変換して、低リソース OCR、古典書籍 OCR、複数画像テキスト QA などのロングテール能力を重点的に補強しました。訓練側では Stage-3 を再設計し、画像解像度を 4K まで引き上げ、コンテキストウィンドウを 128K に拡大、後訓練段階では異なる OCR タスクで RL を実施しました。

検証結果

ステップ4を実行し終えると、標準出力に構造化された Markdown / JSON が得られるはずです。表は行と列を保持し、数式は LaTeX で出力され、段組レイアウトは読み順に復元されます。さらに精度を比較したい場合は、公式が同時期に公開した2つのオープンソース benchmark、Chronicles-OCR（中国語「七体」古文字認識、arXiv:2605.11960）と ChartArena（多言語チャート解析、arXiv:2606.01348）を使えます。

よくある質問

• 3つの推論環境で1つの conda env を共有できる？ できません。vLLM とネイティブ transformers が要求する transformers バージョンは互換性がなく、公式は inference/README.md で「検証済みの制限であり、好みの問題ではない」と強調しています。各経路ごとに個別の env を作ることを推奨します。
• vLLM の推論結果が transformers と完全に一致しない？ 公式は README で、vLLM フレームワークに 1.0 時代から transformers との精度差異が存在すること、チームが修正中であることを確認しています。精度整合の確認は inference/transformers を基準にしてください。
• 商用利用は無料？ リポジトリの LICENSE は Tencent Hunyuan Community License Agreement で、個人・研究用途にはフレンドリーですが、商用ではまず LICENSE 全文を読むことを推奨します。
• ファインチューニングできる？ できます。scripts/sft_base.sh は全パラメータ SFT、scripts/sft_dflash.sh は DFlash draft を最初から訓練、scripts/sft_dflash_finetune.sh は既存 draft への追加ファインチューニングです。具体的なハイパーパラメータは docs/training.md を参照してください。