Transformers documentation

Metal

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Metal

Metal 量化将权重打包为 uint32 张量,并为每个组设置仿射缩放和偏置,然后在 Apple 芯片 GPU 上运行融合的解量化和矩阵乘法内核。这些内核来自 MLX,并通过 kernels 库从 Hub(kernels-community/mlx-quantization-metal-kernels)加载。使用它可以在配备 MPS 的 Mac 上运行 2 位、4 位或 8 位模型。

下表总结了 Transformers 中 Metal 支持的功能。

配置MetalConfig
quant_methodmetal
工作流加载时量化
位2, 4, 8
硬件Apple 芯片(MPS)
保存✅
微调❌
自动编译❌

安装 Metal

使用 kernels 附加组件安装 Transformers。首次运行量化层时,Metal 内核会从 Hub 下载。

pip install -U "transformers[kernels]"

使用 Metal 量化模型

创建一个 MetalConfig 并将其传递给 from_pretrained()。设置 device_map="mps" 以便模型在 Apple 芯片 GPU 上运行。下面的示例将每个线性层量化为 4 位,每 64 个权重为一组。

from transformers import AutoModelForCausalLM, MetalConfig

quantization_config = MetalConfig(bits=4, group_size=64)
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    quantization_config=quantization_config,
    device_map="mps",
)

使用 Metal 量化保存的检查点会存储打包的权重、缩放因子和偏置。使用 from_pretrained() 加载时,会直接读取这些值,而无需再次进行量化。

配置 Metal

这些 MetalConfig 参数会改变权重的量化方式。

参数默认效果
bits4每个权重的位数。支持 2、4 和 8。
group_size64共享缩放和偏置的权重数量。必须为正数。
modules_to_not_convertNone不进行量化的模块。

在没有 Apple 芯片的情况下加载 Metal 检查点

如果在没有 MPS 的机器上加载 Metal 检查点,Transformers 会记录一条警告,并将权重反量化回浮点数,以便模型作为常规模型在 CPU 或 CUDA GPU 上运行。要在任何机器上进行反量化,请设置 dequantize=True。下面的示例加载了 使用 Metal 量化模型 中通过 model.save_pretrained("Qwen3-0.6B-metal") 保存的模型。

from transformers import AutoModelForCausalLM, MetalConfig

model = AutoModelForCausalLM.from_pretrained(
    "Qwen3-0.6B-metal",
    quantization_config=MetalConfig(dequantize=True),
    device_map="cpu",
)

dequantize 仅在加载时生效。它不会保存在检查点的配置中。

局限性

  • 量化模型需要 MPS 设备。在没有该设备的情况下进行量化会引发 RuntimeError。
  • 在未安装 kernels 包的情况下加载会引发 ImportError。
  • 如果模型的 device_map 中包含 "cpu" 或 "disk",对其进行量化时会引发 ValueError。

资源

Update on GitHub