huggingface-accelerate

HuggingFace Accelerate 是一个用于统一分布式训练的 Python 库，目标是让同一份 PyTorch 训练脚本无需大幅修改即可运行在 CPU、单 GPU、多 GPU、多节点、TPU 和 Apple MPS 等不同硬件环境上。

用途 Accelerate 主要解决分布式训练中设备放置、混合精度、梯度累积、分片等重复性工程问题。它通过 Accelerator 类、accelerate config 交互式配置命令和 accelerate launch 启动命令，把原本需要手写的分布式逻辑封装起来，使训练脚本保持简洁。

主要能力

• 最小代码改动：在原有 PyTorch 脚本中加入约 4 行代码即可完成改造，包括导入 Accelerator、实例化、用 accelerator.prepare() 包装模型/优化器/数据加载器、用 accelerator.backward() 替换反向传播。
• 自动设备放置：prepare() 之后无需手动调用 .to('cuda')，Accelerate 会自动处理。
• 混合精度训练：支持 fp16（含梯度缩放）、bf16（更稳定、无需缩放）和 fp8（H100+）。
• 梯度累积：通过 Accelerator(gradient_accumulation_steps=4) 与 with accelerator.accumulate(model) 上下文管理器实现，有效批大小为 batch_size × GPU 数 × 累积步数。
• 分布式后端支持：DDP（默认）、DeepSpeed ZeRO（如 ZeRO-2）、FSDP（Fully Sharded Data Parallel，支持 FULL_SHARD 等分片策略）、Megatron 集成。
• 检查点管理：使用 accelerator.save_state() 与 accelerator.load_state()，并可通过 accelerator.is_main_process 仅在主进程保存。
• 随机种子统一：通过 accelerate.utils.set_seed(42) 保证不同分片下结果一致。

使用方式 安装：pip install accelerate 改造脚本（4 行）： import torch from accelerate import Accelerator accelerator = Accelerator() model, optimizer, dataloader = accelerator.prepare(model, optimizer, dataloader) accelerator.backward(loss) 配置：运行 accelerate config，按提示选择机器类型（单/多 GPU、TPU、CPU）、机器数量、混合精度（no/fp16/bf16/fp8）、是否启用 DeepSpeed 等。 启动：

• 单 GPU：accelerate launch train.py
• 多 GPU（8 卡）：accelerate launch --multi_gpu --num_processes 8 train.py
• 多节点：accelerate launch --multi_gpu --num_processes 16 --num_machines 2 --machine_rank 0 --main_process_ip $MASTER_ADDR train.py
• 使用配置文件：accelerate launch --config_file deepspeed_config.json train.py

适用场景

• 希望以最简单方式实现分布式训练。
• 需要一份脚本适配任意硬件。
• 使用 HuggingFace 生态（Transformers、TRL、PEFT 等）。
• 需要灵活切换 DDP/DeepSpeed/FSDP/Megatron。
• 需要快速原型验证。

限制与注意事项

• 不要手动将 batch 移动到设备（如 batch.to('cuda')），prepare() 后由 Accelerate 自动处理。
• 梯度累积必须使用 with accelerator.accumulate(model) 上下文管理器。
• 分布式检查点应使用 accelerator.save_state()/load_state()，并注意仅在主进程保存。
• FSDP 下若结果不同，需确保设置相同随机种子。
• 硬件要求：CPU 可用但较慢；单 GPU、多 GPU、多节点、TPU、Apple MPS 均支持。启动器要求：DDP 使用内置 torch.distributed.run；DeepSpeed 需 pip install deepspeed；FSDP 需 PyTorch 1.12+；Megatron 需自定义环境。
• 版本：1.11.0+。
• 若遇到 CUDA 显存不足，可减小批大小、启用梯度累积/检查点或混合精度、或对模型分片；若损失为 NaN 或发散，可降低学习率、检查数据、启用梯度裁剪。
• 文档：https://huggingface.co/docs/accelerate ；GitHub：https://github.com/huggingface/accelerate ；示例：https://github.com/huggingface/accelerate/tree/main/examples 。

其他说明 Accelerate 被 HuggingFace Transformers、TRL、PEFT 及所有 HF 库使用。若需要回调与高层抽象可考虑 PyTorch Lightning；若需要多节点编排与超参调优可考虑 Ray Train；若需要直接 API 控制与高级特性可考虑 DeepSpeed；若需要最大控制与最小抽象可考虑原生 DDP。