model-compute-simulation

モデル計算シミュレーション

概要

演算子の順序、テンソルの次元、FLOPs、MFU、並列化の確認について質問された場合に使用します。シミュレーターはモデル設定を読み込み、代表的な演算子のシーケンスを構築し、テンソル形状とFLOPsを出力します。また、測定したレイテンシからMFUを推定できます。

入力

シミュレーションを実行する前に、以下の入力を収集または確認してください。

項目	重要な理由	入手方法	ユーザーが指定しない場合のデフォルト
モデル名	model-config-index.json 内の設定に対応付けられ、アーキテクチャ全体を決定します	ユーザーに尋ねるか、トレースのコンテキストから推定します	—（必須）
設定の正確性	インデックス内の値は実際のサービング設定と異なる場合があります（例：routed_expert_intermediate_size、compress_ratios）	ユーザーに config.json の提供を依頼するか、主要なパラメーターをHuggingFaceと照合します	注意書きを添えてインデックス内の値を使用します
GPU の種類	MFUの分母に使うピークFLOPSを決定します	ユーザーに尋ねます	—（MFUの計算には必須）
dtype（bf16 / fp8）	ピークFLOPSの選択に影響します。fp8ではピークが2倍になります	ユーザーに尋ねます	bf16
バッチサイズとシーケンス長	FLOPsとテンソル形状に直接影響します	ユーザーに尋ねます	B=1、S=1（デコード）
TP / DP / EP	TPはGEMMのFLOPsをGPU間で分割し、EPはエキスパートのFLOPsを分割します	ユーザーに尋ねます	実行マニフェストを確認します。なければ、前提を明示して報告します
測定レイテンシ（ms）	MFUの分子に必要です。GPUごとのフォワードパスのウォールクロック時間である必要があります	ユーザーに尋ねるか、プロファイラートレースから抽出します	—（任意。指定がなければMFUは計算しません）

モデルが model-config-index.json にない場合は、推定を実行する前にユーザーに config.json のパスを尋ねるか、インデックスに設定を追加してください。 2026-10-05のインデックスには、V4 Flash/Pro/V4.1、K3、GLM-5.2/5.3/5.3-Flash、Qwen3.8-Flash-Next、Hy3/Hy4、Inkling、dots3、Step-3.7、Nemotron-3/3.5、LongCat、Gemma4の公開HF設定リビジョンが固定され、古いモデルの次元が修正されています。 Qwen/Qwen3.8-A95B はこの監査時にHTTP 401を返したため、インデックスには含まれていません。 生のネストされたHF設定には --config /path/to/config.json を使用してください。ローカルの正規化処理が、テキストラッパーとエキスパート／レイヤーの別名を展開します。

投機的MoEの形状とタイミングの制限

DSV4.1では、トレースから実際のターゲット／ドラフト行数を取得してください。DSPARKのブロックサイズが5の場合、リクエストBS=1でターゲット検証行を6行発行することがあります。計算された行数の代わりに受理長を使用しないでください。TPでシャーディングされた共有エキスパートの形状は、ルーティングされたエキスパートの割り当てやEPとは分けて考慮してください。未検証のモデルテンプレートをTP/EPで割り、測定済みFLOPsとして扱ってはいけません。シミュレーターは、ルーティングされたエキスパートの外側では一律にTPで除算し、内側では一律にEPで除算します。これは仮定を置いた概算です。MFUを解釈する前に、複製されたルーター、正規化、潜在射影、バックエンドに依存する共有エキスパートの所有関係について、実行ごとの調整が必要です。固定されたV4.1のエントリーは静的なターゲットモデルテンプレートです。DSPARKのドラフト、ビジョン、Engram/PLEのメモリトラフィック、バックエンドのディスパッチについては、別途根拠が必要です。

カーネル実行時間の合計には、オーバーラップやPDLの依存関係による待ち時間が含まれる場合があります。パス全体のMFUの分母にはウォールクロック時間を使い、すべてのFP8演算で有効FLOPsが2倍になると仮定せず、実測したGPUのSKUとdtypeに基づくピーク値を使用してください。カーネル名をアテンション、共有エキスパート、ルーティング、mHCに割り当てる際は、ディスパッチとタイミングの原則に従ってください。

ワークフロー

ステップ1：モデル設定を読み込む

モデル名を特定し、設定パラメーターを読み込みます。

python3 skills/model-compute-simulation/scripts/model_compute_simulator.py "<model name>" --list-models

スクリプトはモデル名を references/model-config-index.json と照合します。このファイルには、公開されているHuggingFaceの設定パラメーター（hidden_size、num_experts、MLAランクなど）が保存されています。

モデルがインデックスにない場合は、ユーザーに config.json のパスを提供するよう伝えるか、インデックスの更新を依頼してください。

ステップ 2：実行フローとテンソル次元を生成する

バッチサイズ、シーケンス長、並列化設定を指定してシミュレーターを実行します。

python3 skills/model-compute-simulation/scripts/model_compute_simulator.py "Qwen3-235B-A22B" \
  --batch-size 1 --seq-len 1 \
  --tp 8 --dp 1 --ep 8 \
  --gpu b200 --dtype bf16

シミュレーターは次の内容を出力します。

• FLOPs とテンソル形状（shape_in → shape_out）を含む、レイヤーごとの演算子シーケンス
• レイヤーごとの Attention と MoE/FFN の FLOPs の比率
• 1 回のフォワードパスにおけるモデル全体の FLOPs

デコードの場合は、--seq-len 1 --context-len TOTAL_KV_LENGTH を使用します。 拡張の場合、--context-len はプレフィックスの長さで、新しい --seq-len トークンに対して因果計算が行われます。Full/Window Attention では、QK と AV の FLOPs に KV コンテキストが含まれます。 --all-token-logits を指定しない場合、LM ヘッドは最終トークンのロジットを計算します。 各実行では、バッチ、形状、並列化、GPU、dtype に関する前提が stderr に出力されます。 スパース選択、KDA/Mamba のスカラー演算、正規化／Sinkhorn、ゼロエキスパートの top-k は、実測された命令数ではなく、アーキテクチャに基づく推定値です。LongCat のルーティング FLOPs は、すべての top-k がゼロ以外であると仮定しています（ルーティングを実測するまでは上限値です）。 プリフィルの場合は、--seq-len <prompt_length> を使用します。

ステップ 3：実測レイテンシで MFU を推定する

実測したフォワードパスのレイテンシを指定して MFU を計算します。

python3 skills/model-compute-simulation/scripts/model_compute_simulator.py "Qwen3-235B-A22B" \
  --batch-size 1 --seq-len 1 \
  --tp 8 --dp 1 --ep 8 \
  --gpu b200 --dtype bf16 \
  --measured-ms 15.0

MFU = 理論上の最小時間 / 実測時間 × 100%

シミュレーターは次の内容を出力します。

• 全体の MFU
• レイヤーごとの MFU（レイヤー時間が均一であるという前提）
• 演算子ごとの FLOPs の比率（支配的な演算を特定するため）

GPU のピーク FLOPS は references/gpu-specs.json から読み込まれます。付属のハードウェア表には H100/H200/B200、B300、GB300、MI355X、RTX PRO 6000、DGX Spark が掲載されており、それぞれに公式 URL が記載されています。H20 は、未検証の過去の推定値として残されています。未知の dense ピーク値は null であり、その dtype の MFU は計算できません。RTX Server と Spark のスパース性は未確認です。B300/GB300 のメモリ容量は物理的な最大値であり、使用可能な割り当て容量ではありません。--dtype は bf16、fp8/mxfp8、fp4/mxfp4/nvfp4 を受け付けます。INT8 では、別途公開されているピーク値を使用する必要があります。該当するローカルマシンで実行する場合は、--gpu h100、--gpu b2000、--gpu b200 などのエイリアスを使用してください。

ステップ 4：カーネルレベルのレイテンシで演算子ごとの MFU を計算する

カーネルごとの実測レイテンシがある場合、カーネルの実行時間を計算フローに対応付けて、演算子ごとの MFU を計算します。

方法 A：--kernel-flow（カーネルレベルの MFU、推奨）

カーネルごとの詳細を JSON として指定し、シミュレーターに渡して カーネルレベルの MFU 分析を行います。これにより、計算フローの すべてのカーネル行が保持され、FLOPs／MFU 列が追加されます。

python3 skills/model-compute-simulation/scripts/model_compute_simulator.py "Qwen3-235B-A22B" \
  --batch-size 1 --seq-len 8192 \
  --tp 8 --dp 1 --ep 8 \
  --gpu b200 --dtype bf16 \
  --measured-ms 100 --kernel-flow @/tmp/layer3_detail.json

--kernel-flow パラメーターは、JSON 文字列または @file パスを受け取ります。 計算フローのすべてのカーネル行を保持し、次の項目を追加した カーネルレベルの MFU テーブルを生成します。

• Mapped Op：このカーネルが対応する演算子
• FLOPs：演算子の合計 FLOPs
• Theo(us)：理論上の最小時間
• MFU%：実測 FLOPs 利用率
• shape_in→shape_out：演算子のテンソル次元

--kernel-flow を指定すると、カーネルレベルの MFU テーブルにカーネルごとの 形状と FLOPs の情報が含まれるため、演算子ごとの静的テンプレートは省略されます。 出力には、モデルの概要、サービング設定、合計 FLOPs、実測レイヤー時間から 算出した全体 MFU、カーネルレベルの MFU テーブルが含まれます。--format json では、生の根拠データは kernel_flow に格納され、テキストテーブルは追加されません。

マッピングのルール：

• 直接一致するカーネル（mla、moe、mhc、rmsnorm、hadamard、rope、quant、topk など）：時間を対応する演算子に直接割り当てます
• 汎用 GEMM カーネル（gemm_fp8、gemm_bf16）：未割り当ての投影 GEMM 演算子に、FLOPs の比率に応じて時間を配分します
• オーバーヘッドカーネル（allreduce、moe_align、moe_sort、other）：行を保持し、FLOPs／MFU は N/A と表示します

FP8 カーネルの MFU 補正：--dtype bf16 を指定した場合でも、カテゴリ moe （fused_moe_kernel）および gemm_fp8 のカーネルは内部で fp8 演算を使用します。 これらのカーネルでは、MFU の分母に bf16 ピーク値ではなく、GPU の fp8 ピーク FLOPS （bf16 ピークの 2 倍）を使用します。fp8 の分母を使用したことを示すため、 算出された MFU には上付き文字 ⁸ が付きます（例：63.7%⁸）。 gemm_bf16 カーネルでは、引き続き bf16 ピーク FLOPS を分母に使用します。

方法 B：--kernel-detail（演算子レベルの MFU、旧方式）

--kernel-flow と同じ入力を使用しますが、演算子レベルの要約テーブルを 出力します（カーネルごとではなく、演算子ごとに集計）。簡潔な表示が必要な場合に使用します。

python3 skills/model-compute-simulation/scripts/model_compute_simulator.py "Qwen3-235B-A22B" \
  --batch-size 1 --seq-len 8192 \
  --tp 8 --dp 1 --ep 8 \
  --gpu b200 --dtype bf16 \
  --measured-ms 100 --kernel-detail @/tmp/layer3_detail.json

方法 C：--kernel-ms（カテゴリレベルの近似）

カーネルごとの詳細を取得できない場合に限り、手動で集計したカテゴリーマップを使用します。

python3 skills/model-compute-simulation/scripts/model_compute_simulator.py "Qwen3-235B-A22B" \
  --batch-size 1 --seq-len 8192 \
  --tp 8 --dp 1 --ep 8 \
  --gpu b200 --dtype bf16 \
  --measured-ms 100 --kernel-ms '{
    "mla": 4.922, "moe": 1.644, "allreduce": 0.769,
    "hadamard": 0.348, "mhc": 1.388, "gemm_fp8": 1.692,
    "gemm_bf16": 0.125, "rmsnorm": 0.227, "quant": 0.311,
    "rope": 0.209, "topk": 0.122, "activation": 0.071,
    "other": 0.437
  }'

--kernel-ms パラメーターは、カーネルカテゴリー名と実測時間（ミリ秒）を 対応付ける JSON オブジェクトを受け取ります。カテゴリー全体にわたって FLOPs の比率に 応じて時間を配分します。汎用 GEMM カテゴリー（gemm_fp8、gemm_bf16）が複数の演算子 カテゴリーにまたがるため、--kernel-detail より精度が低くなります。

--per-layer-ms、--kernel-ms、--kernel-detail、--kernel-flow のうち、 指定できるのは 1 つだけです。すべての実測時間は正の値である必要があります。 3 種類のカーネル入力では、パス全体の実測ウォールクロック時間を示す --measured-ms も必要です。これらの例にある 100 ms は、実測値に置き換えるための プレースホルダーです。ストリームが重複する場合、カーネル時間の合計から経過時間を 算出することはできません。

出力には次の項目が含まれます。

• モデルアーキテクチャの概要（layers、hidden_size、attention_type、MoE 設定）
• レイヤーごとの計算フロー：テンソル次元、FLOPs、shape_in→shape_out を含む演算子の順序
• 演算子ごとの MFU テーブル：各演算子の FLOPs、理論時間、（トレースから得られた）実測時間、MFU%
• カーネルから演算子へのマッピングの説明（直接一致、FLOPs 比例、オーバーヘッド）
• 全体およびレイヤーごとの MFU

使用する場面

• 既知のモデルまたは設定について、計算レベルの詳細が必要な場合
• 特定のサービング形状について、実行フロー、テンソル次元、または FLOPs を尋ねられた場合
• MFU について尋ねられ、実測のフォワードパス遅延を提示できる場合
• 異なる並列処理設定間で計算プロファイルを比較する場合

便利なコマンド

既知のモデル ID を一覧表示する：

python3 skills/model-compute-simulation/scripts/model_compute_simulator.py --list-models

既知の GPU タイプを一覧表示する：

python3 skills/model-compute-simulation/scripts/model_compute_simulator.py --list-gpus

自動化用に JSON を出力する：

python3 skills/model-compute-simulation/scripts/model_compute_simulator.py "GLM-5" --format json

レポートのチェックリスト

次の項目を含めてください。

1. モデルアーキテクチャの概要：モデル名、設定の参照元、num_layers、hidden_size、attention_type、MoE の設定（num_experts、topk、shared_experts）、MHC、head_dim
2. サービング設定：batch_size、seq_len、TP、DP、EP、GPU、dtype
3. レイヤーごとの計算フロー（最初の代表的なレイヤーを詳細に示す）：
   • 演算子の順序を示す表：name、category、FLOPs、shape_in → shape_out
   • Attention と MoE/FFN の FLOPs の割合
4. 単一のフォワードパスにおけるモデル全体の FLOPs
5. カーネルレベルの MFU 表（--kernel-flow が指定された場合）：
   • 計算フローに含まれるすべてのカーネル行を維持します（削除しません）
   • カーネルごとの列：# | Half | Category | Simplified Name | dur(us) | % | Mapped Op | FLOPs | Theo(us) | MFU% | shape_in→shape_out
   • 直接マッチするカーネル：対応する演算子の FLOPs/MFU を表示します
   • オーバーヘッドカーネル：FLOPs/MFU は N/A とし、行は維持します
6. 演算子レベルの MFU 表（--kernel-detail または --measured-ms が指定された場合）：
   • 各演算子について、name、category、合計 FLOPs、GPU ごとの FLOPs、理論時間、（トレースから取得した）実測時間、MFU% を示します
   • カーネルカテゴリから演算子へのマッピングを説明します
7. 全体の MFU と レイヤーごとの MFU
8. 一行の要約：支配的な計算カテゴリ、MFU の状態、主なボトルネック

トレースに基づく検証（extract_compute_flow_from_trace.py）

scripts/extract_compute_flow_from_trace.py を使用して、torch profiler のトレースから実際の演算子の順序とテンソルの次元を抽出し、静的テンプレートと比較して正解データとして検証します。

# Extract compute flow from a trace
python3 skills/model-compute-simulation/scripts/extract_compute_flow_from_trace.py \
  --input /path/to/trace.json.gz --format text

# Compare trace against static template
python3 skills/model-compute-simulation/scripts/extract_compute_flow_from_trace.py \
  --input /path/to/trace.json.gz \
  --compare qwen3-235b-a22b \
  --batch-size 1 --seq-len 1 --tp 8 --ep 8

トレースとテンプレートの演算子の有無は、matmul、attention、norm、router などのセマンティックファミリーを通じて比較します。生の aten::* 名をセマンティックなテンプレート名と直接比較することはありません。正の --min-flops しきい値を指定すると、FLOPs を特定できなかった演算子が除外されます。

計算フローの確認階層

静的テンプレートまたはトレース抽出で計算プロセスを完全に確認できない場合（スコープが曖昧、shape が不足、新しいモデルアーキテクチャなど）は、次の段階的な確認手順に従ってください。

1. 静的テンプレート（model_compute_simulator.py + model-config-index.json） — 高速で、既知のモデルを網羅します

2. トレース抽出（extract_compute_flow_from_trace.py） — 実際の実行と照合してテンプレートを検証します

3. 推論フレームワークのソースコード — トレースが不十分な場合（Input Dims の欠落、CUDA Graph のリプレイ、スコープ情報のないコンパイル済みカーネルなど）は、サービングフレームワークのソースコードからモデルのフォワードフローを直接確認します。

   • SGLang：python/sglang/srt/models/<model_name>.py — forward() メソッド、および python/sglang/srt/layers/layer_boundary/factories.py の declare_attn/declare_ffn ステージ境界が含まれています
   • vLLM：移行済みの 2026 年のファミリーは vllm/models/<family>/{common,nvidia,amd}/、旧モデルは引き続き model_executor/models にあります
   • TensorRT-LLM：tensorrt_llm/_torch/models/modeling_<family>.py + モデル設定

   フレームワークのソースコードを確認する際は、次の点に注目してください。

   • forward() メソッド：演算子の呼び出し順序と残差接続
   • QKV / O projection：LoRA 形式の down/up projection（q_lora_rank、o_lora_rank）を使用するかどうか
   • MoE ルーティング：top-k 選択、shared expert と routed expert の分割
   • TP/EP のスライス：どの次元を分割するか、および FLOPs を GPU 間でどのように分配するか
   • 静的テンプレートに含まれていないモデル固有の演算子（MHC、Hadamard、indexer など）

   対応：フレームワークのソースコードから静的テンプレートとの差異が見つかった場合は、必要に応じて model-config-index.json および／または build_layer_ops() を更新してください。

トレース抽出の制限事項

制限事項	詳細	回避策
record_shapes=True が必要	トレースは形状記録を有効にして取得する必要があります。有効にしないと、Input Dims フィールドが存在せず、FLOPs を計算できません	SGLang のライブキャプチャと vLLM の torch_profiler_with_stack=true では、すでに有効になっています。TensorRT-LLM では、record_shapes=True を追加する py_executor.py のオーバーライドが必要です
CUDA Graph モード	グラフのリプレイ中、cpu_op イベントはキャプチャ時に一度しか表示されない場合があります。リプレイされたイテレーションの形状情報は再記録されません	スクリプトはグラフのキャプチャフェーズを検出し、影響を受ける演算に注記を付けます。すべてを網羅するには、イーガーモードのトレースを使用してください
TP で分割された次元	トレースには完全なモデルのビューではなく、TP 分割後の次元（例：H/TP）が表示されます	--compare モードで --tp を使用し、トレースの FLOPs を完全なモデル相当の値に換算してください
スコープ帰属の品質	Python スコープは with_stack=True に依存します。一部のフレームワークやコンパイル済みのパスでは、スコープチェーンが浅い、または欠落している場合があります	適切に縮退処理され、スコープを解決できない演算は「other」に分類されます
静的テンプレートの代替ではありません	トレース抽出は検証と探索のためのツールです。静的テンプレートは、引き続き主要な高速分析手段です	新しいモデルのテンプレートを検証するにはトレース抽出を使用し、差異が見つかった場合は model-config-index.json を更新してください

参考資料

• references/model-config-index.json：モデルの設定パラメーター（hidden_size、エキスパート数、MLA ランクなど）。
• references/gpu-specs.json：MFU 計算用の GPU ピーク FLOPS 仕様。
• scripts/extract_compute_flow_from_trace.py：トレースベースの計算フロー抽出およびテンプレート検証ツール。

ソースの監査先：SGLang V4、 K3 latent experts、 NVIDIA HGX dense/sparse specs、 AMD MI355X specs。 HF フィールドの出典は hf_config_revision における hf_config_source です。正確な出典を確認するには、 https://huggingface.co/<repo>/blob/<revision>/config.json を構成してください。 設定を更新しても、GPU での実行を意味するものではありません。