Transformers 支持直接在本地运行 GGUF 量化模型

变化内容

Hugging Face 于 2026 年 9 月 22 日发布博文，说明 transformers 已支持加载 GGUF 模型：用 from_pretrained 指定 Hub 上的 gguf_file 即可在本地生成文本，后续流程沿用标准 transformers API。

背景

GGUF 由 llama.cpp 团队开发，把模型权重与元数据（含分词器信息、可选对话模板）打包在单个文件中，支持多种量化级别。Q4_K_M 这类变体混合不同张量精度，大部分权重为 4 位，敏感张量保留更高精度。文中以 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 量化内核构建支持，通常是最近两个 PyTorch 版本；
• transformers 目前需用 main 分支（直至下一次发布），并搭配兼容版本的 kernels。

加载时若权重保持在 Metal 上打包，transformers 会自动启用 ggml/Metal 层内核，并使用 ggml-org/ggml-attn 作为注意力实现；拉取不到该内核时会回退到 sdpa 并给出警告，也可显式指定 attn_implementation="sdpa"。没有兼容量化内核时，加载器会反量化模型，占用更多内存。

此外可用 transformers serve 以 <model_id>:<filename>.gguf 形式暴露 OpenAI 兼容接口，Jan、Pi 等客户端可通过自定义 provider 接入（Base URL 为 http://localhost:8000/v1）。支持思考模板的模型可用 --reasoning off/on/auto 控制。

性能与基准

内核包括 ggml-quantization（直接读取打包量化权重）、ggml-norm、ggml-attn，以及作者自研的 topk 路由内核；ggml-gated-delta-net 用于 Qwen3.5/Qwen3.8 混合架构的线性注意力层。generate 中还做了两处优化：在无 padding 的输入上提前去掉多余的注意力掩码；异步复制停止判断并在下一步消费，减少 CPU 等待。

基准在 MacBook Pro M2 Max（32 GB 统一内存、macOS 26.6、PyTorch 2.12.1、kernels 0.17.0）上测得，比较三个 GGUF 检查点。llama.cpp 数据来自 llama-bench（build 5f55650a7，release b10200，ggml 0.18.0 Metal 后端），只计 decode 吞吐；transformers 一侧包含 prefill，两者条件并不完全相同，因此文中只说“接近”而非相等。

限制

• 打包推理路径目前仅支持 MPS；GGUF 文件支持不等于所有设备都能用打包内核；
• padding 与批处理表现较弱，作者计划把优化扩展到 MPS 上的 generate_batch；
• 打包加载器目前只覆盖 Qwen3.5 稠密与 MoE 架构（含兼容的 Qwen3.8 检查点），其他架构需逐步接入；
• 文中称 llama.cpp 仍是优先追求高效本地推理时推荐的引擎；transformers 的定位是在 Python/PyTorch 中试验、评估量化检查点、校验 GGUF 转换、尝试自定义解码，或用 GgufConfig(dequantize=True) 反量化后继续微调。

以上性能结论来自官方博文，未提及独立的第三方复测。