debug-model

パリティ／一貫性の失敗に対処するプロトコル

モデルはエラーなく実行されますが、出力が正しくありません。スカラー値を出力する F.print のタップでは方向性のあるバグが隠れ、タップを追加するたびにフルリコンパイルが必要になります。まずレイヤーごとのテンソルダンプ比較ツールを作成してください。以降のチェックはすべて、ディスクから読み込んだ numpy データで行えます。

このスキルを使う場合： 実行してフックを追加できる PyTorch リファレンスと MAX の出力が一致しない場合に使います。主な対象は、サーバーとして動作するものの、パリティまたは一貫性チェックに失敗するカスタムアーキテクチャの移植です。このプロトコルは、動作する移植の量子化バリアント、動作するシングル GPU 移植のマルチ GPU 変換、MAX のアップグレード後のリグレッションにも適用できます。信頼できるリファレンスがある場合は、どのようなケースにも適用できます。

このスキルを使わない場合：

• サーバーがロード時にクラッシュする場合 → config、weights、module を修正します（import-model）
• module の実装がまだ完了していない場合 → import-model Phase 2
• すでに検証済みのモデルで、ロジット比較の許容誤差を調整する必要がある場合 → これはしきい値のキャリブレーションであり、このスキルの対象外です

リファレンス

ファイル	次の場合に読みます
comparator-build.md	HF／MAX ダンパーと比較ツールを構築する場合
comparator-output-patterns.md	比較ツールの出力、誤った急変、トークン 0 の不変条件を解釈する場合
agent-workflow.md	並列調査エージェントを割り当てる場合
stacked-failures.md	修正で改善したものの、検証にまだ失敗する場合

MAX に組み込まれたランタイムデバッグ機能（NaN チェック、ソーストレースバック、op ロギング）については、 MAX のデバッグツールを参照してください。 max.nn.hooks.PrintHook（comparator-build.md で説明）は、初期トリアージ用にレイヤーの 入力と出力を出力します。

プロトコル

Step 0: HF の健全性を確認する

同じ HF リポジトリ、プロンプト、チェックポイントで model.generate(...) を実行します。HF の出力に一貫性がない場合は、まずトークナイザーまたはチャットテンプレートを修正してください。問題は MAX モデルではありません。

pixi run python -c "
import torch
from transformers import AutoTokenizer, AutoModelForCausalLM
tok = AutoTokenizer.from_pretrained('<repo>')
model = AutoModelForCausalLM.from_pretrained('<repo>', dtype=torch.float32, 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]))
"

Step 1: 比較ツールを構築する

comparator-build.mdに従ってください。必要な成果物は 3 つです。HF ダンパー、MAX ダンパー（forward() のタップとスタンドアロンランナー）、比較スクリプトです。MAX の forward() 内でダンプテンソルを FP32 にキャストします。

注意：信頼する前にダンパーを検証してください。 MAX がすでに正しくサーブしている ModuleV3 モデルにタップを追加し、両方のダンパーを実行します。olmo3、または --prefer-module-v3 を指定してサーブした llama3_modulev3 を使ってください。すべてのレイヤーで cos ≈ 0.999、両側の prompt_tokens.npy が同一、post_embed の cos = 1.0 になることを確認してください。これに満たない場合は、ダンパーに問題があります。移植版の比較結果を読む前に修正してください。

Step 2: 比較ツールの出力を確認してから、分岐する

comparator-output-patterns.mdに従ってください。モデルを二分探索する前に、誤った急変（誤った hidden_states のインデックス指定、decode-prefix ダンプでの attention_mask の欠落）を確認します。

ガードを通過した最初の比較実行結果から、次のステップを選びます。

• 一部のレイヤーで乖離する → レイヤーを調査します。Step 3 から Step 5 に進みます。
• すべてのレイヤーが一致する（cos ≥ 0.99）が、生成結果はまだ乖離する → モデルの演算はおそらく正しいです。Step 6 に進みます。レイヤーの二分探索は行わないでください。
• パターンが誤った急変の特徴と一致する → ダンパーを修正し、再度ダンプして、もう一度確認します。壊れた比較ツールを使ってモデルをデバッグしないでください。

全体の cos が曖昧な場合は、トークンごと、次元ごとのコサインスライスを計算します。

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])]

HF では大きくスパイクし、MAX では平坦な max_diff が高い場合、通常は移植版で形成されなかったアテンションアンカーを HF が形成しています。

ステップ 3：調査エージェントを派遣する

agent-workflow.mdに従います。リードエージェントがダンプを分析し、テンソルの証拠に基づいて仮説に順位を付けます。ヘルパーエージェントは並行して作業します（重み統計、コード差分、カーネルの調査、サブタップの準備）。リードエージェントが原因を特定するまでは、修正を試みるエージェントを派遣しないでください。

ステップ 4：再コンパイルの前に数値で検証する

仮説ごとに、ダンプテンソルを読み込み、修正によって得られる結果を計算して、HF と比較します。一致したら再コンパイルします。一致しなければ次の仮説に進みます。

ステップ 5：修正を適用し、再ダンプして再比較する

コンパイルを 1 回、スモークテストを 1 回実行し、全レイヤーで cos > 0.99 となるよう、比較処理をすべて実行します。検証に失敗した場合は、stacked-failures.mdを参照してください。

ステップ 6：サーブとパイプラインを切り分ける

デコードステップ K の教師強制ダンプが HF と一致しているのに生成テキストが異なる場合、モデルの計算は正しい可能性が高いです。レイヤーを再度二分探索する前に、以下の順で二分探索してください。

チェック	成功	失敗 →
教師強制ダンプ @ K	cos ≥ 0.99、argmax が一致	ステップ 1〜5（モデルのバグ）
インクリメンタルなパイプラインデコード @ K	トークン K が HF と一致	デコード状態のバグ（KV、コンボリューションキャッシュ）
サーブとパイプライン @ K	一致	ハーネスのバグ（トークナイザー、チャットテンプレート、トークンの復元）

不足している場合は、パイプラインデコード比較、インクリメンタルなレイヤーダンプ、サーブ比較のスクリプトを作成します。教師強制とパイプラインの両方が成功しているのにサーブが失敗する場合は、モデルを編集しないでください。