Transformers可直接加载GGUF量化模型

原文要点

来源称transformers新增GGUF运行支持：在from_pretrained传model_id与gguf_file，后续沿用标准API；为接近llama.cpp，经kernels复用ggml内核并减少generate开销。首发聚焦Apple Silicon与Qwen3.5架构，示例给出Unsloth Qwen3.5-4B体积：BF16 8.42GB、Q6_K 3.53GB、Q5_K_M 3.14GB、Q4_K_M 2.74GB，建议从Q4_K_M起步。还支持transformers serve提供OpenAI兼容接口；限制是打包推理暂仅MPS，填充/批处理与架构覆盖有限。

这次做成什么

在一台Apple Silicon Mac上，用熟悉的transformers代码加载一个Hub GGUF量化模型，完成一次本地聊天生成，并能切换量化档位、识别内核回退、必要时用serve暴露OpenAI兼容端点；练习目标不是复现作者基准，而是跑通“选文件-加载-生成-排错”闭环。

准备什么

• Apple Silicon Mac，已安装Python 3.10+与可用的pip/venv环境
• PyTorch需为已发布ggml-quantization内核构建支持的版本，通常为最近两个PyTorch发布版
• 安装transformers main分支与兼容kernels；能访问Hugging Face Hub下载公开GGUF
• 准备至少约4GB空闲内存做Q4_K_M小模型练习，更大档位需更多统一内存

具体怎么做

1. 建隔离环境并装指定依赖

   新建venv后执行：pip install -U "git+https://github.com/huggingface/transformers.git" kernels。不要用旧release transformers；若安装失败，先升级pip/setuptools，再确认PyTorch版本是否落在内核构建支持范围。

2. 选一个GGUF文件而不是整仓盲下

   在Hub仓库如unsloth/Qwen3.5-4B-GGUF的Files里确认具体文件名，例如Qwen3.5-4B-Q4_K_M.gguf。把仓库名与文件名分别记下；一个仓可有多个量化档位，serve时也用<model_id>:<filename>.gguf精确选择。

3. 用gguf_file加载并做最小生成

   运行artifacts中的load_gguf.py：AutoTokenizer与AutoModelForCausalLM都传model_id与gguf_file=filename；随后用apply_chat_template构造messages，generate设max_new_tokens=128。观察是否自动加载ggml/Metal层内核与ggml-attn；若出现无法获取内核的警告，会回退sdpa，或显式传attn_implementation="sdpa"对照。

4. 做一次量化档位与内存记录

   同一提示词分别试Q4_K_M，再在内存充裕时试Q5_K_M或Q6_K。记录文件大小、是否能加载、首token是否明显变慢、回答是否偏题；不要根据档位名断定质量，按你的任务比较。

5. 可选：用serve接客户端

   安装serving额外依赖后运行：transformers serve "unsloth/Qwen3.5-4B-GGUF:Qwen3.5-4B-Q4_K_M.gguf"。在支持自定义OpenAI provider的客户端填Base URL http://localhost:8000/v1、Model ID用同一串；这是本机端点，不要暴露到公网。

可直接复制的材料

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)
messages = [{'role': 'user', 'content': '用三句话解释为什么天空是蓝色的。'}]
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=128)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

serve_command: transformers serve "unsloth/Qwen3.5-4B-GGUF:Qwen3.5-4B-Q4_K_M.gguf"
client_provider:
  base_url: http://localhost:8000/v1
  model_id: unsloth/Qwen3.5-4B-GGUF:Qwen3.5-4B-Q4_K_M.gguf
reasoning_option: auto
fallback_check: 若日志提示ggml-attn不可用，显式加attn_implementation=sdpa再测

variant,file_size_gb,load_ok,first_token_delay,task_score_1_to_5,note
BF16,8.42,,,,
Q6_K,3.53,,,,
Q5_K_M,3.14,,,,
Q4_K_M,2.74,,,,

输入与输出示例

本站虚构演示，非原作者结果，未声称真实调用；device与警告取决于你的机器和kernels。

输入

练习输入：model_id=unsloth/Qwen3.5-4B-GGUF，filename=Qwen3.5-4B-Q4_K_M.gguf；messages=[{"role":"user","content":"给阳台种植新手三条可执行建议，每条不超过20字。"}]，max_new_tokens=96。

对应输出

示意输出关键行：model.device=mps；未出现ggml-attn获取失败警告；decode文本形如“1. 选朝南位置，每天晒四小时。2. 土干再浇水，避免积水。3. 先种生菜和小葱。”；记录表填Q4_K_M load_ok=TRUE、task_score=4。

做完检查这些

• AutoTokenizer与AutoModelForCausalLM都传入同一个gguf_file，且能完成apply_chat_template到generate_decode的完整流程
• 加载日志没有出现强制回退sdpa的警告；若有警告，显式attn_implementation="sdpa"后仍能生成并记录差异
• 同一提示词至少在Q4_K_M与另一个更高档位上各跑一次，CSV中load_ok、相对延迟、任务分数均已填写
• serve练习中端点仅监听localhost，客户端Base URL与Model ID与启动命令中的<model_id>:<filename>完全一致

容易卡住的地方

• 把仓库名当文件名传入会失败；必须在Files页复制确切.gguf文件名
• 没有兼容量化内核时会反量化加载，内存占用明显升高，这不是性能异常而是路径变化
• 打包推理当前仅MPS；非Apple Silicon或无MPS环境不要套用packed结论
• 来源基准的transformers含prefill而llama-bench报decode-only，不能直接当作严格同条件对比
• 过大档位在32GB以下统一内存可能交换或失败，需从Q4_K_M逐步上调