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／多 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（完全分片数据并行）

启用 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 或使用高级功能
• 原生 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 库

Agent 操作流程

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：高级 PyTorch 框架，提供 Trainer 类、自动分布式训练（DDP/FSDP/DeepSpeed）、回调系统和精简的样板代码……
• deepspeed：介绍用于分布式深度学习训练和 I/O 的 DeepSpeed：ZeRO 优化阶段、流水线并行、FP16/BF16/FP8 训练、1-……