在任何类型的设备上运行您的原始 PyTorch 训练脚本

易于集成

🤗 Accelerate 是为那些喜欢自己编写 PyTorch 模型训练循环，但又不愿编写和维护多 GPU/TPU/fp16 所需样板代码的 PyTorch 用户而设计的。

🤗 Accelerate 只抽象与多 GPU/TPU/fp16 相关的样板代码，而保持您的其余代码不变。

以下是一个示例：

  import torch
  import torch.nn.functional as F
  from datasets import load_dataset
+ from accelerate import Accelerator

+ accelerator = Accelerator()
- device = 'cpu'
+ device = accelerator.device

  model = torch.nn.Transformer().to(device)
  optimizer = torch.optim.Adam(model.parameters())

  dataset = load_dataset('my_dataset')
  data = torch.utils.data.DataLoader(dataset, shuffle=True)

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

  model.train()
  for epoch in range(10):
      for source, targets in data:
          source = source.to(device)
          targets = targets.to(device)

          optimizer.zero_grad()

          output = model(source)
          loss = F.cross_entropy(output, targets)

-         loss.backward()
+         accelerator.backward(loss)

          optimizer.step()

正如您在此示例中看到的那样，只需向任何标准的 PyTorch 训练脚本添加 5 行代码，您就可以在任何单机或分布式节点环境中运行它（单 CPU、单 GPU、多 GPU 和 TPU），并且可以使用或不使用混合精度（fp8、fp16、bf16）。

特别是，相同的代码无需修改即可在您的本地机器上用于调试，也可以在您的训练环境中运行。

🤗 Accelerate 甚至会为您处理设备放置问题（这需要对您的代码进行一些额外的更改，但通常更安全），因此您可以进一步简化训练循环：

  import torch
  import torch.nn.functional as F
  from datasets import load_dataset
+ from accelerate import Accelerator

- device = 'cpu'
+ accelerator = Accelerator()

- model = torch.nn.Transformer().to(device)
+ model = torch.nn.Transformer()
  optimizer = torch.optim.Adam(model.parameters())

  dataset = load_dataset('my_dataset')
  data = torch.utils.data.DataLoader(dataset, shuffle=True)

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

  model.train()
  for epoch in range(10):
      for source, targets in data:
-         source = source.to(device)
-         targets = targets.to(device)

          optimizer.zero_grad()

          output = model(source)
          loss = F.cross_entropy(output, targets)

-         loss.backward()
+         accelerator.backward(loss)

          optimizer.step()

想了解更多？请查看 文档 或浏览我们的 示例。

启动脚本

🤗 Accelerate 还提供了一个可选的命令行工具，允许您在启动脚本之前快速配置和测试训练环境。无需记住如何使用 torch.distributed.run，也不必为 TPU 训练编写特定的启动器！只需在您的机器上运行：

accelerate config

并回答相关问题。这将生成一个配置文件，该文件将在执行以下操作时自动用于正确设置默认选项：

accelerate launch my_script.py --args_to_my_script

例如，以下是在仓库根目录下运行 MRPC 任务的 GLUE 示例的方法：

accelerate launch examples/nlp_example.py

此命令行工具是可选的，您仍然可以根据需要使用 python my_script.py 或 python -m torchrun my_script.py。

如果您不想运行 accelerate config，也可以直接将原本传递给 torchrun 的参数作为 accelerate launch 的参数传递。例如，以下是在两块 GPU 上启动的方式：

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

要了解更多信息，请查阅此处提供的 CLI 文档：加速包参考 CLI。

或者查看配置模板库：配置 YAML 模板。

使用 MPI 启动多 CPU 运行

🤗 以下是另一种使用 MPI 启动多 CPU 运行的方式。您可以在此页面上了解如何安装 Open MPI。您也可以使用 Intel MPI 或 MVAPICH。 一旦您的集群上设置了 MPI，只需运行：

accelerate config

回答相关问题，选择以多 CPU 方式运行，并在被问及是否希望 Accelerate 启动 mpirun 时回答“是”。然后，使用 accelerate launch 运行您的脚本，例如：

accelerate launch examples/nlp_example.py

或者，您也可以直接使用 mpirun，而不通过命令行工具，例如：

mpirun -np 2 python examples/nlp_example.py

使用 DeepSpeed 启动训练

🤗 Accelerate 支持使用 DeepSpeed 在单个或多个 GPU 上进行训练。要使用它，您无需更改训练代码中的任何内容；只需通过 accelerate config 即可完成所有设置。不过，如果您希望从 Python 脚本中调整与 DeepSpeed 相关的参数，我们提供了 DeepSpeedPlugin。

from accelerate import Accelerator, DeepSpeedPlugin

# deepspeed 需要提前知道您的梯度累积步数，因此请务必传递该参数
# 请记住，您仍然需要自行执行梯度累积操作，就像在不使用 deepspeed 的情况下一样
deepspeed_plugin = DeepSpeedPlugin(zero_stage=2, gradient_accumulation_steps=2)
accelerator = Accelerator(mixed_precision='fp16', deepspeed_plugin=deepspeed_plugin)

# 如何保存您的 🤗 Transformer？
accelerator.wait_for_everyone()
unwrapped_model = accelerator.unwrap_model(model)
unwrapped_model.save_pretrained(save_dir, save_function=accelerator.save, state_dict=accelerator.get_state_dict(model))

注意：目前 DeepSpeed 支持仍处于实验阶段。如果您遇到任何问题，请提交 issue。

从笔记本中启动训练

🤗 Accelerate 还提供了一个 notebook_launcher 函数，您可以在笔记本中使用它来启动分布式训练。这对于具有 TPU 后端的 Colab 或 Kaggle 笔记本尤其有用。只需在 training_function 中定义您的训练循环，然后在最后一行添加：

from accelerate import notebook_launcher

notebook_launcher(training_function)

示例可在此笔记本中找到。

为什么应该使用 🤗 Accelerate？

当您希望在不放弃对训练循环完全控制的情况下，轻松地在分布式环境中运行训练脚本时，就应使用 🤗 Accelerate。它并不是 PyTorch 之上的高级框架，而是一个轻量级封装，因此您无需学习新的库。事实上，🤗 Accelerate 的整个 API 都集中在 Accelerator 类中。

为什么不使用 🤗 Accelerate？

如果您不想自己编写训练循环，则不应使用 🤗 Accelerate。PyTorch 之上有许多高级库可以为您提供这一功能，而 🤗 Accelerate 并不属于此类。

使用 🤗 Accelerate 的框架

如果您喜欢 🤗 Accelerate 的简洁性，但更倾向于在其功能之上构建更高层次的抽象，以下是一些基于 🤗 Accelerate 构建的框架和库：

• Amphion 是一个用于音频、音乐和语音生成的工具包。其目标是支持可重复的研究，并帮助初级研究人员和工程师入门音频、音乐和语音生成领域的研究与开发。
• Animus 是一个极简的机器学习实验框架。Animus 强调机器学习实验中的常见“断点”，并在 IExperiment 中为这些断点提供统一的接口。
• Catalyst 是一个用于深度学习研究与开发的 PyTorch 框架。它专注于可重复性、快速实验和代码重用，以便您可以创造新东西，而不是再写一个训练循环。Catalyst 提供一个 Runner 来连接实验的所有部分：硬件后端、数据变换、模型训练和推理逻辑。
• fastai 是一个简化了现代最佳实践下快速准确神经网络训练的 PyTorch 深度学习框架。fastai 提供一个 Learner 来处理深度学习算法的训练、微调和推理。
• Finetuner 是一项服务，使模型能够为语义搜索、视觉相似性搜索、跨模态文本<->图像搜索、推荐系统、聚类、重复检测、异常检测或其他用途创建更高质量的嵌入。
• InvokeAI 是 Stable Diffusion 模型的创意引擎，提供行业领先的 WebUI 和终端使用支持，并作为许多商业产品的基础。
• Kornia 是一个可微分库，允许将经典计算机视觉集成到深度学习模型中。Kornia 提供一个 Trainer 专门用于训练和微调库中支持的深度学习算法。
• Open Assistant 是一个基于聊天的助手，能够理解任务、与其各方系统交互，并动态获取信息以完成任务。
• pytorch-accelerated 是一个轻量级训练库，其精简的功能集围绕通用的 Trainer 展开，非常强调简单性和透明度；使用户能够清楚地了解底层正在发生的事情，而无需自己编写和维护样板代码！
• Stable Diffusion web UI 是一个基于 Gradio 库的开源浏览器界面，专为 Stable Diffusion 设计，易于使用。
• torchkeras 是一种以 Keras 风格训练 PyTorch 模型的简单工具，在笔记本中会提供动态且美观的图表来监控损失或指标。
• transformers 作为帮助在 PyTorch、TensorFlow 和 JAX 中训练最先进机器学习模型的工具。（Accelerate 是 PyTorch 部分的后端）。

安装

本仓库已在 Python 3.8+ 和 PyTorch 1.10.0+ 环境下测试通过。

您应在 虚拟环境 中安装 🤗 Accelerate。如果您不熟悉 Python 虚拟环境，请参阅 用户指南。

首先，创建一个使用您计划使用的 Python 版本的虚拟环境，并激活它。

接着，您需要安装 PyTorch：请参考 官方安装页面，根据您的平台选择合适的安装命令。然后，您可以使用 pip 安装 🤗 Accelerate，命令如下：

pip install accelerate

支持的集成

• 仅 CPU
• 单节点多 CPU
• 多节点多 CPU
• 单 GPU
• 单节点多 GPU
• 多节点多 GPU
• TPU
• FP16/BFloat16 混合精度
• 使用 Transformer Engine 或 MS-AMP 的 FP8 混合精度
• DeepSpeed 支持（实验性）
• PyTorch 全量分片数据并行（FSDP）支持（实验性）
• Megatron-LM 支持（实验性）

引用 🤗 Accelerate

如果您在论文或其他出版物中使用了 🤗 Accelerate，请使用以下 BibTeX 条目进行引用。

@Misc{accelerate,
  title =        {Accelerate: Training and inference at scale made simple, efficient and adaptable.},
  author =       {Sylvain Gugger and Lysandre Debut and Thomas Wolf and Philipp Schmid and Zachary Mueller and Sourab Mangrulkar and Marc Sun and Benjamin Bossan},
  howpublished = {\url{https://github.com/huggingface/accelerate}},
  year =         {2022}
}

🤗 Accelerate 快速上手指南

🤗 Accelerate 是 Hugging Face 推出的一款轻量级库，旨在帮助开发者轻松地在任何硬件配置（单 CPU、单 GPU、多 GPU、TPU）下运行原生 PyTorch 训练脚本。它仅抽象了分布式训练和混合精度所需的样板代码，让你无需学习新框架即可掌控完整的训练循环。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统: Linux, macOS, 或 Windows
• Python: 3.8 或更高版本
• 核心依赖:
  • PyTorch >= 1.10.0
  • (可选) Transformers, Datasets 等 Hugging Face 生态库（若你的项目需要）
• 硬件支持:
  • CPU
  • NVIDIA GPU (需安装对应的 CUDA 版本)
  • Google TPU (需在 Colab/Kaggle 或 GCP 环境)

提示：国内用户建议在安装 PyTorch 时使用清华或中科大镜像源，以获得更快的下载速度。

安装步骤

你可以使用 pip 直接安装最新稳定版。

标准安装

pip install accelerate

使用国内镜像加速安装

推荐中国开发者使用清华源进行安装：

pip install accelerate -i https://pypi.tuna.tsinghua.edu.cn/simple

安装最新开发版（可选）

如果你需要体验最新功能：

pip install git+https://github.com/huggingface/accelerate.git

基本使用

只需对现有的 PyTorch 训练脚本进行极少量的修改（通常仅需 5 行代码），即可使其支持分布式训练和混合精度。

1. 初始化 Accelerator

导入 Accelerator 类并实例化，它将自动检测当前环境（CPU/GPU/TPU）。

2. 准备对象

使用 accelerator.prepare() 包装模型、优化器和数据加载器。

3. 替换反向传播

将 loss.backward() 替换为 accelerator.backward(loss)。

代码示例对比

以下是将原生 PyTorch 脚本转换为 Accelerate 脚本的最小改动示例：

import torch
import torch.nn.functional as F
from datasets import load_dataset
# 1. 导入 Accelerator
from accelerate import Accelerator

# 2. 初始化 accelerator
accelerator = Accelerator()

# 不再需要手动指定 device = 'cuda' 或 'cpu'，accelerator.device 会自动处理
model = torch.nn.Transformer()
optimizer = torch.optim.Adam(model.parameters())

dataset = load_dataset('my_dataset')
data = torch.utils.data.DataLoader(dataset, shuffle=True)

# 3. 准备模型、优化器和数据
model, optimizer, data = accelerator.prepare(model, optimizer, data)

model.train()
for epoch in range(10):
    for source, targets in data:
        # 4. 数据会自动移动到正确的设备上，无需手动 .to(device)
        # source = source.to(device) 
        # targets = targets.to(device)

        optimizer.zero_grad()

        output = model(source)
        loss = F.cross_entropy(output, targets)

        # 5. 使用 accelerator 进行反向传播
        accelerator.backward(loss)

        optimizer.step()

启动训练

配置好代码后，你可以通过 CLI 工具轻松启动训练，无需手动编写 torch.distributed.run 命令。

第一步：配置环境 运行以下命令并根据提示回答关于你的硬件环境的问题（如 GPU 数量、是否使用混合精度等）：

accelerate config

第二步：启动脚本 使用 accelerate launch 运行你的脚本：

accelerate launch my_script.py --args_to_my_script

如果你不想运行配置向导，也可以直接在命令行传递参数（例如在 2 张 GPU 上运行）：

accelerate launch --multi_gpu --num_processes 2 my_script.py

对于本地调试，你依然可以直接使用 python my_script.py 运行，代码无需修改。