magpie-kernel-evaluator

Magpie

Magpie を使って、関連する次の 3 つの作業を行います。

1. 推論ワークロードをベンチマークし、スループット、レイテンシ、トレースを収集します。
2. GPU カーネルの正確性とパフォーマンスを分析または比較します。
3. ベンチマークで見つかったボトルネックから、ソースコード、候補カーネル、エンドツーエンドの検証まで、最適化ループを進めます。

チェックアウト済みの Magpie バージョンでサポートされている機能のみを説明してください。検証されていない ROCm、GPU、フレームワーク、または実験的な統合への対応を推測しないでください。

ワークフローを選択する

ユーザーの目的	ワークフロー
1 つの実装を評価する	analyze
2 つ以上の実装を順位付けする	compare
モデルサービングのパフォーマンスを測定する	benchmark
既存のトレースから負荷の高いカーネルを見つける	スタンドアロンのギャップ分析
プロファイリング済みの推論ワークロードを説明する	benchmark → TraceLens の後処理 → ステージ／ルーフラインのレビュー
エンドツーエンドのワークロードを最適化する	benchmark → TraceLens／ギャップ分析 → ソースマッピング → analyze／compare → 再ベンチマーク

再現可能な作業や複数ステップの作業には YAML 設定を使用します。簡単な探索的実行にはインライン CLI 引数を使用します。

事前確認

このスキルをインストールしても、Magpie アプリケーション（magpie-eval）はインストールされません。準備のみを求められた場合は、提供されたフィクスチャと reference.md を読み、求められた計画または設定を作成し、未検証のままのコマンドを明示してください。ユーザーがパッケージのインストールやワークロードの実行を禁止している場合は、それらを行わないでください。Magpie がインストールされていなくても、計画の準備はできます。

Magpie のワークロードを実行する前に、次を確認してください。

1. 使用する Python 環境（Python 3.10 以降）で magpie --help を確認します。コマンドが見つからない場合は、同じ環境で python -m Magpie --help を試してください。モジュールのエントリーポイントが動作する場合は、CLI の代わりに使用できます。No module named Magpie は、その環境にアプリケーションがインストールされていないことを意味します。インストール済みの Magpie パッケージ内でエラーが発生した場合は、報告されたインポートまたは依存関係の問題を診断してください。

2. Magpie がインストールされていない場合は、続行する前に使用する環境にインストールします。

   python -m pip install git+https://github.com/AMD-AGI/Magpie.git
   

   既存の Magpie ソースチェックアウトがある場合は、代わりに python -m pip install -e /path/to/Magpie を使用します。インストール済みのスキルフォルダーとテストケースのワークスペースは、Magpie のソースチェックアウトではありません。magpie --help または python -m Magpie --help を再実行して、インストールを確認します。失敗した場合は、ワークロードを実行する前にエラーを報告してください。

3. 選択したワークフローのインストール済みインターフェイスを確認します（モジュールのエントリーポイントを使う場合は、python -m Magpie に置き換えてください）。

   magpie --help
   magpie analyze --help
   magpie compare --help
   magpie benchmark --help
   magpie --gpu-info
   

4. 該当する場合は、必要なツール、モデルへのアクセス、GPU の可視性、書き込み可能な出力領域、コンテナまたは Ray へのアクセスを確認します。Python パッケージをインストールしても、ROCm／CUDA、プロファイラー、モデルの重みはインストールされません。

5. バージョンに関する記述をする前に、リポジトリの互換性マトリックスを確認します。ROCm またはそこに記載されていないハードウェアは、テストするまで未検証として扱ってください。

6. ベンチマークを比較できるように、正確な設定、モデルのリビジョン、イメージ、環境変数、GPU 割り当て、Magpie のコミットを記録します。

カーネルを分析する

正確性やプロファイラーの設定が重要な場合は、設定ファイルを使用してください。

magpie analyze --kernel-config path/to/kernel.yaml

単一カーネルを簡単に実行するには、次を使用します。

magpie analyze path/to/kernel.hip --type hip --testcase "./run_test.sh"

サポートされている公開カーネルタイプは hip、cuda、pytorch、triton です。プロファイリングなしで正確性または実行を検証したい場合に限り、--no-perf を使用してください。

実行に成功したことを数値的な正確性と同一視しないでください。最適化後の結果を採用または却下する場合は、代表的なテストケースを指定してください。

カーネルのバリエーションを比較する

少なくとも 2 つの実装を比較し、ベースラインを明示してください。

magpie compare --kernel-config path/to/compare.yaml

候補間で入力、許容誤差、ウォームアップ、反復回数、GPU 割り当て、プロファイラーの設定を同一にしてください。パフォーマンスの順位を検討する前に、正確性に失敗した候補を除外してください。

テストケースなしで PyTorch を使用する場合、Magpie の組み込みチェックで検証できるのは各結果が有限値であることだけです。バリエーション間の数値的な等価性は証明できません。数値検証にはテストケースが必要です。

ベンチマーク推論

チェックイン済みのベンチマーク設定を優先してください。

magpie benchmark --benchmark-config path/to/benchmark.yaml

安定版の公開 CLI は vllm、sglang、atom をサポートしています。直接の docker および local 実行モードに対応しています。分散実行には、YAML 設定とリポジトリの Ray の例を使用してください。内部の列挙型や部分的なコードパスにのみ存在する連携機能を、安定版として案内しないでください。

プロファイリングは意図的に有効にしてください。プロファイラーの実行はレイテンシーに影響するため、クリーンなベースラインの代わりに使用しないでください。同等のワークロードを使って、スループット、完了したリクエスト数、TTFT、TPOT、ITL、エンドツーエンドのレイテンシーを比較してください。

TraceLens でトレースを後処理する

プロファイリング対象のベンチマーク YAML で TraceLens を有効にしてください。torch トレースが必須の入力です。

benchmark:
  profiler:
    torch_profiler:
      enabled: true
    tracelens:
      enabled: true
      analysis_mode: inference
      analysis_stages: all
      export_format: csv

vLLM／SGLang では analysis_mode: inference を使用してください。利用可能な場合は rank-0 のトレースを prefilldecode、decode、prefill の各ステージに分割し、TraceLens による後処理を実行して、完全なステージレポートと簡潔な *_kernel_roofline_simple.csv ファイルをベンチマークのワークスペース内の tracelens/ ディレクトリに出力します。PyTorch トレースを直接レポートする場合は、analysis_mode: pytorch を使用してください。

まず、簡潔なルーフライン CSV を開いてください。行を kernel_time_ms_sum または time_pct で順位付けし、次に roofline_bound、演算強度、実測 TFLOP/s または TB/s、pct_roofline_mean を使って最適化の仮説を立ててください。後処理が成功したと判断する前に、benchmark_report.json.tracelens_analysis に出力があり、エラーがないことを確認してください。従来の直接的な単一ランクまたは複数ランクの集団通信レポートが必要なタスクでは、analysis_mode: pytorch を使用してください。

Magpie に統合された TraceLens のステージでは、CSV／Excel の分析成果物が生成されます。エージェントが作成した analysis.md は生成されません。ユーザーが優先順位付きのエージェント型レポートを求めている場合は、インストールされていれば、取得済みのトレースを別個の tracelens-analysis-orchestrator スキルに渡してください。その結果は Magpie のベンチマークレポートとは区別してください。

既存のトレースを分析し、ソースを特定する

benchmark で --trace-dir を直接指定して、スタンドアロンのギャップ分析を実行してください。

magpie benchmark \
  --trace-dir path/to/torch_trace \
  --top-k 20 \
  --find-kernel-sources \
  --kernel-source-repos path/to/repository

位置引数の gap-analysis トークンを挿入しないでください。これは CLI のサブコマンドではありません。生成された集計 CSV とランクごとの CSV を調べ、すべての正規化されたカーネル名が一意に対応付けられると決めつけず、ソースマッピングの信頼度を保持してください。

最適化の反復を進める

1. プロファイリングなしでベースラインのベンチマークを実行し、その設定とレポートを保存します。
2. torch プロファイリングと TraceLens の推論後処理を有効にして、再度実行します。
3. ステージ単位の TraceLens ルーフライン要約を確認し、支配的な処理と、演算、メモリ、通信に関するボトルネックの可能性を分類します。
4. 代表的な定常状態ウィンドウに対してギャップ分析を実行し、具体的なカーネルを順位付けします。
5. 単一のディスパッチ時間だけでなく、総寄与度に基づいてボトルネックを選びます。
6. 選んだカーネルをソースと実行可能なテストケースに対応付けます。
7. ベースラインを保持したまま、候補実装を個別に生成します。
8. 反復には analyze を使用し、候補の順位付けには正確性ゲートを設けて compare を使用します。
9. 採用候補を使い、同じワークロードで元のプロファイリングなしのベンチマークを再実行します。性能低下も含め、カーネル単位とエンドツーエンドの両方の変化を報告します。

正確性が証明されていない場合、ベンチマーク入力が変更された場合、ソースマッピングが不確かな場合、またはエンドツーエンドの改善が実行間のばらつきの範囲内である場合は、成功を主張する前に作業を止めてください。

利用可能な場合は MCP ツールを使用する

ハードウェアの調査、カーネルの検出、設定の生成、分析／比較、最適化の提案、結果の検索、レポートの比較、Ray ジョブの管理、ベンチマークの一括実行など、構造化されたエージェントのワークフローでは Magpie MCP ツールを優先してください。

結果オブジェクトの performance_state と performance_result を想定する MCP ツールに、CLI の analyze_report.json ラッパーを直接渡さないでください。すべての CLI オプションが MCP に存在すると決めつけないでください。カーネルソースの拡充は、現在 CLI のギャップ分析パスでのみ利用できます。

追加リソース

• CLI リファレンス全文：reference.md
• コピーして使えるコマンド例：examples.md