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 텐서로 패키징하고, 각 그룹마다 affine scale과 bias를 적용하며, Apple silicon GPU에서 fused dequantize 및 matmul 커널을 실행합니다. 해당 커널은 MLX에서 제공되며, kernels 라이브러리를 통해 Hub(kernels-community/mlx-quantization-metal-kernels)에서 로드됩니다. 이를 사용하여 Mac에서 MPS로 2, 4, 8비트 모델을 실행할 수 있습니다.

아래 표는 Transformers에서 Metal이 지원하는 사항을 요약합니다.

설정MetalConfig
quant_methodmetal
워크플로Quantize while loading
Bits2, 4, 8
하드웨어Apple silicon (MPS)
저장✅
파인튜닝❌
자동 컴파일❌

Metal 설치

kernels extra를 포함하여 Transformers를 설치합니다. Metal 커널은 양자화 레이어가 처음 실행될 때 Hub에서 다운로드됩니다.

pip install -U "transformers[kernels]"

Metal로 모델 양자화

MetalConfig를 생성하고 from_pretrained()에 전달합니다. device_map="mps"를 설정하여 모델이 Apple silicon GPU에서 실행되도록 합니다. 아래 예시는 모든 linear layer를 64개의 가중치 그룹으로 4비트로 양자화합니다.

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 silicon 없이 Metal 체크포인트 로드

MPS가 없는 머신에서 Metal 체크포인트를 로드하면 Transformers가 경고를 기록하고 가중치를 부동 소수점으로 역양자화하여, 모델이 CPU 또는 CUDA GPU에서 일반 모델처럼 실행됩니다. 모든 머신에서 역양자화를 수행하려면 dequantize=True를 설정합니다. 아래 예제는 model.save_pretrained("Qwen3-0.6B-metal")로 저장된 후 Metal로 모델 양자화에서 모델을 로드합니다.

from transformers import AutoModelForCausalLM, MetalConfig

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

dequantize는 로딩 시에만 적용됩니다. 체크포인트의 config에 저장되지 않습니다.

한계

  • 모델을 양자화하려면 MPS 장치가 필요합니다. MPS 장치 없이 양자화를 시도하면 RuntimeError가 발생합니다.
  • kernels 패키지가 설치되지 않은 상태에서 로딩을 시도하면 ImportError가 발생합니다.
  • device_map에 "cpu" 또는 "disk"가 포함된 모델을 양자화하면 ValueError가 발생합니다.

리소스

Update on GitHub