Accelerate：Hugging Face 统一 PyTorch 多卡多机训练启动器｜部署与使用全指南

仓库：https://github.com/huggingface/accelerate 官方文档：https://huggingface.co/docs/accelerate 许可证：Apache-2.0 运行形态：Python 库 + CLI，无 Web 端口

1. 项目简介

Accelerate 是 Hugging Face 维护的 PyTorch 训练加速库。官方定位是"Run your raw PyTorch training script on any kind of device"：它只抽象多 GPU / TPU / fp16 等样板代码，其余代码一行不改，就能在单 CPU、单 GPU、多 GPU、TPU 及混合精度（fp8 / fp16 / bf16）下运行同一份脚本。

1.1 核心信息一览

1.2 适用场景

• 已有原生 PyTorch 训练脚本，想不加改动跑多卡 / 混合精度；
• 想在本地调试和集群训练间复用同一份代码；
• 需要 DeepSpeed / FSDP 等分布式训练配置。

1.3 能力边界（官方口径）

• 只抽象设备与分布式样板，不替代训练逻辑本身；
• DeepSpeed 等高级配置通过 accelerate config 或 DeepSpeedPlugin 设定；
• 硬件（GPU / TPU）与驱动需自行准备。

2. 功能特性

• 5 行改造：引入 Accelerator()、accelerator.prepare(...)、accelerator.backward(loss)；
• 设备无关：自动设备放置，同一份代码跑单机 / 多机 / TPU；
• 混合精度：fp8 / fp16 / bf16 开关；
• DeepSpeed / FSDP：经 accelerate config 配置，无需改训练代码；
• CLI 启动：accelerate launch 等价 torchrun，可直接透传 torchrun 参数。

3. 官方界面预览

上图为官方 README logo（README 官方素材）。

4. 官方跳转链接汇总

• 仓库主页：https://github.com/huggingface/accelerate
• 文档：https://huggingface.co/docs/accelerate
• HF Course：https://hf.co/course
• Releases：https://github.com/huggingface/accelerate/releases

5. 前置要求与服务器配置

• Python 环境与 PyTorch；
• GPU / TPU 集群（多卡训练时）及对应驱动；
• 无端口、无数据库。

6. 方式一：pip 安装（推荐）

pip install accelerate

交互式生成配置：

accelerate config

启动训练：

accelerate launch my_script.py --args_to_my_script

不跑 config 直接透传 torchrun 参数：

accelerate launch --multi_gpu --num_processes 2 examples/nlp_example.py

7. 方式二：脚本改造（最小 diff）

from accelerate import Accelerator

accelerator = Accelerator()
device = accelerator.device

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

for source, targets in data:
    optimizer.zero_grad()
    output = model(source)
    loss = F.cross_entropy(output, targets)
    accelerator.backward(loss)
    optimizer.step()

8. 配置项说明

9. 常用运维命令

# 安装
pip install accelerate

# 配置
accelerate config

# 启动
accelerate launch examples/nlp_example.py

# 多卡透传
accelerate launch --multi_gpu --num_processes 2 my_script.py

# 升级
pip install -U accelerate

10. 常见故障排查

• 显存不足：在 accelerate config 里开混合精度或梯度累积；
• 多机起不来：确认网络 / NCCL 环境变量与 --num_processes；
• DeepSpeed 报错：用 accelerate config 重新生成或在脚本用 DeepSpeedPlugin；
• 设备识别错：accelerator.device 而非手动 cuda。

11. 风险与合规说明

• Apache-2.0 许可；
• 硬件费用（GPU 集群）由使用者承担；
• 本文为社区部署笔记，命令以官方文档最新版本为准。