PyTorch AOTInductor CUDA 非法内存访问（IMA）调试指南：从可复现定位到中间值排查

PyTorch AOTInductor CUDA 非法内存访问（IMA）调试指南：从可复现定位到中间值排查

【免费下载链接】pytorchTensors and Dynamic neural networks in Python with strong GPU acceleration项目地址: https://gitcode.com/GitHub_Trending/py/pytorch

AOT Inductor 是 PyTorch 2.x PT2 技术栈中面向 C++ 部署环境的编译后端：它与torch.compile共享同一套 Inductor 代码生成逻辑，但产出的是可直接在纯 C++ 环境中链接加载的编译产物。当你在使用 AOT Inductor 时遇到CUDA illegal memory access（IMA）错误——这类错误常以非确定性、时隐时现的方式出现，甚至有时程序正常退出但数值早已悄悄出错——本指南提供了从"基础健全性检查"到"逐 kernel 中间值审查"的系统化排查路径。读完本文，你将掌握 AOTI 调试中三个关键环境变量组合的用法、可复现 IMA 的确定性触发手段，以及利用 Intermediate Value Debugger 精确定位问题 kernel 的完整工作流。

AOT Inductor 与 CUDA IMA 调试的整体思路

AOT Inductor（常缩写为 AOTI）是 PT2（PyTorch 2）编译栈的一部分，与torch.compile类似，但它生成的是一份可以在C++ 环境中运行的编译产物（shared library + 导出模型结构），而非依赖 Python 运行时。由于其产物直接以裸 kernel 调用的形式执行，一旦出现越界写、野指针等内存错误，往往表现为 CUDA IMA——而这类错误可能非确定性地出现在不同位置，甚至偶尔完全不出现（不出现只是意味着数值已静默错误）。

针对这一特性，官方调试指南将排查过程划分为三个高层步骤，本文即按此骨架展开：

1. Sanity checks（健全性检查）：先用现成的调试开关快速排除常见问题；
2. Pinpoint the CUDA IMA（锁定错误位置）：让非确定性错误变得可复现、可定位；
3. Identify problematic kernels（识别问题 kernel）：用中间值调试器检查 kernel 的输入与输出。

Step 1：健全性检查——先用两个编译期开关探路

在投入精力做可靠复现之前，先尝试已有的调试标志：

AOTI_RUNTIME_CHECK_INPUTS=1 TORCHINDUCTOR_NAN_ASSERTS=1

这两个开关在编译期（更精确地说是代码生成阶段）生效：

• AOTI_RUNTIME_CHECK_INPUTS=1：在运行时检查输入是否满足编译期间使用的同一组 guard（形状/步幅守卫）。从源码看，该开关与 AOTI 配置中的 lowerbound/upperbound 动态形状约束检查协同工作：torch/_inductor/config.py中check_lowerbound（默认True，检查[2+, ...]下界约束）与check_upperbound（默认True，根据 lowering 输入与动态形状规格推断上界）两项配置共同决定了运行时对动态形状边界的校验强度（见 config.py）。这一开关主要用于确认"输入是否合法"，从而把动态形状越界类问题提前暴露出来。
• TORCHINDUCTOR_NAN_ASSERTS=1：在每个 Inductor kernel 的前后插入 NaN 检查代码，用于快速发现数值异常（NaN/Inf）从哪个 kernel 开始产生。源码中对应nan_asserts = os.environ.get("TORCHINDUCTOR_NAN_ASSERTS") == "1"（见 config.py）。

提示：若只想针对 Triton kernel 做运行时 NaN 检查，仓库还提供TORCHINDUCTOR_RUNTIME_TRITON_NAN_ASSERTS=1的独立开关（见 config.py）。此外还有一组兄弟开关如TORCHINDUCTOR_SIZE_ASSERTS（默认开启，生成代码中放置形状断言）与TORCHINDUCTOR_SCALAR_ASSERTS（默认开启，放置符号范围断言），可作为健全性检查的补充（见 config.py）。

Step 2：锁定 CUDA IMA——让非确定性错误变得可复现

CUDA IMA 调试最难的部分在于它的非确定性：错误可能发生在不同位置，有时干脆不发生（尽管数值已经错乱）。罪魁祸首通常是 PyTorch 的Caching Allocator：它为了减少显存分配次数，会一次性分配比实际需求更大的缓冲区并缓存复用，这会让"越界写恰好落在缓存池内部未使用区域"从而掩盖错误。

用以下两个运行时开关可以把错误变为确定性触发：

PYTORCH_NO_CUDA_MEMORY_CACHING=1 CUDA_LAUNCH_BLOCKING=1

Figure: 启用 Caching Allocator 时，越界访问落在已分配缓存块内部的空闲区域（illegal memory access但不抛错，标注no error）；禁用后同一越界访问将直接触发错误（will throw an error）。

• PYTORCH_NO_CUDA_MEMORY_CACHING=1：禁用 PyTorch Caching Allocator。由于分配行为退化为"用多少、分配多少"，越界访问不再被预分配的大块缓冲区掩盖，错误得以稳定暴露——这正是 IMA 非确定性的最常见来源。
• CUDA_LAUNCH_BLOCKING=1：强制 kernel逐个同步启动。若不加此开关，异步启动的 kernel 会带来著名的"CUDA kernel errors might be asynchronously reported at some other API call"警告——错误报告位置与实际出错 kernel 完全错位，导致无法定位。

注意这两个开关在运行时生效（AOTI_RUNTIME_CHECK_INPUTS与TORCHINDUCTOR_NAN_ASSERTS则在编译/codegen 期生效），因此应在加载并执行编译产物（如 AOTI 生成的.so）的程序运行环境中设置。

Step 3：用 Intermediate Value Debugger 识别问题 Kernel

拿到确定性复现后，下一步是精确定位出错 kernel并检查其输入输出。AOTI 提供了专门的Intermediate Value Debugger（中间值调试器）。

3.1 先打印 kernel 名称序列，锁定"出错前最后启动的 kernel"

AOT_INDUCTOR_DEBUG_INTERMEDIATE_VALUE_PRINTER=3

该开关在编译期生效，会在运行时逐个打印被启动的 kernel 名称。配合 Step 2 的两个运行时开关，你就能知道错误发生前刚启动的是哪个 kernel。

从源码看，该开关对应 AOTI 配置中的debug_intermediate_value_printer环境变量（见 config.py），取值分四级：

取值	行为
0	关闭调试输出（默认）
1	保存中间张量值
2	打印中间张量值
3	仅打印 kernel 名称（用于锁定可疑 kernel）

代码生成侧的实现位于torch/_inductor/codegen/debug_utils.py：IntermediateValueDebuggingLevel枚举定义了PRINT_ONLY = "2"与PRINT_KERNEL_NAMES_ONLY = "3"两个级别，其中级别 3 只输出 kernel 名而不输出张量内容（见 debug_utils.py），并相应提供codegen_intermediate_tensor_value_save/codegen_intermediate_tensor_value_print等代码生成钩子（见 debug_utils.py）。

3.2 检查可疑 kernel 的输入

必须强调：错误发生在某个 kernel，不代表这个 kernel 本身有问题。很可能是更早的某个 kernel 产生了错误输出，只是错误直到后续 kernel 访问这块内存时才暴露。因此下一步是检查可疑 kernel 的输入是否符合预期：

AOT_INDUCTOR_FILTERED_KERNELS_TO_PRINT="triton_poi_fused_add_ge_logical_and_logical_or_lt_231,_add_position_embeddings_kernel_5" AOT_INDUCTOR_DEBUG_INTERMEDIATE_VALUE_PRINTER=2

• AOT_INDUCTOR_FILTERED_KERNELS_TO_PRINT：指定想检查的 kernel 名称列表（逗号分隔）。源码中该变量会被解析成小写列表，逐个与 kernel 名做包含匹配（见 debug_utils.py）；当级别为 2 且当前 kernel 不在过滤列表中时，会跳过打印（见 debug_utils.py），避免海量输出淹没关键信息。
• AOT_INDUCTOR_DEBUG_INTERMEDIATE_VALUE_PRINTER=2：开启中间值打印，配合过滤列表只输出目标 kernel 的输入/输出张量信息（形状、数值等）。

如果发现该 kernel 的输入不符合预期，就继续向上游追溯：检查产生该输入的那个 kernel（回到 3.1 的 kernel 名称序列，找到对应的前驱 kernel，用同样的过滤 + 打印流程复查其输出），如此沿数据依赖链逐级回溯，直到找到第一个产生错误数值/越界访问的源头 kernel。

补充调试工具

日志与追踪

• tlparse / TORCH_TRACE：提供完整的输出代码供人工检查，并记录编译期使用的 guard 集合。AOTI 的 guard 信息对动态形状类 IMA 尤其重要，因为运行时输入若不满足编译期 guard 就可能引发内存错误。
• TORCH_LOGS：使用TORCH_LOGS="+inductor,output_code"查看更详细的 PT2 内部日志，其中output_code会输出 Inductor 生成的实际 kernel 代码——配合上文 kernel 名序列，可以直接核对每个 kernel 的索引计算与边界条件。
• TORCH_SHOW_CPP_STACKTRACES：设置TORCH_SHOW_CPP_STACKTRACES=1可尝试获得更完整的 C++ 调用栈，帮助在崩溃时定位到具体代码路径。

常见问题来源

• 动态形状（Dynamic shapes）：历史上一大 IMA 来源。动态形状下符号边界（Symbolic bounds）推断不准确、guard 未覆盖实际输入范围，都容易导致越界。调试动态形状场景时需格外关注 Step 1 的AOTI_RUNTIME_CHECK_INPUTS与 AOTI 配置中的check_lowerbound/check_upperbound行为。深入理解动态形状的语义与约束可参考仓库中的 动态形状指南。
• 自定义算子（Custom ops）：尤其是用 C++ 实现且配合动态形状使用的自定义算子。此时需要将 meta functionSymint'ify（即把元函数中涉及形状的参数从普通 int 改为 SymInt），否则符号形状信息无法正确传递，下游 kernel 的边界计算就可能出错。

排查流程速查表

阶段	目标	关键环境变量	生效时机
Step 1 健全性检查	快速排除输入/数值异常	AOTI_RUNTIME_CHECK_INPUTS=1、TORCHINDUCTOR_NAN_ASSERTS=1	编译期（codegen）
Step 2 锁定错误	让 IMA 确定性复现并同步启动	PYTORCH_NO_CUDA_MEMORY_CACHING=1、CUDA_LAUNCH_BLOCKING=1	运行时
Step 3 定位 kernel	打印 kernel 启动序列	AOT_INDUCTOR_DEBUG_INTERMEDIATE_VALUE_PRINTER=3	编译期
Step 3 检查中间值	审查指定 kernel 的输入输出	AOT_INDUCTOR_FILTERED_KERNELS_TO_PRINT=...+AOT_INDUCTOR_DEBUG_INTERMEDIATE_VALUE_PRINTER=2	编译期

整体工作流可概括为：先用编译期开关做健全性检查 → 用运行时开关把非确定错误变确定 → 用级别 3 打印 kernel 序列锁定出错位置 → 用级别 2 + 过滤列表沿数据依赖链向上回溯，直到找到真正产生坏数据的源头 kernel。对于动态形状与 C++ 自定义算子这两类高发场景，还需结合 guard 检查与 SymInt 化改造加以防范。相关实现与配置可直接在 config.py 与 debug_utils.py 中继续深入研读。

【免费下载链接】pytorchTensors and Dynamic neural networks in Python with strong GPU acceleration项目地址: https://gitcode.com/GitHub_Trending/py/pytorch