PyTorch 2.0 故障排除（旧版）

作者: Michael Lazos

注意

本文档已过时，现在主要作为关于如何运行 torch.compile 缩小器的主要资源。请参阅更新的故障排除文档。还有一个更全面的 torch.compile 手册可供参考。

我们正在积极开发调试工具、分析器，并改进我们的错误和警告消息。下面是可用工具及其典型用法的表格。有关更多帮助，请参阅诊断运行时错误。

标题

工具	目的	用法
信息日志记录	查看编译的摘要步骤	torch._logging.set_logs(dynamo = logging.INFO) 或 TORCH_LOGS="dynamo"
调试日志记录	查看编译的详细步骤（打印每个跟踪的指令）	torch._logging.set_logs(dynamo = logging.DEBUG) 和 torch._dynamo.config.verbose = True，或 TORCH_LOGS="+dynamo" TORCHDYNAMO_VERBOSE=1
任何后端的缩小器	查找重现任何后端错误的最小子图	设置环境变量 TORCHDYNAMO_REPRO_AFTER="dynamo"
TorchInductor 的缩小器	如果已知错误发生在 AOTAutograd 之后，则查找在 TorchInductor 降低期间重现错误的最小子图	设置环境变量 TORCHDYNAMO_REPRO_AFTER="aot"
Dynamo 精度缩小器	当您怀疑问题出在 AOTAutograd 中时，查找重现 eager 模式模型和优化模型之间精度问题的最小子图	TORCHDYNAMO_REPRO_AFTER="dynamo" TORCHDYNAMO_REPRO_LEVEL=4
Inductor 精度缩小器	当您怀疑问题出在后端（例如 inductor）中时，查找重现 eager 模式模型和优化模型之间精度问题的最小子图。如果这不起作用，请尝试 Dynamo 精度缩小器。	TORCHDYNAMO_REPRO_AFTER="aot" TORCHDYNAMO_REPRO_LEVEL=4
torch._dynamo.explain	查找图中断并显示其原因	torch._dynamo.explain(fn)(*inputs)
记录/重放	记录和重放帧，以重现图捕获期间的错误	torch._dynamo.config.replay_record_enabled = True
TorchDynamo 函数名称过滤	仅编译具有给定名称的函数，以减少调试问题时的噪声	设置环境变量 TORCHDYNAMO_DEBUG_FUNCTION=<name>
TorchInductor 调试日志记录	打印常规 TorchInductor 调试信息和生成的 Triton/C++ 代码	torch._inductor.config.debug = True
TorchInductor 跟踪	显示每个 TorchInductor 阶段所花费的时间 + 输出代码和图可视化	设置环境变量 TORCH_COMPILE_DEBUG=1 或 torch._inductor.config.trace.enabled = True

除了信息和调试日志记录外，您还可以使用 torch._logging 进行更细粒度的日志记录。

诊断运行时错误

在高层次上，TorchDynamo 堆栈由来自 Python 代码的图捕获 (TorchDynamo) 和后端编译器组成。例如，后端编译器可能由后向图跟踪 (AOTAutograd) 和图降低 (TorchInductor)* 组成。错误可能发生在堆栈的任何组件中，并将提供完整的堆栈跟踪。

要确定错误发生在哪个组件中，您可以使用信息级别日志记录 torch._logging.set_logs(dynamo = logging.INFO) 或 TORCH_LOGS="dynamo" 并查找 Step #: ... 输出。日志在每个步骤的开始和结束时生成，因此错误应对应的步骤是最近记录的且尚未记录其结束的步骤。这些步骤对应于堆栈的以下部分

步骤	组件
1	TorchDynamo
2	编译器后端
3	TorchInductor

如果信息日志记录不足，您可以使用可用的后端选项。这些选项包括

• "eager"：仅运行 TorchDynamo 前向图捕获，然后使用 PyTorch 运行捕获的图。这提供了 TorchDynamo 是否引发错误的指示。

• "aot_eager"：运行 TorchDynamo 以捕获前向图，然后运行 AOTAutograd 以跟踪后向图，而无需任何额外的后端编译器步骤。然后将使用 PyTorch eager 模式运行前向图和后向图。这有助于将问题缩小到 AOTAutograd。

缩小问题范围的一般步骤如下

1. 使用 "eager" 后端运行您的程序。如果错误不再发生，则问题出在正在使用的后端编译器中（如果使用 TorchInductor，请继续执行步骤 2。否则，请参阅本节）。如果使用 "eager" 后端时错误仍然发生，则这是运行 torchdynamo 时的错误。

2. 仅当 TorchInductor 用作后端编译器时，此步骤才是必要的。使用 "aot_eager" 后端运行模型。如果此后端引发错误，则错误发生在 AOTAutograd 跟踪期间。如果使用此后端时错误不再发生，则错误在 TorchInductor* 中。

以下各节分析了每种情况。

注意

TorchInductor 后端由 AOTAutograd 跟踪和 TorchInductor 编译器本身组成。我们将通过将 TorchInductor 称为后端来消除歧义，并将 TorchInductor 降低称为降低 AOTAutograd 跟踪的图的阶段。

Torchdynamo 错误

如果生成的错误在使用 "eager" 后端时发生，则 TorchDynamo 最有可能是错误的来源。以下是生成错误的代码示例。

import torch

import torch._dynamo as dynamo


def test_assertion_error():
    y = torch.ones(200, 200)
    z = {y: 5}
    return z

compiled_test_assertion_error = torch.compile(test_assertion_error, backend="eager")

compiled_test_assertion_error()

上面的代码生成以下错误

torch._dynamo.convert_frame: [ERROR] WON'T CONVERT test_assertion_error /scratch/mlazos/torchdynamo/../test/errors.py line 26
due to:
Traceback (most recent call last):
  File "/scratch/mlazos/torchdynamo/torchdynamo/symbolic_convert.py", line 837, in BUILD_MAP
    assert isinstance(k, ConstantVariable) or (
AssertionError

from user code:
   File "/scratch/mlazos/torchdynamo/../test/errors.py", line 34, in test_assertion_error
    z = {y: 5}

Set torch._dynamo.config.verbose=True for more information
==========

正如消息建议的那样，您可以设置 torch._dynamo.config.verbose=True 以获取 TorchDynamo 和用户代码中错误的完整堆栈跟踪。除了此标志之外，您还可以通过 torch._logging.set_logs(dynamo = logging.INFO) 或 TORCH_LOGS="dynamo" 设置 TorchDynamo 的 log_level。这些级别包括

• logging.DEBUG 或 TORCH_LOGS="+dynamo"：除了下面列出的所有日志级别外，还打印遇到的每个指令。

• logging.INFO：除了下面列出的所有日志级别外，还打印编译的每个函数（原始字节码和修改后的字节码）以及捕获的图。

• logging.WARNING（默认）：除了下面列出的所有日志级别外，还打印图中断。

• logging.ERROR：仅打印错误。

如果模型非常大，日志可能会变得难以承受。如果错误发生在模型 Python 代码的深处，则仅执行发生错误的帧以方便调试可能很有用。有两种工具可用于实现此目的

• 将环境变量 TORCHDYNAMO_DEBUG_FUNCTION 设置为所需的函数名称将仅对具有该名称的函数运行 torchdynamo。

• 启用记录/重放工具（设置 torch._dynamo.config.replay_record_enabled = True），该工具会在遇到错误时转储执行记录。然后可以重放此记录以仅运行发生错误的帧。

诊断 TorchInductor 错误

如果错误不使用 "eager" 后端发生，则后端编译器是错误的来源（错误示例）。TorchDynamo 的后端编译器有不同的选择，其中 TorchInductor 满足大多数用户的需求。本节重点介绍 TorchInductor 作为动机示例，但某些工具也可以与其他后端编译器一起使用。

下面是我们关注的堆栈部分

使用 TorchInductor 作为选定的后端，AOTAutograd 用于从 torchdynamo 捕获的前向图生成后向图。重要的是要注意，错误可能在此跟踪期间发生，也可能在 TorchInductor 将前向图和后向图降低为 GPU 代码或 C++ 时发生。一个模型通常可以包含数百或数千个 FX 节点，因此缩小发生问题的确切节点可能非常困难。幸运的是，有一些工具可以自动缩小这些输入图，使其仅包含导致问题的节点。第一步是确定错误是在使用 AOTAutograd 跟踪后向图期间发生，还是在 TorchInductor 降低期间发生。如上面的步骤 2 中所述，可以使用 "aot_eager" 后端来仅隔离运行 AOTAutograd，而无需降低。如果使用此后端时错误仍然发生，则表明错误发生在 AOTAutograd 跟踪期间。

这是一个例子

import torch

import torch._dynamo as dynamo

model = torch.nn.Sequential(*[torch.nn.Linear(200, 200) for _ in range(5)])

def test_backend_error():

    y = torch.ones(200, 200)
    x = torch.ones(200, 200)
    z = x + y
    a = torch.ops.aten._foobar(z)  # dummy function which errors
    return model(a)


compiled_test_backend_error = torch.compile(test_backend_error, backend="inductor")
compiled_test_backend_error()

运行此代码应为您提供此错误，并在其下方显示更长的堆栈跟踪

Traceback (most recent call last):
  File "/scratch/mlazos/torchdynamo/torchinductor/graph.py", line 246, in call_function
    return lowerings[target](*args, **kwargs)
  File "/scratch/mlazos/torchdynamo/torchinductor/lowering.py", line 185, in wrapped
    return decomp_fn(*args, **kwargs)
  File "/scratch/mlazos/torchdynamo/torchinductor/lowering.py", line 810, in _foobar
    assert False
AssertionError
...

错误以及完整的堆栈跟踪

如果您然后将 torch.compile(backend="inductor") 更改为 torch.compile(backend="aot_eager")，它将无错误运行，因为问题出在 TorchInductor 降低过程中，而不是在 AOTAutograd 中。

缩小 TorchInductor 错误

从这里开始，让我们运行缩小器以获得最小的重现。设置环境变量 TORCHDYNAMO_REPRO_AFTER="aot" （或直接设置 torch._dynamo.config.repro_after="aot"）将生成一个 Python 程序，该程序将 AOTAutograd 生成的图缩小到重现错误的最小子图。（有关我们缩小 TorchDynamo 生成的图的示例，请参见下文）使用此环境变量运行程序应显示几乎相同的输出，并附加一行指示 minifier_launcher.py 已写入的位置。可以通过将 torch._dynamo.config.base_dir 设置为有效的目录名称来配置输出目录。最后一步是运行缩小器并检查它是否成功运行。成功运行看起来像这样。如果缩小器成功运行，它将生成可运行的 python 代码，该代码重现完全相同的错误。对于我们的示例，这是以下代码

import torch
from torch import tensor, device
import torch.fx as fx
from torch._dynamo.testing import rand_strided
from math import inf
from torch.fx.experimental.proxy_tensor import make_fx

# torch version: 1.13.0a0+gitfddfc44
# torch cuda version: 11.6
# torch git version: fddfc4488afb207971c54ad4bf58130fdc8a4dc5


# CUDA Info:
# nvcc: NVIDIA (R) Cuda compiler driver
# Copyright (c) 2005-2022 NVIDIA Corporation
# Built on Thu_Feb_10_18:23:41_PST_2022
# Cuda compilation tools, release 11.6, V11.6.112
# Build cuda_11.6.r11.6/compiler.30978841_0

# GPU Hardware Info:
# NVIDIA A100-SXM4-40GB : 8

from torch.nn import *

class Repro(torch.nn.Module):
    def __init__(self):
        super().__init__()

    def forward(self, add):
        _foobar = torch.ops.aten._foobar.default(add);  add = None
        return (_foobar,)

args = [((200, 200), (200, 1), torch.float32, 'cpu')]
args = [rand_strided(shape, stride, dtype, device) for shape, stride, dtype, device in args]
mod = make_fx(Repro())(*args)
from torch._inductor.compile_fx import compile_fx_inner

compiled = compile_fx_inner(mod, args)
compiled(*args)

Repro 模块的 forward 方法包含导致问题的确切算子。提交问题时，请包含任何缩小的重现示例，以帮助调试。

缩小后端编译器错误

对于 TorchInductor 以外的后端编译器，查找导致错误的子图的过程与TorchInductor 中的错误中的过程几乎相同，但有一个重要的注意事项。即，缩小器现在将在 TorchDynamo 跟踪的图上运行，而不是 AOTAutograd 的输出图。让我们来看一个例子。

import torch

import torch._dynamo as dynamo

model = torch.nn.Sequential(*[torch.nn.Linear(200, 200) for _ in range(5)])
# toy compiler which fails if graph contains relu
def toy_compiler(gm: torch.fx.GraphModule, _):
    for node in gm.graph.nodes:
        if node.target == torch.relu:
            assert False

    return gm


def test_backend_error():
    y = torch.ones(200, 200)
    x = torch.ones(200, 200)
    z = x + y
    a = torch.relu(z)
    return model(a)


compiled_test_backend_error = torch.compile(test_backend_error, backend=toy_compiler)
compiled_test_backend_error()

为了在 TorchDynamo 跟踪前向图后运行代码，您可以使用 TORCHDYNAMO_REPRO_AFTER 环境变量。使用 TORCHDYNAMO_REPRO_AFTER="dynamo" （或 torch._dynamo.config.repro_after="dynamo"）运行此程序应生成此输出以及 {torch._dynamo.config.base_dir}/repro.py 中的以下代码。

注意

TORCHDYNAMO_REPRO_AFTER 的另一个选项是 "aot"，它将在生成后向图后运行缩小器。

import torch
import torch._dynamo as dynamo
from torch import tensor, device
import torch.fx as fx
from torch._dynamo.testing import rand_strided
from math import inf
from torch._dynamo.debug_utils import run_fwd_maybe_bwd

from torch.nn import *

class Repro(torch.nn.Module):
    def __init__(self):
        super().__init__()

    def forward(self, add):
        relu = torch.relu(add);  add = None
        return (relu,)


mod = Repro().cuda()
opt_mod = torch.compile(mod, backend="None")


args = [((200, 200), (200, 1), torch.float32, 'cpu', False)]
args = [rand_strided(sh, st, dt, dev).requires_grad_(rg) for (sh, st, dt, dev, rg) in args]


with torch.cuda.amp.autocast(enabled=False):
    ref = run_fwd_maybe_bwd(mod, args)
    res = run_fwd_maybe_bwd(opt_mod, args)

缩小器成功地将图缩小到在 toy_compiler 中引发错误的算子。与TorchInductor 错误中的过程的另一个区别是，在遇到后端编译器错误后，缩小器会自动运行。成功运行后，缩小器会将 repro.py 写入 torch._dynamo.config.base_dir。

性能分析

访问 TorchDynamo 分析器

TorchDynamo 具有内置的统计函数，用于收集和显示每个编译阶段花费的时间。可以通过在执行 Torch._Dynamo 后调用 torch._dynamo.utils.compile_times() 来访问这些统计信息。默认情况下，这会返回一个字符串表示形式，其中包含每个 TorchDynamo 函数按名称花费的编译时间。

使用 TORCH_COMPILE_DEBUG 进行 TorchInductor 调试

TorchInductor 具有内置的统计和跟踪函数，用于显示每个编译阶段花费的时间、输出代码、输出图可视化和 IR 转储。这是一个调试工具，旨在使理解和排除 TorchInductor 内部结构的问题更加容易。

让我们使用以下测试程序 (repro.py) 运行一个示例

import torch

@torch.compile()
def test_model(x):
    model = torch.nn.Sequential(
        torch.nn.Linear(10, 10),
        torch.nn.LayerNorm(10),
        torch.nn.ReLU(),
    )
    return model(x)


y = test_model(torch.ones(10, 10))

设置环境变量 TORCH_COMPILE_DEBUG=1 将导致创建调试跟踪目录，默认情况下，此目录将位于当前目录中，并命名为 torch_compile_debug（可以在 torchdynamo 配置字段 debug_dir_root 和 env var TORCH_COMPILE_DEBUG_DIR 中覆盖此目录）。在此目录中，每次运行都会有一个单独的文件夹，以运行的时间戳和进程 ID 命名

$ env TORCH_COMPILE_DEBUG=1 python repro.py
$ cd torch_compile_debug
$ ls
run_2023_03_01_08_20_52_143510-pid_180167

在运行文件夹中，将有一个 torchdynamo 目录，其中包含调试日志，以及一个 torchinductor 文件夹，其中包含每个已编译内核的子文件夹，其中包含 inductor 调试工件。

$ cd
run_2023_03_01_08_20_52_143510-pid_180167
$ ls
torchinductor  torchdynamo

进一步进入 torchinductor 目录，\*.log 文件是来自编译的 AOT Autograd 阶段的日志，model__0_forward_1.0 包含 inductor 调试工件。

$ cd torchinductor
$ ls
aot_model___0_debug.log  model__0_forward_1.0
$ cd model__0_forward_1.0
$ ls
debug.log  fx_graph_readable.py  fx_graph_runnable.py  fx_graph_transformed.py  ir_post_fusion.txt  ir_pre_fusion.txt  output_code.py

以下是内容摘要

• fx_graph_readable.py 和 fx_graph_runnable.py 是 inductor 接收的 fx_graph 的可读和可运行版本。

• fx_graph_transformed.py 是 inductor 运行所有 fx 传递后的 fx 图。

• ir\*.txt 是融合前后的 inductor ir。

• output_code.py 是子图的已编译 Triton 内核。

以下是测试程序的调试目录内容示例

import torch

@torch.compile()
def test_model(x):
    model = torch.nn.Sequential(
        torch.nn.Linear(10, 10),
        torch.nn.LayerNorm(10),
        torch.nn.ReLU(),
    )
    return model(x)


y = test_model(torch.ones(10, 10))

该调试跟踪中的每个文件都可以通过 torch._inductor.config.trace.* 启用和禁用。默认情况下，配置文件和图表都处于禁用状态，因为它们生成成本很高。

此新调试格式中的单个节点如下所示

buf1: SchedulerNode(ComputedBuffer)
buf1.writes =
    {   MemoryDep(name='buf1', index=0, size=()),
        MemoryDep(name='buf1', index=0, size=(s0,))}
buf1.unmet_dependencies = {MemoryDep(name='buf0', index=c0, size=(s0,))}
buf1.met_dependencies = {MemoryDep(name='primals_2', index=c0, size=(s0,))}
buf1.group.device = cuda:0
buf1.group.iteration = (1, s0)
buf1.sizes = ([], [s0])
class buf1_loop_body:
    var_ranges = {z0: s0}
    index0 = z0
    index1 = 0
    def body(self, ops):
        get_index = self.get_index('index0')
        load = ops.load('buf0', get_index, False)
        get_index_1 = self.get_index('index0')
        load_1 = ops.load('primals_2', get_index_1, False)
        add = ops.add(load, load_1)
        get_index_2 = self.get_index('index1')
        reduction = ops.reduction('buf1', torch.float32, torch.float32, 'sum', get_index_2, add)
        return reduction

有关更多示例，请参见调试目录输出示例。

图中断

给定如下程序

def some_fun(x):
    ...

compiled_fun = torch.compile(some_fun, ...)
...

TorchDynamo 将尝试将 some_fun 中的所有 torch/tensor 操作编译到单个 FX 图中，但它可能无法将所有内容捕获到一个图中。

对于 TorchDynamo 来说，一些图中断原因是无法克服的，并且无法轻易修复。 - 调用 torch 以外的 C 扩展对 torchdynamo 是不可见的，并且可能会执行任意操作，而 TorchDynamo 无法引入必要的保护（请参阅使 Dynamo 可靠：保护）以确保编译后的程序可以安全地重用。如果生成的片段很小，图中断可能会阻碍性能。为了最大限度地提高性能，尽可能减少图中断非常重要。

识别图中断的原因

要识别程序中的所有图中断以及中断的相关原因，可以使用 torch._dynamo.explain。此工具在提供的函数上运行 TorchDynamo，并聚合遇到的图中断。以下是用法示例

import torch
import torch._dynamo as dynamo
def toy_example(a, b):
    x = a / (torch.abs(a) + 1)
    print("woo")
    if b.sum() < 0:
        b = b * -1
    return x * b
explanation = dynamo.explain(toy_example)(torch.randn(10), torch.randn(10))
print(explanation_verbose)
"""
Graph Count: 3
Graph Break Count: 2
Op Count: 5
Break Reasons:
  Break Reason 1:
    Reason: builtin: print [<class 'torch._dynamo.variables.constant.ConstantVariable'>] False
    User Stack:
      <FrameSummary file foo.py, line 5 in toy_example>
  Break Reason 2:
    Reason: generic_jump TensorVariable()
    User Stack:
      <FrameSummary file foo.py, line 6 in torch_dynamo_resume_in_toy_example_at_5>
Ops per Graph:
  ...
Out Guards:
  ...
"""

输出包括

• out_guards - 列表的列表，其中每个子列表包含必须通过的保护，以确保跟踪的图有效。

• graphs - 成功跟踪的图模块列表。

• ops_per_graph - 列表的列表，其中每个子列表包含在图中运行的算子。

要在遇到的第一个图中断时抛出错误，请使用 fullgraph 模式。此模式禁用 TorchDynamo 的 Python 回退，并且仅当整个程序可转换为单个图时才成功。用法示例

def toy_example(a, b):
   ...

compiled_toy = torch.compile(toy_example, fullgraph=True, backend=<compiler>)(a, b)

过度重新编译

当 TorchDynamo 编译函数（或函数的一部分）时，它会对局部变量和全局变量做出某些假设，以便允许编译器优化，并将这些假设表示为保护，这些保护在运行时检查特定值。如果任何这些保护失败，Dynamo 将重新编译该函数（或部分函数），最多 torch._dynamo.config.cache_size_limit 次。如果您的程序达到缓存限制，您首先需要确定哪个保护失败以及程序的哪个部分触发了它。

如果您的程序表现出有限的动态性，您或许可以调整 TorchDynamo 缓存限制，以允许编译和缓存每个变体，但如果缓存限制过高，您可能会发现重新编译的成本超过了任何优化优势。

torch._dynamo.config.cache_size_limit = <your desired cache limit>

TorchDynamo 计划支持动态张量形状的许多常见情况，例如变化的批大小或序列长度。它不计划支持秩动态性。与此同时，可以将特定缓存限制与分桶技术结合使用，以实现某些动态模型的可接受的重新编译次数。

精度调试

如果设置环境变量 TORCHDYNAMO_REPRO_LEVEL=4，也可以缩小精度问题，它以类似于 git bisect 模型的方式运行，完整的重现可能类似于 TORCHDYNAMO_REPRO_AFTER="aot" TORCHDYNAMO_REPRO_LEVEL=4，我们需要这样做的原因是下游编译器将生成代码，无论是 Triton 代码还是 C++ 后端，这些下游编译器的数值可能以微妙的方式不同，但对您的训练稳定性产生巨大影响。因此，精度调试器对于我们检测代码生成或后端编译器中的错误非常有用。

如果您想确保 torch 和 triton 之间的随机数生成相同，则可以启用 torch._inductor.config.fallback_random = True

扩展调试

可以使用以下实验性标志启用扩展调试。

TORCHDYNAMO_EXTENDED_DEBUG_GUARD_ADDED - 提供扩展调试信息，如果 guard 的字符串表示形式与此标志值匹配。例如，将其设置为 “Ne(s0, 10)” 以在发出 guard 时生成完整的 Python 和 C++ 回溯。TORCHDYNAMO_EXTENDED_DEBUG_CREATE_SYMBOL - 当分配特定符号时，提供扩展调试信息。例如，将其设置为 “u2” 以在创建此符号时生成完整的 Python 和 C++ 回溯。TORCHDYNAMO_EXTENDED_DEBUG_CPP - 为所有扩展调试设置以及错误提供扩展调试信息（C++ 回溯）。例如，将其设置为 “1”。C++ 回溯速度较慢且非常繁琐，因此默认情况下不包含在扩展调试中。

冷启动计时和缓存损坏调试

为了测量冷启动编译时间或调试缓存损坏，可以传递 TORCHINDUCTOR_FORCE_DISABLE_CACHES=1 或设置 torch._inductor.config.force_disable_caches = True，这将覆盖任何其他缓存配置选项并禁用所有编译时缓存。