DeepGEMM-Ascend JIT 调试手册:用 DG_JIT_* 环境变量快速定位昇腾内核问题
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 内核最常见的"疑难杂症"是启动后挂死:错误不立即抛出,程序直接卡住。两个变量配合使用:
DG_JIT_LAUNCH_TIMEOUT(默认 300 秒):内核启动超时阈值,超时会触发失败而非无限等待。调小(如60)可以更快暴露问题;设0则禁用超时(不推荐用于调试)。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 固化值 |
📚 参考资料
- 环境变量官方说明:README.md
- JIT 运行时初始化与
DG_JIT_WITH_LINEINFO:csrc/jit/jit.hpp - 启发式选参打印逻辑:csrc/jit_kernels/heuristics.hpp
- 构建时持久化变量清单:setup.py
- 持久化环境变量加载:deep_gemm/init.py
- 测试用例(可复现各 GEMM 场景):tests/
🔑 记住一句话:先在进程外 export,再启动 Python;排查从
DG_JIT_DEBUG=1总开关开始,按症状精挑细选,就能用零代码改动覆盖 DeepGEMM-Ascend 90% 的 JIT 调试需求。