huggingface-accelerate

HuggingFace Accelerate - 統合分散トレーニング

クイックスタート

Accelerate を使うと、分散トレーニングを 4 行のコードで簡単に実行できます。

インストール:

pip install accelerate

PyTorch スクリプトの変換（4 行）:

import torch
+ from accelerate import Accelerator

+ accelerator = Accelerator()

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

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

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

実行（単一のコマンド）:

accelerate launch train.py

一般的なワークフロー

ワークフロー 1: シングル GPU からマルチ GPU へ

元のスクリプト:

# train.py
import torch

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

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

Accelerate を使う場合（4 行を追加）:

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

accelerator = Accelerator()  # +2

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

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

for epoch in range(10):
    for batch in dataloader:
        # No .to('cuda') needed - automatic!
        optimizer.zero_grad()
        loss = model(batch).mean()
        accelerator.backward(loss)  # +4
        optimizer.step()

設定（対話形式）:

accelerate config

質問:

• どのマシンですか？（単一／マルチ GPU／TPU／CPU）
• マシンはいくつですか？（1）
• 混合精度を使用しますか？（いいえ／fp16／bf16／fp8）
• DeepSpeed を使用しますか？（いいえ／はい）

起動（どのようなセットアップでも動作します）:

# 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 を有効にする:

from accelerate import Accelerator

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

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

または設定を使用:

accelerate config
# Select: DeepSpeed → ZeRO-2

deepspeed_config.json:

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

起動:

accelerate launch --config_file deepspeed_config.json train.py

ワークフロー 4: FSDP（Fully Sharded Data Parallel）

FSDP を有効にする:

from accelerate import Accelerator, FullyShardedDataParallelPlugin

fsdp_plugin = FullyShardedDataParallelPlugin(
    sharding_strategy="FULL_SHARD",  # ZeRO-3 equivalent
    auto_wrap_policy="TRANSFORMER_AUTO_WRAP",
    cpu_offload=False
)

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

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

または設定を使用:

accelerate config
# 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 を直接制御したい場合や、高度な機能が必要な場合
• Raw 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: 動作します
• マルチ GPU: DDP（デフォルト）、DeepSpeed、または FSDP
• マルチノード: DDP、DeepSpeed、FSDP、Megatron
• TPU: サポートされています
• Apple MPS: サポートされています

ランチャーの要件:

• DDP: torch.distributed.run（組み込み）
• DeepSpeed: deepspeed（pip install deepspeed）
• FSDP: PyTorch 1.12+（組み込み）
• Megatron: カスタムセットアップ

リソース

• ドキュメント: https://huggingface.co/docs/accelerate
• GitHub: https://github.com/huggingface/accelerate
• バージョン: 1.11.0+
• チュートリアル: 「Accelerate your scripts」
• 例: https://github.com/huggingface/accelerate/tree/main/examples
• 使用例: HuggingFace Transformers、TRL、PEFT、すべての HF ライブラリ

エージェントの運用手順

1. 環境を確認します。 GPU の種類、メモリ、ドライバー／CUDA のバージョン（nvidia-smi）、フレームワークのバージョン、データセットの保存場所とサイズを確認します。
2. 入力を明確にします。 データまたはユーザーに確認し、形式、識別子、パラメーターを確定します。結果に影響する値は推測せず、質問してください。
3. まず小規模な実行を行います。 スモークテストを実行します。小さなモデルまたはサブセットを使い、少ないステップ数で実行して、損失が減少し、チェックポイントが保存されることを確認します。
4. 上記の手順と参考情報に従って、タスク全体を実行します。
5. 結果を検証します。 保留データでメトリクスを追跡し、ベースラインと比較して、シード、設定、ハードウェアを記録します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した項目、未確認の事項を明記します。

発生した場合	対応
CUDA のメモリ不足	バッチサイズを小さくする、勾配累積／チェックポイントまたは混合精度を有効にする、あるいはモデルをシャーディングします。
損失が NaN になる、または発散する	学習率を下げ、データに無効な値がないか確認し、勾配クリッピングを有効にします。
これらの手順に記載された関数、フラグ、エンドポイントがインストール済みバージョンにない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して対応し、ユーザーに伝えます。API を捏造してはいけません。
必須の入力、識別子、パラメーターが曖昧	ユーザーに確認するか、実行前に仮定を明示します。

インテグリティに関するルール

• 結果、パラメーター、識別子、引用、統計を決して捏造しないでください。実行または検証できないことは、率直に伝えてください。
• ログなしに学習結果を主張してはいけません。大規模なジョブを開始する前に、計算コストを見積もってください。
• ここに記載されているバージョン固有の情報は古くなっている可能性があるため、インストール済みバージョンの公式ドキュメントで確認してください。
• 費用が発生する操作、共有 GPU やクラウドのクォータを消費する操作、個人データや患者データに触れる操作、取り消せない操作を行う前に、許可を求めてください。

関連スキル

• pytorch-lightning：lightning パッケージ（PyTorch Lightning）を使用して PyTorch の学習コードを構成します。LightningModule、LightningDataModule、Trainer、コールバックなど…
• pytorch-lightning-distributed：Trainer クラス、自動分散学習（DDP/FSDP/DeepSpeed）、コールバックシステム、最小限のボイラープレートを備えた高水準の PyTorch フレームワーク…
• deepspeed：分散ディープラーニングの学習と I/O に DeepSpeed を使用します。ZeRO 最適化ステージ、パイプライン並列処理、FP16/BF16/FP8 学習など、1-…