Transformers 直接跑 GGUF：Python 追平 llama.cpp

从最终配置里只关掉层内核（量化内核在两组里都开着）后的吞吐对比。图片来源：Hugging Face Blog

只保留 ggml-quantization、关掉其余层内核，4B 从 70.4 掉到 44.2，27B 从 15.9 掉到 10.5，35B-A3B 从 60.2 掉到 28.8——对应 1.59×、1.51×、2.09× 的差距。这些内核通过 kernels 库以编译好的构建产物形式发布在 Hub 上，由 transformers 按需拉取：

前四个建立在 ggml 的内核之上，topk 针对的是 MoE 路由这个单独的瓶颈。MoE 那一档（35B-A3B）提速倍数最高（2.09×），与这条线索是一致的。

3.2 生成循环：CPU 别再干等 GPU

两处 generate 改动前后的吞吐对比，两组均开启全部层内核。图片来源：Hugging Face Blog

第二处成本根本不在模型里，而在模型外面那个循环。生成时由 CPU 调度 GPU 操作并控制"下一个 token"的循环，一旦要把结果从 GPU 读回来，CPU 就得等队列里的操作做完；每个 token 都等上一小下，累积起来就是可观的吞吐损失。原文改了两处：

• 提前丢掉不必要的注意力掩码（PR #48814）。受支持的 decoder-only 输入若没有 padding，那条全 1 的 padding 掩码可以在生成开始时就移除，下游注意力代码不必反复检查它能不能跳过。因果注意力仍然保留。
• 延后停止判断（PR #47975）。在受支持的路径上，generate 异步拷贝停止判断、下一步再消费它，CPU 得以继续排布工作而 GPU 保持在跑。流式输出用同样的做法，多跑的那一步会从结果里剔除。

效果是 1.42×、1.16×、1.79×。要注意这两张消融图不能相乘：它们各自是从同一个最终配置里拿掉一项，黄色柱都是同一个终点（70.4 / 15.9 / 60.2）。

两处加在一起给出的判断是：所谓"Python 慢"的代价，主要不在 Python 的算术上，而在通用内核要先把量化权重摊开和CPU 与 GPU 之间的同步点。两者都不是语言本身的问题，所以也都能在不换语言的前提下修掉。顺带一提，生成循环这两处改动惠及所有 transformers 模型，不限于 GGUF。

四、实际怎么跑

4.1 前置条件

三条，缺一不可：一台 Apple Silicon Mac；一个被已发布的 ggml-quantization 内核构建支持的 PyTorch 版本（通常是最近两个发行版）；最新的 transformers（原文发布时还需装 main 分支）和与之兼容的 kernels。

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

4.2 加载

GGUF 专属的步骤只有一步：把 Hub 上的 model_id 和文件名作为 gguf_file 传给 from_pretrained。

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)

之后全是标准的 transformers API：apply_chat_template 拼对话、generate 生成、decode 解码，与平时无异。

不需要额外配置：当权重以打包状态留在 Metal 上时，transformers 会自动加载匹配的 ggml/Metal 层内核，并用 ggml-org/ggml-attn 作为注意力实现。这里有两个静默降级点值得盯住：

• 拉不到内核时，模型会带一条警告回退到 "sdpa"。你也可以显式传 attn_implementation="sdpa" 强制走这条路。
• 没有兼容的量化内核时，加载器会回退到反量化整个模型，占用更多内存。

这两条意味着"跑起来了"不等于"跑在快路径上"。装完第一件事是看日志里有没有那条 warning，否则你可能拿着 44.2 tok/s 的配置去和别人的 70.4 比。

4.3 选哪一档量化

以 Unsloth 的 Qwen3.5-4B 为例，量化档位对文件体积的影响：

Q4_K_M 这类变体是混合精度：大部分权重用 4 bit，敏感的张量保留更高精度。原文的建议是从 Q4_K_M 起步，内存宽裕再试 Q5_K_M 或 Q6_K；更激进的量化能把更大的模型塞进来，但质量损失取决于模型和任务——要在你真正要它干的活上评，不要看别人的榜。

4.4 当成服务跑

同一份权重可以直接交给 transformers serve，它暴露的是 OpenAI 兼容接口：

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 仓库，冒号后是要加载的文件——一个仓库里往往放着好几档量化，靠这个冒号挑。对话模板支持思考过程的模型，可以加 --reasoning off 跳过或 --reasoning on 打开，默认的 --reasoning auto 跟随模板自己的设置。

客户端（如 Jan、Pi）里加一个自定义的 OpenAI 兼容供应商即可：

模型在你自己的 Mac 上跑，客户端只负责对话界面。其他支持这套接口的客户端同样可以接。

4.5 一个容易被忽略的测速细节

原文公开的基准脚本里有一行注释值得单独拎出来：每轮之间 time.sleep(90)，理由是让机器冷却，背靠背连续跑会衰减 10% 甚至更多。任何人在自己的 Mac 上复现这类数字，都该先抄走这一条——否则你测到的是散热曲线，不是推理性能。

五、Hugging Face 自己划的边界

GGML 和 llama.cpp 加入 Hugging Face 时，双方的角色分工被描述为互补：llama.cpp 是本地推理的底座，transformers 是模型定义的底座。GGUF 支持把两者拉近了一步，但没有合并。原文明确列出的用途是五类：

1. 在 Python 和 PyTorch 里做实验——用 hook 看中间激活、改模型的 forward、拿熟悉的 PyTorch 工具原型化自定义层。
2. 评测 GGUF 模型——直接用你现有的 transformers 评测流程去量化版本的质量。
3. 验证 GGUF 转换是否正确——把原始权重和它的 GGUF 转换版都装进 transformers 比对，把量化误差考虑进去后检查权重转对没有。
4. 试新的解码思路——自定义 logits processor 和停止条件，或者干脆自己写生成循环。
5. 从 GGUF 检查点继续微调——反量化后走标准训练流程，用 GgufConfig(dequantize=True) 配合 dtype=torch.bfloat16。

这五条有一个共同点：它们都是要把模型拆开看的场景。如果你要的只是"本地有个能聊天的模型、一直开着"，llama.cpp / Ollama 这条路没有理由换。这不是谦辞，是原文的原话。

六、比性能数字更值钱的那条线

原文后半段提到了一个更大的机会：把 ggml 的性能带给 llama.cpp 不支持的模型。

逻辑是这样的：transformers 里已经有这些架构的 PyTorch 实现，而 ggml 的内核和量化方案现在能在 PyTorch 里调用了，于是可以在不先把整个模型在 llama.cpp 里实现一遍的前提下加速它们支持的算子。对新架构、研究模型、以及那些可能永远等不到 llama.cpp 专门实现的自定义变体，这条路径的意义比跑分大得多。

而且这件事不止于 GGUF 格式本身——原文的措辞是：内核作用于张量，它不要求整个模型来自 GGUF 文件。同一批构件可以接进其他 transformers 模型和加载流程，也给视觉、音频、多模态模型复用注意力、归一化、矩阵乘内核开了一条路。当然，每个架构仍需各自集成和验证，这次给出的例子只覆盖文本生成。

把内核做成 Hub 上可分发、可版本化的产物，而不是焊死在某个运行时里——这是这次工作里最可能被低估的一步。

七、当前限制，以及现在值不值得动手

原文列出的边界很诚实，照抄如下：

• 打包推理路径目前只支持 MPS。也就是说，这一整套加速现在只对 Apple Silicon 有效；通过反量化导入 GGUF 仍是另一条独立选项，但"支持这个文件格式"不等于"每种设备上都有打包内核"。
• Padding 与批处理还没做好。没有 padding 的输入才吃得到上面那条掩码优化，带 padding 的批次走不了这条捷径、性能会更低。团队想把工作扩展到 MPS 上的 generate_batch。
• 架构覆盖有限。打包加载器目前覆盖 Qwen3.5 的稠密与 MoE 架构，包括兼容的 Qwen3.8 权重。原文说增加其他架构相对直接，会逐步扩展，并邀请用户把想用的 GGUF 权重和使用场景提 issue，好排优先级。

对国内开发者，可以按手里的机器直接分诊：

用 N 卡或 Windows 的，这一轮先不用动——MPS-only 这条把话说死了，等架构和设备覆盖扩展再说。手里是 Apple Silicon Mac 的，值得花半小时装一遍，但装的目的要选对：不是替掉 Ollama，而是拿到一个能用 PyTorch 拆开看的量化模型。国内团队做垂类微调时最常见的一个断点，正是"手里只剩量化后的 GGUF、想接着训却接不回训练流程"，第 5 条用途和 GgufConfig(dequantize=True) 正对着这个断点。

预期也可以校准了：16.5 GB 的 27B 权重在 32 GB 统一内存的 M2 Max 上是 15.9 tok/s 这个量级，4B 是 70 上下，35B 的 MoE 因为每 token 只激活一小部分专家、反而能跑到 60。买机器、定本地部署方案时，这三个数比任何"能不能跑"的说法都更有参考价值。