人工智能模型编译Ascend【免费下载链接】torchairTorchAir 支持用户基于PyTorch框架和torch_npu插件在昇腾NPU上使用图模式进行推理。项目地址https://gitcode.com/Ascend/torchair点击查看免费下载导读图模式编译在问题定位时往往面临黑盒困境一次编译经过 Dynamo 追踪、AOT Autograd 分区、多轮 Pass 优化与 aclgraph 捕获任何一个环节出错都难以还原现场。TorchAir 的 npugraph_ex 通过复用 PyTorch 原生TORCH_COMPILE_DEBUG环境变量提供了一键式的图编译 Debug 信息保存能力只要设置该环境变量为 1即可自动收集 Dynamo 日志、npugraph_ex 日志、AOT 前后 GraphModule、每个 Pass 处理后的 FX 图、编译后的图结构代码以及模型运行实例 JSON 等关键调试产物。阅读本文后你将掌握该功能的开启方式、产物目录结构与每个文件的含义并从源码层面理解日志级别初始化、分布式 rank 目录命名、Pass 图 Dump 等底层实现原理能够在昇腾 NPU 图模式推理的问题定位中快速收集完整现场。功能简介为方便问题定位过程中的信息收集npugraph_ex 通过复用 PyTorch原生 DEBUG 环境变量TORCH_COMPILE_DEBUG当其设置为 1 时将自动开启所有必要的日志打印与文件 Dump无需再单独配置任何 npugraph_ex 专属调试开关。这种设计在 npugraph_ex/design_principles.md 中被明确为设计原则——复用 PyTorch 原生基础设施通过 PyTorch 原生的TORCH_COMPILE_DEBUG环境变量和torch._dynamo.utils.get_debug_dir()函数驱动不引入独立的调试开关用户获得与社区一致的调试体验。开启本功能后图编译过程中能自动收集的关键调试信息如下图所示详细说明参见下表。图编译示意图开启 TORCH_COMPILE_DEBUG 后图编译过程中自动收集的调试信息表 1 信息收集表| 信息类型 | 说明 | | -- | -- | | 日志信息 | PyTorch 原生 Dynamo 日志npugraph_ex 日志 | | Debug 信息 | AOT 前的 GraphModuleAOT 后的 GraphModule每个公共 Pass 处理后的 FX 图txt 文件aclgraph 优化中不同 Pass 处理后的 FX 图txt 文件aclgraph 编译后的 FX 图结构信息output_code.py 文件aclgraph 在 Capture 阶段捕获的模型运行实例信息原始*.json文件及用于可视化的*.aligned.json文件注意仅当配套的 CANN 版本是 8.5.0 及之后的版本才会有该文件生成否则不会生成。 |工作原理一个环境变量如何驱动全套调试收集TORCH_COMPILE_DEBUG1之所以能一次性触发日志打印、Pass 图 Dump、JSON 捕获等全链路调试能力是因为 npugraph_ex 的多处关键模块都在初始化或执行时读取该环境变量日志级别初始化在 npugraph_ex/npugraph_ex/core/utils.py 中npugraph_ex 的logger在模块导入阶段即根据环境变量确定级别为 1 时使用logging.DEBUG否则为logging.ERROR。这意味着环境变量必须在import npugraph_ex或import torchair之前设置否则debug.log文件不会创建。C 端日志联动C 侧 torchair/concrete_graph/tng_status.cpp 在库加载时读取TORCH_COMPILE_DEBUG若其值为1则将 TNGTorchAir NPU Graph日志级别设置为DEBUG否则为ERROR。由此可见该环境变量同时控制 Python 与 C 两个层面的日志详细程度。Debug 文件路径生成所有调试产物统一通过torch._dynamo.utils.get_debug_dir()获取基目录PyTorch 原生默认位于当前脚本路径下的torch_compile_debug/run_时间-pid_进程号再拼接npugraph_ex子目录。相关实现见 npugraph_ex/npugraph_ex/_utils/graph_transform_observer.py。分布式 rank 标注模块导入时npugraph_ex/npugraph_ex/core/utils.py 中的_set_dynamo_run_dir_name()会把get_debug_dir()替换为包装函数在torch.distributed已初始化时于运行目录名末尾追加-rank_rank_id后缀并通过_TORCHAIR_RUN_NAME_PATCHED标志保证补丁只执行一次幂等。此外所有落盘操作都会经过 npugraph_ex/npugraph_ex/_utils/path_manager.py 中PathManager的安全校验路径长度、软链接检测、字符白名单、目录/文件创建权限等避免调试产物写入过程中引入安全风险。使用约束使用该功能前需注意以下约束使用 compile_fx 开启该功能时不会收集 AOT 前的 GraphModule 文件dynamo_out_graph.txt。原因是该文件仅在 AOT 编译入口_compile_graph_with_aot()中生成见 npugraph_ex/npugraph_ex/npu_fx_compiler.py而compile_fx路径不经过 AOT 流程见 npugraph_ex/npugraph_ex/npu_fx_compiler.py。分布式场景下需在脚本开头import npugraph_ex确保 debug 目录能正确创建。这是因为 rank 后缀补丁_set_dynamo_run_dir_name与日志初始化都发生在模块导入阶段若先执行分布式初始化再导入模块补丁时机可能错过编译入口。使用方法在执行脚本前先在终端设置环境变量export TORCH_COMPILE_DEBUG1 python main.py假设待执行的脚本main.py代码如下该脚本的目标是实现简单的乘法开启 Dynamo 日志。设置图编译模式。构造一个随机输入设置dynamicFalse及requires_gradFalse执行了一次推理。import logging import torch import torch_npu # 开启Dynamo日志 torch._logging.set_logs(dynamologging.DEBUG, aotlogging.DEBUG, output_codeTrue, graph_codeTrue) class Model(torch.nn.Module): def forward(self, x): return 2 * x model Model().npu() model torch.compile(model, backendnpugraph_ex, dynamicFalse, fullgraphTrue) x torch.randn(20, 20, requires_gradFalse).npu() out model(x)运行示例脚本编译过程中必要的 Debug 信息产物目录结构如下仅供参考具体取决于实际开启的 Pass 数量。torch_compile_debug 为 PyTorch 原生开启环境变量时创建的目录默认在当前脚本路径下。分布式场景下运行目录名会在末尾追加-rank_rank_id例如torch_compile_debug/run_时间-pid_进程号-rank_rank_id。torch_compile_debug ├── run_时间-pid_进程号 │ ├── npugraph_ex │ │ ├── debug.log # npugraph_ex日志 │ │ ├── model__0 # model__0为模型ID │ │ │ ├── forward # 前向推理 │ │ │ │ ├── output_code.py # 编译后的图结构文件 │ │ │ │ ├── 000_aot_forward_graph.txt # AOT后的GraphModule │ │ │ │ ├── 001_aot_forward_graph_after_${pass1_name}.txt # 公共图优化过程中每个Pass的输出FX图 │ │ │ │ ├── 002_aot_forward_graph_after_${pass2_name}.txt │ │ │ │ ├── 003_aot_forward_graph_after_${pass5_name}.txt # aclgraph优化中不同pass处理后的FX图 │ │ │ │ ├── 004_aot_forward_graph_after_${pass6_name}.txt │ │ │ │ ├── ...... # 其他Pass优化 │ │ │ ├── dynamo_out_graph.txt # AOT前的GraphModule │ │ │ ├── graph_1_id_${aclgraph_id}_rank_${rank_id}_pid_${pid}_ts_${timestamp}.json # 捕获的模型运行实例原始JSON │ │ │ ├── graph_1_id_${aclgraph_id}_rank_${rank_id}_pid_${pid}_ts_${timestamp}.aligned.json # 对齐后的JSON用于可视化 │ └── torchdynamo │ └── debug.log # Torch原生Dynamo日志 └── ... # Torch原生其他产物[!NOTE]说明 模型运行实例信息通过 RuntimeaclmdlRIDebugJsonPrint接口获取其使用方法和说明详见《CANN Runtime 运行时 API》文档。产物目录与文件源码级解析上述目录结构中的每一类文件都可以在仓库源码中找到对应的生成逻辑debug.lognpugraph_ex 日志由 npugraph_ex/npugraph_ex/core/utils.py 中的_create_debug_log_paths()/_init_debug_logging()创建。日志格式包含进程号、解释器路径、毫秒/微秒级时间戳、文件名行号与线程 ID便于多进程、多线程场景下的问题定位。dynamo_out_graph.txtAOT 前 GraphModule在_compile_graph_with_aot()中通过dump_fx_safety(gm, ...)落盘见 npugraph_ex/npugraph_ex/npu_fx_compiler.py记录 Dynamo 追踪输出的原始 FX 图。000_aot_forward_graph.txtAOT 后 GraphModule及NNN_aot_forward_graph_after_${pass_name}.txt每个 Pass 处理后的 FX 图由 npugraph_ex/npugraph_ex/_utils/graph_transform_observer.py 中的GraphTransformObserver.apply_gm_pass()/dump_gm()生成。每个 Pass 执行后图会以{序号:03d}_aot_{phase}_graph_after_{pass_name}.txt的命名写入序号由类级计数器__file_count递增确保文件按 Pass 执行顺序排列内容为gm.print_readable(False)的可读图文本。该文件的生成受DebugContext阶段管理forward/backward/joint/compile_fx控制见同文件的wrap_compiler_phase()。output_code.py编译后的图结构文件由 npugraph_ex/npugraph_ex/npu_fx_compiler.py 中的_dump_run_codegen()生成。它把 codegen 产出的 Python 代码与if __name__ __main__: main()入口拼接后写入并附加文件锁与0o600权限方便单独回放执行。graph_1_id_${aclgraph_id}_rank_${rank_id}_pid_${pid}_ts_${timestamp}.json与.aligned.json在 aclgraph 的 Capture 阶段生成见 npugraph_ex/npugraph_ex/_acl_concrete_graph/acl_graph.py。文件名编码了 aclgraph ID、rank ID、进程号与 UTC 时间戳。其中原始*.json为捕获的模型运行实例信息*.aligned.json为对齐后的可视化数据。注意仅当配套 CANN 版本为 8.5.0 及之后时才会生成该文件。与死锁检查deadlock_check的联动值得说明的是模型运行实例 JSON 的 Dump 并不只服务于TORCH_COMPILE_DEBUG。在 npugraph_ex/npugraph_ex/_acl_concrete_graph/acl_graph.py 中只要满足enable_torch_compile_debug或配置项deadlock_check二者之一就会执行debug_dump()若开启了deadlock_check还会基于 Dump 出的 JSON 调用 npugraph_ex/npugraph_ex/_acl_concrete_graph/utils.py 中的run_deadlock_check()做通信算子的死锁检测。deadlock_check配置项定义于 npugraph_ex/npugraph_ex/configs/compiler_config.py默认值为False。测试验证仓库中的冒烟测试 npugraph_ex/tests/smoke/hcom_static_kernel_test.py 直接验证了本功能的两个关键行为在设置TORCH_COMPILE_DEBUG1后以torch.multiprocessing.spawn拉起多 rank 进程执行分布式图编译断言每个 rank 的运行目录都以-rank_rank_id后缀命名且npugraph_ex/debug.log文件真实存在。该测试用例可作为验证分布式场景下 Debug 目录与日志文件是否正常生成的参考。常见问题与使用建议环境变量设置时机TORCH_COMPILE_DEBUG必须在import npugraph_ex或import torchair之前设置否则日志级别在模块导入时已按默认值确定debug.log不会创建。compile_fx 产物差异使用compile_fxAPI 时不会生成dynamo_out_graph.txtAOT 前 FX 图因为该路径不经过_compile_graph_with_aot()。分布式目录命名分布式场景下运行目录名为torch_compile_debug/run_时间-pid_进程号-rank_rank_id可通过目录名快速区分不同 rank 的调试产物。定位思路排查问题时建议按npugraph_ex 日志debug.log→ Dynamo 日志torchdynamo/debug.log→ Pass 序列 FX 图NNN_aot_forward_graph_after_*.txt→ 图结构代码output_code.py→ 模型运行实例 JSON的顺序逐层排查其中 FX 图文件名的序号即代表 Pass 执行顺序可精确定位到具体哪个 Pass 引入了异常。参考链接功能文档docs/zh/npugraph_ex/dfx/debug_save.mdAPI 说明compile_fx设计原则npugraph_ex/design_principles.md核心实现graph_transform_observer.py、core/utils.py、npu_fx_compiler.py、acl_graph.pyC 日志联动tng_status.cpp测试用例hcom_static_kernel_test.py赞分享人工智能模型编译Ascend【免费下载链接】torchairTorchAir 支持用户基于PyTorch框架和torch_npu插件在昇腾NPU上使用图模式进行推理。项目地址https://gitcode.com/Ascend/torchair点击查看免费下载相关推荐TorchAir 图编译 Debug 信息保存功能详解基于 TORCH_COMPILE_DEBUG 的一键式调试信息收集TorchAir 图编译 Debug 信息保存功能详解基于 TORCH_COMPILE_DEBUG 的一键式调试信息收集 TorchAir 在 GE 图模式下人工智能模型编译AscendTorchAir npugraph_ex 静态Kernel编译static_kernel_compile深度解析原理、配置、缓存与产物管理TorchAir npugraph_ex 静态Kernel编译static_kernel_compile深度解析原理、配置、缓存与产物管理 本文面向在昇腾人工智能模型编译AscendTorchAir 图编译统计信息导出功能export_compile_stat实战指南TorchAir 图编译统计信息导出功能export_compile_stat实战指南 图编译统计信息导出是 TorchAir 在 GE 图模式下提供的一项人工智能模型编译Ascend上一篇Nango Push Notification集成移动应用消息推送实现下一篇garble版本管理如何在不同Go版本间保持混淆兼容性创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考