Hugging Face's logo

Transformers documentation

Apple Silicon

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.2).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Apple Silicon

Apple Silicon (M-series) 칩은 Metal Performance Shaders (MPS) 백엔드를 통해 PyTorch를 실행하며, 디바이스 문자열은 mps입니다. CPU와 GPU는 하나의 통합 메모리 풀을 공유합니다.

MPS는 표준 torch 설치와 함께 작동합니다. Apple Silicon용 현재 PyTorch 릴리스는 macOS 14 이상을 요구합니다. PyTorch가 MPS로 빌드되었는지 및 GPU를 감지할 수 있는지 확인하세요.

import torch

print(torch.backends.mps.is_available())

MPS가 사용 준비가 되면 True를 출력합니다.

어텐션 백엔드 선택

모델을 로드할 때 attn_implementation으로 어텐션 백엔드를 설정하면 추론과 학습 모두에 적용됩니다. 모델은 기본적으로 SDPA를 사용합니다. PyTorch 2.13 이상에서는 MPS의 SDPA가 키와 밸류 헤드를 먼저 반복하지 않고 그룹 쿼리 어텐션을 직접 처리합니다.

트레이닝에 SDPA를 사용하세요.

  • kernels-community/metal-flash-sdpa는 패딩이 포함된 attention mask를 가진 배치나 packed sequences와 같이 가변 길이 입력만 지원합니다. 패딩이 없는 배치, 예를 들어 단일 프롬프트의 경우 오류가 발생합니다. query, key, value 투영에 대한 그래디언트를 계산하지 않습니다. MPS에서 flash attention을 요청하면 gpt-oss가 자동으로 이 커널로 전환합니다.
  • kernels이 설치된 경우 ggml-org/ggml-attn는 transformers serve와 GGUF 모델의 기본값입니다.

어떤 커널을 사용하든 kernels 추가 항목을 설치해야 합니다. Transformers가 지원하는 버전이 설치됩니다.

pip install "transformers[kernels]"

추론 실행

device_map="mps"를 from_pretrained()에 전달합니다. device를 전달하지 않으면 pipeline()이 자동으로 MPS를 선택합니다.

from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-0.6B", device_map="mps")
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-0.6B")

inputs = tokenizer("Apple Silicon is", return_tensors="pt")
output = model.generate(**inputs, max_new_tokens=50, do_sample=False)
print(tokenizer.decode(output[0], skip_special_tokens=True))

MPS를 대상으로 하는 device_map을 사용하면 Transformers는 safetensors 가중치를 MPS 장치에 직접 로드합니다.

모델 서빙

transformers serve는 OpenAI 호환 서버를 시작합니다. --device 옵션의 기본값은 auto이므로, 추가 플래그 없이 MPS에 모델을 로드합니다. 서빙 의존성을 설치하고 서버를 시작합니다.

pip install "transformers[serving]"
transformers serve

서버는 요청에서 모델이 처음 언급될 때 해당 모델을 로드합니다. http://localhost:8000으로 채팅 요청을 보내세요.

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-0.5B-Instruct",
    "messages": [{"role": "user", "content": "What is Apple Silicon? Answer in one sentence."}],
    "max_tokens": 64,
    "temperature": 0
  }'
{"id":"b48e84c1-b3c6-484d-b781-4c9ce8022dff","choices":[{"finish_reason":"stop","index":0,"message":{"content":"Apple Silicon is a type of processor technology developed and manufactured by Apple Inc., designed to offer faster performance and lower power consumption compared to traditional silicon-based processors. This technology allows for the creation of more efficient and energy-efficient devices, such as high-performance computers, smartphones, and other Apple products.","role":"assistant"}}],"created":1791843839,"model":"Qwen/Qwen2.5-0.5B-Instruct@main","object":"chat.completion","usage":{"completion_tokens":59,"prompt_tokens":39,"total_tokens":98}}

kernels이 설치된 경우, transformers serve는 MPS에서 기본적으로 ggml-org/ggml-attn를 사용하며 시작 시 경고를 기록합니다. 대신 SDPA를 사용하려면 --attn-implementation sdpa를 전달하세요.

모델 양자화

모델 가중치는 macOS 및 Mac에서 실행되는 기타 모든 요소와 통합 메모리를 공유하므로, 이를 양자화하면 추론 또는 파인튜닝에 더 큰 모델을 사용할 수 있습니다. Metal은 모델을 로드할 때 양자화를 수행하는 반면, GGUF는 이미 양자화된 체크포인트를 실행합니다. 두 방식 모두 추론 전용입니다.

  • Metal은 Hub의 Metal 커널을 사용하여 2, 4 또는 8비트로 양자화합니다.
  • ggml-org/ggml-quantization 커널이 사용 가능한 경우, GGUF는 MPS에서 가중치를 압축된 상태로 유지합니다.
  • bitsandbytes는 네이티브 MPS 커널을 사용하여 4비트로 양자화합니다.

메모리에 맞지 않는 모델을 파인튜닝하려면 bitsandbytes를 사용하여 4비트로 로드하고 PEFT로 LoRA 어댑터를 학습하세요.

Trainer로 학습

TrainingArguments는 MPS를 감지하여 장치를 mps로 설정하므로, Trainer는 별도의 장치 설정 없이 해당 장치에서 학습을 수행합니다. bf16과 fp16 혼합 정밀도 모두 작동합니다. metal-flash-sdpa는 어텐션 투영에 대한 기울기를 계산하지 않으므로, 모델은 기본 SDPA 어텐션을 사용하여 로드해야 합니다.

from transformers import TrainingArguments

training_args = TrainingArguments(
    output_dir="./outputs",
    bf16=True,
)
print(training_args.device)

Trainer가 GPU에서 학습할 경우 mps를 출력합니다.

macOS에서는 Python이 기본적으로 spawn으로 워커 프로세스를 시작하며, 이는 스크립트를 다시 가져오고 picklable한 데이터셋과 collate_fn을 요구합니다. dataloader_num_workers가 1보다 크면, TrainingArguments는 MPS에서 dataloader_multiprocessing_context="fork"를 설정하여 워커가 학습 프로세스의 복사본에서 시작되도록 합니다. 데이터 소스가 fork-safe하지 않은 경우 "spawn"으로 설정하세요.

그래프 캐시 증가 제한

MPS는 확인하는 각 텐서 형식에 대해 Metal 커널을 컴파일하며, 이를 절대 제거되지 않는 그래프 캐시에 유지합니다. 가변 길이 입력으로 학습하면 새로운 형식마다 커널이 추가되어 통합 메모리가 부족해질 수 있습니다.

pad_to_multiple_of 인수를 사용하여 각 배치의 길이를 고정된 길이의 배수로 패딩하여 DataCollatorWithPadding의 shape 수를 줄입니다.

from transformers import AutoTokenizer, DataCollatorWithPadding

tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-0.6B")
data_collator = DataCollatorWithPadding(tokenizer, pad_to_multiple_of=64)

data_collator=data_collator와 함께 Trainer에 전달합니다.

한계

  • device_map="auto"는 MPS와 CPU가 동일한 메모리를 공유하기 때문에 레이어를 CPU로 오프로드할 수 없습니다. 오버플로우는 디스크로 이동합니다.
  • compressed-tensors FP8 체크포인트는 MPS에서 로드되지만, 가중치가 첫 번째 forward pass에서 압축 해제되므로 추론 중 메모리를 줄이지 않습니다.
  • Mac은 하나의 장치만 가지고 있기 때문에 Tensor parallelism은 지원되지 않습니다.
  • 일부 PyTorch 연산에는 아직 MPS 구현이 없습니다. 오류를 발생시키지 않고 대신 CPU에서 실행하려면 PYTORCH_ENABLE_MPS_FALLBACK=1을 설정하세요.

다음 단계

  • 지원되는 연산 및 알려진 문제를 확인하려면 PyTorch MPS 백엔드 참고 문서를 읽어보세요.
  • attn_implementation이 어텐션 함수를 선택하는 방식을 배우려면 Attention backends 가이드를 읽어보세요.
  • 양자화 개요의 Metal 열을 확인하여 MPS에서 실행되는 모든 양자화 방법을 찾아보세요.
Update on GitHub

←NVIDIA GPU Intel GPU→