Huggingface Accelerate

Простейший API для распределённого обучения. 4 строки для добавления поддержки распределённых вычислений в любой скрипт PyTorch. Единый API для DeepSpeed/FSDP/Megatron/DDP. Автоматическое размещение устройств, смешанная точность (FP16/BF16/FP8). Интерактивная конфигурация, единая команда запуска. Стандарт экосистемы HuggingFace.

Метаданные навыка


Источник	Опционально — установка с помощью `vibeos skills install official/mlops/accelerate`
Путь	`optional-skills/mlops/accelerate`
Версия	`1.0.0`
Автор	Orchestra Research
Лицензия	MIT
Зависимости	`accelerate`, `torch`, `transformers`
Платформы	linux, macos, windows
Теги	`Распределённое обучение`, `HuggingFace`, `Accelerate`, `DeepSpeed`, `FSDP`, `Смешанная точность`, `PyTorch`, `DDP`, `Единый API`, `Простота`

Справочник: полный SKILL.md

к сведению

Ниже приведено полное описание навыка, которое VibeOS загружает при его активации. Это те инструкции, которые видит агент, когда навык активен.

HuggingFace Accelerate — единое распределённое обучение

Быстрый старт

Accelerate упрощает распределённое обучение до 4 строк кода.

Установка:

pip install accelerate

Преобразование скрипта PyTorch (4 строки):

import torch
+ from accelerate import Accelerator

+ accelerator = Accelerator()

  model = torch.nn.Transformer()
  optimizer = torch.optim.Adam(model.parameters())
  dataloader = torch.utils.data.DataLoader(dataset)

+ model, optimizer, dataloader = accelerator.prepare(model, optimizer, dataloader)

  for batch in dataloader:
      optimizer.zero_grad()
      loss = model(batch)
-     loss.backward()
+     accelerator.backward(loss)
      optimizer.step()

Запуск (одна команда):

accelerate launch train.py

Типовые сценарии

Сценарий 1: от одного GPU к нескольким

Исходный скрипт:

# train.py
import torch

model = torch.nn.Linear(10, 2).to('cuda')
optimizer = torch.optim.Adam(model.parameters())
dataloader = torch.utils.data.DataLoader(dataset, batch_size=32)

for epoch in range(10):
    for batch in dataloader:
        batch = batch.to('cuda')
        optimizer.zero_grad()
        loss = model(batch).mean()
        loss.backward()
        optimizer.step()

С Accelerate (добавлено 4 строки):

# train.py
import torch
from accelerate import Accelerator  # +1

accelerator = Accelerator()  # +2

model = torch.nn.Linear(10, 2)
optimizer = torch.optim.Adam(model.parameters())
dataloader = torch.utils.data.DataLoader(dataset, batch_size=32)

model, optimizer, dataloader = accelerator.prepare(model, optimizer, dataloader)  # +3

for epoch in range(10):
    for batch in dataloader:
        # .to('cuda') не нужен — автоматически!
        optimizer.zero_grad()
        loss = model(batch).mean()
        accelerator.backward(loss)  # +4
        optimizer.step()

Настройка (интерактивно):

accelerate config

Вопросы:

Какая машина? (один/несколько GPU/TPU/CPU)
Сколько машин? (1)
Смешанная точность? (нет/fp16/bf16/fp8)
DeepSpeed? (нет/да)

Запуск (работает на любой конфигурации):

# Один GPU
accelerate launch train.py

# Несколько GPU (8 GPU)
accelerate launch --multi_gpu --num_processes 8 train.py

# Несколько узлов
accelerate launch --multi_gpu --num_processes 16 \
  --num_machines 2 --machine_rank 0 \
  --main_process_ip $MASTER_ADDR \
  train.py

Сценарий 2: обучение со смешанной точностью

Включение FP16/BF16:

from accelerate import Accelerator

# FP16 (с масштабированием градиентов)
accelerator = Accelerator(mixed_precision='fp16')

# BF16 (без масштабирования, более стабильно)
accelerator = Accelerator(mixed_precision='bf16')

# FP8 (H100+)
accelerator = Accelerator(mixed_precision='fp8')

model, optimizer, dataloader = accelerator.prepare(model, optimizer, dataloader)

# Всё остальное автоматически!
for batch in dataloader:
    with accelerator.autocast():  # Опционально, делается автоматически
        loss = model(batch)
    accelerator.backward(loss)

Сценарий 3: интеграция DeepSpeed ZeRO

Включение DeepSpeed ZeRO-2:

from accelerate import Accelerator

accelerator = Accelerator(
    mixed_precision='bf16',
    deepspeed_plugin={
        "zero_stage": 2,  # ZeRO-2
        "offload_optimizer": False,
        "gradient_accumulation_steps": 4
    }
)

# Тот же код, что и раньше!
model, optimizer, dataloader = accelerator.prepare(model, optimizer, dataloader)

Или через конфиг:

accelerate config
# Выберите: DeepSpeed → ZeRO-2

deepspeed_config.json:

{
    "fp16": {"enabled": false},
    "bf16": {"enabled": true},
    "zero_optimization": {
        "stage": 2,
        "offload_optimizer": {"device": "cpu"},
        "allgather_bucket_size": 5e8,
        "reduce_bucket_size": 5e8
    }
}

Запуск:

accelerate launch --config_file deepspeed_config.json train.py

Сценарий 4: FSDP (Fully Sharded Data Parallel)

Включение FSDP:

from accelerate import Accelerator, FullyShardedDataParallelPlugin

fsdp_plugin = FullyShardedDataParallelPlugin(
    sharding_strategy="FULL_SHARD",  # Эквивалент ZeRO-3
    auto_wrap_policy="TRANSFORMER_AUTO_WRAP",
    cpu_offload=False
)

accelerator = Accelerator(
    mixed_precision='bf16',
    fsdp_plugin=fsdp_plugin
)

model, optimizer, dataloader = accelerator.prepare(model, optimizer, dataloader)

Или через конфиг:

accelerate config
# Выберите: FSDP → Full Shard → No CPU Offload

Сценарий 5: накопление градиентов

Накопление градиентов:

from accelerate import Accelerator

accelerator = Accelerator(gradient_accumulation_steps=4)

model, optimizer, dataloader = accelerator.prepare(model, optimizer, dataloader)

for batch in dataloader:
    with accelerator.accumulate(model):  # Управляет накоплением
        optimizer.zero_grad()
        loss = model(batch)
        accelerator.backward(loss)
        optimizer.step()

Эффективный размер батча: batch_size * num_gpus * gradient_accumulation_steps

Когда использовать вместо альтернатив

Используйте Accelerate, когда:

Нужно простейшее распределённое обучение
Требуется единый скрипт для любого оборудования
Используете экосистему HuggingFace
Нужна гибкость (DDP/DeepSpeed/FSDP/Megatron)
Требуется быстрая разработка прототипов

Ключевые преимущества:

4 строки: Минимальные изменения кода
Единый API: Один код для DDP, DeepSpeed, FSDP, Megatron
Автоматизация: Размещение устройств, смешанная точность, шардинг
Интерактивная конфигурация: Без ручной настройки запуска
Единый запуск: Работает везде

Используйте альтернативы вместо:

PyTorch Lightning: Нужны колбэки, высокоуровневые абстракции
Ray Train: Оркестрация нескольких узлов, настройка гиперпараметров
DeepSpeed: Прямой контроль API, продвинутые функции
Обычный DDP: Максимальный контроль, минимальная абстракция

Частые проблемы

Проблема: Неправильное размещение устройства

Не перемещайте данные на устройство вручную:

# НЕПРАВИЛЬНО
batch = batch.to('cuda')

# ПРАВИЛЬНО
# Accelerate делает это автоматически после prepare()

Проблема: Накопление градиентов не работает

Используйте контекстный менеджер:

# ПРАВИЛЬНО
with accelerator.accumulate(model):
    optimizer.zero_grad()
    accelerator.backward(loss)
    optimizer.step()

Проблема: Сохранение контрольных точек в распределённом режиме

Используйте методы accelerator:

# Сохранять только на главном процессе
if accelerator.is_main_process:
    accelerator.save_state('checkpoint/')

# Загружать на всех процессах
accelerator.load_state('checkpoint/')

Проблема: Разные результаты с FSDP

Убедитесь, что используется одинаковое случайное зерно:

from accelerate.utils import set_seed
set_seed(42)

Продвинутые темы

Интеграция Megatron: См. references/megatron-integration.md для настройки тензорного, конвейерного и последовательного параллелизма.

Пользовательские плагины: См. references/custom-plugins.md для создания собственных плагинов распределённых вычислений и расширенной конфигурации.

Настройка производительности: См. references/performance.md для профилирования, оптимизации памяти и лучших практик.

Требования к оборудованию

CPU: Работает (медленно)
Один GPU: Работает
Несколько GPU: DDP (по умолчанию), DeepSpeed или FSDP
Несколько узлов: DDP, DeepSpeed, FSDP, Megatron
TPU: Поддерживается
Apple MPS: Поддерживается

Требования к запуску:

DDP: torch.distributed.run (встроено)
DeepSpeed: deepspeed (pip install deepspeed)
FSDP: PyTorch 1.12+ (встроено)
Megatron: Пользовательская настройка

Ресурсы

Документация: https://huggingface.co/docs/accelerate
GitHub: https://github.com/huggingface/accelerate
Версия: 1.11.0+
Учебник: «Accelerate your scripts»
Примеры: https://github.com/huggingface/accelerate/tree/main/examples
Используется: HuggingFace Transformers, TRL, PEFT, все библиотеки HF

Метаданные навыка​

Справочник: полный SKILL.md​

HuggingFace Accelerate — единое распределённое обучение

Быстрый старт​

Типовые сценарии​

Сценарий 1: от одного GPU к нескольким​

Сценарий 2: обучение со смешанной точностью​

Сценарий 3: интеграция DeepSpeed ZeRO​

Сценарий 4: FSDP (Fully Sharded Data Parallel)​

Сценарий 5: накопление градиентов​

Когда использовать вместо альтернатив​

Частые проблемы​

Продвинутые темы​

Требования к оборудованию​

Ресурсы​