Hugging Face Transformers GGUF 支援

Hugging Face 已將 GGUF (GPT-Generated Unified Format) 模型的支援整合至 transformers 函式庫中，讓使用者能夠使用熟悉的 PyTorch 和 Transformers API 來載入並執行原本為 llama.cpp 設計的量化檢查點 (quantized checkpoints)。此整合透過利用底層的 ggml 核心，在 Apple Silicon 上實現了高效的本地推論，並保持了接近專用本地推論引擎的效能。

GGUF 格式與量化

GGUF 是由 llama.cpp 團隊開發的一種檔案格式，它將模型權重、分詞器 (tokenizer) 資訊以及選用的聊天模板封裝在單一檔案中。其主要優勢在於支援多種量化等級，讓使用者能透過犧牲部分精度來減少模型的記憶體佔用。

例如，使用 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 迴圈。

整合 ggml Metal 核心

transformers 現在不再以獨立的執行階段取代模型，而是使用 kernels 函式庫直接從 PyTorch 呼叫相容的 ggml Metal 核心。這使得模型能保留在 Python 中，同時由專門的 GPU 程式處理繁重的運算：

  • ggml-quantization：讀取封裝後的量化權重以進行矩陣運算，避免在每次解碼操作前展開權重矩陣。
  • ggml-norm：融合正規化運算，包括 Qwen3.5 和 Qwen3.8 中使用的零中心 RMSNorm。
  • ggml-attn：為提示詞處理與 Token 解碼實作 ggml 的 Metal Flash Attention。
  • ggml-gated-delta-net：加速 Qwen3.5 和 Qwen3.8 混合架構中的線性注意力層。
  • topk：一種自訂的 Metal 實作，用於優化專家混合 (MoE) 模型中的專家選擇。

生成迴圈優化

Hugging Face 減少了 generate 函式中的 CPU-GPU 同步開銷，以確保 GPU 保持滿載。引入了兩項關鍵變更：

  1. 注意力遮罩優化：對於沒有填充 (padding) 的僅解碼器 (decoder-only) 輸入，在生成開始時移除全 1 的填充遮罩，防止注意力程式碼重複檢查遮罩。
  2. 延遲停止檢查：停止決策以非同步方式複製，允許 CPU 在 GPU 執行當前步驟時繼續排程工作。

效能與基準測試

在 MacBook Pro M2 Max (32 GB 統一記憶體) 上進行的基準測試中，transformers 在小型密集模型、大型密集模型和 MoE 模型中均展現出接近 llama.cpp 的吞吐量。值得注意的是，transformers 的測量數據包含了預填充 (prefill) 階段，而 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 進行部署，該 CLI 提供與 OpenAI 相容的 API，以便與 Jan 或 Pi 等用戶端整合：

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 檢查點，進行以下任務：

  • 原型設計：使用 Hook 檢查中間激活值或修改前向傳遞。
  • 評估：使用現有的 transformers 工作流程來測量量化模型的品質。
  • 驗證：比較原始檢查點與 GGUF 轉換後的差異，以檢查量化誤差。
  • 微調：透過 GgufConfig(dequantize=True) 對權重進行去量化，以繼續標準的訓練工作流程。

當前限制

  • 硬體：封裝後的推論路徑目前僅限於 MPS (Apple Silicon)。
  • 批次處理：填充後的批次目前效能較低；針對 MPS 上 generate_batch 的優化正在進行中。
  • 架構：初步支援僅限於 Qwen3.5 密集與 MoE 架構 (包含 Qwen3.8)。

未來展望

Hugging Face 的目標是將 ggml 的效能帶入目前 llama.cpp 尚未支援的架構中。透過將 ggml 核心整合至 PyTorch，transformers 可以在無需為每個新架構實作完整 llama.cpp 的情況下，加速新的研究模型與自訂變體。

Sources