profile-model

MAX でモデルのプロファイリングを行う

このスキルでは、組み込みアーキテクチャでも、--custom-architectures で読み込んだカスタムアーキテクチャでも、MAX で実行できるあらゆるモデルについて、次の 3 つの疑問に答えます。

1. GPU は実際に使用されていますか？（使用率、メモリ、クロック）
2. モデルはどこに最も時間を費やしていますか？（カーネル／フェーズ）
3. このカーネルが遅いのはなぜですか？（占有率、ストール、ルーフライン）

MAX を pip または pixi でインストールし、公開されている max CLI または Python スクリプトを使って実行します。

何を実行するかの判断方法

各疑問に答えるには、前の手順より詳細でコストのかかる計測が必要です。最も手軽な確認から始め、より介入度の高い手順へと進み、それぞれの結果を見てさらに詳しく調べる価値があるか判断してください。疑問に答えるのに必要な範囲を超えて計測しないでください。

1. まず使用率を確認します。ワークロードの実行中に GPU がアイドル状態または低負荷なら、ボトルネックはホスト側（CPU、転送、小さなバッチ）にあります。その旨を報告して終了してください。カーネルトレースを取得しても、GPU がビジー状態でない限り新たに分かることはありません。
2. GPU がビジー状態なら、カーネルの内訳を取得します。これが一般的なケースで、たいていはこれで結論が出ます。GPU 時間の大半を占めるカーネルが分かります。
3. 特定のカーネルが支配的で、その理由を知る必要がある場合に限り、そのカーネルだけを詳しく調べます。内訳から特定のカーネルが判明している場合を除き、この手順は省略してください。カーネルを何度も再実行するため、時間がかかります。

確認する内容	ツール	コスト
GPU はビジー状態ですか？	max.profiler.gpu（純粋な Python、NVIDIA + AMD）	数秒、追加インストール不要
時間はどこにかかっていますか？	max ... --profile、または nsys（NVIDIA）／rocprofv3（AMD）	プロファイリング付きの実行が数回
1 つのカーネルが遅いのはなぜですか？	Nsight Compute（ncu、NVIDIA のみ）	カーネルごとに時間のかかる計測を 1 回

すべての手順の資料をまとめて読むのではなく、現在の手順に対応するリファレンスを参照してください。

• 使用率の確認 → references/utilization-api.md（および同梱の scripts/gpu_snapshot.py）
• カーネルの内訳、NVIDIA → references/nsys.md
• カーネルの内訳、AMD → references/rocprofv3.md
• 単一カーネルの詳細調査（NVIDIA） → references/ncu.md

--custom-architectures で読み込んだモデル

カスタムアーキテクチャでも、プロファイリング自体の手順は組み込みアーキテクチャと同じです。異なるのは読み込みの部分です。カスタムアーキテクチャには、追加の前提条件と失敗要因があります。インストール済みの MAX バージョンとのインポート互換性、PYTHONPATH に関する落とし穴、アーキテクチャ名の衝突、チャットテンプレートのないベースモデル、カスタム埋め込みモデルに対する max serve の制限などです。これらの問題があると、プロファイリングを実行する前にモデルの読み込みが停止します。--custom-architectures で渡したモデルをプロファイリングする場合は、先に references/custom-architectures.md を読んでください。

結果の読み方（カーネルの構成から分かること）

プロファイリングで分かることは2つあります。GPUが飽和しているか（使用率の確認）と、時間がどこに使われているか（カーネルの内訳）です。確認した結果を診断に結び付けましょう。

• デコードの大半をgemv_split_k_*のGEMVが占め、*_mha_*アテンションとrms_normがそれに続く — 密なLLMのトークン生成（デコードはメモリ律速のGEMV）で見られる正常かつ健全な構成です。特に調べる必要はありません。
• スパースMoEのデコードの大半を、グループ化／ブロックスケールされた行列乗算カーネルとルーティングカーネルが占める — 密なGEMMではなく、エキスパートごとのグループ化行列乗算（*grouped*／block_scaled_*行列乗算）が支配的なカーネルです。これに加えて、top-kルーティング（topk_*、moe_create_indices）やエキスパートのギャザー／スキャッターも見られます。マルチGPUでは、EPのdispatch／combine集団通信も現れます。これはMixture-of-Expertsモデルの健全な構成です。ルーティングやギャザーのオーバーヘッドは想定内であり、行列乗算に匹敵する場合にのみ調べる価値があります。
• 低ビット重み（FP8／FP4／NVFP4）では量子化準備カーネルが追加される — 行列乗算に加えて、動的な活性化量子化やスケールレイアウトのカーネル（*quantize*、*block_scales*）、および通常のgemv／gemmではなくブロックスケール版の行列乗算が見られます。低ビットモデルでは、量子化／逆量子化の準備に時間がかかるのは正常です。それが入力先の行列乗算よりも大幅に長い場合にのみ注意してください。カーネルのプレフィックスはGPUアーキテクチャ固有です（Blackwellではsm100_*、Hopper／MIでは別のものになります）。正確な名前ではなく、カーネルのファミリーで照合してください。
• カスタムアーキテクチャで想定される融合カーネルが使われていない（たとえば、アテンションが*_mha_*カーネルではなく汎用のelementwise／matmulとして表示される、またはノルム／RoPEが融合されていない） — 配線に問題がある兆候です。ロジットが正しくても、想定どおりにグラフが構築されていない可能性があります。立ち上げ時に確認する価値があります。
• デコードのtok/sが極端に低く、プリフィルに似たカーネル構成が各ステップで繰り返される — KVキャッシュがない、または壊れていることで起きる、典型的なO(n²)の再プリフィルです。これは単なる速度の問題ではなく、正しさにも関わるバグです。
• ワークロードの実行中にgpu_usage_percentが低い — ホスト側が律速になっているか、起動／同期のオーバーヘッドがあるか、バッチが小さすぎます。GPUがボトルネックではありません。
• スロットリングの理由が表示される — GPUがクロック制限を受けています。温度や電力の問題に対処するまでは、数値は代表値になりません。

維持すべきアルゴリズム

ツールや MAX のパッケージングは頻繁に変わりますが、維持すべきなのはこの手順です。どの方法で計測する場合も、以下の手順に従ってください。

1. ツールを決める前に環境を検出します。nvidia-smi または rocm-smi を実行してベンダーを確認します。カーネルの内訳を調べるツールや詳細分析ツールはベンダーによって異なります。プロファイラーがインストールされていることを確認します（which nsys ／ which rocprofv3 ／ which ncu）。インストールされていない場合は、途中で失敗させるのではなく、正確なインストールコマンドをユーザーに伝えてください（リファレンスを参照）。
2. 長時間実行する前に確認を取ります。max serve のプロファイリングでは、コンパイルキャッシュがウォームアップされ（コールドコンパイルには数分かかることがあります）、サーバーが起動し、ベンチマークが実行されます。実行する前に、モデル、フラグ、予定しているコマンドをユーザーに示し、確認を待ってください。小さなモデルで一度だけ実行する max generate --profile は、コストが十分に低いため確認を省略できます。
3. 先にキャッシュをウォームアップし、その後プロファイリングします。モデルの初回実行では、一度限りのコンパイルと重みの読み込みに時間がかかり、実際のカーネル実行時間が埋もれてしまいます。プロファイリングなしでウォームアップを実行してから、プロファイリングを実行してください。そうすることで、計測結果にコンパイルではなく、定常状態の推論が反映されます。
4. 計測時間を短く保ちます。同時実行数が 1 の場合、カーネルの構成を確認するには 10 秒の計測で十分です。長時間の計測では、開くのに時間がかかる巨大なトレースファイルが生成される一方、情報は増えません。
5. 速やかに失敗を検出します。サーバーの起動後、数秒以内にプロセスが稼働しており、ログに初期エラー（モデルが見つからない、OOM、フラグが無効など）がないことを確認してから、/health のポーリングを開始してください。すでに停止したサーバーに対してタイムアウトまで待たないでください。
6. 成果物を確認してから報告します。成功を報告する前に、出力ファイルが存在し、サイズがゼロではないことを確認してください。成果物のパス、開き方、主要な数値（上位のカーネル、または GPU のピーク使用率）を報告してください。
7. 自分が起動したものだけを終了します。起動したサーバー／ベンチマークのプロセスグループを終了してください。共有マシンで広範囲に影響する pkill -f max を実行するのは避けてください。他のユーザーの実行を停止させる可能性があります。

Nightly 版と安定版

プロファイリング機能は安定版より先に nightly 版に追加されるため、このスキルでは nightly 版の max-serve ビルドを対象としています。pixi を使ってインストールしてください。

pixi init quickstart -c https://conda.modular.com/max-nightly/ -c conda-forge
cd quickstart && pixi add max-serve
pixi run max --version          # expect a *.dev build

使用率 API（GPUDiagContext、BackgroundRecorder）は conda の max パッケージに含まれているため、通常の pip install max でインストールするホイールではなく、pixi または conda を使ってインストールしてください。通常のホイールでは max.profiler.gpu が公開されない場合があります。以下のコマンドで 404 が発生したりインポートに失敗したりする場合は、最近の nightly 版ビルドを使っていることを確認してください。

インストールに関する注意

• MAX 本体：pixi を使って nightly 版の max-serve パッケージをインストールしたプロジェクト（上記の「Nightly 版と安定版」を参照）。以下の max CLI コマンドはすべて、そのプロジェクトで pixi run max ... を実行できることを前提としています。max-serve パッケージには、MAX でモデルをサーブするために必要な追加の依存関係が含まれています。これらはメインの max パッケージには含まれていません。
• nsys と ncu は CUDA Toolkit に含まれています。CUDA が存在するのに which nsys が失敗する場合は、export PATH=/usr/local/cuda/bin:$PATH を実行してください。それ以外の場合は、NVIDIA から Nsight Systems ／ Nsight Compute をインストールするか、sudo apt-get install nsight-systems を実行してください。
• rocprofv3 は ROCm（/opt/rocm/bin）に含まれています。必要に応じて PATH に追加してください。
• 使用率 API は max 以外のツールを必要としません。max.profiler.gpu を通じて NVML ／ ROCm SMI と直接通信します。

手早く実行する方法

手順が最も簡単なコマンドを以下に示します。各コマンドの詳細は、それぞれのリファレンスファイルを参照してください。

• 「GPU は使われていますか？」 → 短いベンチマークと並行して scripts/gpu_snapshot.py を実行します。純粋な Python で、NVIDIA と AMD の両方で動作します。
• 「手早くカーネルの内訳を確認したい」 → pixi run max generate --model <m> --prompt "hello" --num-warmups 1 --profile を実行します。GPU カーネルの上位 N 件を順位付けした表が出力され、.nsys-rep ファイルが書き込まれます（NVIDIA）。GPU がない場合は、CPU の概要に切り替わります。
• 「サービングのベンチマークをプロファイリングしたい」 → MODULAR_ENABLE_PROFILING=detailed と nsys launch ／ rocprofv3 を使う、サービングエンドポイントの手順に従います。