尧图网页设计 
MAX 模型精度调试完全指南用 debug_model 与 compare_tensors 定位 MAX 与 PyTorch 的数值分歧【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo本文基于 max/docs/accuracy-debugging.md 展开讲解在 MAXModular 的高性能推理平台流水线中排查数值精度问题的完整方法论当 MAX 流水线输出与 PyTorchHugging Face参考实现不一致时如何通过对比两套框架的中间张量逐层定位分歧源头。读完本文你将掌握debug_model与compare_tensors两个工具的组合用法、PipelineOracle的注册方式、细粒度打印与全量张量导出的操作细节以及 FMA 收缩、dtype 不匹配、配置差异等典型精度问题的判别方法。精度调试的总体流程如果 MAX 流水线的输出与 PyTorch 参考实现不一致可以按以下五个步骤定位分歧源头分别用 MAX 与 PyTorch 运行debug_model导出dump中间张量并排对比两份张量日志找到可疑的层在可疑层的中间张量处添加细粒度打印日志再次运行debug_model导出详细的张量数据用compare_tensors基于导出的张量数据计算 PyTorch 参考模型与 MAX 模型之间的数值差异。debug_model与compare_tensors两个工具都位于 max/tests/integration/tools/ 目录基础用法参见 tools README。该目录下还包含create_pipelines.pyPipelineOracle定义、debugging_utils.py调试核心逻辑等配套文件。从源码结构看debug_model.py是一个基于click的命令行入口真正执行逻辑在 debugging_utils.py 的run_debug_model()中它会根据框架名分别走 MAX、Torch、vLLM 三条执行路径并为 MAX 与 Torch 统一挂载打印钩子print hook从而在模型前向过程中自动捕获每个模块的输入与输出张量。前置条件为模型注册 PipelineOracle新模型必做如果你调试的模型在 MAX 中已完全受支持可以跳过本节——该模型通常已经提供了PipelineOracle。debug_model工具要同时实例化 MAX 与 PyTorch 两个版本的模型依赖定义在 max/tests/integration/tools/create_pipelines.py 中的PipelineOracle类。要为你的模型添加PipelineOracle只需在该文件的PIPELINE_ORACLES字典中新增一个条目例如PIPELINE_ORACLES: Mapping[str, PipelineOracle] { # ... existing oracles ... my-org/my-model: GenericOracle( model_pathmy-org/my-model, device_encoding_map{gpu: [bfloat16]}, config_params{max_length: 8192, trust_remote_code: True}, ), }GenericOracle是 create_pipelines.py 中定义的最常用的PipelineOracle实现。从源码看它支持的构造参数包括model_pathHugging Face 仓库 ID必填torch_model_path可选PyTorch 参考模型路径当 MAX 加载的是量化权重、而 transformers 无法直接加载时用它指定 MAX 权重量化前的 bf16 源模型量化误差会落在容差范围内device_encoding_map设备类型到支持的量化编码列表的映射如{cpu: [float32], gpu: [bfloat16]}weight_path_map编码到权重的映射用于从独立权重仓库加载config_params透传给PipelineArgs的额外配置参数prompts/apply_chat_template自定义提示词与是否应用聊天模板use_cache是否启用 KV cacheauto_model_cls/auto_processor_cls自定义模型与分词器类task流水线任务类型如文本生成batch_size/add_bos_token批量大小与是否添加 BOS token。对于多模态模型或需要自定义预处理的模型可能需要创建自定义的PipelineOracle子类可以参考已有的InternVLPipelineOracle、Qwen2_5VLPipelineOracle等实现。PipelineOracle基类create_pipelines.py 第 165 行附近是一个抽象基类规定了device_encoding_map、create_max_pipeline()、create_torch_pipeline()等抽象成员并默认提供create_vllm_pipeline()实现。第一步用 debug_model 导出中间张量如果模型权重来自 Hugging Face请先配置访问令牌export HF_TOKENhf_...然后分别用 MAX 与 PyTorch 运行debug_model导出中间张量。默认情况下工具会把缩略版张量表示打印到控制台先把两份输出分别重定向到文件bazel run //max/tests/integration/tools:debug_model -- \ --framework max \ --pipeline google/gemma-3-1b-it max_tensors.logbazel run //max/tests/integration/tools:debug_model -- \ --framework torch \ --pipeline google/gemma-3-1b-it torch_tensors.log结合 debug_model.py 源码与 tools READMEdebug_model的完整常用选项如下选项说明--framework {max,torch,vllm}运行模型的框架默认max--pipeline NAMEHugging Face 模型路径或PipelineOracle键必填--device DEVICE设备类型cpu、gpu、default或gpu:0,1指定多卡-o, --output DIR将完整张量保存到目录生成.pt/.max文件供compare_tensors使用缺省时只向控制台打印缩略表示--num-hidden-layers N使用的隐藏层数量默认 1传all使用全部层--num-steps N推理步数默认 1--prompt TEXT自定义提示词省略时使用流水线默认提示词--image URL多模态模型的图片输入可重复传入--encoding NAME量化编码如bfloat16、float32--max-batch-size N评估时使用的最大 batch size--hf-config-overrides JSON应用于 Hugging FaceAutoConfig字段的 JSON 覆盖字典--prefer-module-v3优先选用 ModuleV3eager-API架构变体从 debugging_utils.py 的run_debug_model()实现可以看到工具的底层机制--num-hidden-layers会通过create_layer_overrides()生成层数覆盖并与用户传入的--hf-config-overrides合并用户覆盖优先再通过debug_context()上下文管理器同时作用于 MAX 与 Torch 模型MAX 路径下apply_max_hooks()会 patchInferenceSession.__init__在创建会话时自动调用set_debug_print_options(stylePrintStyle.BINARY_MAX_CHECKPOINT, output_directory...)把TensorValue.print()的输出以 MAX checkpoint 格式写入目录同时 patchModule.load_state_dict在权重加载完成后调用hook.name_layers()为各层命名Torch 路径下工具会打印模型类与其源文件路径并创建TorchPrintHook挂载到模型上详见 torch_print_hook.py。第二步对比日志定位分歧层打开两份日志文件找到第一个张量出现有意义分歧的位置——那通常就是 bug 所在。提示把这两份文件交给 LLM让它帮忙找出分歧点可以显著加快排查速度。良好——输出一致# MAX output model.layers.0.mlp.fc1-output tensor([[[-2.0156, -3.8125, ... # PyTorch output (should closely match) model.layers.0.mlp.fc1-output tensor([[[-2.0156, -3.8125, ...异常——输出分歧# MAX GELU output model.layers.0.mlp.gelu-output tensor([[[-4.32e-02, 0.00e00, ... # PyTorch GELU output (values differ significantly) model.layers.0.activation-output tensor([[[-4.42e-02, -2.61e-04, ...注意第二组示例中不仅数值差异明显张量命名也不同gelu-outputvsactivation-output——这本身就提示了两个框架对同一算子的命名/位置差异可以作为进一步核对的线索。第三步添加细粒度打印日志上面的日志只在层边界如MLP、Attention、Linear暴露中间张量。要精确定位导致分歧的具体算子需要检查可疑层内部的值。例如如果 MLP 层输出分歧但输入一致就应该在 MLP 块内的每一步打印张量。在 MAX 侧添加打印在 MAX 模型代码中为每个算子添加TensorValue.print()调用class MLP(Module): def forward(self, x: TensorValueLike) - TensorValue: x_tensor TensorValue(x) x_tensor.print(mlp_input) gate_out self.gate_proj(x_tensor) gate_out.print(mlp_gate) activated self.activation_function(gate_out) activated.print(mlp_activated) # ... rest of implementationTensorValue.print()的输出去向由InferenceSession.set_debug_print_options()设置的样式决定详见下文配置 MAX 调试打印选项小节。在 PyTorch 侧添加打印debug_model工具使用 PyTorch 的 hook API 在外部捕获模块输入输出无需修改源码。但若要在模块forward()方法内部添加torch.save()调用则需要直接编辑源文件。相关代码位于transformers包中默认只读。先用以下脚本将其改为可编辑安装bash utils/local_transformers_setup/setup_local_transformers.sh要找到模型的源码位置直接看第一步生成的torch_tensors.log顶部 Model class: transformers.models.gemma3.modeling_gemma3.Gemma3ForCausalLM Model source file: /path/to/transformers/models/gemma3/modeling_gemma3.py 打开那个.py文件为每个算子添加torch.save()调用保存到torch_debug目录class Gemma3MLP(nn.Module): def forward(self, x): import os os.makedirs(torch_debug, exist_okTrue) torch.save(x, torch_debug/mlp_input.pt) gate self.gate_proj(x) torch.save(gate, torch_debug/mlp_gate.pt) activated self.act_fn(gate) torch.save(activated, torch_debug/mlp_activated.pt) # ... rest of implementation关键两个框架中保存的张量必须同名compare_tensors才能自动配对。例如 MAX 中的x_tensor.print(mlp_A_input)要与 PyTorch 中的torch.save(x, torch_debug/mlp_A_input.pt)一一对应。第四步用 debug_model 导出完整张量加入新的打印语句后再次运行debug_model导出完整张量做数值对比。MAX 侧增加-o选项把完整张量输出保存为max_tensors路径下的.max文件bazel run //max/tests/integration/tools:debug_model -- \ --framework max \ --pipeline google/gemma-3-1b-it \ -o max_tensors/ \ max_tensors.logPyTorch 侧不需要-o因为上面代码中的torch.save()已经指定了.pt文件路径bazel run //max/tests/integration/tools:debug_model -- \ --framework torch \ --pipeline google/gemma-3-1b-it \ torch_tensors.log下一步并不需要.log文件但再次捕获它可以让控制台保持干净。从实现上看MAX 侧导出依赖PrintStyle.BINARY_MAX_CHECKPOINT样式由apply_max_hooks()自动配置生成的.max文件携带 dtype/shape 元数据compare_tensors可直接读取PyTorch 侧则是.pt文件。如果你想在自定义脚本中编程式地取回这些张量debugging_utils.py 还提供了load_intermediate_tensors()返回dict[str, torch.Tensor]与get_torch_testdata()返回指定模块的输入/输出张量两个辅助函数。第五步用 compare_tensors 计算数值差异现在用compare_tensors按名称自动配对对应的张量文件并计算两者之间的数值差异bazel run //max/tests/integration/tools:compare_tensors -- \ --torch-tensor torch_tensors/ \ --max-tensor max_tensors/工具会为每对张量报告绝对差异、相对差异等指标帮助精确定位两个实现输出分歧的位置和方式。示例输出Found 6 matching tensor pair(s) Tensor: mlp_A_input vs mlp_A_input Shapes: torch(507, 1152), max(507, 1152) Greatest absolute difference: 0.354 at index (246, 941) Greatest relative difference: 0.012 at index (100, 500) Tensor: mlp_B_gate vs mlp_B_gate Shapes: torch(507, 6912), max(507, 6912) Greatest absolute difference: 0.102 at index (151, 2146) Greatest relative difference: 0.008 at index (151, 2146) ...从 compare_tensors.py 源码可以了解这些指标的精确计算方式MAX 张量.max文件通过load_max_buffer()加载后经torch.from_dlpack()转为 torch 张量再移到 CPU绝对差异abs_diff |torch - max|取最大值及其索引torch.unravel_index还原多维下标相对差异rel_diff abs_diff / max(|torch|, 1e-10)同样报告最大值与索引当指定--rtol/--atol时用torch.isclose()判定每个元素是否通过并报告失败元素数量与总元素数即失败比例两者都未指定时只报告指标、不做通过/失败判定。compare_tensors的其他关键选项选项说明--torch-tensor PATHPyTorch 张量文件.pt或目录路径--max-tensor PATHMAX 张量文件.max或目录路径--rtol FLOAT通过/失败判定的相对容差--atol FLOAT通过/失败判定的绝对容差--allow-reshape允许比较元素总数相同但形状不同的张量输出还包括形状对比、--allow-reshape下的重整形状态以及指定容差时的元素失配百分比。至此一轮迭代完成反复执行第 35 步直到找到并解决问题或者掌握足够信息提交详细的 bug 报告。调试完成后记得恢复只读的 transformers 安装bash utils/local_transformers_setup/cleanup_local_transformers.sh常见精度问题排查以下是最常见的精度 bug 类型及排查方向。Kernel 实现 bug某个 kernel 实现可能与参考实现存在细微数值差异。这是最常见的情况——优先怀疑算子的 kernel 层实现例如 max/kernels/ 下的算子实现。权重适配问题检查权重是否正确加载并转换。特别地GenericOracle的weight_path_map/torch_model_path参数正是用于处理MAX 加载量化权重、PyTorch 参考加载 bf16 源权重的典型场景若配置不当会引入系统性偏差。FMA 收缩差异MAX 默认通过 LLVM 的contractfastmath 标志启用 FMAfused multiply-add融合乘加收缩配置位于 Mojo/lib/KGENToLLVM/LLVMLoweringUtils.h。这允许编译器把一次fmul fadd融合成单条 FMA 指令后者只舍入一次而分开计算需要舍入两次。对bfloat16运算而言这会产生与 PyTorch 最多 1 ULP 的差异——因为 PyTorch 每次运算后都舍入而 FMA 保持了中间乘积的全精度。最大误差通常落在输入量级对应的 BF16 ULP 范围内例如 0.0625 2^-4。这是设计使然——FMA 结果比 PyTorch 的双重舍入更精确。如果在bfloat16乘加模式中看到逐元素差异先确认这是否就是原因再继续排查把两个结果分别与float64参考对比——MAX 结果应当更接近把同样的算子拆分到独立图强制中间结果物化应当与 PyTorch 完全一致从而确认 FMA 收缩是差异来源。从编译器的角度看LowerKGENToLLVM.cpp 中维护了fp_contract→fp-contract的属性映射而 SetFastMathFlags.cpp 中的 pass 可以清除FastmathFlags::contract标志——这也从实现层面印证了contract是可通过编译选项控制的。[!NOTE] 这类逐元素差异不影响模型级指标困惑度、KL 散度、评测分数。只有在模型级精度确实下降时才应将其标记为 bug。dtype 不匹配查找 dtype 被错误转换的位置。常见问题是本应使用bfloat16的运算在float32下执行或反之。可以借助--hf-config-overrides或检查模型配置中的默认 dtype 来核对。配置差异确保 MAX 模型配置与 Hugging Face 配置完全一致关键词参数rope_scaling类型、激活函数名称等数值参数head_dim、hidden_size等特性开关use_cache、tie_word_embeddings等。更多调试选项配置 MAX 调试打印选项如果你在编写自定义脚本或希望改变 MAX 的打印行为可以使用InferenceSession.set_debug_print_options()。它设置的样式决定TensorValue.print()的输出去向控制台输出COMPACT显示张量角部值与形状的缩略输出默认FULL完整张量内容小数精度可配置。文件输出BINARY_MAX_CHECKPOINT保存带 dtype/shape 元数据的.max文件推荐用于compare_tensorsBINARY不含元数据的原始缓冲区文件加载时必须自行跟踪 dtype/shape。例如from max.engine import InferenceSession from max.engine.api import PrintStyle session InferenceSession(...) # Abbreviated output to console - shows corners and shape (default) session.set_debug_print_options(stylePrintStyle.COMPACT) # Full tensor contents to console (with configurable decimal precision) session.set_debug_print_options( stylePrintStyle.FULL, precision8, # digits of precision (default: 6) ) # Save as MAX checkpoint files (recommended for compare_tensors) session.set_debug_print_options( stylePrintStyle.BINARY_MAX_CHECKPOINT, output_directory/tmp/max_output ) # Raw binary buffer (loadable with numpy.frombuffer, but requires # you to specify dtype and shape when loading) session.set_debug_print_options( stylePrintStyle.BINARY, output_directory/tmp/max_output )直接使用打印钩子debug_model工具会自动处理钩子挂载但在以下场景你可能希望直接使用打印钩子 API把张量检查集成到自己的测试脚本中使用filter参数只打印特定层在流水线完全就绪前的模型开发阶段调试需要编程式控制钩子的挂载与移除时机。MAXPrintHookfrom max.nn.hooks import PrintHook # Create hook and name layers hook PrintHook() hook.name_layers(model) # Names all layers based on their attribute path # Build and run graph... # Clean up hook.remove()PyTorchTorchPrintHookfrom test_common.torch_print_hook import TorchPrintHook # Create hook with optional export path hook TorchPrintHook(export_path/tmp/torch_tensors) hook.name_layers(model) # Run model - tensors are automatically saved # Clean up hook.remove()TorchPrintHook定义在 max/tests/integration/test_common/torch_print_hook.py继承自BasePrintHook与 MAX 侧保持一致的命名与导出约定便于后续compare_tensors自动配对。用更少的层调试默认情况下debug_model只运行 1 个隐藏层以加速调试。这通常已足够因为 bug 往往出现在第一层。如有需要可用--num-hidden-layers增加层数# Use 3 hidden layers bazel run //max/tests/integration/tools:debug_model -- \ --framework max \ --pipeline google/gemma-3-1b-it \ --num-hidden-layers 3 # Use all layers (full model) bazel run //max/tests/integration/tools:debug_model -- \ --framework max \ --pipeline google/gemma-3-1b-it \ --num-hidden-layers allFAQ如何在 MAX 与 PyTorch 之间匹配张量对比过程中你会发现 PyTorch/HuggingFace 模型结构与 MAX 模型结构并不总是逐层对齐——一个模型有的层在另一个模型中可能看不到。不读代码很难判断这是否是 bug。此时有两种选择暂停手动对比直接阅读代码弄清楚为什么一个模型暴露了更多层。例如MAX 缓存了k和v因此 dump 中只出现q层。确认架构差异有合理原因后即可继续。跳过架构分歧寻找下一个共享层沿用上面的例子MAX 缓存k、v后可能到layer_norm又完全对齐了。一旦找到同步点就可以确信此前的架构差异并非 bug继续前进。在缩略输出中看不到分歧怎么办先尝试以下两步检查验证失败的细节是否在同一硬件、同一提示词下运行可以通过--prompt参数向debug_model显式指定提示词debug_model默认只运行 1 层--num-hidden-layers 1但某些 bug 只出现在更靠后的层。尝试增大--num-hidden-layers再看。如果仍无帮助可以用compare_tensors数值对比各层来找分歧。这比较繁琐建议采用二分搜索策略。首先为两个框架重新运行debug_model并用-o保存完整张量bazel run //max/tests/integration/tools:debug_model -- \ --framework torch \ --pipeline google/gemma-3-1b-it \ -o torch_tensors/ bazel run //max/tests/integration/tools:debug_model -- \ --framework max \ --pipeline google/gemma-3-1b-it \ -o max_tensors/然后开始对比预期应该匹配的张量例如bazel run //max/tests/integration/tools:compare_tensors -- \ --torch-tensor torch_tensors/0/model.lm_head-output.pt \ --max-tensor max_tensors/model.language_model-output_0.max[!NOTE] 如果某个张量只需简单 reshape 即可比较compare_tensors的--allow-reshape标志可以处理这种情况。当输出中的rtol与atol指标开始发散时你就有了下手的起点可以按上一节描述的方法继续深挖。整套方法论的核心是先用层边界粗筛定位分歧区域再在可疑模块内部细粒度打印、导出完整张量最终用compare_tensors的数值指标锁定具体算子——这套流程同样适用于 MAX 之外的框架组合是 MAX 流水线精度回归与 bug 报告前的标准排查路径。【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MAX 模型精度调试完全指南：用 debug_model 与 compare_tensors 定位 MAX 与 PyTorch 的数值分歧
MAX 模型精度调试完全指南用 debug_model 与 compare_tensors 定位 MAX 与 PyTorch 的数值分歧【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo本文基于 max/docs/accuracy-debugging.md 展开讲解在 MAXModular 的高性能推理平台流水线中排查数值精度问题的完整方法论当 MAX 流水线输出与 PyTorchHugging Face参考实现不一致时如何通过对比两套框架的中间张量逐层定位分歧源头。读完本文你将掌握debug_model与compare_tensors两个工具的组合用法、PipelineOracle的注册方式、细粒度打印与全量张量导出的操作细节以及 FMA 收缩、dtype 不匹配、配置差异等典型精度问题的判别方法。精度调试的总体流程如果 MAX 流水线的输出与 PyTorch 参考实现不一致可以按以下五个步骤定位分歧源头分别用 MAX 与 PyTorch 运行debug_model导出dump中间张量并排对比两份张量日志找到可疑的层在可疑层的中间张量处添加细粒度打印日志再次运行debug_model导出详细的张量数据用compare_tensors基于导出的张量数据计算 PyTorch 参考模型与 MAX 模型之间的数值差异。debug_model与compare_tensors两个工具都位于 max/tests/integration/tools/ 目录基础用法参见 tools README。该目录下还包含create_pipelines.pyPipelineOracle定义、debugging_utils.py调试核心逻辑等配套文件。从源码结构看debug_model.py是一个基于click的命令行入口真正执行逻辑在 debugging_utils.py 的run_debug_model()中它会根据框架名分别走 MAX、Torch、vLLM 三条执行路径并为 MAX 与 Torch 统一挂载打印钩子print hook从而在模型前向过程中自动捕获每个模块的输入与输出张量。前置条件为模型注册 PipelineOracle新模型必做如果你调试的模型在 MAX 中已完全受支持可以跳过本节——该模型通常已经提供了PipelineOracle。debug_model工具要同时实例化 MAX 与 PyTorch 两个版本的模型依赖定义在 max/tests/integration/tools/create_pipelines.py 中的PipelineOracle类。要为你的模型添加PipelineOracle只需在该文件的PIPELINE_ORACLES字典中新增一个条目例如PIPELINE_ORACLES: Mapping[str, PipelineOracle] { # ... existing oracles ... my-org/my-model: GenericOracle( model_pathmy-org/my-model, device_encoding_map{gpu: [bfloat16]}, config_params{max_length: 8192, trust_remote_code: True}, ), }GenericOracle是 create_pipelines.py 中定义的最常用的PipelineOracle实现。从源码看它支持的构造参数包括model_pathHugging Face 仓库 ID必填torch_model_path可选PyTorch 参考模型路径当 MAX 加载的是量化权重、而 transformers 无法直接加载时用它指定 MAX 权重量化前的 bf16 源模型量化误差会落在容差范围内device_encoding_map设备类型到支持的量化编码列表的映射如{cpu: [float32], gpu: [bfloat16]}weight_path_map编码到权重的映射用于从独立权重仓库加载config_params透传给PipelineArgs的额外配置参数prompts/apply_chat_template自定义提示词与是否应用聊天模板use_cache是否启用 KV cacheauto_model_cls/auto_processor_cls自定义模型与分词器类task流水线任务类型如文本生成batch_size/add_bos_token批量大小与是否添加 BOS token。对于多模态模型或需要自定义预处理的模型可能需要创建自定义的PipelineOracle子类可以参考已有的InternVLPipelineOracle、Qwen2_5VLPipelineOracle等实现。PipelineOracle基类create_pipelines.py 第 165 行附近是一个抽象基类规定了device_encoding_map、create_max_pipeline()、create_torch_pipeline()等抽象成员并默认提供create_vllm_pipeline()实现。第一步用 debug_model 导出中间张量如果模型权重来自 Hugging Face请先配置访问令牌export HF_TOKENhf_...然后分别用 MAX 与 PyTorch 运行debug_model导出中间张量。默认情况下工具会把缩略版张量表示打印到控制台先把两份输出分别重定向到文件bazel run //max/tests/integration/tools:debug_model -- \ --framework max \ --pipeline google/gemma-3-1b-it max_tensors.logbazel run //max/tests/integration/tools:debug_model -- \ --framework torch \ --pipeline google/gemma-3-1b-it torch_tensors.log结合 debug_model.py 源码与 tools READMEdebug_model的完整常用选项如下选项说明--framework {max,torch,vllm}运行模型的框架默认max--pipeline NAMEHugging Face 模型路径或PipelineOracle键必填--device DEVICE设备类型cpu、gpu、default或gpu:0,1指定多卡-o, --output DIR将完整张量保存到目录生成.pt/.max文件供compare_tensors使用缺省时只向控制台打印缩略表示--num-hidden-layers N使用的隐藏层数量默认 1传all使用全部层--num-steps N推理步数默认 1--prompt TEXT自定义提示词省略时使用流水线默认提示词--image URL多模态模型的图片输入可重复传入--encoding NAME量化编码如bfloat16、float32--max-batch-size N评估时使用的最大 batch size--hf-config-overrides JSON应用于 Hugging FaceAutoConfig字段的 JSON 覆盖字典--prefer-module-v3优先选用 ModuleV3eager-API架构变体从 debugging_utils.py 的run_debug_model()实现可以看到工具的底层机制--num-hidden-layers会通过create_layer_overrides()生成层数覆盖并与用户传入的--hf-config-overrides合并用户覆盖优先再通过debug_context()上下文管理器同时作用于 MAX 与 Torch 模型MAX 路径下apply_max_hooks()会 patchInferenceSession.__init__在创建会话时自动调用set_debug_print_options(stylePrintStyle.BINARY_MAX_CHECKPOINT, output_directory...)把TensorValue.print()的输出以 MAX checkpoint 格式写入目录同时 patchModule.load_state_dict在权重加载完成后调用hook.name_layers()为各层命名Torch 路径下工具会打印模型类与其源文件路径并创建TorchPrintHook挂载到模型上详见 torch_print_hook.py。第二步对比日志定位分歧层打开两份日志文件找到第一个张量出现有意义分歧的位置——那通常就是 bug 所在。提示把这两份文件交给 LLM让它帮忙找出分歧点可以显著加快排查速度。良好——输出一致# MAX output model.layers.0.mlp.fc1-output tensor([[[-2.0156, -3.8125, ... # PyTorch output (should closely match) model.layers.0.mlp.fc1-output tensor([[[-2.0156, -3.8125, ...异常——输出分歧# MAX GELU output model.layers.0.mlp.gelu-output tensor([[[-4.32e-02, 0.00e00, ... # PyTorch GELU output (values differ significantly) model.layers.0.activation-output tensor([[[-4.42e-02, -2.61e-04, ...注意第二组示例中不仅数值差异明显张量命名也不同gelu-outputvsactivation-output——这本身就提示了两个框架对同一算子的命名/位置差异可以作为进一步核对的线索。第三步添加细粒度打印日志上面的日志只在层边界如MLP、Attention、Linear暴露中间张量。要精确定位导致分歧的具体算子需要检查可疑层内部的值。例如如果 MLP 层输出分歧但输入一致就应该在 MLP 块内的每一步打印张量。在 MAX 侧添加打印在 MAX 模型代码中为每个算子添加TensorValue.print()调用class MLP(Module): def forward(self, x: TensorValueLike) - TensorValue: x_tensor TensorValue(x) x_tensor.print(mlp_input) gate_out self.gate_proj(x_tensor) gate_out.print(mlp_gate) activated self.activation_function(gate_out) activated.print(mlp_activated) # ... rest of implementationTensorValue.print()的输出去向由InferenceSession.set_debug_print_options()设置的样式决定详见下文配置 MAX 调试打印选项小节。在 PyTorch 侧添加打印debug_model工具使用 PyTorch 的 hook API 在外部捕获模块输入输出无需修改源码。但若要在模块forward()方法内部添加torch.save()调用则需要直接编辑源文件。相关代码位于transformers包中默认只读。先用以下脚本将其改为可编辑安装bash utils/local_transformers_setup/setup_local_transformers.sh要找到模型的源码位置直接看第一步生成的torch_tensors.log顶部 Model class: transformers.models.gemma3.modeling_gemma3.Gemma3ForCausalLM Model source file: /path/to/transformers/models/gemma3/modeling_gemma3.py 打开那个.py文件为每个算子添加torch.save()调用保存到torch_debug目录class Gemma3MLP(nn.Module): def forward(self, x): import os os.makedirs(torch_debug, exist_okTrue) torch.save(x, torch_debug/mlp_input.pt) gate self.gate_proj(x) torch.save(gate, torch_debug/mlp_gate.pt) activated self.act_fn(gate) torch.save(activated, torch_debug/mlp_activated.pt) # ... rest of implementation关键两个框架中保存的张量必须同名compare_tensors才能自动配对。例如 MAX 中的x_tensor.print(mlp_A_input)要与 PyTorch 中的torch.save(x, torch_debug/mlp_A_input.pt)一一对应。第四步用 debug_model 导出完整张量加入新的打印语句后再次运行debug_model导出完整张量做数值对比。MAX 侧增加-o选项把完整张量输出保存为max_tensors路径下的.max文件bazel run //max/tests/integration/tools:debug_model -- \ --framework max \ --pipeline google/gemma-3-1b-it \ -o max_tensors/ \ max_tensors.logPyTorch 侧不需要-o因为上面代码中的torch.save()已经指定了.pt文件路径bazel run //max/tests/integration/tools:debug_model -- \ --framework torch \ --pipeline google/gemma-3-1b-it \ torch_tensors.log下一步并不需要.log文件但再次捕获它可以让控制台保持干净。从实现上看MAX 侧导出依赖PrintStyle.BINARY_MAX_CHECKPOINT样式由apply_max_hooks()自动配置生成的.max文件携带 dtype/shape 元数据compare_tensors可直接读取PyTorch 侧则是.pt文件。如果你想在自定义脚本中编程式地取回这些张量debugging_utils.py 还提供了load_intermediate_tensors()返回dict[str, torch.Tensor]与get_torch_testdata()返回指定模块的输入/输出张量两个辅助函数。第五步用 compare_tensors 计算数值差异现在用compare_tensors按名称自动配对对应的张量文件并计算两者之间的数值差异bazel run //max/tests/integration/tools:compare_tensors -- \ --torch-tensor torch_tensors/ \ --max-tensor max_tensors/工具会为每对张量报告绝对差异、相对差异等指标帮助精确定位两个实现输出分歧的位置和方式。示例输出Found 6 matching tensor pair(s) Tensor: mlp_A_input vs mlp_A_input Shapes: torch(507, 1152), max(507, 1152) Greatest absolute difference: 0.354 at index (246, 941) Greatest relative difference: 0.012 at index (100, 500) Tensor: mlp_B_gate vs mlp_B_gate Shapes: torch(507, 6912), max(507, 6912) Greatest absolute difference: 0.102 at index (151, 2146) Greatest relative difference: 0.008 at index (151, 2146) ...从 compare_tensors.py 源码可以了解这些指标的精确计算方式MAX 张量.max文件通过load_max_buffer()加载后经torch.from_dlpack()转为 torch 张量再移到 CPU绝对差异abs_diff |torch - max|取最大值及其索引torch.unravel_index还原多维下标相对差异rel_diff abs_diff / max(|torch|, 1e-10)同样报告最大值与索引当指定--rtol/--atol时用torch.isclose()判定每个元素是否通过并报告失败元素数量与总元素数即失败比例两者都未指定时只报告指标、不做通过/失败判定。compare_tensors的其他关键选项选项说明--torch-tensor PATHPyTorch 张量文件.pt或目录路径--max-tensor PATHMAX 张量文件.max或目录路径--rtol FLOAT通过/失败判定的相对容差--atol FLOAT通过/失败判定的绝对容差--allow-reshape允许比较元素总数相同但形状不同的张量输出还包括形状对比、--allow-reshape下的重整形状态以及指定容差时的元素失配百分比。至此一轮迭代完成反复执行第 35 步直到找到并解决问题或者掌握足够信息提交详细的 bug 报告。调试完成后记得恢复只读的 transformers 安装bash utils/local_transformers_setup/cleanup_local_transformers.sh常见精度问题排查以下是最常见的精度 bug 类型及排查方向。Kernel 实现 bug某个 kernel 实现可能与参考实现存在细微数值差异。这是最常见的情况——优先怀疑算子的 kernel 层实现例如 max/kernels/ 下的算子实现。权重适配问题检查权重是否正确加载并转换。特别地GenericOracle的weight_path_map/torch_model_path参数正是用于处理MAX 加载量化权重、PyTorch 参考加载 bf16 源权重的典型场景若配置不当会引入系统性偏差。FMA 收缩差异MAX 默认通过 LLVM 的contractfastmath 标志启用 FMAfused multiply-add融合乘加收缩配置位于 Mojo/lib/KGENToLLVM/LLVMLoweringUtils.h。这允许编译器把一次fmul fadd融合成单条 FMA 指令后者只舍入一次而分开计算需要舍入两次。对bfloat16运算而言这会产生与 PyTorch 最多 1 ULP 的差异——因为 PyTorch 每次运算后都舍入而 FMA 保持了中间乘积的全精度。最大误差通常落在输入量级对应的 BF16 ULP 范围内例如 0.0625 2^-4。这是设计使然——FMA 结果比 PyTorch 的双重舍入更精确。如果在bfloat16乘加模式中看到逐元素差异先确认这是否就是原因再继续排查把两个结果分别与float64参考对比——MAX 结果应当更接近把同样的算子拆分到独立图强制中间结果物化应当与 PyTorch 完全一致从而确认 FMA 收缩是差异来源。从编译器的角度看LowerKGENToLLVM.cpp 中维护了fp_contract→fp-contract的属性映射而 SetFastMathFlags.cpp 中的 pass 可以清除FastmathFlags::contract标志——这也从实现层面印证了contract是可通过编译选项控制的。[!NOTE] 这类逐元素差异不影响模型级指标困惑度、KL 散度、评测分数。只有在模型级精度确实下降时才应将其标记为 bug。dtype 不匹配查找 dtype 被错误转换的位置。常见问题是本应使用bfloat16的运算在float32下执行或反之。可以借助--hf-config-overrides或检查模型配置中的默认 dtype 来核对。配置差异确保 MAX 模型配置与 Hugging Face 配置完全一致关键词参数rope_scaling类型、激活函数名称等数值参数head_dim、hidden_size等特性开关use_cache、tie_word_embeddings等。更多调试选项配置 MAX 调试打印选项如果你在编写自定义脚本或希望改变 MAX 的打印行为可以使用InferenceSession.set_debug_print_options()。它设置的样式决定TensorValue.print()的输出去向控制台输出COMPACT显示张量角部值与形状的缩略输出默认FULL完整张量内容小数精度可配置。文件输出BINARY_MAX_CHECKPOINT保存带 dtype/shape 元数据的.max文件推荐用于compare_tensorsBINARY不含元数据的原始缓冲区文件加载时必须自行跟踪 dtype/shape。例如from max.engine import InferenceSession from max.engine.api import PrintStyle session InferenceSession(...) # Abbreviated output to console - shows corners and shape (default) session.set_debug_print_options(stylePrintStyle.COMPACT) # Full tensor contents to console (with configurable decimal precision) session.set_debug_print_options( stylePrintStyle.FULL, precision8, # digits of precision (default: 6) ) # Save as MAX checkpoint files (recommended for compare_tensors) session.set_debug_print_options( stylePrintStyle.BINARY_MAX_CHECKPOINT, output_directory/tmp/max_output ) # Raw binary buffer (loadable with numpy.frombuffer, but requires # you to specify dtype and shape when loading) session.set_debug_print_options( stylePrintStyle.BINARY, output_directory/tmp/max_output )直接使用打印钩子debug_model工具会自动处理钩子挂载但在以下场景你可能希望直接使用打印钩子 API把张量检查集成到自己的测试脚本中使用filter参数只打印特定层在流水线完全就绪前的模型开发阶段调试需要编程式控制钩子的挂载与移除时机。MAXPrintHookfrom max.nn.hooks import PrintHook # Create hook and name layers hook PrintHook() hook.name_layers(model) # Names all layers based on their attribute path # Build and run graph... # Clean up hook.remove()PyTorchTorchPrintHookfrom test_common.torch_print_hook import TorchPrintHook # Create hook with optional export path hook TorchPrintHook(export_path/tmp/torch_tensors) hook.name_layers(model) # Run model - tensors are automatically saved # Clean up hook.remove()TorchPrintHook定义在 max/tests/integration/test_common/torch_print_hook.py继承自BasePrintHook与 MAX 侧保持一致的命名与导出约定便于后续compare_tensors自动配对。用更少的层调试默认情况下debug_model只运行 1 个隐藏层以加速调试。这通常已足够因为 bug 往往出现在第一层。如有需要可用--num-hidden-layers增加层数# Use 3 hidden layers bazel run //max/tests/integration/tools:debug_model -- \ --framework max \ --pipeline google/gemma-3-1b-it \ --num-hidden-layers 3 # Use all layers (full model) bazel run //max/tests/integration/tools:debug_model -- \ --framework max \ --pipeline google/gemma-3-1b-it \ --num-hidden-layers allFAQ如何在 MAX 与 PyTorch 之间匹配张量对比过程中你会发现 PyTorch/HuggingFace 模型结构与 MAX 模型结构并不总是逐层对齐——一个模型有的层在另一个模型中可能看不到。不读代码很难判断这是否是 bug。此时有两种选择暂停手动对比直接阅读代码弄清楚为什么一个模型暴露了更多层。例如MAX 缓存了k和v因此 dump 中只出现q层。确认架构差异有合理原因后即可继续。跳过架构分歧寻找下一个共享层沿用上面的例子MAX 缓存k、v后可能到layer_norm又完全对齐了。一旦找到同步点就可以确信此前的架构差异并非 bug继续前进。在缩略输出中看不到分歧怎么办先尝试以下两步检查验证失败的细节是否在同一硬件、同一提示词下运行可以通过--prompt参数向debug_model显式指定提示词debug_model默认只运行 1 层--num-hidden-layers 1但某些 bug 只出现在更靠后的层。尝试增大--num-hidden-layers再看。如果仍无帮助可以用compare_tensors数值对比各层来找分歧。这比较繁琐建议采用二分搜索策略。首先为两个框架重新运行debug_model并用-o保存完整张量bazel run //max/tests/integration/tools:debug_model -- \ --framework torch \ --pipeline google/gemma-3-1b-it \ -o torch_tensors/ bazel run //max/tests/integration/tools:debug_model -- \ --framework max \ --pipeline google/gemma-3-1b-it \ -o max_tensors/然后开始对比预期应该匹配的张量例如bazel run //max/tests/integration/tools:compare_tensors -- \ --torch-tensor torch_tensors/0/model.lm_head-output.pt \ --max-tensor max_tensors/model.language_model-output_0.max[!NOTE] 如果某个张量只需简单 reshape 即可比较compare_tensors的--allow-reshape标志可以处理这种情况。当输出中的rtol与atol指标开始发散时你就有了下手的起点可以按上一节描述的方法继续深挖。整套方法论的核心是先用层边界粗筛定位分歧区域再在可疑模块内部细粒度打印、导出完整张量最终用compare_tensors的数值指标锁定具体算子——这套流程同样适用于 MAX 之外的框架组合是 MAX 流水线精度回归与 bug 报告前的标准排查路径。【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考