Metal

Metal 量化在 Apple Silicon（MPS）设备上使用托管于 Hugging Face Hub 的 Metal 内核（kernels-community/mlx-quantization-metal-kernels）执行仿射量化。这些内核源自 MLX 框架，并通过 kernels 库进行编译。

权重被打包为带有分组缩放因子和偏置的 uint32 张量，前向传播使用融合的反量化 + 矩阵乘法 Metal 内核（affine_qmm_t）。这能在完全于 GPU 上运行推理且无需 CPU 往返的情况下，保持较低的内存占用。

支持的位宽为 2、4 和 8。分组大小可配置（默认值为 64）。

要求

支持 MPS 的 Apple Silicon Mac（M1 / M2 / M3 / M4）
kernels 软件包：

pip install kernels

Metal 内核会在首次使用时从 Hub 自动下载——无需手动编译。

即时量化

通过传入 MetalConfig，可以在加载时加载任意模型并对其进行量化。所有符合条件的 nn.Linear 层都会被替换为量化版本。

from transformers import AutoModelForCausalLM, AutoTokenizer, MetalConfig

quantization_config = MetalConfig(bits=4, group_size=64)
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.2-1B",
    device_map="mps",
    quantization_config=quantization_config,
)

tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-3.2-1B")
inputs = tokenizer("Apple Silicon is", return_tensors="pt").to("mps")
output = model.generate(**inputs, max_new_tokens=50)
print(tokenizer.decode(output[0], skip_special_tokens=True))

加载预量化模型

如果检查点中已经包含量化后的权重（weight 为打包的 uint32，scales、qbiases），则会直接加载它们，无需重新量化。

from transformers import AutoModelForCausalLM, MetalConfig

model = AutoModelForCausalLM.from_pretrained(
    "your-org/model-metal-4bit",
    device_map="mps",
)

反量化

在没有 MPS 的机器上，预量化检查点会自动反量化回 float，以便模型仍可在 CPU 或 CUDA 上使用。您也可以显式强制此行为：

from transformers import AutoModelForCausalLM, MetalConfig

config = MetalConfig(dequantize=True)
model = AutoModelForCausalLM.from_pretrained(
    "your-org/model-metal-4bit",
    quantization_config=config,
    device_map="cpu",
)

排除层

某些层（例如 lm_head）可以通过 modules_to_not_convert 从量化中排除：

config = MetalConfig(bits=4, group_size=64, modules_to_not_convert=["lm_head"])

配置选项

参数	默认	描述
`bits`	`4`	用于权重量化的位宽（2、4 或 8）
`group_size`	`64`	每个量化组的元素数量
`modules_to_not_convert`	`None`	需要以完整精度保留的模块名称列表
`dequantize`	`False`	强制反量化为 float（针对非 MPS 设备）

Update on GitHub

Transformers

Metal

要求

即时量化

加载预量化模型

反量化

排除层

配置选项