MAX 模型能加载/服务且能生成 token…

当 MAX 输出与可运行且可 hook 的 PyTorch 参考不一致（乱码、greedy token 分歧、argmax 不同等）时，按该协议先建参考 vs MAX 张量转储比较器，再数值验证修复并区分图/解码状态/服务 harness 问题。

适用场景

解决思路

1. 按需阅读参考文件：构建 HF/MAX dumper 和 comparator 时读 references/comparator-build.md；解释 comparator 输出、false cliffs、token-0 invariant 时读 references/comparator-output-patterns.md；调度并行调查 agent 时读 references/agent-workflow.md；修复有效但验证仍失败时读 references/stacked-failures.md。
2. 需要 MAX 内置运行时调试选项（NaN 检查、源码回溯、op logging）时查看 https://max.modular.com/develop/debugging/；`max.nn.hooks.PrintHook`（见 comparator-build.md）可打印层输入和输出用于快速 triage。
3. Step 0：在相同 HF repo、prompt、checkpoint 上运行 `model.generate(...)` 做 HF sanity-check；如果 HF 输出不连贯，先修 tokenizer/chat-template，MAX 图不是问题。示例：`pixi run python -c "import torch from transformers import AutoTokenizer, AutoModelForCausalLM tok = AutoTokenizer.from_pretrained('<repo>') model = AutoModelForCausalLM.from_pretrained('<repo>', torch_dtype=torch.bfloat16, device_map='auto') text = tok.apply_chat_template([{'role':'user','content':'Hello!'}], tokenize=False, add_generation_prompt=True) out = model.generate(**tok(text, return_tensors='pt').to(model.device), max_new_tokens=32, do_sample=False) print(tok.decode(out[0]))"`
4. Step 1：按 comparator-build.md 构建 comparator，需要三个产物：HF dumper、MAX dumper（图编辑 + 独立 runner）、comparator script；在 MAX 图中把 dump 张量 cast 到 FP32。
5. Step 1 守卫：在信任 dumper 前验证它们。在一个 MAX 已正确服务的模型上运行两个 dumper（任何已注册 Llama 可用）；期望每层 cos ≈ 0.999，两侧 `prompt_tokens.npy` 完全相同，`post_embed` cos = 1.0。若达不到，说明 dumper 坏了——在把 port 上的比较结果当回事之前先修好它们。
6. Step 2：按 comparator-output-patterns.md 读取 comparator 输出，然后分支；在 bisect 图之前检查 false cliffs（错误的 `hidden_states` indexing、decode-prefix dump 缺少 `attention_mask`）。
7. Step 2 分支：首次可信 comparator 运行是分叉，不是检查点。若某些层 diverges → 进行 graph hunt，继续 Steps 3 到 5；若每层匹配（cos ≥ 0.99）但生成仍 diverges → 图可能正确，跳到 Step 6，不要 bisect 层；若模式匹配 false-cliff 签名 → 修 dumper，re-dump，re-read，不要用坏 comparator 调试图。
8. Step 2 计算：当全局 cos 模糊时计算 per-token 和 per-dim cosine slices：`cos_per_token = [cos(h[t], m[t]) for t in range(h.shape[0])]`，`cos_per_dim = [cos(h[:, d], m[:, d]) for d in range(h.shape[1])]`。若 `max_diff` 高且 HF 有尖峰而 MAX 平坦，通常表示 HF 形成了你的 port 没有形成的 attention anchor，而不是 MAX 爆炸。
9. Step 3：按 agent-workflow.md 调度调查 agents。一个 lead agent 分析 dumps，并用张量证据给 hypotheses 排序；helpers 并行运行（weight stats、code diff、kernel inspection、sub-tap prep）。在 lead 定位前不要调度 fix-attempt agents。
10. Step 4：在重新编译前数值验证。对每个 hypothesis：读取 dump tensors，计算该 fix 会产生什么，与 HF 比较；匹配 → recompile；不匹配 → 下一个 hypothesis。
11. Step 5：应用 fix，re-dump，re-compare。一次 compile，一次 smoke，完整 comparator pass（所有层 cos > 0.99）。若验证仍失败，见 stacked-failures.md。
12. Step 6：当 decode step K 的 teacher-forced dumps 与 HF 匹配但生成文本 diverges 时，图可能正确；在重新 bisect 层之前先 bisect：`Teacher-forced dump @ K` 通过=cos ≥ 0.99 且 argmax matches，失败→Steps 1 到 5（graph bug）；`Incremental pipeline decode @ K` 通过=token K matches HF，失败→Decode-state bug（KV、conv cache）；`Serve vs pipeline @ K` 通过=match，失败→Harness bug（tokenizer、chat template、token recovery）。
13. Step 6 补充：若缺少 pipeline decode compare、incremental layer dump、serve compare scripts，则构建它们；若 teacher-forced 和 pipeline 都通过但 serve 失败，不要编辑 graph。

适用边界 · 注意事项

• 服务器在加载时崩溃：应修 config、weights、graph（用 import-model），不是此技能。
• 尚未完成图实现：应走 import-model Phase 2。
• 已验证模型只需要调 logit-comparison 容差：那是 threshold calibration，不是 corruption。