SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场huggingface-accelerate

huggingface-accelerate

智能体与模型

查看项目

更新于 10-15 13:10

技能介绍

HuggingFace Accelerate 是一个统一分布式训练 API，目标是让任意 PyTorch 脚本以最小改动获得分布式训练能力。官方定位为“最简单的分布式训练 API”，用约 4 行代码即可为脚本添加分布式支持，并为 DeepSpeed、FSDP、Megatron、DDP 提供统一接口，同时自动处理设备放置。

用途 Accelerate 用于把原本只在单 GPU 上运行的 PyTorch 训练脚本，平滑扩展到多 GPU、多节点、TPU、Apple MPS 等环境，而无需重写训练循环。它适合希望用同一份脚本适配不同硬件、使用 HuggingFace 生态、需要快速原型验证，以及在 DDP、DeepSpeed、FSDP、Megatron 之间灵活切换的场景。

主要能力

  • 统一 API：同一份代码可运行于 DDP、DeepSpeed、FSDP、Megatron。
  • 自动处理：设备放置、混合精度、分片等由框架自动完成。
  • 混合精度：支持 fp16（带梯度缩放）、bf16（无缩放、更稳定）、fp8（H100+）。
  • DeepSpeed ZeRO 集成：可通过参数或配置文件启用 ZeRO-2 等阶段，支持优化器卸载、梯度累积步数等设置。
  • FSDP 支持：通过 FullyShardedDataParallelPlugin 配置分片策略（如 FULL_SHARD，等价 ZeRO-3）、自动包装策略、CPU 卸载等。
  • 梯度累积：通过 gradient_accumulation_steps 与 accelerator.accumulate(model) 上下文管理器实现，有效批大小为 batch_size × GPU 数 × 梯度累积步数。
  • 交互式配置：accelerate config 以问答方式选择机器类型、机器数量、混合精度、是否启用 DeepSpeed 等。
  • 单命令启动：accelerate launch 可在任意配置上启动，支持单 GPU、多 GPU（--multi_gpu --num_processes）、多节点（--num_machines、--machine_rank、--main_process_ip）等参数。
  • 分布式检查点：提供 accelerator.save_state / load_state，并可用 accelerator.is_main_process 控制仅主进程保存。
  • 随机种子工具：accelerate.utils.set_seed 用于保证分布式下结果一致。

使用方式 安装：pip install accelerate

最小改造（4 行）：

  1. 导入：from accelerate import Accelerator
  2. 实例化：accelerator = Accelerator()
  3. 准备对象：model, optimizer, dataloader = accelerator.prepare(model, optimizer, dataloader)
  4. 反向传播：将 loss.backward() 替换为 accelerator.backward(loss) 改造后无需手动 .to('cuda')，设备放置自动完成。

配置与启动：

  • 交互式配置：accelerate config
  • 单 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

混合精度示例：Accelerator(mixed_precision='fp16' | 'bf16' | 'fp8')，其余自动完成，可选使用 accelerator.autocast()。

DeepSpeed 示例：Accelerator(mixed_precision='bf16', deepspeed_plugin={"zero_stage": 2, "offload_optimizer": False, "gradient_accumulation_steps": 4})，或通过 accelerate config 选择 DeepSpeed → ZeRO-2，并可用 deepspeed_config.json 指定 fp16/bf16、zero_optimization 等。

FSDP 示例：使用 FullyShardedDataParallelPlugin(sharding_strategy="FULL_SHARD", auto_wrap_policy="TRANSFORMER_AUTO_WRAP", cpu_offload=False)，再传入 Accelerator(fsdp_plugin=...)，或通过 accelerate config 选择 FSDP → Full Shard → No CPU Offload。

梯度累积示例：Accelerator(gradient_accumulation_steps=4)，训练循环中用 with accelerator.accumulate(model): 包裹 zero_grad、backward、step。

适用场景

  • 希望以最少代码改动实现分布式训练。
  • 需要一份脚本适配多种硬件。
  • 使用 HuggingFace 生态（Transformers、TRL、PEFT 等）。
  • 需要在 DDP/DeepSpeed/FSDP/Megatron 之间灵活切换。
  • 需要快速原型验证。

限制与注意事项

  • 不要手动将 batch 移到设备（如 batch.to('cuda')），prepare() 后由 Accelerate 自动处理。
  • 梯度累积必须使用 accelerator.accumulate(model) 上下文管理器，否则不生效。
  • 分布式检查点应使用 accelerator.save_state / load_state，并配合 is_main_process 控制保存进程。
  • 使用 FSDP 时若结果不一致，需通过 set_seed 设置相同随机种子。
  • 硬件支持：CPU（可用但慢）、单 GPU、多 GPU（DDP 默认、DeepSpeed、FSDP）、多节点（DDP、DeepSpeed、FSDP、Megatron）、TPU、Apple MPS。
  • 启动器要求：DDP 使用内置 torch.distributed.run；DeepSpeed 需 pip install deepspeed；FSDP 需 PyTorch 1.12+（内置）；Megatron 需自定义环境。
  • 若需要回调与高层抽象可考虑 PyTorch Lightning；多节点编排与超参调优可考虑 Ray Train；需要直接 API 控制与高级特性可考虑 DeepSpeed；需要最大控制与最小抽象可考虑原生 DDP。

资源

  • 文档：https://huggingface.co/docs/accelerate
  • GitHub：https://github.com/huggingface/accelerate
  • 版本：1.11.0+
  • 示例：https://github.com/huggingface/accelerate/tree/main/examples
  • 被使用于：HuggingFace Transformers、TRL、PEFT 及所有 HF 库。

高级主题（资料提及）

  • Megatron 集成：张量并行、流水线并行、序列并行设置，见 references/megatron-integration.md。
  • 自定义插件：创建自定义分布式插件与高级配置，见 references/custom-plugins.md。
  • 性能调优：性能分析、内存优化与最佳实践，见 references/performance.md。