Hugging Face Transformers 新增 GGUF 量化模型本機推理支援
Transformers now runs llama.cpp quants
Hugging Face 為 Transformers 加入 GGUF 支援,讓用户可透過熟悉的 Transformers API 在本機載入量化檢查點並生成內容。
文章示範透過 Transformers API 從 Hub 載入 GGUF 量化檢查點,並以 Q4_K_M 等選項説明檔案大小與精度的取捨。
我們正在為 transformers 加入高效率執行 GGUF 模型的支援,讓你可以透過熟悉的 transformers API,使用適合筆記型電腦記憶體容量的檢查點。從 Hub 選擇 GGUF,以 from_pretrained 載入,便可在自己的電腦開始生成。
在筆記型電腦上執行 AI 模型已容易得多,llama.cpp 對此功不可沒。它的推理引擎為 Ollama、LM Studio 和 Jan 等本機 AI 工具提供動力。它與 MLX 等專案共同推動本機推理,令其成為日常實用選項。
近期一個本機 AI 體驗示例:
我們現在已經走到這一步。老實説,感覺相當神奇 🧙♀️
在 MacBook Pro 上透過 Llama.cpp,於 Pi 程式編寫智能體中執行 Qwen3.6 27B
對 @huggingface 程式碼庫中的非簡單任務而言,這感覺非常、非常接近 Claude 中最新 Opus 的表現…… pic.twitter.com/lsIxLoUneU
— Julien Chaumond (@julien_c) April 24, 2026
由 llama.cpp 團隊開發的 GGUF,是廣泛使用的本機推理格式。該團隊亦在 Hub 的 ggml-org 分享量化檢查點。Unsloth、LM Studio Community 和 bartowski 等發布者亦提供各種量化程度、可即時使用的 GGUF 檢查點,方便用戶選擇適合自己電腦的版本。GGUF 模型的下載量已達數百萬次。
我們也希望令使用 transformers 在本機執行這些模型更容易。只有模型容易使用,相容性才有意義。為了讓效能接近 llama.cpp,我們透過 kernels 函式庫重用其底層 ggml 核心,並降低 generate 的額外開銷。我們初期聚焦於在 Apple Silicon 上進行本機推理,先支援 Qwen3.5 架構。
甚麼是 GGUF 檔案格式?
GGUF 會把模型權重和中繼資料(包括 tokenizer 資訊及可選的聊天範本)封裝在單一檔案中。它支援不同量化等級,讓你在部分精度和較小記憶體佔用之間取捨。Q4_K_M 等變體會混合張量精度,大部分權重採用 4-bit,同時讓較敏感的張量保留更高精度。
以下看看量化如何改變 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 | 適合開始本機推理的實用選擇 |
建議先從 Q4_K_M 開始;如果記憶體較充裕,可再試 Q5_K_M 或 Q6_K。更激進的量化方式有助較大型模型放入記憶體,但品質取捨視乎模型和任務而定。請以模型實際需要執行的工作進行評估。Hub 的 GGUF 文件介紹了可用的量化類型。
使用 transformers 載入 GGUF
開始前,你需要:
- 一部 Apple Silicon Mac。
- 支援已發布 ggml-quantization 核心版本的 PyTorch 版本,通常是最新的兩個 PyTorch 版本。
- 最新版本的 transformers(目前使用 main 分支,直到下一個版本發布)及相容版本的
kernels。
pip install -U "git+https://github.com/huggingface/transformers.git" kernels
要載入 GGUF 模型,請把 Hub 的 model_id 和檔案名稱作為 gguf_file 傳入 from_pretrained。
無需額外設定:只要權重以封裝格式留在 Metal 上,transformers 就會自動載入相容的 ggml/Metal 層核心,並使用 ggml-org/ggml-attn 作為注意力實作。如果無法取得該核心,模型便會在發出警告後改用 "sdpa";你亦可以明確強制使用 "sdpa",方法是傳入 attn_implementation="sdpa"。如需瞭解其他載入選項,請參閲 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
)
這是唯一與 GGUF 有關的步驟。之後全部使用標準 transformers API:
messages = [{"role": "user", "content": "Explain why the sky is blue in a few sentences."}]
inputs = tokenizer.apply_chat_template(
messages,
tokenize=True,
add_generation_prompt=True,
return_dict=True,
return_tensors="pt",
).to(model.device)
with torch.inference_mode():
outputs = model.generate(**inputs, max_new_tokens=256)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))
如果沒有相容的量化核心,載入器便會改為解量化模型,並使用更多記憶體。
使用你偏好的介面提供 GGUF 服務
你亦可使用同一檢查點搭配 transformers serve,以提供相容於 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"
model 參數採用 <model_id>:<filename>.gguf 格式:冒號前是 Hub 儲存庫(unsloth/Qwen3.5-4B-GGUF),後面則是要載入的檔案(Qwen3.5-4B-Q4_K_M.gguf)。這樣便可從可能包含多個檔案的儲存庫中選取特定量化版本。
若模型的聊天範本支援思考模式,可加入 --reasoning off 停用,或加入 --reasoning on 啟用。預設的 --reasoning auto 會沿用聊天範本的預設值。詳情請參閲推理選項。
你可以加入自訂 OpenAI 相容供應者,並使用以下設定連接 Jan 或 Pi 等用戶端:
| 設定 | 值 |
|---|---|
| Base URL | http://localhost:8000/v1 |
| 模型 ID | unsloth/Qwen3.5-4B-GGUF:Qwen3.5-4B-Q4_K_M.gguf |
transformers 會在你的 Mac 上執行模型,而用戶端則提供對話介面。其他支援這種 API 的用戶端亦可使用同一端點。
與 llama.cpp 比較基準測試
我們以 llama.cpp 作為本機推理效能的參考。以下比較聚焦於三個 GGUF 檢查點:小型稠密模型、較大型稠密模型,以及混合專家模型。
llama.cpp 欄位的數據取自 llama-bench 工具(建置版本 5f55650a7、發布版本 b10200、ggml 0.18.0 的 Metal 後端),執行命令為 llama-bench -m <file> -p 0 -n 128 -r 3。工具回報 tg128:解碼 128 個 token 的生成速度,取三次重複測試的平均值,不包括提示處理時間。transformers 欄位則以 generate 根據 12-token 提示生成相同的 128 個 token,採用暖機後三次執行中的最佳結果,並包括預填充時間。
測試裝置為 MacBook Pro M2 Max,配備 32 GB 統一記憶體,系統為 macOS 26.6、PyTorch 2.12.1、kernels 0.17.0,並接上電源。
基準測試程式碼
import time
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
model_id, filename = "unsloth/Qwen3.5-4B-GGUF", "Qwen3.5-4B-Q4_K_M.gguf"
model = AutoModelForCausalLM.from_pretrained(model_id, gguf_file=filename)
tokenizer = AutoTokenizer.from_pretrained(model_id, gguf_file=filename)
inputs = tokenizer("The capital of France is Paris. The capital of Germany is", return_tensors="pt")
inputs = inputs.to(model.device)
with torch.inference_mode():
model.generate(**inputs, max_new_tokens=8, min_new_tokens=8, do_sample=False) # warm up
torch.mps.synchronize()
for _ in range(3):
time.sleep(90) # let the machine cool: back-to-back runs decay by 10% or more
start = time.perf_counter()
model.generate(**inputs, max_new_tokens=128, min_new_tokens=128, do_sample=False)
torch.mps.synchronize()
print(f"{128 / (time.perf_counter() - start):.1f} tok/s")
另一個欄位的測試方式:
llama-bench -hf unsloth/Qwen3.5-4B-GGUF:Q4_K_M -p 0 -n 128 -r 3
三個檢查點的測試均啟用了所有層核心。下圖使用上文所述的相同測量數據,但不代表基準測試條件完全相同,因為 Transformers 的測量包括預填充,而 llama-bench 只回報解碼吞吐量。
transformers 與 llama.cpp
GGML 和 llama.cpp 加入 Hugging Face時,我們曾説明兩者各自互補的角色:llama.cpp 為本機推理提供基礎,transformers 則為模型定義提供基礎。支援 GGUF 令兩者更緊密結合。
如果首要目標是高效率本機推理,我們仍建議使用 llama.cpp 作為引擎。它的專用執行環境、記憶體管理和廣泛硬件支援,都是為此目標而建。這項整合則讓開發者能在 transformers 中方便地使用相同 GGUF 檢查點:
- 在 Python 和 PyTorch 中試驗 GGUF。使用 hooks 檢視中間啟動、修改模型的 forward pass,或以熟悉的 PyTorch 工具製作自訂層原型。
- 評估 GGUF 模型。沿用現有的 transformers 評估工作流程,測量量化檢查點的品質。
- 驗證 GGUF 轉換。對我們開發者而言,在 transformers 中載入原始檢查點和轉換後的 GGUF,更容易檢查權重是否正確轉換,並考慮量化誤差。
- 嘗試新的解碼方法。使用自訂 logits 處理器和停止條件搭配
generate,或以 Python 編寫自己的生成迴圈。 - 從 GGUF 檢查點微調。解量化權重,然後沿用標準 transformers 訓練工作流程。
就最後一種情況而言,請使用 GgufConfig(dequantize=True):
import torch
from transformers import AutoModelForCausalLM, GgufConfig
model = AutoModelForCausalLM.from_pretrained(
"unsloth/Qwen3.5-4B-GGUF",
gguf_file="Qwen3.5-4B-Q4_K_M.gguf",
quantization_config=GgufConfig(dequantize=True),
dtype=torch.bfloat16,
)
超越 GGUF:讓更多模型使用 ggml 核心
更大的機遇,是把 ggml 的效能帶到 llama.cpp 尚未支援的模型。
transformers 已提供這些架構的 PyTorch 實作。PyTorch 有了 ggml 核心和量化方案後,我們可以逐步加速相關支援操作,而毋須先在 llama.cpp 完整實作整個模型。這對新架構、研究模型和自訂變體特別有用,因為它們可能永遠不會有專屬的 llama.cpp 實作。
這個機遇不只限於 GGUF 格式本身。核心只對張量執行操作,不要求整個模型都來自 GGUF 檔案。同一批基礎元件亦可整合到其他 transformers 模型和載入工作流程。這也為其他模態開拓道路:電腦視覺模型、音訊模型和多模態模型都可能重用相容的注意力、正規化和矩陣乘法核心,毋須先在 llama.cpp 完成全面實作。每種架構仍須整合和驗證;本文初期的 GGUF 示例聚焦文字生成。
使用 Python 和 PyTorch 進行快速本機推理
我們亦想展示,在模型和生成迴圈都保留於 Python 的前提下,效能可以提升到甚麼程度。配合合適核心和高效率生成迴圈,Python 與 PyTorch 也能提供出色的本機推理效能。核心負責繁重運算,而生成迴圈則避免不必要的同步操作,讓 GPU 持續忙碌。
我們的目標是在無需 torch.compile 的情況下加快 eager execution。對互動式使用而言,我們希望可以快速開始並穩定串流 token,不必等待編譯,也不會因輸入形狀改變而重新編譯。這項工作的兩個主要部分是核心和 generate 本身。
重用 ggml 的 Metal 核心
核心是在 GPU 執行操作的小型程式。PyTorch 提供通用實作;專用核心則可以減少工作量、合併多項操作,或直接讀取以原有格式儲存的量化權重。
kernels 函式庫讓我們可在 Hub 發布相容的 ggml Metal 核心建置版本,並從 transformers 呼叫。這樣便能把 ggml 的成果帶入 PyTorch 模型,而不必用另一個推理執行環境取代模型。
| 核心 | 用途 |
|---|---|
ggml-quantization |
讀取矩陣運算所用的封裝量化權重,包括 MoE 模型中選取的專家權重。它無需在每次解碼操作前展開整個權重矩陣。 |
ggml-norm |
融合多種正規化操作,包括 Qwen3.5 和 Qwen3.8 使用的零中心 RMSNorm。 |
ggml-attn |
提供 ggml 的 Metal flash attention,用於提示處理和 token 解碼。 |
ggml-gated-delta-net |
加速 Qwen3.5 和 Qwen3.8 混合架構線性注意力層所用的 gated delta network。 |
topk |
為 MoE 模型中的每個 token 選取專家,結合 softmax 和 top-k 路由。這是我們自行實作的 Metal 核心。 |
首四個套件以 ggml 核心為基礎;top-k 核心則處理 MoE 路由中的另一個瓶頸。這些核心共同減少每次生成 token 所需的 GPU 工作量。
為展示層核心的作用,我們比較啟用和停用層核心時使用的相同封裝 GGUF 檢查點。兩種設定都會啟用量化核心;停用它亦會改變權重表示方式,測量的便是另一種取捨。
讓 CPU 和 GPU 協同運作
只有 GPU 有工作可做,更快的核心才有用。生成期間,CPU 會安排 GPU 操作,並控制產生下一個 token 的迴圈。從 GPU 讀取結果可能迫使 CPU 等待佇列中的操作完成。即使每個 token 只需等待一小段時間,反覆等待也會明顯降低吞吐量。
以下兩項改動改善了 generate,讓所有 transformers 模型都受惠(不只是在執行 GGUF 檔案時):
- 提早移除不必要的注意力遮罩(#48814)。如果受支援的僅解碼器輸入沒有填充內容,便可在生成開始時移除全為一的填充遮罩。下游注意力程式碼無需再反覆檢查遮罩,以判斷是否可以略過。因果注意力仍會保留。
- 延後停止檢查(#47975)。在受支援的路徑中,
generate會非同步複製停止判斷,並在下一步才讀取。CPU 可在 GPU 運作期間繼續安排工作。串流 token 亦採用相同方法,而停止條件之後多出的步驟會從結果移除。
這些改動改善了模型外圍的生成迴圈,因此不只適用於 GGUF。它們與核心工作相輔相成:核心降低單項操作的成本,而減少同步點則讓 CPU 排程和 GPU 執行可以重疊。
所有層核心均保持啟用;圖表中的長條只顯示生成迴圈改動帶來的差異。
目前限制和下一步
初期目標是在 Apple Silicon 上進行單一互動式對話。有幾項限制需要留意:
- 目前只有 MPS 支援封裝推理路徑。透過解量化匯入 GGUF 仍是另一個選項;支援檔案格式並不代表所有裝置都能使用封裝核心。
- 填充和批次處理仍有待改善。沒有填充的輸入可受惠於上述遮罩最佳化;有填充的批次無法採用相同捷徑,效能可能較低。我們希望把這項工作擴展至 MPS 上的
generate_batch。 - 支援的架構仍有限。目前封裝載入器涵蓋 Qwen3.5 稠密和 MoE 架構,包括相容的 Qwen3.8 檢查點。加入其他架構的支援相對直接,我們會逐步擴大涵蓋範圍。
如果你想在 transformers 使用某個 GGUF 模型,請提出 issue,並附上檢查點和使用情境,協助我們按本機用戶實際執行的模型排定支援優先次序。
鳴謝
我們感謝 Arthur Zucker 發起這項工作並審閲我所有的 PR,亦感謝 Cyril Vallez 負責 generate 相關 PR。我們感謝 Sayak Paul、llama.cpp 團隊和 Bertrand Chevalier 協助整合核心。亦感謝 Aritra Roy Gosthipaty 和 Pedro Cuenca 審閲本文,以及 Lysandre Debut 督導專案。
來源:Hugging Face Blog · huggingface.co