故障排除

本指南提供了一些在使用 Accelerate 时可能遇到的问题解决方案。由于 Accelerate 是一个不断发展中的活跃库，并且存在许多不同的用例和分布式训练设置，因此并非所有错误都包含在内。如果此处描述的解决方案无法解决您的特定错误，请查看寻求帮助部分，了解在哪里以及如何获得帮助。

日志记录

日志记录可以帮助您识别错误的来源。在具有多个进程的分布式设置中，日志记录可能是一个挑战，但 Accelerate 提供了logging()实用程序来确保日志同步。

要解决问题，请使用logging()而不是标准的 Python logging模块。使用log_level参数设置详细程度级别（INFO、DEBUG、WARNING、ERROR、CRITICAL），然后您可以

将log_level导出为ACCELERATE_LOG_LEVEL环境变量。
将log_level直接传递给get_logger。

例如，要设置log_level="INFO"

from accelerate.logging import get_logger

logger = get_logger(__name__, log_level="DEBUG")

默认情况下，日志仅在主进程中调用。要在所有进程中调用它，请传递main_process_only=False。如果应按顺序在所有进程中调用日志，则还应传递in_order=True。

from accelerate.logging import get_logger

logger = get_logger(__name__, log_level="DEBUG")
# log all processes
logger.debug("thing_to_log", main_process_only=False)
# log all processes in order
logger.debug("thing_to_log", main_process_only=False, in_order=True)

代码挂起和超时错误

代码挂起的原因有很多。让我们看看如何解决一些可能导致代码挂起的最常见问题。

张量形状不匹配

张量形状不匹配是一个常见问题，它可能导致您的代码在分布式设置中长时间挂起。

在分布式设置中运行脚本时，诸如Accelerator.gather()和Accelerator.reduce()之类的函数对于跨设备获取张量以共同对其执行操作是必要的。这些（以及其他）函数依赖于torch.distributed来执行gather操作，这要求张量在所有进程中具有**完全相同的形状**。当张量形状不匹配时，您的代码会挂起，并且最终会遇到超时异常。

您可以使用 Accelerate 的操作调试模式立即捕获此问题。我们建议在accelerate config设置期间启用此模式，但您也可以从 CLI、环境变量或通过手动编辑config.yaml文件来启用它。

CLI

环境变量

config.yaml

启用调试模式后，您应该会收到一个指向张量形状不匹配问题的回溯。

Traceback (most recent call last):
  File "/home/zach_mueller_huggingface_co/test.py", line 18, in <module>
    main()
  File "/home/zach_mueller_huggingface_co/test.py", line 15, in main
    broadcast_tensor = broadcast(tensor)
  File "/home/zach_mueller_huggingface_co/accelerate/src/accelerate/utils/operations.py", line 303, in wrapper
accelerate.utils.operations.DistributedOperationException:

Cannot apply desired operation due to shape mismatches. All shapes across devices must be valid.

Operation: `accelerate.utils.operations.broadcast`
Input shapes:
  - Process 0: [1, 5]
  - Process 1: [1, 2, 5]

提前停止

对于分布式训练中的提前停止，如果每个进程都有特定的停止条件（例如验证损失），则它可能不会在所有进程之间同步。因此，进程 0 可能发生中断，但进程 1 未发生中断，这会导致您的代码无限期挂起，直到发生超时。

如果您有提前停止条件，请使用set_breakpoint和check_breakpoint方法确保所有进程都正确结束。

# Assume `should_do_breakpoint` is a custom defined function that returns a conditional, 
# and that conditional might be true only on process 1
if should_do_breakpoint(loss):
    accelerator.set_breakpoint()

# Later in the training script when we need to check for the breakpoint
if accelerator.check_breakpoint():
    break

Linux 上的内核版本过低

在内核版本< 5.5 的 Linux 上，已报告进程挂起问题。为避免此问题，请将系统升级到更高版本的内核。

MPI

如果您的使用 MPI 的分布式 CPU 训练作业挂起，请确保您在节点之间设置了无需密码的 SSH（使用密钥）。这意味着对于主机文件中的所有节点，您都应该能够从一个节点 SSH 到另一个节点，而无需提示输入密码。

接下来，尝试运行mpirun命令作为健全性检查。例如，以下命令应打印出每个节点的主机名。

mpirun -f hostfile -n {number of nodes} -ppn 1 hostname

CUDA 内存不足

在运行训练脚本时，最令人沮丧的错误之一是遇到“CUDA 内存不足”。整个脚本需要重新启动，并且任何进度都会丢失。

为了解决此问题，Accelerate 提供了find_executable_batch_size()实用程序，该程序很大程度上基于toma。此实用程序重试因 OOM（内存不足）条件而失败的代码并自动降低批次大小。对于每个 OOM 条件，算法将批次大小减半并重试代码，直到成功为止。

要使用find_executable_batch_size()，请重构您的训练函数以包含一个带有find_executable_batch_size的内部函数，并在其中构建您的数据加载器。至少，这只需要 4 行新代码。

内部函数**必须**将批次大小作为第一个参数，但我们在调用它时不会传递给它。包装器将为您处理此问题。任何消耗 CUDA 内存并传递给Accelerator的对象（模型、优化器）也**必须**在内部函数中声明。

def training_function(args):
    accelerator = Accelerator()

+   @find_executable_batch_size(starting_batch_size=args.batch_size)
+   def inner_training_loop(batch_size):
+       nonlocal accelerator # Ensure they can be used in our context
+       accelerator.free_memory() # Free all lingering references
        model = get_model()
        model.to(accelerator.device)
        optimizer = get_optimizer()
        train_dataloader, eval_dataloader = get_dataloaders(accelerator, batch_size)
        lr_scheduler = get_scheduler(
            optimizer, 
            num_training_steps=len(train_dataloader)*num_epochs
        )
        model, optimizer, train_dataloader, eval_dataloader, lr_scheduler = accelerator.prepare(
            model, optimizer, train_dataloader, eval_dataloader, lr_scheduler
        )
        train(model, optimizer, train_dataloader, lr_scheduler)
        validate(model, eval_dataloader)
+   inner_training_loop()

设备设置之间结果不可重现

如果您更改了设备设置并观察到不同的模型性能，则可能是您在从一个设置切换到另一个设置时没有更新脚本。即使您使用相同的脚本和相同的批次大小，在 TPU、多 GPU 和单 GPU 上的结果仍然会有所不同。

例如，如果您在单个 GPU 上以 16 的批次大小进行训练，然后切换到双 GPU 设置，则需要将批次大小更改为 8 以获得相同的有效批次大小。这是因为在使用 Accelerate 进行训练时，传递给数据加载器的批次大小是**每个 GPU 的批次大小**。

为了确保您可以在不同的设置之间重现结果，请确保使用相同的种子，相应地调整批次大小，并考虑缩放学习率。

有关更多详细信息以及批次大小的快速参考，请查看比较不同设备设置之间的性能指南。

不同 GPU 上的性能问题

如果您的多 GPU 设置包含不同的 GPU，您可能会遇到一些性能问题。

GPU 之间可能存在 GPU 内存不平衡。在这种情况下，内存较小的 GPU 将限制可以加载到 GPU 上的批次大小或模型大小。
如果您使用具有不同性能配置文件的 GPU，则性能将由您使用的最慢的 GPU 决定，因为其他 GPU 将不得不等待它完成其工作负载。

同一设置中差异很大的 GPU 可能会导致性能瓶颈。

寻求帮助

如果此处提供的解决方案和建议均无法解决您的问题，您始终可以联系社区和 Accelerate 团队寻求帮助。

在 Hugging Face 论坛上寻求帮助，在Accelerate 类别中发布您的问题。请确保撰写一篇描述性帖子，其中包含有关您的设置和可重现代码的相关上下文，以最大程度地提高解决您问题的可能性！
在Discord上发布问题，并让团队和社区帮助您。
如果您认为发现了与库相关的错误，请在 Accelerate 的GitHub 存储库上创建一个 Issue。请提供有关错误的上下文以及有关您的分布式设置的详细信息，以帮助我们更好地了解问题所在以及如何解决它。

< > 更新在 GitHub 上

加速