Tencent-Hunyuan/HunyuanOCR

HunyuanOCR‑1.5 – 軽量なOCR専用視覚言語モデル

何であるか

• 画像内のテキストを読み取り、ドキュメント解析、情報抽出、テーブル解析、テキスト画像翻訳も可能なエンドツーエンドの視覚言語モデル（VLM）。以前のHunyuanOCR‑1.0を基盤としており、DFlash 指示推論による高速化と、llama.cpp を通じたPC側での容易なデプロイメントという2つの主要なアップグレードを追加。

主なアイデアと機能

機能	重要性
DFlash 指示推論	軽量な「ドラフト」モデルが並列で複数の候補トークンを予測し、メインモデルが1回のパスで検証。密度の高いドキュメント、テーブル、数式の長時間自己回帰推論のボトルネックを削減しつつ、同じ出力分布を維持。
統合推論環境	CUDA 13を搭載したuvベースの環境により、3つの構成（通常のvLLM自己回帰、DFlash加速、ネイティブHuggingFace Transformers）を同じ重みとプロンプトで実行可能。ベンチマークが容易に実施可能。
llama.cppを介したPC側デプロイ	モデル（およびDFlashドラフト）をGGUFに変換し、CPU、コンシューマーグラフィックスカード、ノートPCのハードウェアでOpenAI互換のllama-serverで提供可能。
エージェントデータフロー	モデルの弱点をターゲットデータ構築タスク（例：低リソーススクリプト、古代中国語文字、マルチ画像QA）に変換する内部パイプライン。このデータはトレーニングプロセスにフィードバックされる。
大規模なコンテキストと解像度	最大4K画像解像度と128Kトークンのコンテキスト窓をサポート。長文ドキュメントや複数ページの推論が可能。
広範なベンチマーク	CHAOS‑Bench、Chronicles‑OCR、ChartArena、Wild‑OmniDocBench、MMTIT‑Benchなど、コミュニティレベルのベンチマークをリポジトリに同梱。幻覚、古代スクリプトOCR、チャート解析などを評価可能。

一般的な利用例

• スキャンされたドキュメント、学術論文、契約書、歴史文書のデジタル化。
• 画像から構造化情報（テーブル、フォーム）を直接抽出。
• 複数言語間のOCR駆動型質問応答や翻訳。
• llama.cpp経由で低スペックハードウェア（ノートPC/CPU）でも実行可能。

導入手順（概要）

1. 統合推論環境のセットアップ（Python 3.12とCUDA 13が必要）:

   pip install uv
   uv venv --python 3.12 && source .venv/bin/activate
   uv pip install "vllm>=0.25.1" "flash-attn==2.8.3"
   

2. HuggingFaceからモデルをダウンロード:

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

3. クイックサーバーの起動（vLLM自己回帰、単一GPU）:

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

4. 画像の送信（ドキュメント解析例）:

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

   doc_parseを--list-tasksで確認可能な12種類のタスクタイプのいずれかに置き換える。
5. オプション：DFlash加速 – inference/DFlash/serve_DFlash.shスクリプトを使用。同じクライアントがそのまま利用可能。
6. PC側デプロイ – 提供されたconvert_hf_to_gguf.pyスクリプトでチェックポイントをGGUFに変換し、docs/llama_cpp.mdに記載された通りllama.cppで提供。

トレーニング（微調整や拡張を希望する場合）

• scripts/pack_data.shパイプラインで、OCR用JSONLファイルを長序列（最大20,480トークン）にパック。
• ベースモデルでの教師付き微調整を実行（scripts/sft_base.sh）。
• 新たなDFlashドラフトをゼロからトレーニング（scripts/sft_dflash.sh）または既存ドラフトの継続微調整（scripts/sft_dflash_finetune.sh）。
• すべてのスクリプトは標準的なNNODES、MASTER_ADDRなどを通じたマルチノード分散トレーニングをサポート。PyTorch 2.1+、DeepSpeed、Flash‑Attentionに依存。

ドキュメントと追加リーディング

• docs/training.md – 詳細なハイパーパラメータと分散設定。
• docs/inference/inference.md – 完全な推論レシピ、タスクタイプ表、マルチGPUガイド。
• docs/llama_cpp.md – コンシューマーハードウェアでの変換と提供のステップバイステップ説明。
• ベンチマークの説明はbenchmarks/CHAOS-BenchおよびリンクされたarXiv論文に記載。

引用 HunyuanOCR‑1.5を研究で使用する場合、READMEに記載されたarXiv論文（2026）を引用してください。

---

上記のすべての情報はリポジトリのREADMEから直接取得。外部の仮定は一切追加されていません。