MAX 模型运行崩溃无诊断输出时如何用 MODULAR_DEBUG 捕获 Mojo 堆栈与 IR 转储

MAX 模型运行崩溃无诊断输出时如何用 MODULAR_DEBUG 捕获 Mojo 堆栈与 IR 转储

【免费下载链接】mojoThe Modular Platform (includes MAX & Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo

用 MAX 运行模型时，进程可能直接段错误退出，控制台上一行诊断都没有——这正是默认的 Python traceback 帮不上忙的场景：默认的 Python traceback 只覆盖 Python 帧，而 MAX 的失败往往发生在编译后的 Mojo 代码里，比如 kernel、标准库例程或运行时本身。MAX 内置的调试工具可以通过MODULAR_DEBUG环境变量解决这两个盲区：在进程崩溃或报错时打印 Mojo 级别的堆栈（包含编译后的 Mojo 帧），以及在图编译的每个 lowering 阶段把中间表示（IR）转储到磁盘，用于定位编译器层面的问题。本文适用前提是你已通过max serve等方式使用 MAX 运行模型，例如文档示例中的：

max serve --model modularai/Llama-3.1-8B-Instruct-GGUF

先弄清调试选项在哪个阶段生效

MAX 的调试选项在流水线的不同阶段生效，配置时机不对就会静默无效：

• Graph build time：必须在实例化Graph对象之前设置，图创建之后设置的选项不生效。
• Model build time：必须在编译图之前设置；调试信息在编译期集成进去，改动后需要重新编译模型。
• Run time：在运行模型之前设置即可，已编译的模型可以在两次运行之间修改这类选项。

用环境变量配置MODULAR_DEBUG时不用纠结这一点：环境变量和配置文件在进程启动前加载，始终在需要时生效。这一点来自 调试总览。

另外注意命名规则：环境变量和配置文件中用 kebab-case（nan-check），Python API 中用下划线形式（nan_check）。同一选项两种方式都配置时，Python API 优先。

用 MODULAR_DEBUG 捕获 Mojo 堆栈

Runtime errors 文档说明，MAX 在两个不同时刻捕获 Mojo 堆栈，对应两个MODULAR_DEBUG选项：

• stack-trace-on-error：代码抛出可恢复的 Mojo 错误（否则只会显示一条简短信息）时捕获堆栈。
• stack-trace-on-crash：进程遇到不可恢复的崩溃（如段错误，否则进程会直接退出且无任何诊断输出）时捕获堆栈。

两者可以同时启用：

MODULAR_DEBUG=stack-trace-on-error,stack-trace-on-crash max serve --model modularai/Llama-3.1-8B-Instruct-GGUF

Mojo 级别堆栈显示导致错误的完整调用链——哪个函数抛出错误、谁调用了它，一路回溯到程序入口。它能帮你判断失败点在你的模型代码、某个 kernel，还是两者之间。

边界限制：stack-trace-on-error和stack-trace-on-crash只为在 CPU 上执行的代码提供堆栈，对 GPU 上执行的代码不会给出堆栈。如果怀疑崩溃源自 GPU kernel，配合device-sync-mode使用（见 Debug GPU errors：强制同步 dispatch，让失败出现在真正出错的那个 op 上）。

用 ir-output-dir 转储编译器 IR

如果怀疑问题出在编译器层面，可以转储图编译过程中的 IR。MAX 在运行图之前，图编译器会经过一系列中间表示（IR）逐级 lowering；每个 lowering 阶段都会做算子融合、内存规划或设备放置之类的变换，所以对比各阶段的 IR 能看出编译器对模型具体做了什么。

把ir-output-dir设为一个目录路径，MAX 会在该目录下为每个 lowering 阶段写一个文件：

MODULAR_DEBUG=ir-output-dir=/tmp/ir-dump max serve --model modularai/Llama-3.1-8B-Instruct-GGUF

运行完成后检查/tmp/ir-dump中的文件（每个文件对应一个 lowering 阶段）即可做编译器级别问题的 triage。注意这个选项在 model build time 生效：设置后需要模型重新编译才有效。

如何确认捕获生效

• 堆栈：按文档，启用后当错误/崩溃发生时，MAX 会打印 Mojo 堆栈，其中包含编译后的 Mojo 帧（Python 默认 traceback 不包含这些帧）。如果你的堆栈只有 Python 帧而没有 Mojo 帧，检查失败代码是否运行在 GPU 上——这是文档明确说明的覆盖范围限制。
• IR 转储：以ir-output-dir指定的目录下出现逐 lowering 阶段的文件为准，检查这些文件来判断编译器行为。
• 环境变量是否传到位可以用 shell 的常规方式确认（如echo $MODULAR_DEBUG），确认值为上面设置的逗号分隔列表。

可选：一次开启整套默认调试

如果不想逐项勾选，可以用MODULAR_DEBUG=sensible启用一套精选的默认调试项。根据 DebugConfig API 说明，sensible包含nan_check、assert_level='all'、device_sync_mode、stack_trace_on_error、stack_trace_on_crash和source_tracebacks，之后可以用单项属性覆盖这些默认值。适合快速进入调试状态；如果只想最小化开启堆栈捕获和 IR 转储，用前面两条针对性命令即可。

排查与限制

• MODULAR_DEBUG接受逗号分隔的选项列表，带取值的选项用name=value形式，完整选项表见 环境变量参考 的 Debugging 一节。
• 堆栈工具不覆盖 GPU 上执行的代码（见上文边界限制）。
• 用 Python API 同时配置同一选项时，API 优先于环境变量；API 配置的选项可用InferenceSession.debug.reset()清空，而MODULAR_DEBUG中的值仍然保持生效。
• 当错误涉及 NaN、Inf 或未初始化内存时，Debug accuracy issues 有针对性的检查项；当需要看到 op 执行顺序及对应 Python 源码位置时，见 Execution tracing（op-log-level与source-tracebacks）。

拿到堆栈和 IR 转储后，下一步是依据堆栈中的 Mojo 帧判断失败点位于模型代码、kernel 还是运行时，再按上述链接的 GPU、精度或 tracing 文档继续收窄范围。

【免费下载链接】mojoThe Modular Platform (includes MAX & Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo