我們正在為 Transformers 函式庫新增對 GGUF 模型的高效運行支援，讓您能透過熟悉的 Transformers API，使用適合筆記型電腦記憶體大小的模型檢查點。您可以從 Hugging Face Hub 選擇一個 GGUF 模型，使用 `from_pretrained` 載入，然後在自己的機器上開始生成。

在筆記型電腦上運行 AI 模型已變得更加容易，而 llama.cpp 在其中扮演了重要角色。其推論引擎支援了 Ollama、LM Studio 和 Jan 等本地 AI 工具。與 MLX 等專案一同，它幫助本地推論成為日常使用的實用選項。

llama.cpp 團隊開發的 GGUF 是一種廣泛用於本地推論的格式。該團隊也在 Hugging Face Hub 上的 ggml-org 帳號下分享量化後的檢查點。Unsloth、LM Studio Community 和 bartowski 等發布者也提供了各種量化程度的即用型 GGUF 檢查點，使用者可以選擇適合自己機器的版本。GGUF 模型已被下載數百萬次。

我們也希望讓這些模型更容易透過 Transformers 在本地運行。相容性只有在模型運行順暢時才有意義。為了使效能接近 llama.cpp，我們透過 `kernels` 函式庫重複使用其底層的 ggml 核心，並減少生成過程中的開銷。我們最初的重點是 Apple Silicon 上的本地推論，從 Qwen3.5 架構開始。

GGUF 檔案格式是什麼？GGUF 將模型權重和中繼資料（包括分詞器資訊和可選的聊天模板）打包在一個檔案中。它支援不同的量化級別，讓您可以犧牲一些精度來換取更小的記憶體佔用。例如 Q4_K_M 等變體會混合張量精度，主要使用 4 位元權重，同時將敏感張量保持在更高的精度。

以下是量化如何改變 Unsloth 的 Qwen3.5-4B 檔案大小的範例：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。更激進的量化可以幫助更大的模型適應，但品質的權衡取決於模型和任務。請根據您實際希望模型執行的工作來評估。

要開始使用，您需要：一台 Apple Silicon Mac、PyTorch 版本支援已發布的 ggml-quantization 核心建置（通常是兩個最新的 PyTorch 版本），以及最新版本的 Transformers（目前是 main 分支，直到下一個版本）和相容版本的 `kernels`。

您可以透過 `pip install -U "git+https://github.com/huggingface/transformers.git" kernels` 進行安裝。

要載入 GGUF 模型，請將其 Hub 模型 ID 和檔案名稱作為 `gguf_file` 參數傳遞給 `from_pretrained`。無需額外配置：當權重保持在 Metal 上時，Transformers 會自動載入相容的 ggml/Metal 層核心，並使用 ggml-org/ggml-attn 作為注意力實作。

如果無法獲取該核心，模型會發出警告並回退到「sdpa」，您也可以透過明確傳遞 `attn_implementation="sdpa"` 來強制使用「sdpa」。

這就是唯一與 GGUF 相關的步驟。之後的一切都是標準的 Transformers API。例如，您可以定義訊息、使用 `tokenizer.apply_chat_template` 準備輸入，然後使用 `model.generate` 進行生成。如果沒有相容的量化核心，載入器會回退到對模型進行去量化，並使用更多記憶體。

您也可以使用 `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_id>:<filename>.gguf` 格式：冒號前是 Hub 儲存庫（unsloth/Qwen3.5-4B-GGUF），冒號後是要載入的檔案（Qwen3.5-4B-Q4_K_M.gguf）。這可以從可能包含多個量化版本的儲存庫中選擇特定的量化。

您可以透過新增自訂的 OpenAI 相容提供者，將 Jan 或 Pi 等客戶端連接到此服務，設定 Base URL 為 `http://localhost:8000/v1`，Model ID 為 `unsloth/Qwen3.5-4B-GGUF:Qwen3.5-4B-Q4_K_M.gguf`。

我們以 llama.cpp 作為本地推論效能的參考。下面的比較側重於三個 GGUF 檢查點：一個小型密集模型、一個較大型密集模型和一個專家混合模型。llama.cpp 的數據來自 `llama-bench` 工具，報告的是在 128 個解碼 token 上的 token 生成速率（tg128），平均三次重複，不包括提示處理。

Transformers 的數據是生成相同的 128 個 token，從 12 個 token 的提示開始，三次預熱運行中取最佳，並包括預填充時間。

在 MacBook Pro M2 Max（32 GB 統一記憶體，macOS 26.6，PyTorch 2.12.1，kernels 0.17.0）上進行測量。Transformers 在所有三個檢查點上的表現都接近 llama.cpp。圖表使用上述相同的測量方法；它並不意味著基準測試條件完全相同，因為 Transformers 的測量包括預填充，而 llama-bench 報告的是僅解碼的吞吐量。

當 GGML 和 llama.cpp 加入 Hugging Face 時，我們描述了它們的互補作用：llama.cpp 為本地推論提供了基礎，而 Transformers 為模型定義提供了基礎。GGUF 支援使兩者更緊密地結合。當您的首要任務是高效的本地推論時，llama.cpp 仍然是我們推薦的引擎。其專用的運行時、記憶體管理和廣泛的硬體支援都是圍繞該目標構建的。

這項整合為開發人員提供了一種方便的方式，可以在 Transformers 內部使用相同的 GGUF 檢查點：在 Python 和 PyTorch 中試驗 GGUF；使用現有的 Transformers 評估工作流程來衡量量化檢查點的品質；驗證 GGUF 轉換；嘗試新的解碼想法；以及從 GGUF 檢查點進行微調。

對於最後一種情況，您可以使用 `GgufConfig(dequantize=True)` 來去量化權重並繼續標準的 Transformers 訓練工作流程。

更大的機會是將 ggml 的效能帶給 llama.cpp 不支援的模型。Transformers 已經提供了這些架構的 PyTorch 實作。透過 PyTorch 中可用的 ggml 核心和量化方案，我們可以努力加速其支援的操作，而無需首先在 llama.cpp 中實作整個模型。這對於新架構、研究模型和可能永遠不會獲得專用 llama.cpp 實作的自訂變體特別有用。

這個機會不僅限於 GGUF 格式本身。核心在張量上操作；它不要求整個模型都來自 GGUF 檔案。相同的構建塊可以整合到其他 Transformers 模型和載入工作流程中。這也為其他模態開闢了道路：電腦視覺模型、音訊模型和多模態模型可以重複使用相容的注意力、正規化和矩陣乘法核心，而無需首先在 llama.cpp 中進行完整實作。每個架構仍然需要整合和驗證；這裡的初始 GGUF 範例涵蓋了文字生成。

我們還想展示在保持模型和生成迴圈在 Python 中時，我們可以達到多遠的效能。透過正確的核心和高效的生成迴圈，Python 和 PyTorch 可以提供強大的本地推論效能。核心處理繁重的計算，而生成迴圈透過避免不必要的同步來保持 GPU 忙碌。

我們的重點是讓 eager execution 快速運行，而無需 `torch.compile`。對於互動式使用，我們希望快速啟動並穩定生成 token 流，而不會出現編譯暫停或輸入形狀改變時的重新編譯。這項工作的兩個主要部分是核心和 `generate` 本身。

核心是一個在 GPU 上執行操作的小程式。PyTorch 提供通用實作；專用核心可以減少工作量，組合多個操作，或直接以其儲存格式讀取量化權重。`kernels` 函式庫使我們能夠在 Hugging Face Hub 上分發 ggml Metal 核心的相容建置，並從 Transformers 中呼叫它們。這將 ggml 的工作引入 PyTorch 模型，而無需重新實作。