Hugging Face Transformers GGUF サポート

Hugging Faceは、GGUF (GPT-Generated Unified Format) モデルのサポートを transformers ライブラリに統合しました。これにより、ユーザーは本来 llama.cpp 用に設計された量子化済みチェックポイントを、使い慣れた PyTorch および Transformers API を使用して読み込み、実行できるようになりました。この統合により、基盤となる ggml カーネルを活用することで、専用のローカル推論エンジンに近いパフォーマンスを維持しつつ、Apple Silicon 上での効率的なローカル推論が可能になります。

GGUF 形式と量子化

GGUF は llama.cpp チームによって開発されたファイル形式で、モデルの重み、トークナイザー情報、およびオプションのチャットテンプレートを単一のファイルにパッケージ化します。その主な利点は、さまざまな量子化レベルをサポートしていることであり、ユーザーは精度を多少犠牲にすることでモデルのメモリフットプリントを削減できます。

例えば、Unsloth の Qwen3.5-4B モデルを使用した場合、量子化バリアントによってメモリ要件は以下のように異なります。

GGUF バリアント ファイルサイズ トレードオフ
BF16 8.42 GB 非量子化リファレンス
Q6_K 3.53 GB 高精度
Q5_K_M 3.14 GB サイズと精度のバランス
Q4_K_M 2.74 GB ローカル推論の実用的な開始点

技術的実装: ggml カーネルと生成ループ

llama.cpp に匹敵するパフォーマンスレベルを達成するために、Hugging Face は ggml カーネルの再利用と generate ループの効率化という2つの主要な技術的最適化を実装しました。

ggml Metal カーネルの統合

transformers はモデルを別のランタイムに置き換えるのではなく、kernels ライブラリを使用して、PyTorch から直接互換性のある ggml Metal カーネルを呼び出すようになりました。これにより、重い計算は専用の GPU プログラムによって処理されつつ、モデルは Python 上に留まることができます。

  • ggml-quantization: 行列演算のためにパックされた量子化済み重みを読み込み、デコード操作のたびに重み行列を展開する必要を回避します。
  • ggml-norm: Qwen3.5 や Qwen3.8 で使用されるゼロ中心 RMSNorm を含む正規化操作を統合します。
  • ggml-attn: プロンプト処理とトークンデコードの両方に対して、ggml の Metal フラッシュアテンションを実装します。
  • ggml-gated-delta-net: Qwen3.5 および Qwen3.8 ハイブリッドアーキテクチャにおける線形アテンション層を高速化します。
  • topk: Mixture-of-Experts (MoE) モデルにおけるエキスパート選択を最適化するためのカスタム Metal 実装です。

生成ループの最適化

Hugging Face は、GPU が常に飽和状態を維持できるように、generate 関数における CPU-GPU 同期オーバーヘッドを削減しました。2つの重要な変更が導入されています。

  1. アテンションマスクの最適化: パディングのないデコーダー専用入力の場合、生成開始時にすべてが1のパディングマスクが削除され、アテンションコードが繰り返しマスクを検査することを防ぎます。
  2. 停止チェックの遅延: 停止判定が非同期にコピーされるため、GPU が現在のステップを実行している間に CPU が次の作業をスケジュールし続けることができます。

パフォーマンスとベンチマーク

MacBook Pro M2 Max (32 GB ユニファイドメモリ) で実施されたベンチマークにおいて、transformers は小規模な密モデル、大規模な密モデル、および MoE モデル全体で llama.cpp に近いスループットを示しました。注目すべき点として、transformers の測定値にはプリフィルが含まれていますが、llama.cpp の llama-bench 結果はデコードのみのスループットに焦点を当てています。

使用方法とデプロイ

GGUF モデルの読み込み

ユーザーは from_pretrained 内の gguf_file パラメータを使用して、Hugging Face Hub から GGUF モデルを読み込むことができます。

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "unsloth/Qwen3.5-4B-GGUF"
filename = "Qwen3.5-4B-Q4_K_M.gguf"

tokenizer = AutoTokenizer.from_pretrained(model_id, gguf_file=filename)
model = AutoModelForCausalLM.from_pretrained(model_id, gguf_file=filename)

OpenAI 互換 API を介したサービング

モデルは transformers serve CLI を使用してサービングできます。これにより、Jan や Pi などのクライアントと統合するための OpenAI 互換 API が公開されます。

pip install -U "transformers[serving] @ git+https://github.com/huggingface/transformers.git" kernels

transformers serve "unsloth/Qwen3.5-4B-GGUF:Qwen3.5-4B-Q4_K_M.gguf"

戦略的意義と制限事項

純粋なローカル推論の効率性については依然として llama.cpp が推奨されるエンジンですが、この統合により、開発者は以下のようなタスクのために PyTorch エコシステム内で GGUF チェックポイントを使用できるようになります。

  • プロトタイピング: フックを使用して中間アクティベーションを検査したり、フォワードパスを変更したりする。
  • 評価: 既存の transformers ワークフローを使用して、量子化済みモデルの品質を測定する。
  • 検証: 元のチェックポイントと GGUF 変換後のものを比較し、量子化誤差を確認する。
  • ファインチューニング: GgufConfig(dequantize=True) を介して重みを非量子化し、標準的なトレーニングワークフローを継続する。

現在の制限事項

  • ハードウェア: パックされた推論パスは現在 MPS (Apple Silicon) に限定されています。
  • バッチ処理: パディングされたバッチは現在パフォーマンスが低く、MPS 上での generate_batch の最適化が進行中です。
  • アーキテクチャ: 初期サポートは Qwen3.5 の密モデルおよび MoE アーキテクチャ (Qwen3.8 を含む) に限定されています。

今後の展望

Hugging Face は、現在 llama.cpp でサポートされていないアーキテクチャにも ggml のパフォーマンスをもたらすことを目指しています。ggml カーネルを PyTorch に統合することで、transformers は新しいアーキテクチャごとに完全な llama.cpp 実装を必要とすることなく、新しい研究モデルやカスタムバリアントを高速化できるようになります。

Sources