Hermes Agent Wiki 非公式・日本語wiki
この skill をそのまま使う: GitHub で原文を見る

英語原文・frontmatter 込みで、Hermes が読み込む実体そのままです（このページの本文は日本語版）。

Accelerate

目次

PyTorch の学習を、ほとんど書き換えずに複数の GPU で走らせます。

skill の情報
提供元 追加インストール — hermes skills install official/mlops/accelerate で導入します
パス optional-skills/mlops/accelerate
バージョン 1.0.1
作者 Orchestra Research
ライセンス MIT
依存関係 accelerate, torch, transformers
対応プラットフォーム linux, macos, windows
タグ Distributed Training, HuggingFace, Accelerate, DeepSpeed, FSDP, Mixed Precision, PyTorch, DDP, Unified API, Simple

参考: SKILL.md 全文

HuggingFace Accelerate - Unified Distributed Training

すぐ試す

Accelerate を使うと、複数の計算機やGPUに分けて学習させる仕組みが、たった 4 行で書けます。

導入:

pip install accelerate

PyTorch のスクリプトを書き換える（4 行）:


+ 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 1 枚から複数枚へ

もとのスクリプト:

# train.py

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

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:
        # No .to('cuda') needed - automatic!
        optimizer.zero_grad()
        loss = model(batch).mean()
        accelerator.backward(loss)  # +4
        optimizer.step()

設定する（対話式）:

accelerate config

聞かれること:

  • どの計算機で走らせますか（GPU 1 枚 / 複数枚 / TPU / CPU）
  • 計算機は何台ですか（1）
  • 混合精度を使いますか（no/fp16/bf16/fp8）
  • DeepSpeed を使いますか（no/yes）

起動する（どんな構成でも同じコマンドです）:

# Single GPU
accelerate launch train.py

# Multi-GPU (8 GPUs)
accelerate launch --multi_gpu --num_processes 8 train.py

# Multi-node
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 (with gradient scaling)
accelerator = Accelerator(mixed_precision='fp16')

# BF16 (no scaling, more stable)
accelerator = Accelerator(mixed_precision='bf16')

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

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

# Everything else is automatic!
for batch in dataloader:
    with accelerator.autocast():  # Optional, done automatically
        loss = model(batch)
    accelerator.backward(loss)

進め方 3: DeepSpeed ZeRO と組み合わせる

DeepSpeed ZeRO-2 を有効にする（素の辞書ではなく DeepSpeedPlugin を渡します）:

from accelerate import Accelerator, DeepSpeedPlugin

deepspeed_plugin = DeepSpeedPlugin(
    zero_stage=2,                     # ZeRO-2
    offload_optimizer_device="none",  # or "cpu" to offload
    gradient_accumulation_steps=4,
)

accelerator = Accelerator(
    mixed_precision='bf16',
    deepspeed_plugin=deepspeed_plugin,  # DeepSpeedPlugin instance (or dict[str, DeepSpeedPlugin])
)

# Same code as before!
model, optimizer, dataloader = accelerator.prepare(model, optimizer, dataloader)

プラグイン経由で、DeepSpeed の JSON 設定をまるごと指すこともできます:

from accelerate import Accelerator, DeepSpeedPlugin

# hf_ds_config accepts a path to a DeepSpeed config JSON (or a dict)
deepspeed_plugin = DeepSpeedPlugin(hf_ds_config="ds_config.json")
accelerator = Accelerator(mixed_precision='bf16', deepspeed_plugin=deepspeed_plugin)

ds_config.json（素の DeepSpeed 設定です。--config_file ではなくプラグイン経由で渡します）:

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

対話式の設定から指定することもできます:

accelerate config
# Select: DeepSpeed → ZeRO-2
# This writes an accelerate YAML config (default: ~/.cache/huggingface/accelerate/default_config.yaml)

起動する（--config_file が受け取るのは accelerate の YAML であって、素の DeepSpeed の JSON ではありません）:

# Uses the default accelerate config written by `accelerate config`
accelerate launch train.py

# Or point at a specific accelerate YAML
accelerate launch --config_file accelerate_deepspeed.yaml train.py

進め方 4: FSDP（Fully Sharded Data Parallel）

FSDP を有効にする:

from accelerate import Accelerator, FullyShardedDataParallelPlugin

fsdp_plugin = FullyShardedDataParallelPlugin(
    sharding_strategy="FULL_SHARD",  # ZeRO-3 equivalent
    auto_wrap_policy="transformer_based_wrap",  # valid: transformer_based_wrap | size_based_wrap | no_wrap
    cpu_offload=False
)

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

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

設定から指定することもできます:

accelerate config
# Select: 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):  # Handles accumulation
        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: 抽象を挟まず、細かく制御したい

つまずきやすいところ

デバイスへの配置がおかしい

自分でデバイスへ移さないでください。

# WRONG
batch = batch.to('cuda')

# CORRECT
# Accelerate handles it automatically after prepare()

勾配の蓄積が効かない

コンテキストマネージャーを使ってください。

# CORRECT
with accelerator.accumulate(model):
    optimizer.zero_grad()
    accelerator.backward(loss)
    optimizer.step()

分散環境での途中保存

accelerator のメソッドを使ってください。

# Save only on main process
if accelerator.is_main_process:
    accelerator.save_state('checkpoint/')

# Load on all processes
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 1 枚: 動きます
  • 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: 個別の設定が必要です

参考先

  • Docs: 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 のライブラリ全般