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) выполняют PyTorch через бэкенд Metal Performance Shaders (MPS) с строкой устройства mps. ЦП и ГП разделяют один пул унифицированной памяти.

MPS работает со стандартной установкой torch. Текущие версии PyTorch для Apple Silicon требуют macOS 14 или более позднюю. Убедитесь, что PyTorch собран с поддержкой MPS и может видеть GPU.

import torch

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

Выводит True, когда MPS готов к использованию.

Выберите бэкенд внимания

Установите бэкенд внимания с помощью attn_implementation при загрузке модели; он применяется как для инференса, так и для обучения. По умолчанию модели используют SDPA. В PyTorch 2.13 и новее SDPA на MPS напрямую обрабатывает grouped-query attention, без предварительного дублирования ключей и значений.

Используйте SDPA для обучения.

  • kernels-community/metal-flash-sdpa поддерживает только входные данные переменной длины, например, упакованные последовательности или батчи, в которых маска внимания содержит заполнители. Батч без заполнителей, например, одиночный промпт, вызывает ошибку. Ядро не вычисляет градиенты для проекций query, key и value. gpt-oss автоматически переключается на него, когда вы запрашиваете flash attention на MPS.
  • ggml-org/ggml-attn используется по умолчанию для transformers serve и для моделей GGUF, если установлен пакет kernels.

Установите дополнительный пакет kernels, чтобы использовать любое из ядер. Он устанавливает версию, поддерживаемую Transformers.

pip install "transformers[kernels]"

Запуск вывода

Передайте device_map="mps" в from_pretrained(). pipeline() автоматически выбирает MPS, если вы не передаёте device.

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))

При использовании device_map, нацеленного на MPS, 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 по умолчанию использует ggml-org/ggml-attn на MPS и выводит предупреждение при запуске. Чтобы использовать SDPA, передайте аргумент --attn-implementation sdpa.

Квантование моделей

Веса модели разделяют с macOS и всеми остальными процессами, работающими на Mac, единое пространство памяти, поэтому квантование позволяет разместить для инференса или дообучения модель большего размера. Metal выполняет квантование модели при её загрузке, тогда как GGUF работает с уже заквантованными чекпоинтами. Оба варианта поддерживают только инференс.

  • Metal выполняет квантование до 2, 4 или 8 бит с использованием Metal-ядер из Hub.
  • GGUF сохраняет веса в сжатом виде на MPS, если доступно ядро ggml-org/ggml-quantization.
  • bitsandbytes выполняет квантование до 4 бит с использованием нативных ядра MPS.

Чтобы дообучить модель, которая не помещается в память, загрузите её в 4-битном формате с помощью bitsandbytes и обучите адаптеры LoRA с PEFT.

Обучение с помощью Trainer

TrainingArguments определяет MPS и устанавливает устройство в mps, поэтому Trainer обучает на нём без каких-либо настроек устройства. Работают как bf16, так и fp16 смешанной точности. Загружайте модель с вниманием SDPA по умолчанию, так как metal-flash-sdpa не вычисляет градиенты для проекций внимания.

from transformers import TrainingArguments

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

Выводит mps, если Trainer будет обучать на GPU.

На macOS Python по умолчанию запускает рабочие процессы с помощью spawn, что приводит к повторному импорту вашего скрипта и требует, чтобы датасет и collate_fn были сериализуемы. Когда dataloader_num_workers больше 1, TrainingArguments устанавливает dataloader_multiprocessing_context="fork" на MPS, поэтому рабочие процессы запускаются из копии процесса обучения. Установите значение "spawn", если источник данных не поддерживает fork.

Ограничение роста кэша графа

MPS компилирует ядро Metal для каждой формы тензора, которую он встречает, и хранит их в кэше графа, который никогда не очищается. Обучение с входными данными переменной длины добавляет ядро для каждой новой формы и может привести к исчерпанию общей памяти.

Сократите количество форм, дополняя каждый батч до кратного фиксированной длине с помощью аргумента pad_to_multiple_of в DataCollatorWithPadding.

from transformers import AutoTokenizer, DataCollatorWithPadding

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

Передайте его в Trainer с параметром data_collator=data_collator.

Ограничения

  • device_map="auto" не может выгружать слои на CPU, так как MPS и CPU используют общую память. Переполнение выгружается на диск.
  • Чекпоинты compressed-tensors FP8 загружаются на MPS, но их веса разжимаются при первом проходе, поэтому они не уменьшают потребление памяти во время инференса.
  • Параллелизм тензоров не поддерживается, так как на Mac имеется только одно устройство.
  • Некоторые операции PyTorch пока не имеют реализации для MPS. Установите PYTORCH_ENABLE_MPS_FALLBACK=1, чтобы выполнять их на CPU вместо вывода ошибки.

Дальнейшие шаги

  • Ознакомьтесь с примечаниями к MPS backend PyTorch, чтобы узнать о поддерживаемых операциях и известных проблемах.
  • Ознакомьтесь с руководством Attention backends, чтобы узнать, как attn_implementation выбирает функцию внимания.
  • Проверьте столбец Metal в обзоре квантования, чтобы найти все методы квантования, работающие на MPS.
Update on GitHub

←NVIDIA GPU Intel GPU→