Accelerate documentation

Ускоритель

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Ускоритель

Класс Accelerator является основным для организации распределённого обучения на любом типе конфигурации обучения. Прочитайте учебник Добавление Accelerator в ваш код, чтобы узнать, как добавить Accelerator в ваш скрипт.

Ускоритель

класс accelerate.Accelerator

< >

( device_placement: bool = Truesplit_batches: bool = <object object at 0x7f7bf6a755a0>mixed_precision: PrecisionType | str | None = Nonegradient_accumulation_steps: int = 1cpu: bool = Falsedataloader_config: DataLoaderConfiguration | None = Nonedeepspeed_plugin: DeepSpeedPlugin | dict[str, DeepSpeedPlugin] | None = Nonefsdp_plugin: FullyShardedDataParallelPlugin | None = Nonetorch_tp_plugin: TorchTensorParallelPlugin | None = Nonemegatron_lm_plugin: MegatronLMPlugin | None = Nonerng_types: list[str | RNGType] | None = Nonelog_with: str | LoggerType | GeneralTracker | list[str | LoggerType | GeneralTracker] | None = Noneproject_dir: str | os.PathLike | None = Noneproject_config: ProjectConfiguration | None = Nonegradient_accumulation_plugin: GradientAccumulationPlugin | None = Nonestep_scheduler_with_optimizer: bool = Truekwargs_handlers: list[KwargsHandler] | None = Nonedynamo_backend: DynamoBackend | str | None = Nonedynamo_plugin: TorchDynamoPlugin | None = Nonedeepspeed_plugins: DeepSpeedPlugin | dict[str, DeepSpeedPlugin] | None = Noneparallelism_config: ParallelismConfig | None = None )

Параметры

  • device_placement (bool, необязательный, по умолчанию True) — Определяет, должен ли акселератор размещать объекты на устройстве (тензоры, возвращаемые загрузчиком данных, модель и т. д.).
  • mixed_precision (str, необязательный) — Использовать ли обучение с смешанной точностью. Выберите ‘no’, ‘fp16’, ‘bf16’ или ‘fp8’. По умолчанию используется значение переменной окружения ACCELERATE_MIXED_PRECISION, которое использует значение по умолчанию в конфигурации accelerate текущей системы или флаг, переданный с командой accelerate.launch. Для ‘fp8’ требуется установка transformers-engine.
  • gradient_accumulation_steps (int, необязательный, по умолчанию 1) — Количество шагов, которое должно пройти до накопления градиентов. Значение > 1 следует использовать в сочетании с Accelerator.accumulate. Если не передано, будет использовано значение из переменной окружения ACCELERATE_GRADIENT_ACCUMULATION_STEPS. Также можно настроить через GradientAccumulationPlugin.
  • cpu (bool, необязательный) — Указывает, следует ли принудительно выполнять скрипт на CPU. Если установлено в True, доступный GPU будет игнорироваться, а выполнение будет ограничено одним процессом.
  • dataloader_config (DataLoaderConfiguration, необязательный) — Конфигурация, определяющая, как следует обрабатывать загрузчики данных в распределённых сценариях.
  • deepspeed_plugin (DeepSpeedPlugin или словарь str — DeepSpeedPlugin, необязательный): Настройте аргументы, связанные с DeepSpeed, с помощью этого параметра. Этот параметр необязательный и может быть настроен напрямую с помощью accelerate config. При использовании нескольких плагинов используйте настроенное свойство key каждого плагина для доступа к ним через accelerator.state.get_deepspeed_plugin(key). Псевдоним для deepspeed_plugins.
  • fsdp_plugin (FullyShardedDataParallelPlugin, необязательный) — Настройте аргументы, связанные с FSDP, с помощью этого параметра. Этот параметр необязателен и может быть настроен напрямую с помощью accelerate config
  • torch_tp_plugin (TorchTensorParallelPlugin, необязательный) — Устарело: используйте parallelism_config с tp_size.
  • megatron_lm_plugin (MegatronLMPlugin, необязательный) — Настройте аргументы, связанные с MegatronLM, с помощью этого параметра. Этот параметр необязательный и может быть настроен напрямую с помощью accelerate config
  • rng_types (список str или RNGType) — Список генераторов случайных чисел, которые необходимо синхронизировать в начале каждой итерации в подготовленных вами загрузчиках данных. Должен содержать один или несколько из следующих элементов:
    • "torch": базовый генератор случайных чисел torch
    • "cuda": генератор случайных чисел CUDA (только GPU)
    • Тип устройства любого зарегистрированного ускорителя PyTorch: его генератор случайных чисел для устройства.
    • "xla": генератор случайных чисел XLA (только TPU)
    • "generator": torch.Generator сэмплера (или батч-сэмплера, если в вашем dataloader нет сэмплера) или итерируемого датасета (если он существует), если базовый датасет имеет соответствующий тип.

    По умолчанию будет ["torch"] для версий PyTorch <=1.5.1 и ["generator"] для версий PyTorch >= 1.6.

  • log_with (список str, LoggerType или GeneralTracker, необязательный) — Список логгеров для настройки отслеживания экспериментов. Должен содержать один или несколько из:
    • "all"
    • "tensorboard"
    • "wandb"
    • "trackio"
    • "aim"
    • "comet_ml"
    • "mlflow"
    • "dvclive"
    • "swanlab" Если выбрано значение "all", будут обнаружены и инициализированы все доступные в окружении трекеры. Также можно передавать реализации GeneralTracker для пользовательских трекеров, и это можно комбинировать с "all".
  • project_config (ProjectConfiguration, необязательный) — Конфигурация, определяющая способ обработки сохранения состояния.
  • project_dir (str, os.PathLike, необязательный) — Путь к каталогу для хранения данных, таких как журналы локально-совместимых логгеров и потенциально сохранённые контрольные точки.
  • step_scheduler_with_optimizer (bool, необязательный, по умолчанию True) — Установите True, если планировщик скорости обучения обновляется одновременно с оптимизатором, и False, если это происходит только в определённых обстоятельствах (например, в конце каждой эпохи).
  • kwargs_handlers (список KwargsHandler, необязательный) — Список KwargsHandler для настройки создания объектов, связанных с распределённым обучением, профилированием или смешанной точностью. Подробнее см. kwargs.
  • dynamo_backend (str или DynamoBackend, необязательный, по умолчанию "no") — Укажите один из доступных dynamo backends для оптимизации обучения с помощью torch dynamo.
  • dynamo_plugin (TorchDynamoPlugin, необязательный) — Настройка того, как следует обрабатывать torch dynamo, если требуется более тонкая настройка, чем просто backend или mode.
  • gradient_accumulation_plugin (GradientAccumulationPlugin, необязательный) — Настройка того, как следует обрабатывать накопление градиентов, если требуется более тонкая настройка, чем просто gradient_accumulation_steps.

Создаёт экземпляр ускорителя для распределённого обучения или обучения с смешанной точностью.

Доступные атрибуты:

  • device (torch.device) — Устройство, которое будет использоваться.
  • distributed_type (DistributedType) — конфигурация распределённого обучения.
  • local_process_index (int) — Индекс процесса на текущей машине.
  • mixed_precision (str) — Настроенный режим смешанной точности.
  • num_processes (int) — Общее количество процессов, используемых для обучения.
  • optimizer_step_was_skipped (bool) — Указывает, был ли пропущен шаг обновления оптимизатора (из-за переполнения градиентов при смешанной точности), в этом случае скорость обучения не должна изменяться.
  • process_index (int) — Общий индекс текущего процесса среди всех процессов.
  • state (AcceleratorState) — Состояние распределённой конфигурации.
  • sync_gradients (bool) — Указывает, синхронизируются ли градиенты между всеми процессами в данный момент.
  • use_distributed (bool) — Указывает, настроена ли текущая конфигурация для распределённого обучения.

accumulate

< >

( *models )

Параметры

  • *models (список torch.nn.Module) — модули PyTorch, подготовленные с помощью Accelerator.prepare. Модели, переданные в accumulate(), будут пропускать синхронизацию градиентов во время обратного распространения в распределённом обучении

Контекстный менеджер, который автоматически выполняет накопление градиентов

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator(gradient_accumulation_steps=1)
>>> dataloader, model, optimizer, scheduler = accelerator.prepare(dataloader, model, optimizer, scheduler)

>>> for input, output in dataloader:
...     with accelerator.accumulate(model):
...         outputs = model(input)
...         loss = loss_func(outputs)
...         loss.backward()
...         optimizer.step()
...         scheduler.step()
...         optimizer.zero_grad()

autocast

< >

( autocast_handler: AutocastKwargs = None )

Если включено, внутри этого контекстного менеджера в блоке будет применяться автоматическое смешанное разрешение. В противном случае ничего не изменится.

В качестве autocast_handler можно передать другой, чтобы переопределить тот, что задан в объекте Accelerator. Это полезно в блоках под autocast, где требуется вернуться к fp32.

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator(mixed_precision="fp16")
>>> with accelerator.autocast():
...     train()

backward

< >

( loss**kwargs )

Масштабирует градиенты в соответствии с GradientAccumulationPlugin и вызывает правильный backward() на основе конфигурации.

Должно использоваться вместо loss.backward().

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator(gradient_accumulation_steps=2)
>>> outputs = model(inputs)
>>> loss = loss_fn(outputs, labels)
>>> accelerator.backward(loss)

check_trigger

< >

( )

Проверяет, установлен ли внутренний тензор триггера в 1 в каком-либо из процессов. Если да, возвращает True и сбрасывает тензор триггера в 0.

Примечание: Не требует wait_for_everyone()

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> # Assume later in the training script
>>> # `should_do_breakpoint` is a custom function to monitor when to break,
>>> # e.g. when the loss is NaN
>>> if should_do_breakpoint(loss):
...     accelerator.set_trigger()
>>> # Assume later in the training script
>>> if accelerator.check_trigger():
...     break

очистить

< >

( *objects )

Псевдоним для Accelerate.free_memory, освобождает все ссылки на внутренние объекты и вызывает сборщик мусора. Вы должны вызывать этот метод между двумя тренировками с разными моделями/оптимизаторами.

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> model, optimizer, scheduler = ...
>>> model, optimizer, scheduler = accelerator.prepare(model, optimizer, scheduler)
>>> model, optimizer, scheduler = accelerator.clear(model, optimizer, scheduler)

clip_grad_norm_

< >

( parametersmax_normnorm_type = 2 ) → torch.Tensor

Возвращает

torch.Tensor

Суммарная норма градиентов параметров (рассматриваемых как единый вектор).

Должен использоваться вместо torch.nn.utils.clip_grad_norm_.

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator(gradient_accumulation_steps=2)
>>> dataloader, model, optimizer, scheduler = accelerator.prepare(dataloader, model, optimizer, scheduler)

>>> for input, target in dataloader:
...     optimizer.zero_grad()
...     output = model(input)
...     loss = loss_func(output, target)
...     accelerator.backward(loss)
...     if accelerator.sync_gradients:
...         accelerator.clip_grad_norm_(model.parameters(), max_grad_norm)
...     optimizer.step()

clip_grad_value_

< >

( parametersclip_value )

Должен использоваться вместо torch.nn.utils.clip_grad_value_.

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator(gradient_accumulation_steps=2)
>>> dataloader, model, optimizer, scheduler = accelerator.prepare(dataloader, model, optimizer, scheduler)

>>> for input, target in dataloader:
...     optimizer.zero_grad()
...     output = model(input)
...     loss = loss_func(output, target)
...     accelerator.backward(loss)
...     if accelerator.sync_gradients:
...         accelerator.clip_grad_value_(model.parameters(), clip_value)
...     optimizer.step()

deepspeed_ulysses_dl_adapter

< >

( dlmodel )

обычно это вызывается как часть prepare, но когда dataloader был подготовлен отдельно от модели (для внешнего вызова accelerator.prepare), этот дополнительный вызов необходимо выполнить после prepare(model) (см. HF Trainer в качестве примера использования)

end_training

< >

( )

Выполняет специальные действия в конце обучения, например, остановку трекеров только в основном процессе или уничтожение группы процессов. Всегда следует вызывать в конце вашего скрипта при использовании отслеживания экспериментов.

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator(log_with="tensorboard")
>>> accelerator.init_trackers("my_project")
>>> # Do training
>>> accelerator.end_training()

free_memory

< >

( *objects )

Отпустит все ссылки на внутренние объекты и вызовет сборщик мусора. Этот метод следует вызывать между двумя тренировками с разными моделями/оптимизаторами. Также сбросит Accelerator.step до 0.

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> model, optimizer, scheduler = ...
>>> model, optimizer, scheduler = accelerator.prepare(model, optimizer, scheduler)
>>> model, optimizer, scheduler = accelerator.free_memory(model, optimizer, scheduler)

gather

< >

( tensor ) → torch.Tensor, or a nested tuple/list/dictionary of torch.Tensor

Параметры

  • tensor (torch.Tensor или вложенный кортеж/список/словарь из torch.Tensor) — Тензоры, которые нужно собрать со всех процессов.

Возвращает

torch.Tensor или вложенный кортеж/список/словарь из torch.Tensor

Собранный тензор (тензоры). Обратите внимание, что первое измерение результата равно num_processes, умноженному на первое измерение входных тензоров.

Собирает значения из tensor со всех процессов и конкатенирует их по первому измерению. Полезно для группировки предсказаний со всех процессов при выполнении оценки.

Примечание: Эта операция сбора выполняется во всех процессах.

Пример:

>>> # Assuming four processes
>>> import torch
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> process_tensor = torch.tensor([accelerator.process_index], device=accelerator.device)
>>> gathered_tensor = accelerator.gather(process_tensor)
>>> gathered_tensor
tensor([0, 1, 2, 3])

gather_for_metrics

< >

( input_datause_gather_object = False )

Параметры

  • input_data (torch.Tensor, object, вложенный кортеж/список/словарь из torch.Tensor или вложенный кортеж/список/словарь из object) — Тензоры или объекты для вычисления метрик во всех процессах
  • use_gather_object(bool) — Следует ли принудительно использовать gather_object вместо gather (что уже выполняется, если все переданные объекты не содержат тензоров). Этот флаг может быть полезен для сбора тензоров разного размера, которые мы не хотим дополнять нулями и конкатенировать по первому измерению. Использование с тензорами на GPU поддерживается плохо и неэффективно, так как требует передачи GPU -> CPU, поскольку тензоры будут сериализованы.

Собирает input_data и при необходимости удаляет дубликаты в последней партии, если система распределённая. Следует использовать для сбора входных данных и целевых значений для вычисления метрик.

Пример:

>>> # Assuming two processes, with a batch size of 5 on a dataset with 9 samples
>>> import torch
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> dataloader = torch.utils.data.DataLoader(range(9), batch_size=5)
>>> dataloader = accelerator.prepare(dataloader)
>>> batch = next(iter(dataloader))
>>> gathered_items = accelerator.gather_for_metrics(batch)
>>> len(gathered_items)
9

get_state_dict

< >

( modelunwrap = True ) → dict

Параметры

  • model (torch.nn.Module) — Модель PyTorch, переданная через Accelerator.prepare()
  • unwrap (bool, необязательный, по умолчанию True) — Определяет, следует ли вернуть исходный базовый state_dict объекта model или вернуть обёрнутый state_dict

Возвращает

dict

Словарь состояний модели, потенциально без полной точности.

Возвращает словарь состояния модели, переданной через Accelerator.prepare(), возможно, без полного разрешения.

Пример:

>>> import torch
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> net = torch.nn.Linear(2, 2)
>>> net = accelerator.prepare(net)
>>> state_dict = accelerator.get_state_dict(net)

get_tracker

< >

( name: strunwrap: bool = False ) → GeneralTracker

Параметры

  • name (str) — Имя трекера, соответствующее свойству .name.
  • unwrap (bool) — Определяет, следует ли возвращать внутренний механизм отслеживания или обёрнутый трекер (рекомендуется).

Возвращает

GeneralTracker

Трекер, соответствующий name, если он существует.

Возвращает tracker из self.trackers на основе name только в основном процессе.

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator(log_with="tensorboard")
>>> accelerator.init_trackers("my_project")
>>> tensorboard_tracker = accelerator.get_tracker("tensorboard")

join_uneven_inputs

< >

( joinableseven_batches = None )

Параметры

  • joinables (list[torch.distributed.algorithms.Joinable]) — Список моделей или оптимизаторов, являющихся подклассами torch.distributed.algorithms.Joinable. Как правило, это PyTorch Module, подготовленный с помощью Accelerator.prepare для обучения в режиме DistributedDataParallel.
  • even_batches (bool, необязательный) — Если задано, это значение переопределяет параметр even_batches, установленный в Accelerator. Если не указано, будет использовано значение по умолчанию Accelerator.

Контекстный менеджер, облегчающий распределённое обучение или оценку на неравномерных входных данных, который выступает в роли обёртки вокруг torch.distributed.algorithms.join. Это полезно, когда общий размер батча не делится нацело на длину набора данных.

join_uneven_inputs поддерживается только для обучения с распределённым параллелизмом данных (Distributed Data Parallel) на нескольких GPU. При любой другой конфигурации этот метод не будет иметь эффекта.

Переопределение even_batches не повлияет на загрузчики данных итеративного типа.

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator(even_batches=True)
>>> ddp_model, optimizer, dataloader = accelerator.prepare(model, optimizer, dataloader)

>>> with accelerator.join_uneven_inputs([ddp_model], even_batches=False):
...     for input, output in dataloader:
...         outputs = model(input)
...         loss = loss_func(outputs)
...         loss.backward()
...         optimizer.step()
...         optimizer.zero_grad()

load_state

< >

( input_dir: str | None = Noneload_kwargs: dict | None = None**load_model_func_kwargs )

Параметры

  • input_dir (str или os.PathLike) — Имя папки, в которой были сохранены все соответствующие веса и состояния. Может быть None, если используется automatic_checkpoint_naming, в этом случае будут загружены данные из последней контрольной точки.
  • load_kwargs (dict, необязательный) — Дополнительные именованные аргументы для внутренней функции load, например, необязательные аргументы для state_dict и optimizer.
  • load_model_func_kwargs (dict, необязательный) — Дополнительные именованные аргументы для загрузки модели, которые могут быть переданы в базовую функцию загрузки, например, необязательные аргументы для функции load_checkpoint DeepSpeed или map_location для загрузки модели и оптимизатора.

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

Должно использоваться только в связке с Accelerator.save_state(). Если файл не зарегистрирован для создания контрольных точек, он не будет загружен, даже если хранится в каталоге.

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> model, optimizer, lr_scheduler = ...
>>> model, optimizer, lr_scheduler = accelerator.prepare(model, optimizer, lr_scheduler)
>>> accelerator.load_state("my_checkpoint")

local_main_process_first

< >

( )

Позволяет локальному основному процессу войти в блок with.

Остальные процессы войдут в блок with после завершения основного процесса.

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> with accelerator.local_main_process_first():
...     # This will be printed first by local process 0 then in a seemingly
...     # random order by the other processes.
...     print(f"This will be printed by process {accelerator.local_process_index}")

lomo_backward

< >

( loss: torch.Tensorlearning_rate: float )

Выполняет обратный проход для оптимизаторов LOMO.

main_process_first

< >

( )

Позволяет основному процессу выполняться первым внутри блока with.

Остальные процессы войдут в блок with после завершения основного процесса.

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> with accelerator.main_process_first():
...     # This will be printed first by process 0 then in a seemingly
...     # random order by the other processes.
...     print(f"This will be printed by process {accelerator.process_index}")

maybe_context_parallel

< >

( buffers: list[torch.Tensor] | None = Nonebuffer_seq_dims: list[int] | None = Noneno_restore_buffers: set[torch.Tensor] | None = None )

Параметры

  • buffers (list[torch.Tensor], optional) — Буферы, которые будут разбиты на части вдоль измерения последовательности. Типичные примеры — входные данные, метки или буферы позиционных эмбеддингов. Этот контекстный менеджер будет изменять эти буферы на месте, а после выхода из контекста буферы будут восстановлены в исходное состояние. Чтобы избежать ненужных восстановлений, можно использовать no_restore_buffers, чтобы указать, какие буферы не нужно восстанавливать.
  • buffer_seq_dims (list[int], optional) — Размерности последовательности для buffers.
  • no_restore_buffers (set[torch.Tensor], optional) — Этот набор должен быть подмножеством buffers. Указывает, какие буферы из аргумента buffers не будут восстановлены после выхода из контекста. Эти буферы будут оставаться в шардированном состоянии.

Контекстный менеджер, обеспечивающий обучение с параллелизмом контекста.

context_parallel в настоящее время поддерживается с FSDP2 и требует parallelism_config.cp_size >

  1. Если ни одно из этих условий не выполняется, этот менеджер контекста не будет иметь эффекта, однако, чтобы минимизировать изменения в коде, он не будет вызывать исключение.

Этот контекстный менеджер необходимо создавать заново на каждом шаге обучения, как показано в примере ниже.

Пример:

>>> for batch in dataloader:
...     with accelerator.maybe_context_parallel(
...         buffers=[batch["input_ids"], batch["attention_mask"]],
...         buffer_seq_dims=[1, 1],
...         no_restore_buffers={batch["input_ids"]},
...     ):
...         outputs = model(batch)
...         ...

no_sync

< >

( model )

Параметры

  • model (torch.nn.Module) — модуль PyTorch, подготовленный с помощью Accelerator.prepare

Контекстный менеджер для отключения синхронизации градиентов между процессами DDP с помощью вызова torch.nn.parallel.DistributedDataParallel.no_sync.

Если model не находится в DDP, этот контекстный менеджер ничего не делает

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> dataloader, model, optimizer = accelerator.prepare(dataloader, model, optimizer)
>>> input_a = next(iter(dataloader))
>>> input_b = next(iter(dataloader))

>>> with accelerator.no_sync():
...     outputs = model(input_a)
...     loss = loss_func(outputs)
...     accelerator.backward(loss)
...     # No synchronization across processes, only accumulate gradients
>>> outputs = model(input_b)
>>> accelerator.backward(loss)
>>> # Synchronization across all processes
>>> optimizer.step()
>>> optimizer.zero_grad()

on_last_process

< >

( function: Callable[..., Any] )

Параметры

  • function (Callable) — Функция для декорирования.

Декоратор, который выполняет декорируемую функцию только на последнем процессе. Также может быть вызван с использованием класса PartialState.

Пример:

# Assume we have 4 processes.
from accelerate import Accelerator

accelerator = Accelerator()


@accelerator.on_last_process
def print_something():
    print(f"Printed on process {accelerator.process_index}")


print_something()
"Printed on process 3"

on_local_main_process

< >

( function: Callable[..., Any] | None = None )

Параметры

  • function (Callable) — Функция для декорирования.

Декоратор, который выполняет декорируемую функцию только в локальном главном процессе. Также может вызываться с помощью класса PartialState.

Пример:

# Assume we have 2 servers with 4 processes each.
from accelerate import Accelerator

accelerator = Accelerator()


@accelerator.on_local_main_process
def print_something():
    print("This will be printed by process 0 only on each server.")


print_something()
# On server 1:
"This will be printed by process 0 only"
# On server 2:
"This will be printed by process 0 only"

on_local_process

< >

( function: Callable[..., Any] | None = Nonelocal_process_index: int | None = None )

Параметры

  • function (Callable, необязательный) — Функция для декорирования.
  • local_process_index (int, необязательный) — Индекс локального процесса, на котором следует выполнить функцию.

Декоратор, который выполняет декорируемую функцию только на указанном локальном индексе процесса. Также может вызываться с помощью класса PartialState.

Пример:

# Assume we have 2 servers with 4 processes each.
from accelerate import Accelerator

accelerator = Accelerator()


@accelerator.on_local_process(local_process_index=2)
def print_something():
    print(f"Printed on process {accelerator.local_process_index}")


print_something()
# On server 1:
"Printed on process 2"
# On server 2:
"Printed on process 2"

on_main_process

< >

( function: Callable[..., Any] | None = None )

Параметры

  • function (Callable) — Функция для декорирования.

Декоратор, который выполняет декорируемую функцию только в основном процессе. Также может вызываться с помощью класса PartialState.

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()


>>> @accelerator.on_main_process
... def print_something():
...     print("This will be printed by process 0 only.")


>>> print_something()
"This will be printed by process 0 only"

on_process

< >

( function: Callable[..., Any] | None = Noneprocess_index: int | None = None )

Параметры

  • function (Callable, optional) — Функция, которую нужно декорировать.
  • process_index (int, optional) — Индекс процесса, на котором следует выполнить функцию.

Декоратор, который выполняет декорируемую функцию только на процессе с указанным индексом. Также может вызываться с помощью класса PartialState.

Пример:

# Assume we have 4 processes.
from accelerate import Accelerator

accelerator = Accelerator()


@accelerator.on_process(process_index=2)
def print_something():
    print(f"Printed on process {accelerator.process_index}")


print_something()
"Printed on process 2"

pad_across_processes

< >

( tensordim = 0pad_index = 0pad_first = False ) → torch.Tensor, or a nested tuple/list/dictionary of torch.Tensor

Параметры

  • tensor (вложенный список/кортеж/словарь из torch.Tensor) — Данные для сбора.
  • dim (int, необязательный, по умолчанию 0) — Размерность, по которой выполняется дополнение.
  • pad_index (int, необязательный, по умолчанию 0) — Значение, используемое для дополнения.
  • pad_first (bool, необязательный, по умолчанию False) — Определяет, добавлять ли заполнители в начале или в конце.

Возвращает

torch.Tensor или вложенный кортеж/список/словарь из torch.Tensor

Тензор(ы) с дополнением (padding).

Рекурсивно дополните тензоры в вложенном списке/кортеже/словаре тензоров со всех устройств до одинакового размера, чтобы их можно было безопасно собрать.

Пример:

>>> # Assuming two processes, with the first processes having a tensor of size 1 and the second of size 2
>>> import torch
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> process_tensor = torch.arange(accelerator.process_index + 1).to(accelerator.device)
>>> padded_tensor = accelerator.pad_across_processes(process_tensor)
>>> padded_tensor.shape
torch.Size([2])

prepare

< >

( *argsdevice_placement = None )

Параметры

  • *args (список объектов) — Любой из следующих типов объектов:
    • torch.utils.data.DataLoader: загрузчик данных PyTorch
    • torch.nn.Module: модуль PyTorch
    • torch.optim.Optimizer: Оптимизатор PyTorch
    • torch.optim.lr_scheduler.LRScheduler: планировщик LR в PyTorch
  • device_placement (list[bool], необязательный) — Используется для настройки того, следует ли выполнять автоматическое размещение на устройстве для каждого переданного объекта. Должен представлять собой список той же длины, что и args. Не совместим с DeepSpeed или FSDP.

Подготовьте все объекты, переданные в args, для распределённого обучения и смешанной точности, затем верните их в том же порядке.

Вам не нужно готовить модель, если вы используете её только для инференса без какого-либо смешанного точности

Примеры:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> # Assume a model, optimizer, data_loader and scheduler are defined
>>> model, optimizer, data_loader, scheduler = accelerator.prepare(model, optimizer, data_loader, scheduler)
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> # Assume a model, optimizer, data_loader and scheduler are defined
>>> device_placement = [True, True, False, False]
>>> # Will place the first two items passed in automatically to the right device but not the last two.
>>> model, optimizer, data_loader, scheduler = accelerator.prepare(
...     model, optimizer, data_loader, scheduler, device_placement=device_placement
... )

prepare_data_loader

< >

( data_loader: torch.utils.data.DataLoaderdevice_placement = Noneslice_fn_for_dispatch = None )

Параметры

  • data_loader (torch.utils.data.DataLoader) — обычный PyTorch DataLoader для подготовки
  • device_placement (bool, необязательный) — Определяет, следует ли размещать батчи на соответствующем устройстве в подготовленном загрузчике данных. По умолчанию используется значение self.device_placement.
  • slice_fn_for_dispatch (Callable, optional) -- If passed, this function will be used to slice tensors across num_processes. Will default to [slice_tensors()](/docs/accelerate/v1.16.0/en/package_reference/utilities#accelerate.utils.slice_tensors). This argument is used only when dispatch_batchesis set toTrue` and will be ignored otherwise.

Готовит PyTorch DataLoader для обучения в любом распределённом окружении. Рекомендуется использовать Accelerator.prepare().

Пример:

>>> import torch
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> data_loader = torch.utils.data.DataLoader(...)
>>> data_loader = accelerator.prepare_data_loader(data_loader, device_placement=True)

prepare_model

< >

( model: torch.nn.Moduledevice_placement: bool | None = Noneevaluation_mode: bool = False )

Параметры

  • model (torch.nn.Module) — Модель PyTorch, которую нужно подготовить. Подготавливать модель не нужно, если она используется только для инференса без какого-либо смешанного точности
  • device_placement (bool, необязательный) — Определяет, следует ли размещать модель на соответствующем устройстве. По умолчанию используется значение self.device_placement.
  • evaluation_mode (bool, необязательный, по умолчанию False) — Определяет, следует ли переводить модель только в режим оценки, применяя смешанную точность и torch.compile (если это настроено в объекте Accelerator).

Готовит модель PyTorch для обучения в любом распределённом окружении. Рекомендуется использовать Accelerator.prepare() вместо этого.

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> # Assume a model is defined
>>> model = accelerator.prepare_model(model)

prepare_optimizer

< >

( optimizer: torch.optim.Optimizerdevice_placement = None )

Параметры

  • optimizer (torch.optim.Optimizer) — обычный оптимизатор PyTorch для подготовки
  • device_placement (bool, необязательный) — Определяет, следует ли размещать оптимизатор на соответствующем устройстве. По умолчанию используется значение self.device_placement.

Подготавливает оптимизатор PyTorch для обучения в любом распределённом окружении. Рекомендуется использовать Accelerator.prepare().

Пример:

>>> import torch
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> optimizer = torch.optim.Adam(...)
>>> optimizer = accelerator.prepare_optimizer(optimizer, device_placement=True)

prepare_scheduler

< >

( scheduler: LRScheduler )

Параметры

  • scheduler (torch.optim.lr_scheduler.LRScheduler) — стандартный планировщик PyTorch для подготовки

Готовит планировщик PyTorch для обучения в любом распределённом окружении. Рекомендуется использовать Accelerator.prepare().

Пример:

>>> import torch
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> optimizer = torch.optim.Adam(...)
>>> scheduler = torch.optim.lr_scheduler.LambdaLR(optimizer, ...)
>>> scheduler = accelerator.prepare_scheduler(scheduler)

print

< >

( *args**kwargs )

Замена print(), чтобы печатать только один раз на сервер.

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> accelerator.print("Hello world!")

профиль

< >

( profile_handler: ProfileKwargs | None = None )

Параметры

  • profile_handler (ProfileKwargs, необязательный) — Обработчик профиля, используемый для этого контекстного менеджера. Если не передан, будет использован тот, что задан в объекте Accelerator.

Профилирует код внутри контекстного менеджера. Профиль сохраняется в файл Chrome Trace, если задан profile_handler.output_trace_dir.

Можно передать другой profile_handler, чтобы переопределить тот, что установлен в объекте Accelerator.

Пример:

# Profile with default settings
from accelerate import Accelerator
from accelerate.utils import ProfileKwargs

accelerator = Accelerator()
with accelerator.profile() as prof:
    train()
accelerator.print(prof.key_averages().table())


# Profile with the custom handler
def custom_handler(prof):
    print(prof.key_averages().table(sort_by="self_cpu_time_total", row_limit=10))


kwargs = ProfileKwargs(schedule_option=dict(wait=1, warmup=1, active=1), on_trace_ready=custom_handler)
accelerator = Accelerator(kwarg_handler=[kwargs])
with accelerator.profile() as prof:
    for _ in range(10):
        train_iteration()
        prof.step()


# Profile and export to Chrome Trace
kwargs = ProfileKwargs(output_trace_dir="output_trace")
accelerator = Accelerator(kwarg_handler=[kwargs])
with accelerator.profile():
    train()

reduce

< >

( tensorreduction = 'sum'scale = 1.0 ) → torch.Tensor, or a nested tuple/list/dictionary of torch.Tensor

Параметры

  • tensor (torch.Tensor или вложенный кортеж/список/словарь из torch.Tensor) — Тензоры, которые нужно свести по всем процессам.
  • reduction (str, необязательный, по умолчанию “sum”) — Тип агрегации, может быть одним из ‘sum’, ‘mean’, ‘max’ или ‘none’. Если указано ‘none’, никакие операции не выполняются.
  • scale (float, необязательный, по умолчанию 1.0) — Значение масштабирования по умолчанию, применяемое после reduce; действует только на XLA.

Возвращает

torch.Tensor или вложенный кортеж/список/словарь из torch.Tensor

Сокращенный тензор(ы).

Суммируйте значения в tensor по всем процессам на основе reduction.

Примечание: Все процессы получают уменьшенное значение.

Пример:

>>> # Assuming two processes
>>> import torch
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> process_tensor = torch.arange(accelerator.num_processes) + 1 + (2 * accelerator.process_index)
>>> process_tensor = process_tensor.to(accelerator.device)
>>> reduced_tensor = accelerator.reduce(process_tensor, reduction="sum")
>>> reduced_tensor
tensor([4, 6])

register_for_checkpointing

< >

( *objects )

Делает запись об объектах objects и сохраняет или загружает их во время вызова save_state или load_state.

Их следует использовать при загрузке или сохранении состояния в том же скрипте. Они не предназначены для использования в разных скриптах.

Каждый object должен иметь функции load_state_dict и state_dict для сохранения.

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> # Assume `CustomObject` has a `state_dict` and `load_state_dict` function.
>>> obj = CustomObject()
>>> accelerator.register_for_checkpointing(obj)
>>> accelerator.save_state("checkpoint.pt")

register_load_state_pre_hook

< >

( hook: Callable[..., None] ) → torch.utils.hooks.RemovableHandle

Параметры

Возвращает

torch.utils.hooks.RemovableHandle

обработчик, с помощью которого можно удалить добавленный хук, вызвав handle.remove()

Регистрирует предварительный хук, который выполняется перед вызовом load_checkpoint в Accelerator.load_state().

Хук должен иметь следующую сигнатуру:

hook(models: list[torch.nn.Module], input_dir: str) -> None

Аргумент models — это модели, сохранённые в состоянии акселератора под ключом accelerator._models, а аргумент input_dir — это аргумент input_dir, переданный в Accelerator.load_state().

Должно использоваться только в связке с Accelerator.register_save_state_pre_hook(). Может быть полезно для загрузки конфигураций в дополнение к весам модели. Также можно использовать для переопределения загрузки модели с помощью кастомизированного метода. В этом случае убедитесь, что удалили уже загруженные модели из списка моделей.

register_save_state_pre_hook

< >

( hook: Callable[..., None] ) → torch.utils.hooks.RemovableHandle

Параметры

Возвращает

torch.utils.hooks.RemovableHandle

обработчик, с помощью которого можно удалить добавленный хук, вызвав handle.remove()

Регистрирует предварительный хук, который выполняется перед вызовом save_checkpoint в Accelerator.save_state().

Хук должен иметь следующую сигнатуру:

hook(models: list[torch.nn.Module], weights: list[dict[str, torch.Tensor]], input_dir: str) -> None

Аргумент models — это модели, сохранённые в состоянии акселератора под ключом accelerator._models, аргумент weights — это словари состояний для models, а аргумент input_dir — это аргумент input_dir, переданный в Accelerator.load_state().

Должен использоваться только в связке с Accelerator.register_load_state_pre_hook(). Может быть полезен для сохранения конфигураций в дополнение к весам модели. Также можно использовать для переопределения сохранения модели с помощью кастомного метода. В этом случае убедитесь, что удалили уже загруженные веса из списка весов.

сохранить

< >

( objfsafe_serialization = False )

Параметры

  • obj (object) — Объект для сохранения.
  • f (str или os.PathLike) — место для сохранения содержимого obj.
  • safe_serialization (bool, необязательный, по умолчанию False) — сохранять ли obj с использованием safetensors

Сохраняйте объект, переданный на диск, один раз на машину. Используйте вместо torch.save.

Примечание: Если save_on_each_node был передан в качестве ProjectConfiguration, объект будет сохраняться один раз на каждом узле, а не только один раз на основном узле.

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> arr = [0, 1, 2, 3]
>>> accelerator.save(arr, "array.pkl")

save_model

< >

( model: torch.nn.Modulesave_directory: Union[str, os.PathLike]max_shard_size: Union[int, str] = '10GB'safe_serialization: bool = True )

Параметры

  • model — (torch.nn.Module): Модель, которую нужно сохранить. Модель может быть обёрнута или не обёрнута.
  • save_directory (str или os.PathLike) — Каталог для сохранения. Будет создан, если не существует.
  • max_shard_size (int или str, необязательный, по умолчанию "10GB") — Максимальный размер чекпоинта перед его разбиением на части. Каждая часть чекпоинта будет иметь размер, меньший этого значения. Если значение указано в виде строки, оно должно состоять из цифр и единицы измерения (например, "5MB").

    Если вес модели превышает max_shard_size, он будет размещен в отдельном фрагменте контрольной точки, размер которого превысит max_shard_size.

  • safe_serialization (bool, необязательный, по умолчанию True) — Определяет, сохранять ли модель с помощью safetensors или традиционным способом PyTorch (с использованием pickle).

Сохраните модель так, чтобы её можно было загрузить с помощью load_checkpoint_in_model

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> model = ...
>>> accelerator.save_model(model, save_directory)

save_state

< >

( output_dir: str | None = Nonesafe_serialization: bool = True**save_model_func_kwargs )

Параметры

  • output_dir (str или os.PathLike) — Имя папки, в которой будут сохранены все соответствующие веса и состояния.
  • safe_serialization (bool, необязательный, по умолчанию True) — Определяет, сохранять ли модель с помощью safetensors или традиционным способом PyTorch (с использованием pickle).
  • save_model_func_kwargs (dict, необязательный) — Дополнительные именованные аргументы для сохранения модели, которые могут быть переданы в базовую функцию сохранения, например необязательные аргументы для функции save_checkpoint DeepSpeed.

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

Если объект Accelerator был передан с ProjectConfiguration, в котором включён automatic_checkpoint_naming, то контрольные точки сохраняются в self.project_dir/checkpoints. Если количество текущих сохранений превышает total_limit, самое старое сохранение удаляется. Каждая контрольная точка сохраняется в отдельной папке с именем checkpoint_<iteration>.

В противном случае они просто сохраняются в output_dir.

Должно использоваться только в том случае, если требуется сохранить контрольную точку во время обучения и восстановить состояние в той же среде.

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> model, optimizer, lr_scheduler = ...
>>> model, optimizer, lr_scheduler = accelerator.prepare(model, optimizer, lr_scheduler)
>>> accelerator.save_state(output_dir="my_checkpoint")

set_trigger

< >

( )

Устанавливает внутреннее тензорное значение триггера в 1 на текущем процессе. За этим должно последовать проверка с использованием этого значения, которая будет выполнена на всех процессах.

Примечание: Не требует wait_for_everyone()

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> # Assume later in the training script
>>> # `should_do_breakpoint` is a custom function to monitor when to break,
>>> # e.g. when the loss is NaN
>>> if should_do_breakpoint(loss):
...     accelerator.set_trigger()
>>> # Assume later in the training script
>>> if accelerator.check_breakpoint():
...     break

skip_first_batches

< >

( dataloadernum_batches: int = 0 )

Параметры

  • dataloader (torch.utils.data.DataLoader) — загрузчик данных, в котором нужно пропускать батчи.
  • num_batches (int, необязательный, по умолчанию 0) — количество пакетов, которые нужно пропустить

Создаёт новый torch.utils.data.DataLoader, который эффективно пропускает первые num_batches.

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> dataloader, model, optimizer, scheduler = accelerator.prepare(dataloader, model, optimizer, scheduler)
>>> skipped_dataloader = accelerator.skip_first_batches(dataloader, num_batches=2)
>>> # for the first epoch only
>>> for input, target in skipped_dataloader:
...     optimizer.zero_grad()
...     output = model(input)
...     loss = loss_func(output, target)
...     accelerator.backward(loss)
...     optimizer.step()

>>> # subsequent epochs
>>> for input, target in dataloader:
...     optimizer.zero_grad()
...     ...

split_between_processes

< >

( inputs: list | tuple | dict | torch.Tensorapply_padding: bool = False )

Параметры

  • inputs (list, tuple, torch.Tensor или dict из list/tuple/torch.Tensor) — Входные данные для распределения между процессами.
  • apply_padding (bool, optional, по умолчанию False) — Следует ли применять выравнивание путём повторения последнего элемента входных данных, чтобы все процессы имели одинаковое количество элементов. Полезно при выполнении таких действий, как Accelerator.gather() над результатами или при передаче меньшего количества входных данных, чем количество процессов. Если это необходимо, не забудьте удалить дополненные элементы после завершения операции.

Разбивает input между self.num_processes быстро, после чего может использоваться на соответствующем процессе. Полезно при распределённом выводе, например, с разными промптами.

Обратите внимание, что при использовании dict все ключи должны содержать одинаковое количество элементов.

Пример:

# Assume there are two processes
from accelerate import Accelerator

accelerator = Accelerator()
with accelerator.split_between_processes(["A", "B", "C"]) as inputs:
    print(inputs)
# Process 0
["A", "B"]
# Process 1
["C"]

with accelerator.split_between_processes(["A", "B", "C"], apply_padding=True) as inputs:
    print(inputs)
# Process 0
["A", "B"]
# Process 1
["C", "C"]

trigger_sync_in_backward

< >

( model )

Параметры

  • model (torch.nn.Module) — Модель, для которой необходимо инициировать синхронизацию градиентов.

Запустите синхронизацию градиентов в следующем обратном проходе модели после нескольких прямых проходов в режиме Accelerator.no_sync (применимо только в сценариях с несколькими GPU).

Если скрипт не запущен в распределённом режиме, этот менеджер контекста ничего не делает.

Пример:

>>> from accelerate import Accelerator

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

>>> with accelerator.no_sync():
...     loss_a = loss_func(model(input_a))  # first forward pass
...     loss_b = loss_func(model(input_b))  # second forward pass
>>> accelerator.backward(loss_a)  # No synchronization across processes, only accumulate gradients
>>> with accelerator.trigger_sync_in_backward(model):
...     accelerator.backward(loss_b)  # Synchronization across all processes
>>> optimizer.step()
>>> optimizer.zero_grad()

unscale_gradients

< >

( optimizer = None )

Параметры

  • optimizer (torch.optim.Optimizer или list[torch.optim.Optimizer], необязательный) — Оптимизатор(ы), для которых необходимо снять масштабирование градиентов. Если не задан, снимет масштабирование градиентов для всех оптимизаторов, переданных в prepare().

Убирает масштабирование градиентов при обучении с смешанной точностью с AMP. Во всех остальных режимах это операция без эффекта.

Скорее всего, следует вызывать через Accelerator.clipgrad_norm() или Accelerator.clipgrad_value()

Пример:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> model, optimizer = accelerator.prepare(model, optimizer)
>>> outputs = model(inputs)
>>> loss = loss_fn(outputs, labels)
>>> accelerator.backward(loss)
>>> accelerator.unscale_gradients(optimizer=optimizer)

unwrap_model

< >

( modelkeep_fp32_wrapper: bool = Truekeep_torch_compile: bool = True ) → torch.nn.Module

Параметры

  • model (torch.nn.Module) — Модель, которую нужно развернуть.
  • keep_fp32_wrapper (bool, необязательный, по умолчанию True) — Определяет, следует ли не удалять хук смешанной точности, если он был добавлен.
  • keep_torch_compile (bool, необязательный, по умолчанию True) — Определяет, следует ли не разворачивать скомпилированную модель, если она была скомпилирована.

Возвращает

torch.nn.Module

Развернутая модель.

Убирает model из дополнительного слоя, который мог быть добавлен методом prepare(). Полезно перед сохранением модели.

Пример:

>>> # Assuming two GPU processes
>>> from torch.nn.parallel import DistributedDataParallel
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> model = accelerator.prepare(MyModel())
>>> print(model.__class__.__name__)
DistributedDataParallel

>>> model = accelerator.unwrap_model(model)
>>> print(model.__class__.__name__)
MyModel

verify_device_map

< >

( model: torch.nn.Module )

Проверяет, что model не была подготовлена для инференса больших моделей с device-map, похожим на auto.

wait_for_everyone

< >

( )

Останавливает выполнение текущего процесса, пока все остальные процессы не достигнут этой точки (поэтому при запуске скрипта в одном процессе этот метод ничего не делает). Полезно вызывать перед сохранением модели.

Пример:

>>> # Assuming two GPU processes
>>> import time
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> if accelerator.is_main_process:
...     time.sleep(2)
>>> else:
...     print("I'm waiting for the main process to finish its sleep...")
>>> accelerator.wait_for_everyone()
>>> # Should print on every process at the same time
>>> print("Everyone is here")

Утилиты

accelerate.utils.gather_object

< >

( object: Any )

Параметры

  • object (вложенный список/кортеж/словарь с объектами, поддерживающими сериализацию) — Данные, которые нужно собрать.

Рекурсивно собирает объект из вложенного списка/кортежа/словаря объектов со всех устройств.

Update on GitHub