DeepGEMM-Ascend JIT 调试手册:用 DG_JIT_* 环境变量快速定位昇腾内核问题

原创2026-11-14 18:25:581,881 阅读

DeepGEMM-Ascend JIT 调试手册:用 DG_JIT_* 环境变量快速定位昇腾内核问题

🧭 为什么需要这份手册

DeepGEMM-Ascend 是华为昇腾(Ascend)NPU 上的高效矩阵乘法(GEMM)内核库,支持 BF16、FP8、FP4 GEMM、MQA logits 和 MegaMoE 算子。它的内核通过 JIT(Just-In-Time)即时编译按需生成:每种矩阵形状(M/N/K)都会触发启发式选参 → Bisheng 编译 → 加载到设备的完整流程。

对新手来说,JIT 既高效又"黑盒"——编译慢、选参不透明、报错滞后。好消息是:DeepGEMM-Ascend 内置了一套以 DG_JIT_* 命名的环境变量调试开关,无需改一行代码,就能打印选参配置、编译器命令、加载耗时,甚至定位内核挂死。本手册按"出问题 → 开哪个开关"的思路带你逐个掌握它们。

💡 官方完整说明见 README.md 的 Environment Variables 章节,本文结合源码给出更落地的用法。

⚙️ 先搞懂:DG_JIT_* 变量的两条隐藏规则

在使用之前,有两个机制会显著影响调试体验,务必先了解:

规则 1:快照机制——变量在 JIT 运行时首次创建时生效

所有 DG_JIT_* 变量在 JIT runtime 首次创建时一次性读取并快照(详见 README.md)。也就是说:

  • 必须在启动 Python 进程之前设置环境变量(如 export 或写在命令行前缀里);
  • 进程内动态 os.environ 修改、或跨次调用重新 export,对已初始化的 runtime 不生效。

规则 2:自动回退到 DJ_JIT_* 全局变量

每个 DG_JIT_* 变量未设置时,会自动回退到 DeepJIT 底层对应的 DJ_JIT_* 全局变量。如果你同时使用 DeepGEMM 原生版和 DeepJIT 其他工具,统一用 DJ_JIT_* 即可全局兜底。

附赠机制:构建时环境变量"固化"

setup.py 在打包时会把 7 个核心调试变量的值写入 deep_gemm/envs.py,并在 deep_gemm/init.py 导入时自动回填到 os.environ(仅当用户未显式设置时)。这意味着安装时设过的调试变量会随 wheel 持久化——排查"环境怎么突然不一样了"时,记得检查一下 deep_gemm/envs.py。

📋 DG_JIT_* 环境变量速查表

变量名 取值 作用 默认值
DG_JIT_DEBUG 0/1 总开关:编译器命令 + 加载耗时 + 每形状选参 0
DG_PRINT_CONFIGS 0/1 只打印每个形状选中的 tile 配置 0
DG_JIT_CACHE_DIR 字符串(可 : 分隔多目录) 内核缓存目录,命中查找从头到尾、未命中编译到第一个 $HOME/.dj
DG_JIT_PRINT_COMPILER_COMMAND 0/1 打印编译器与反汇编器命令行 0
DG_JIT_PRINT_LOAD_TIME 0/1 打印内核加载耗时 0
DG_JIT_KERNEL_DEBUG_INFO 0/1 为 Bisheng 内核添加调试信息 0
DG_JIT_LAUNCH_TIMEOUT 整数(秒) 昇腾内核启动超时时间,0 禁用 300
ASCEND_LAUNCH_BLOCKING 布尔 每次 launch 后同步设备,异步错误变同步报错 关闭

另外,setup.py 还将 DG_JIT_DUMP_ASM 列为构建时持久化变量(用于转储汇编产物),DG_JIT_WITH_LINEINFO 可在 JIT 初始化时开启行号调试信息(见 csrc/jit/jit.hpp)。

🔍 场景一:这个形状为什么这么慢?看它选了哪个配置

GEMM 性能高度依赖 tile 配置(block_m/block_n/block_k、流水线级数、L2 缓存策略等)。DeepGEMM-Ascend 的启发式选参逻辑在 csrc/jit_kernels/heuristics.hpp 中,开启打印后每个形状只输出一次去重后的配置:

# 一键开启调试(含选参打印)
export DG_JIT_DEBUG=1
python my_script.py

对应实现位于 heuristics.hpp 第 714 行:DG_JIT_DEBUG 或 DG_PRINT_CONFIGS 任一开启即打印"形状描述 + 完整配置",并用 std::unordered_set 去重,避免多形状刷屏。

💡 只想看选参、不想看编译日志?用 DG_PRINT_CONFIGS=1 更干净。对比两个相似 shape 的配置差异,往往是定位"为什么这个 shape 利用率低"的第一步。

🛠 场景二:编译产物不对劲?直接查看编译器命令行

DG_JIT_PRINT_COMPILER_COMMAND=1 会打印每次调用的 Bisheng 编译器和反汇编器的完整命令行。适合以下情况:

  • 想在本地手动重放一次编译、加参数实验;
  • 怀疑编译选项(如 --cce-disable-vf-stack-reserved-ubuf,见 jit.hpp 注入的默认 Bisheng 参数)影响结果;
  • 排查 CANN 版本升级后行为差异。

若需更深的内核级调试信息(符号、行号),再叠加:

  • DG_JIT_KERNEL_DEBUG_INFO=1:Bisheng 内核附加调试信息;
  • DG_JIT_WITH_LINEINFO=1:JIT 编译开启 debug_info,使报错能定位到内核源码行(见 csrc/jit/jit.hpp)。

⏱ 场景三:首次运行特别慢?区分"编译慢"还是"加载慢"

JIT 冷启动 = 启发式选参 + Bisheng 编译 + 加载,三者耗时可能差距很大。用 DG_JIT_PRINT_LOAD_TIME=1 打印内核加载耗时,即可拆分时间线:

# 组合拳:完整调试链路
export DG_JIT_DEBUG=1
export DG_JIT_PRINT_LOAD_TIME=1
python my_script.py

如果加载本身不慢,那"卡"多半发生在编译阶段或设备执行阶段——前者看场景二,后者看场景四。

🚨 场景四:程序莫名挂起?超时 + 阻塞式启动定位死锁

JIT 内核最常见的"疑难杂症"是启动后挂死:错误不立即抛出,程序直接卡住。两个变量配合使用:

  1. DG_JIT_LAUNCH_TIMEOUT(默认 300 秒):内核启动超时阈值,超时会触发失败而非无限等待。调小(如 60)可以更快暴露问题;设 0 则禁用超时(不推荐用于调试)。
  2. ASCEND_LAUNCH_BLOCKING:每次 launch 后强制同步设备,把"异步提交时的错误"变成当场报出的同步失败——这是定位异步内核报错最实用的开关。
# 挂死排查推荐组合
export ASCEND_LAUNCH_BLOCKING=1
export DG_JIT_LAUNCH_TIMEOUT=60
python my_script.py

📦 场景五:缓存管理——换架构 / 升级 CANN 后必做的事

编译产物默认缓存在 $HOME/.dj,由 DG_JIT_CACHE_DIR 控制。它支持 : 分隔的多目录,查找从头到尾(第一个命中即返回),未命中时编译进第一个目录。

典型用法:

# 调试期使用独立缓存,避免污染线上缓存
export DG_JIT_CACHE_DIR=$HOME/.dj-debug

两个高频踩坑点:

  • 切换 NPU 架构(set_npu_arch / dav-*)或升级 CANN 后,旧缓存必须清理,否则可能加载不兼容产物;
  • 多人共服务器时,建议把 DG_JIT_CACHE_DIR 指向各自的独立目录,避免相互覆盖。

✅ 故障排查速查清单

症状 首选环境变量 次选
某 shape 性能远低于预期 DG_PRINT_CONFIGS=1 对比 DG_JIT_DEBUG=1 全量日志
怀疑编译选项/产物问题 DG_JIT_PRINT_COMPILER_COMMAND=1 DG_JIT_DUMP_ASM + DG_JIT_KERNEL_DEBUG_INFO=1
首次运行慢 DG_JIT_PRINT_LOAD_TIME=1 检查 DG_JIT_CACHE_DIR 是否命中缓存
程序挂死、无报错 ASCEND_LAUNCH_BLOCKING=1 调小 DG_JIT_LAUNCH_TIMEOUT
内核报错无法定位源码行 DG_JIT_WITH_LINEINFO=1 DG_JIT_KERNEL_DEBUG_INFO=1
换架构/升 CANN 后行为异常 清缓存或重设 DG_JIT_CACHE_DIR 核对 deep_gemm/envs.py 固化值

📚 参考资料

🔑 记住一句话:先在进程外 export,再启动 Python;排查从 DG_JIT_DEBUG=1 总开关开始,按症状精挑细选,就能用零代码改动覆盖 DeepGEMM-Ascend 90% 的 JIT 调试需求。

登录后查看全文
DeepGEMM-Ascend