tokimoa/hpd-parsing-mlx-4bit

HPD-Parsing (MLX 4bit)

PaddlePaddleの HPD-Parsing（InternVL3.5-1BベースのHierarchical Parallel Decoding文書パース・1.1B）のMLX変換（4bit量子化・実効7.8bpw）の最軽量版です。

HPDプロトコル（階層並列デコード）のMLX実装を同梱しています（hpd_generate.py）。レイアウト親ブランチが<BLOCK>種別 [座標]<FORK>のスケルトンを生成し、各<FORK>から共有KVキャッシュを継承した子ブランチが中身を埋め、接ぎ合わせて完全なパース結果（レイアウト座標＋テキスト＋HTMLテーブル）を返します。A4文書1ページ約5秒・ピークメモリ3.4GB。

必要バージョン: mlx-vlm 0.6.8以降（または main）。0.6.7以前のinternvl_chatはQwen3系LMに未対応です。上流のP-MTP（投機デコード）ヘッドは本変換には含みません（HPD自体はMTPなしで動作します）。

使い方

pip install "git+https://github.com/Blaizzy/mlx-vlm.git" timm einops torch
# repoをダウンロードして同梱スクリプトを実行
hf download tokimoa/hpd-parsing-mlx-4bit --local-dir hpd-4bit
python hpd-4bit/hpd_generate.py document.png

出力例（請求書）:

<BLOCK>title [63, 45, 187, 77]<CHILD>請求書
<BLOCK>table [64, 185, 937, 350]<CHILD><table><tr><td>品目</td><td>数量</td>...</table>
<BLOCK>text [533, 440, 727, 464]<CHILD>合計: 880,000円

タスクプロンプトは訓練時の正規形document parsing with fork.固定です（自由QAには非対応の特化モデルです）。

変換品質の検証（tokimoa）

• transformers公式実装のgenerate_hpd（greedy・同一入力）との比較で、請求書1ページのパース結果が741文字中740文字一致（唯一の差は両実装とも誤読している小文字セルのbf16ゆらぎ）
• 日本語ビジネス文書5種・正解既知59項目の含有率: 45/59（bf16=47/59より小文字セルでわずかに劣化）。品質重視なら8bit版を推奨（ミスの方向は参照実装と同一＝変換起因でなく1.1Bの小文字読み取り能力の範囲。表構造・数値・座標は高精度）
• レイアウト座標・表構造・主要数値は維持

実測速度（M4 Max 36GB）

• レイアウト＋子ブランチ合計で約5秒/ページ（13タイル・プロンプト約3,400トークン・生成約500トークン）
• ピークメモリ: 3.4GB（重み1.0GB）

変換情報

• 変換元: PaddlePaddle/HPD-Parsing（公式BF16。P-MTPヘッドは除外）
• 変換: mlx-vlm main（internvl_chat Qwen3対応） convert -q --q-bits 4
• HPDプロトコル実装・前処理は同梱（hpd_generate.py・conversation.py・image_preprocess.py）
• 兄弟repo: bf16（参照一致検証の基準）/ 8bit（推奨）
• 変換者: tokimoa

ライセンス

Apache-2.0（元モデルに準拠）