Hugging Face's logo

Accelerate documentation

Accelerator

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

and get access to the augmented documentation experience

to get started

Accelerator

Acceleratorは、あらゆるタイプの学習設定で分散学習を有効にするためのメインクラスです。Acceleratorをコードに追加するチュートリアルを読み、スクリプトにAcceleratorを追加する方法を詳しく学んでください。

Accelerator

クラス accelerate.Accelerator

< >

( device_placement: bool = Truesplit_batches: bool = <object object at 0x7fe7459895c0>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) — アクセラレーターがオブジェクトをデバイスに配置するかどうか（dataloader が生成するテンソル、モデルなど）。
  • 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 を無視し、1 プロセスでのみ実行を強制します。
  • dataloader_config (DataLoaderConfiguration, 任意) — 分散シナリオにおいてdataloaderをどのように処理するかを設定するための設定です。
  • 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、任意）— 非推奨: tp_size を指定して parallelism_config を使用してください。
  • megatron_lm_plugin (MegatronLMPlugin、任意) — この引数を使用して、MegatronLM 関連の引数を調整できます。この引数は任意であり、accelerate config を直接使用して設定することもできます。
  • rng_types (のリスト str または RNGType) — 準備済みのデータローダーの各イテレーションの開始時に同期する乱数生成器のリストです。以下の1つまたは複数に設定してください:
    • "torch": 基本的な torch ランダム数生成器
    • "cuda": CUDA乱数生成器（GPUのみ）
    • "xla": XLA乱数生成器（TPUのみ）
    • "generator": 基盤となるデータセットがそのタイプの場合、サンプラー（dataloader にサンプラーがない場合はバッチサンプラー）またはイテラブルデータセット（存在する場合）の torch.Generator。

    PyTorch バージョン 1.5.1 以下では ["torch"]、1.6 以上では ["generator"] がデフォルトになります。

  • 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") — torch dynamo を用いてトレーニングを最適化するために、利用可能な dynamo バックエンドのいずれかに設定します。
  • dynamo_plugin (TorchDynamoPlugin、任意) — backend や mode だけでは不十分な場合、torch dynamo の処理方法を設定するための構成です。
  • gradient_accumulation_plugin (GradientAccumulationPlugin、任意) — gradient_accumulation_steps だけでは不十分な場合、勾配の蓄積をどのように処理するかを設定するための構成です。

分散学習または混合精度学習用のacceleratorのインスタンスを作成します。

利用可能な属性:

  • 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 のリスト) — Accelerator.prepare で準備された PyTorch モジュールです。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

clear

< >

( *objects )

Accelerate.free_memory の別名です。内部オブジェクトへのすべての参照を解放し、ガベージコレクタを呼び出します。異なるモデル/オプティマイザーで2回のトレーニングを行う間には、このメソッドを呼び出す必要があります。

例:

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

内部オブジェクトに保存されているすべての参照を解放し、ガベージコレクターを呼び出します。異なるモデル/オプティマイザーで2回のトレーニングを行う間には、このメソッドを呼び出す必要があります。また、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の値をすべてのプロセスにわたって集約し、最初の次元で連結します。評価時にすべてのプロセスからの予測を再グループ化する場合に便利です。

Note: このgatherはすべてのプロセスで実行されます。

例:

>>> # 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（すべてのオブジェクトにテンソルが含まれない場合は既に実行されています）の代わりに、gather_objectを強制使用するかどうか。このフラグは、パディングと最初の次元に沿った連結を避けたい、サイズが異なるテンソルを集約する場合に有用です。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) — Accelerator.prepare() を通して渡された PyTorch モデル
  • unwrap (bool、省略可能、デフォルトはTrue) — modelの元の基底のstate_dictを返すか、ラップされた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に対応するトラッカー。

メインプロセスでのみ、name に基づいて self.trackers から tracker を返します。

例:

>>> 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 をサブクラスとするモデルまたはオプティマイザーのリストです。最も一般的なケースは、DistributedDataParallel 学習用に Accelerator.prepare で準備された PyTorch Module です。
  • even_batches (bool、省略可) — 設定されている場合、Accelerator で設定された even_batches の値を上書きします。指定されない場合、Accelerator のデフォルト値が使用されます。

torch.distributed.algorithms.joinをラップして、不揃いな入力での分散学習または評価を容易にするコンテキストマネージャーです。これは、総バッチサイズがデータセットの長さを均等に割り切れない場合に有用です。

join_uneven_inputs は、複数 GPU での Distributed Data Parallel 学習のみサポートされています。その他の構成では、このメソッドは効果がありません。

even_batchesをオーバーライドしても、iterableスタイルのデータローダーには影響しません。

例:

>>> 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) — 関連するすべての重みと状態が保存されたフォルダの名前です。automatic_checkpoint_naming を使用している場合は None にでき、最新のチェックポイントから読み込まれます。
  • load_kwargs (dict, 任意) — load 関数に渡す追加のキーワード引数。state_dict や optimizer に関する任意の引数などが含まれます。
  • load_model_func_kwargs (dict, 省略可) — モデルの読み込みに使用される、基盤となる読み込み関数に渡すことのできる追加のキーワード引数です。例えば、DeepSpeed の load_checkpoint 関数のオプション引数や、モデルとオプティマイザを読み込むための map_location などです。

モデル、オプティマイザー、スケーラー、RNGジェネレーター、および登録済みオブジェクトの現在の状態を読み込みます。

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) — Accelerator.prepare で準備された PyTorch Module

torch.nn.parallel.DistributedDataParallel.no_sync を呼び出して、DDP プロセス間で勾配の同期を無効にするためのコンテキストマネージャーです。

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のネストされたタプル/リスト/辞書

パディングされたテンソル。

…

例:

>>> # 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 Dataloader
    • torch.nn.Module: PyTorchモジュール
    • torch.optim.Optimizer: PyTorchのオプティマイザ
    • torch.optim.lr_scheduler.LRScheduler: PyTorch LR スケジューラ
  • 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, 任意) — 準備済みのdataloaderでバッチを適切なデバイスに配置するかどうか。デフォルトでは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/main/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) — Accelerator オブジェクトで設定されている場合、混合精度と torch.compile を適用するだけで、モデルを評価用に設定するかどうか。

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 Optimizerを任意の分散環境での学習に準備します。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 Schedulerを準備します。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()のドロップイン代替として、サーバーごとに1回だけ出力します。

例:

>>> from accelerate import Accelerator

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

プロファイル

< >

( profile_handler: ProfileKwargs | None = None )

パラメータ

  • profile_handler (ProfileKwargs, 省略可) — このコンテキストマネージャーで使用するプロファイルハンドラーです。指定しない場合、Acceleratorオブジェクトに設定されたものが使用されます。

コンテキストマネージャー内のコードをプロファイルします。profile_handler.output_trace_dirが設定されている場合、プロファイルはChrome Traceファイルに保存されます。

Acceleratorオブジェクトに設定されたものを上書きするために、別のprofile_handlerを渡すことができます。

例:

# 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のネストされたタプル/リスト/辞書

縮小されたテンソル。

reductionに基づいて、tensorの値をすべてのプロセス間で集約します。

Note: すべてのプロセスが削減された値を取得します。

例:

>>> # 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 の状態内の accelerator._models に保存されているモデルであり、input_dir 引数は Accelerator.load_state() に渡される input_dir 引数です。

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 の状態内の accelerator._models に保存されているモデルであり、weights 引数は models の state dict、input_dir 引数は Accelerator.load_state() に渡される input_dir 引数です。

Accelerator.register_load_state_pre_hook() と併せて使用してください。モデルの重みに加えて設定を保存する場合に便利です。カスタマイズされたメソッドでモデルの保存を上書きする場合にも使用できます。この場合、すでに読み込まれた重みを重みのリストから削除することを忘れないでください。

save

< >

( objfsafe_serialization = False )

パラメータ

  • obj (object) — 保存するオブジェクト。
  • f (str または os.PathLike) — obj の内容を保存する場所。
  • safe_serialization (bool、任意、デフォルトはFalse) — safetensorsを使用してobjを保存するかどうか

torch.saveの代わりに、渡されたオブジェクトをマシンごとに1回ディスクに保存します。

Note: save_on_each_nodeがProjectConfigurationとして渡された場合、メインノードでのみ1回保存するのではなく、ノードごとに1回ずつオブジェクトを保存します。

例:

>>> 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, 任意) — モデルの保存に使用される、DeepSpeedのsave_checkpoint関数などのオプション引数を含む、基盤となる保存関数に渡す追加のキーワード引数。

モデル、オプティマイザー、スケーラー、RNGジェネレーター、および登録済みオブジェクトの現在の状態をフォルダーに保存します。

ProjectConfiguration が automatic_checkpoint_naming を有効にして Accelerator オブジェクトに渡された場合、チェックポイントは 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、またはlist/tuple/torch.Tensorのdict) — プロセス間で分割する入力です。
  • 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による混合精度学習では、勾配をアンスケールします。その他の設定では、この操作は何もしません(noop)です。

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が、autoに似たデバイスマップを持つ大規模モデル推論用に準備されていないことを確認します。

wait_for_everyone

< >

( )

現在のプロセスの実行を停止し、他のすべてのプロセスがその地点に到達するまで待機します（スクリプトが1つのプロセスのみで実行されている場合は、何もしません）。モデルを保存する前に実行するのに便利です。

例:

>>> # 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 (pickle可能なオブジェクトのネストされたリスト/タプル/辞書) — 集約するデータ。

…

Update on GitHub

←TPUでのトレーニング ステートフルクラス→