llm-torch-profiler-analysis

統合 LLM Torch プロファイラー分析

概要

以下を対象に、torch.profiler の分析でこのスキルを使用します。

• sglang。既存の SGLang Omni（sglang-omni）ワークロードのトレースも含みます
• vllm
• TensorRT-LLM
• TokenSpeed

SGLang Omni は独立したフレームワークではありません。SGLang ランタイムを通じて動作するため、--framework sglang を使用し、--input または --mapping-input と --formal-input でトレースを分析します。SGLang のライブキャプチャパスは、Omni サーバーでは検証されていません。

公開ワークフローは 1 つだけです。

• triage

推奨される統合エントリーポイント：

• scripts/analyze_llm_torch_profile.py

後方互換性用シム（以前の docker exec ... analyze_sglang_torch_profile.py ... の呼び出しを引き続き使えるように残してあります。統合エントリーポイントに転送するだけです）：

• scripts/analyze_sglang_torch_profile.py

Markdown バンドル用ヘルパー：

• scripts/render_triage_markdown_bundle.py

triage は常に同じ 3 つの表を出力します。

• カーネル表
• オーバーラップ機会の表
• 融合パターン表

デフォルトでは、3 つの表すべてに、累積 GPU 時間の割合が 1.0% 以上の行のみが表示されます。これを下回る行は、ユーザーがより低いしきい値を指定しない限り、デフォルトで非表示になります。

融合パターン表は、ソースに裏付けられた決定論的なものにしてください。 あいまいな照合器にしないでください。

ソースに裏付けられた完全一致の精度が低くても、カーネルクラスターが既知のファミリーに近い場合は、表の後に次のいずれか 1 つを含む短い注記を追加してください。

• high
• medium
• low

対応機能一覧

機能	SGLang	vLLM	TensorRT-LLM	TokenSpeed
既存トレースのトリアージ	対応	対応	対応	対応
単一トレースのライブキャプチャ	対応	対応（サーバーで torch profiler が有効な場合）	プロファイラー制御エンドポイントが必要	対応（/start_profile と /stop_profile が公開されている場合）
2 つのトレースのマッピング＋正式トリアージ	対応	対応	対応	対応
ステージ別のライブワークロード	対応	対応	対応（書き込み可能な共有トレースディレクトリ、またはステージごとのホストランナーが必要）	対応（ワークロード別 HTTP キャプチャを使用）
--profile-by-stage キャプチャ	対応	非対応	非対応	非対応
--profile-prefix の制御	対応	通常、HTTP プロファイラールートでは無視されます	通常、HTTP プロファイラールートでは無視されます	対応（profile_id にマッピング）

TensorRT-LLM でライブキャプチャが機能するのは、サーバーが /start_profile と /stop_profile を公開し、デプロイ環境に共有トレースパスと必要な環境変数が すでに用意されている場合に限られます。

TokenSpeed では、既存トレースのトリアージと、/start_profile および /stop_profile を公開している現行サーバーに対するライブキャプチャの両方を サポートしています。ライブヘルパーは、開始ペイロードに output_dir、 activities、with_stack、record_shapes、profile_id を送信します。 TokenSpeed には手動キャプチャ用の独自のネイティブな profile_by_stage フィールドもありますが、統合ヘルパーでは、フレームワーク間で表を比較可能な 状態に保つため、デフォルトでワークロード別の prefill/ と decode/ ディレクトリを使用します。

B200 実機での検証

現在の B200 スモーク実行は、GPUC5A6（ cirrascale-gpuc5a6）上のコンテナ sglang_bbuf で、2026-06-27 に取得しました。 保存先：

• /data/bbuf/ai_infra_skills_pr72_20260627/profiler/qwen25_0_5b_live

検証済みの実プロファイル：

モデル	GPU	ワークロード	結果
Qwen/Qwen2.5-0.5B-Instruct	1x B200	prefill 128->1、decode 32->8	個別の prefill/*.trace.json.gz と decode/*.trace.json.gz を生成。カーネル、オーバーラップ、融合の各テーブルは、extend/prefill セクションと decode セクションを分けてレンダリング

同じ実行で、小規模な CUDA 行列乗算を使って Nsight Compute の利用可能性も確認しました。

• /data/bbuf/ai_infra_skills_pr72_20260627/profiler/ncu_smoke_qwen_matmul.ncu-rep
• /data/bbuf/ai_infra_skills_pr72_20260627/profiler/ncu_smoke.log

サーバーと ncu のクリーンアップ後、8 基すべての B200 GPU で使用メモリが 0 MiB と報告されました。

2026-08-23 のソース更新では、実際の prefill/decode トレースや ncu --set basic のスモークテストを再取得していません。割り当てられた B200 ホストがポート 22 で SSH 接続を切断したためです。 最後に GPU 上で取得したプロファイラーの証拠として、2026-06-27 の成果物を保持してください。

H100 実機での検証

現在のリファレンス実行は、h100_sglang 上で 2026-04-23 に取得した 4x H100 のマトリックスです。保存先：

• /data/bbuf/validate/unified_llm_profiler_skill/runs/20260423_h100_large_model_matrix_v3

レンダリング済みの Markdown バンドル：

• /data/bbuf/validate/unified_llm_profiler_skill/runs/20260423_h100_large_model_matrix_v3/h100_large_model_matrix_v3_bundle.md

検証済みのモデルディレクトリ：

• mixtral_8x7b_instruct
• qwen2_5_32b_instruct
• qwen3_32b

各モデルディレクトリには、次のファイルが含まれています。

• analysis_sglang.txt
• analysis_vllm.txt
• analysis_trtllm.txt
• フレームワーク固有のトレースルートとプローブ成果物

検証済みのマトリックス：

モデル	SGLang	vLLM	TensorRT-LLM	結果
mistralai/Mixtral-8x7B-Instruct-v0.1	4x H100	4x H100	4x H100	3 つのフレームワークすべてで 3 つのテーブルが正しくレンダリングされ、ベンチマークプローブは直接、空でないテキストを返しました
Qwen/Qwen2.5-32B-Instruct	4x H100	4x H100	4x H100	3 つのフレームワークすべてで 3 つのテーブルが正しくレンダリングされ、ベンチマークプローブは直接、空でないテキストを返しました
Qwen/Qwen3-32B	4x H100	4x H100	4x H100	3 つのフレームワークすべてで 3 つのテーブルが正しくレンダリングされ、vLLM と TensorRT-LLM のチャットプローブでは <think> プレフィックスが出力されることがよくありました

H100 の主なリファレンスには、この実行を使用してください。 以前の 2026-04-22 の単体 GPU による Qwen3 マトリックスは、引き続き初期セットアップに役立ちますが、 現在はデフォルトのリファレンスではありません。 TokenSpeed のサポートは後から追加され、既存トレースのトリアージと HTTP プロファイラー制御のサポートでカバーされていますが、まだこの旧 H100 検証マトリックスには含まれていません。

ステージ分離ワークロードの検証は、h100_sglang 上で 2026-05-01 に取得しました。

• /data/bbuf/validate/unified_llm_profiler_skill/runs/20260501_stage_split_validation
• /data/bbuf/validate/unified_llm_profiler_skill/runs/20260501_stage_split_validation_large

検証済みモデル：

モデル	GPU	ワークロード	結果
Qwen/Qwen2.5-0.5B-Instruct	1x H100	prefill 4090->1、decode 1->2048	prefill/*.trace.json.gz と decode/*.trace.json.gz を個別に生成しました。カーネル、オーバーラップ、フューズの各テーブルは、extend/prefill と decode のセクションを分けて出力しました
Qwen/Qwen2.5-1.5B-Instruct	1x H100	prefill 4090->1、decode 1->2048	prefill/*.trace.json.gz と decode/*.trace.json.gz を個別に生成しました。カーネル、オーバーラップ、フューズの各テーブルは、extend/prefill と decode のセクションを分けて出力しました
Qwen/Qwen2.5-7B-Instruct	1x H100	prefill 4090->1、decode 1->2048	トレースを個別に生成しました。prefill のカーネルテーブルには 28 層分の GEMM/FA3/RMSNorm 処理が記録され、decode には 5 ステップ分のグラフ起動が記録されました。また、フューズの行はステージごとに分割されました
Qwen/Qwen2.5-14B-Instruct	1x H100	prefill 4090->1、decode 1->2048	トレースを個別に生成しました。prefill のカーネルテーブルには 48 層分の GEMM/FA3/RMSNorm 処理が記録され、decode には 5 ステップ分のグラフ起動が記録されました。また、フューズの行はステージごとに分割されました
Qwen/Qwen3-8B	2x H100、TP=2	prefill 4090->1、decode 1->2048、ウォームアップ 10／キャプチャ 5	prefill/decode のトレースを個別に生成し、3 つすべてのテーブルを作成しました。一意のプローブ用プロンプトにより、prefill テーブルがプレフィックスキャッシュによって汚染されるのを防ぎました
mistralai/Mistral-7B-Instruct-v0.3	2x H100、TP=2	prefill 4090->1、decode 1->2048、ウォームアップ 10／キャプチャ 5	prefill/decode のトレースを個別に生成し、3 つすべてのテーブルを作成しました。サーバーログでは、アクティブな prefill 期間中に、プロンプトの繰り返しによるプレフィックスキャッシュのショートカットが発生していないことを確認しました

この検証では、古い SGLang プロファイラーのステートマシンに対する互換性修正も対象としています。ワークロードごとに分けたライブキャプチャでは、出力ディレクトリによってステージを識別し、各ワークロード内で SGLang の内部 profile_by_stage ステートマシンがネストされないようにしています。このヘルパーは、内部スケジューラーのガードステップを 1 つ追加します。SGLang はプロファイラーを停止するか確認する前に forward_ct をインクリメントするためです。このガードがない場合、num_steps=1 の prefill キャプチャは、実際の prefill forward の直前に停止することがあります。追加モデルの 2026-05-01 の 2 枚のカードでの検証アーティファクトは次のとおりです。

• /data/bbuf/validate/core_skill_validation_20260501/qwen3_8b/profiler
• /data/bbuf/validate/core_skill_validation_20260501/mistral_7b_instruct_v03/profiler

検証済みの実行結果を 1 つの Markdown ドキュメントに出力するには、次のようにします。

python3 scripts/render_triage_markdown_bundle.py \
  --analysis-root /data/bbuf/validate/unified_llm_profiler_skill/runs/20260423_h100_large_model_matrix_v3 \
  --output /data/bbuf/validate/unified_llm_profiler_skill/runs/20260423_h100_large_model_matrix_v3/h100_large_model_matrix_v3_bundle.md

バンドルではモデルごとにまとめ、各フレームワークの 3 つのテーブルを保持します。

H100 に関する注意事項：

• 3つすべてのフレームワークで、トレースに明確なステージ分割が含まれている場合、カーネル、オーバーラップ、融合の各テーブルが、extend/prefill セクションと decode セクションに分けて表示されるようになりました
• SGLang のライブキャプチャが検証され、sglang.profiler をシェルから呼び出す代わりに、サーバーのプロファイラー API を直接呼び出します
• SGLang のトレースフラッシュは数秒を大幅に超えて遅れることがあるため、ランナーは以前の実装より長くアーティファクトを待機します
• SGLang のカーネルサイト再構築では、マッピング処理でサンプリングを無効にしたままにし、最適化されたパーサーによって SGLang のテーブル出力が変化しないようにしています。Mixtral-8x7B-Instruct-v0.1、Qwen3-32B、nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-FP8 の一致確認では、結果が一致しました
• vLLM のライブキャプチャでは、--output-dir をサーバーの torch_profiler_dir と一致させる必要があります。検証済みの H100 フローでは、--profiler-config {"profiler":"torch","torch_profiler_dir":"..."} を使用してから、/start_profile と /stop_profile を呼び出します
• TensorRT-LLM の検証では、引き続き --backend pytorch を使用します。H100 フローでは TLLM_TORCH_PROFILE_TRACE でトレースを書き出してから、保存済みのトレースを分析します
• TensorRT-LLM の現在のメインラインは、2026-08-23 に da38c1d2e0dffd073b7dfb6d69e15ee7b45d84a9 で再確認されました。PyTorch プロファイリングでは引き続き record_shapes=True と with_modules=True が使われますが、with_stack=True は使われません。対象イメージで別の方法が有効だと確認できない限り、テーブル品質の Python ロケーションを得るためにオーバーライドパスを維持してください
• SGLang v0.5.18 では、SM12x を含め、DSV4 の融合 MHC post+pre パスがデフォルトで有効になります。decode トレースに MHC post カーネルと MHC pre カーネルの分離が引き続き表示される場合、新たな融合のアイデアというより、パスが無効化されているか、リグレッションしている可能性が高くなります
• TokenSpeed のライブキャプチャは引き続き、HTTP によるプロファイラー制御と既存トレースのトリアージを組み合わせたものです。以前の H100 検証マトリックスには含まれていません
• TokenSpeed のトレース分析には、ネイティブ TokenSpeed CuTe DSL MLA、MLA KV pack + FP8 quantize、fused top-k/top-p sampling、persistent lm_head GEMM、NVFP4 GEMM + SwiGLU + quant 用のレジストリー行が標準で用意されています。対象の TokenSpeed イメージでサポート対象のプロファイラー API が公開されるまでは、ライブキャプチャに既存の torch-profiler トレースが必要です
• このホストでは、すべてのトレースルートを /home/... ではなく /data/... の下に置いてください

使用する場面

• sglang、vllm、TensorRT-LLM、または TokenSpeed の torch.profiler トレースやプロファイルディレクトリを調査する
• 既存の SGLang Omni トレースを分析し、GPU 時間を sglang_omni/ または sglang_omni_router/ の Python ソースに帰属させる
• 稼働中のサービングエンドポイントをプロファイリングし、結果を分析する
• prefill または decode を支配しているカーネルファミリーを要約する
• カーネルを Python コードパスに対応付ける
• コードパスにオーバーラップの余地が残っているか判断する
• 既知の融合パスまたはオーバーラップパスが適用されるべきだったか確認する

Diffusion バックエンドの確認

Diffusion のベンチマークまたはプロファイリングでは、ネイティブ SGLang diffusion バックエンドで生成されたトレースのみを分析してください。

トレース生成時の実行ログに次のいずれかが含まれている場合：

• Falling back to diffusers backend
• Using diffusers backend
• Loaded diffusers pipeline

トレースを分析せず、ワークフローを停止してください。 これはネイティブカーネルのプロファイリングに関する証拠ではなく、バックエンド選択の問題として扱ってください。

主なフロー

ステージ分離型ライブキャプチャの仕様

ライブキャプチャでは、混在したプロンプトをデフォルトとして使用してはいけません。 デフォルトでは、analyze_llm_torch_profile.py --url ... がラベル付きのワークロードを2つキャプチャし、同じ3つのテーブルをステージごとに分けて表示します。

• prefill：合成入力長 4090、出力長 1
• decode：合成入力長 1、出力長 2048

すべてのライブプロファイラーパスでは、プロファイラーを開始する前に 10 ステップのウォームアップを行い、その後、デフォルトで 5 ステップをキャプチャします。カーネルテーブルを比較する前に、SGLang、vLLM、TensorRT-LLM 間でこのウォームアップとアクティブステップの分割を揃えてください。

ベンチマークのワークロードが判明している場合は、次のオプションで仕様を上書きできます。

--profile-workload both \
--warmup-steps 10 --num-steps 5 \
--prefill-input-len 4090 --prefill-output-len 1 \
--decode-input-len 1 --decode-output-len 2048

使用可能な --profile-workload の値：

• both：デフォルト。prefill と decode を別々にキャプチャします
• prefill：長い入力／1トークンのワークロードのみをキャプチャします
• decode：1つの入力／長い出力のワークロードのみをキャプチャします
• legacy：従来の --probe-prompt／--probe-max-new-tokens の動作を維持します

sglang-sota-humanize-loop では、SGLang の低速なベンチマークシナリオで入力／出力の分布が判明している場合、デフォルトを使用しないでください。 代わりに、その低速シナリオに合わせてプロファイラーの長さを設定します。prefill では低速シナリオの入力長と出力 1 を使用し、decode では入力 1 と低速シナリオの出力長を使用します。混合データセットの場合は、ベンチマークレポートで使用した p50 または p95 の入出力ペアなど、最も低速な代表バケットをプロファイルし、そのバケットを成果物のメモに記録してください。

1. 既存のプロファイルディレクトリまたはトレースから単一トレースをトリアージする

python3 scripts/analyze_llm_torch_profile.py \
  --input /path/to/profile_dir_or_trace.json.gz

トレースが1つで十分な場合に使用します。 単一トレースモードでは、オーバーラップテーブルは慎重な結果を示し、マッピング／正式なペアが必要な場合はその旨を通知します。

2. SGLang から単一トレースをライブキャプチャする

python3 scripts/analyze_llm_torch_profile.py \
  --framework sglang \
  --url http://127.0.0.1:30000 \
  --output-dir /data/bbuf/validate/unified_llm_profiler_skill/runs/example/sglang_profile_live \
  --num-steps 5 \
  --warmup-steps 10 \
  --profile-by-stage \
  --profile-workload both

スクリプトは SGLang サーバーに直接 POST /start_profile を送信します。 後続の分析やドキュメントからトレースを参照できるよう、--output-dir は /data/... 配下にしてください。 スクリプトは server_args.json を書き込み、同じワークロード形状でウォームアップを行い、プロファイリング開始後にアクティブプローブリクエストを送信して、デフォルトで個別の prefill/ と decode/ のプロファイルルートをキャプチャします。また、以前の実装より長く待ってトレースのフラッシュを完了します。 デフォルトのワークロード分離キャプチャでは、ディレクトリ名でステージを示し、各ワークロード内では SGLang の内部 profile_by_stage モードを使用しません。これにより、1トークンの prefill プローブと別個の decode プロファイルが混在するのを防ぎます。ヘルパーは引き続き内部ガードステップを1つ追加します。これは、古い SGLang プロファイラーが次の forward を実行する前に対象カウンターを確認するためです。

3. vLLM から単一トレースをライブキャプチャする

torch プロファイラーを有効にして vLLM を起動します。例：

vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --profiler-config '{"profiler":"torch","torch_profiler_dir":"/data/bbuf/validate/unified_llm_profiler_skill/runs/example/vllm_profile"}'

次に、以下を実行します。

python3 scripts/analyze_llm_torch_profile.py \
  --framework vllm \
  --url http://127.0.0.1:8000 \
  --output-dir /data/bbuf/validate/unified_llm_profiler_skill/runs/example/vllm_profile \
  --num-steps 5 \
  --warmup-steps 10 \
  --no-profile-by-stage \
  --profile-workload both

vLLM の場合、--output-dir はサーバーが使用する同じ torch_profiler_dir を指している必要があります。 現在の vLLM プロファイラー設定では torch_profiler_with_stack=true がデフォルトで有効になっているため、ランナーで設定する必要があるのは torch_profiler_dir だけです。 h100_sglang では、外部 vLLM コンテナーに次の両方をマウントしてください。

• /data/.cache/huggingface:/root/.cache/huggingface
• /data/bbuf/validate/unified_llm_profiler_skill:/data/bbuf/validate/unified_llm_profiler_skill

4. TensorRT-LLM から単一トレースをライブキャプチャする

サーバーが POST /start_profile と POST /stop_profile を公開しており、 トレースパスが現在のマシンから共有されている場合にのみ使用してください。

一般的な環境変数の設定は次のとおりです。

• TLLM_PROFILE_START_STOP=<start>-<stop>（例：10-20）
• TLLM_TORCH_PROFILE_TRACE=/shared/path/trace.json または .json.gz

次を実行します。

python3 scripts/analyze_llm_torch_profile.py \
  --framework trtllm \
  --url http://127.0.0.1:8000 \
  --output-dir /shared/path \
  --num-steps 5 \
  --no-profile-by-stage \
  --profile-workload both

デプロイ環境でプロファイラー制御エンドポイントが公開されていない場合は、 ライブキャプチャを試すのではなく、既存のトレースを分析してください。 TensorRT-LLM のトレース出力に固定のファイルパスが設定されている場合は、 --profile-workload both を直接使用する代わりに、 scripts/run_trtllm_pytorch_profile_host.sh --stage prefill と --stage decode を使用し、それぞれのステージで個別のトレースファイルを取得してください。

現在の TensorRT-LLM メインラインでは、py_executor.py は torch プロファイラーを record_shapes=True および with_modules=True で作成しますが、with_stack=True は指定しません。 テーブル品質の検証には、オーバーライドジェネレーターを使用してください。

python3 scripts/make_trtllm_py_executor_override.py \
  --source /path/to/original/py_executor.py \
  --output /data/bbuf/validate/unified_llm_profiler_skill/overrides/trtllm/py_executor_with_stack.py

マトリックスランナーは、TensorRT-LLM のキャプチャ開始前に H100 上でこれを自動的に実行します。

h100_sglang で検証済みの TensorRT-LLM フローは次のとおりです。

1. TLLM_PROFILE_START_STOP=<start>-<stop> および TLLM_TORCH_PROFILE_TRACE=/data/.../trace.json を指定して trtllm-serve を起動します
2. ベンチマークのリクエストを数件実行します
3. 出力されたトレースを --input /data/.../trace.json で分析します

5. TokenSpeed から単一トレースをライブキャプチャする、またはトリアージする

プロファイラールートを公開している稼働中の TokenSpeed サーバーでは、統合ヘルパーを 使ってライブキャプチャを実行できます。

python3 scripts/analyze_llm_torch_profile.py \
  --framework tokenspeed \
  --url http://127.0.0.1:8000 \
  --output-dir /data/bbuf/validate/unified_llm_profiler_skill/runs/example/tokenspeed_profile \
  --num-steps 5 \
  --warmup-steps 10 \
  --no-profile-by-stage \
  --profile-workload both \
  --profile-prefix ts-triage

ヘルパーは、次の内容で POST /start_profile を送信します。

• output_dir：--output-dir のパス
• activities：["CPU", "GPU"]
• with_stack：true
• record_shapes：false
• profile_id：--profile-prefix。ワークロード別キャプチャ時には -prefill または -decode が追加されます

続いて、OpenAI 互換のプローブリクエストを送信し、POST /stop_profile を呼び出します。 TokenSpeed は、出力ディレクトリ内に ts-triage-prefill-TP-0.trace.json.gz などのファイルを書き込みます。 サーバーが複数の TP ランクで起動されている場合は、ランクごとに 1 つのトレースが出力されます。

既存の TokenSpeed torch プロファイラートレースも、引き続き直接分析できます。

python3 scripts/analyze_llm_torch_profile.py \
  --framework tokenspeed \
  --input /path/to/tokenspeed_profile_dir_or_trace.json.gz

TokenSpeed 独自の手動プロファイラー制御インターフェイスも使用できます。

curl -X POST http://127.0.0.1:8000/start_profile \
  -H 'Content-Type: application/json' \
  -d '{"output_dir":"/data/bbuf/profiles/tokenspeed","activities":["CPU","GPU"],"with_stack":true,"record_shapes":false,"profile_id":"ts-manual"}'

# send representative workload here

curl -X POST http://127.0.0.1:8000/stop_profile

サーバー側で自動停止させるには、num_steps を指定します。TokenSpeed ネイティブの EXTEND/DECODE 分割には、profile_by_stage: true を指定します。これにより、 -EXTEND や -DECODE などのステージサフィックスが付いたファイルが出力されます。

TokenSpeed のベンチマークドライバーでもトレースをキャプチャできます。

tokenspeed bench serve \
  --base-url http://127.0.0.1:8000 \
  --model <model> \
  --dataset-name random \
  --random-input-len 4090 \
  --random-output-len 1 \
  --num-prompts 64 \
  --profile \
  --profile-num-steps 5 \
  --extra-body '{"output_dir":"/data/bbuf/profiles/tokenspeed","activities":["CPU","GPU"],"with_stack":true,"profile_id":"ts-bench"}'

output_dir を省略した場合、TokenSpeed は TOKENSPEED_PROFILER_DIR を使用し、 それも設定されていない場合は /tmp にフォールバックします。

トレース収集の前後に、--framework tokenspeed を指定して scripts/probe_llm_server.py を使用し、 小規模な OpenAI 互換エンドポイントのプローブを実行してください。

python3 scripts/probe_llm_server.py \
  --framework tokenspeed \
  --url http://127.0.0.1:8000 \
  --requests 6 \
  --max-tokens 48

sglang-sota-humanize-loop では、TokenSpeed のプロファイラーの情報を、 ベンチマーク結果と同じ低速シナリオのバケットに合わせてください。 可能な場合は、ワークロード別の統合ライブキャプチャを優先してください。 混在したエージェント型トレースしかない場合は、SGLang の prefill/decode トレースと 比較する前に、その制約を analysis/root-cause.md に記載してください。

6. 既存のプロファイルディレクトリまたはトレースから 2 つのトレースをトリアージする

python3 scripts/analyze_llm_torch_profile.py \
  --mapping-input /path/to/graph_off_profile_dir \
  --formal-input /path/to/graph_on_profile_dir

オーバーラップの帰属とカーネルからソースへのマッピングを、より確実に行う必要がある場合に使用してください。

7. 稼働中のサーバーから 2 つのトレースをトリアージする

python3 scripts/analyze_llm_torch_profile.py \
  --framework sglang \
  --mapping-url http://127.0.0.1:31025 \
  --formal-url http://127.0.0.1:31026 \
  --num-steps 5 \
  --profile-by-stage

vllm または TensorRT-LLM では、同じ形式を使い、次の引数を指定してください。

• --framework vllm または --framework trtllm
• --mapping-output-dir ...
• --formal-output-dir ...
• --no-profile-by-stage

TokenSpeed では、/start_profile と /stop_profile を公開しているサーバーに対して --mapping-url と --formal-url を使用するか、--mapping-input と --formal-input を指定して既存の 2 つのトレースディレクトリを渡してください。

--framework auto は、トレース、パス、サーバー引数、エンドポイントのシグネチャを使用します。 いずれの判定でも確定できない場合、アナライザーは処理を停止し、明示的な sglang、vllm、trtllm、または tokenspeed の指定を求めます。 不明なトレースを、デフォルトで SGLang のものとして解釈してはいけません。

profile_by_stage

--profile-by-stageは、SGLangのライブキャプチャ経路でのみ意味があります。

• --profile-workload both／prefill／decodeを指定すると、ワークロードのディレクトリ名がステージラベルになります。ライブキャプチャヘルパーはワークロードごとにSGLangの内部ステージプロファイラーを無効にし、最初にウォームアップを行ってから、選択したワークロードについて指定されたアクティブステップ数をキャプチャします。
• レガシーのSGLangサービングや手動でキャプチャしたSGLangサービングでは、prefillとdecodeでボトルネックが大きく異なることが多いため、内部のprofile_by_stageも引き続き役立ちます。
• SGLangの現在のprofile-v2経路では、ステージベースのプロファイリングが事実上の通常の経路です。
• PD分離サービングでは、追加のルールが1つあります。prefillワーカーとdecodeワーカーは別々にプロファイルする必要があります。これは通常のprofile_by_stageよりも厳格な要件です。
• vllm、TensorRT-LLM、TokenSpeedでは、--no-profile-by-stageを指定して無効にしてください。

トリアージの形式の選び方

単一トレースのトリアージ

手間を最小限に抑えてレポートを作成したい場合に使用します。

• トレースがすでに1つある
• 主にカーネルの比率と融合の手がかりを知りたい
• トレースごとにトリアージを1回実行して、2つの実行結果を並べて比較する

デフォルトではこちらを優先してください。

2トレースのトリアージ

次のことが必要な場合に使用します。

• より確かなオーバーラップの分析
• グラフ無効時のソースマッピングと、グラフ有効時の最終動作
• 中央のテーブルにある、より信頼性の高いオーバーラップの推奨事項

1. マッピング用トレース：グラフを無効にするか、融合を抑えた、読み取りやすい設定で取得します。
2. 正式なトレース：実際のサービング最適化を有効にして取得します。

マッピングの工程を「高速プロファイル」と呼ばないでください。 これはkernel -> cpu_op -> python scopeを復元するためのものです。

ワークフロー

単一トレースのワークフロー

1. ユーザーが診断だけを求めている場合は、トレース1つで十分です。
2. プロファイラーが単一ランクのトレースと結合済みトレースの両方を出力した場合は、単一ランクのトレースを優先してください。
3. ライブサーバーでは、フレームワーク固有の前提条件がすでに満たされている場合に限り、スクリプトからプロファイラーを操作してください。
4. --profile-workload bothを優先してください。古いトレースの契約を再現する場合にのみ、legacyを使用します。
5. SGLangではワークロードを分けたキャプチャを優先してください。内部の--profile-by-stageは主に、legacyまたは手動で収集したトレースに使用します。
6. h100_sglangの場合は、/data配下でパスに確実に書き込めるよう、docker exec sglang_bbuf ...を使って対象のトレースディレクトリを作成または削除してください。

2トレースのワークフロー

1. まず、グラフを無効にするか、融合を抑えた設定でマッピング用トレースを作成します。
2. 次に、実際のサービング最適化を有効にして正式なトレースを作成します。
3. triageを実行して、3つのテーブルからなるレポートを作成します。
4. 次の順に結果を確認します。
   • カーネルテーブル
   • オーバーラップ機会のテーブル
   • 融合パターンのテーブル
5. 何かを「新しい」最適化案と呼ぶ前に、上位の行をreferences/fuse-overlap-catalog.mdとreferences/overlap-catalog.mdの両方と比較してください。まずmainlineの行を確認し、次にステータス監査済みのPRの根拠を確認します。次の内容を優先して報告してください。
   • ここで適用されるべき既存の融合またはオーバーラップ経路
   • このトレースでは無効化、非対応、または後退しているように見える既存の経路
   • 他ではすでにmainlineにあるもののローカルでは欠けている、またはupstreamでまだオープンなパターン
   • カタログのどの項目にも当てはまらない場合に限る、真に新しい機会
6. 完全に一致するパターンがないものの、トレースが既知のパターン群に近い場合は、テーブルの後に簡潔な類似性メモを1つ追加してください。 high、medium、lowのみを使用してください。 そのメモは、単一のカーネル名ではなく、パターン全体の形状に基づいて記述してください。 プロデューサーとコンシューマーの連鎖、ソースの位置、CPUオペレーション名、TPのコンテキスト、モデル固有の構造など、意味的な手がかりを優先してください。 こうしたヒューリスティックな判断を含めるために、スクリプトのテーブル自体を書き換えないでください。

参考資料

必要な場合にのみ読み込んでください。

• references/source-map.md
  • SGLang のプロファイラーのエントリーポイントとトレース書き込みパス。SGLang 固有のソースをさらに調べる際に、引き続き最も役立ちます
• references/heuristics.md
  • オーバーラップのラベル、依存関係リスクの解釈、および制限事項
• references/fuse-overlap-catalog.md
  • 既存の融合およびオーバーラップパターンをまとめた、ソースに基づく混合カタログ。メインラインの項目に加え、オープン、マージ済み、クローズ済み・未マージの PR の根拠を明示して掲載
• references/vllm-torch-compile-fusions.md
  • 現在の vLLM の torch.compile 融合パスと、対象となるソースパターン
• references/overlap-catalog.md
  • LLM、VLM、拡散モデル、非分離処理、HiSparse、投機的スケジューリングを対象とする、オーバーラップ専用の参照表

出力仕様

以下を返してください。

• トレースパスまたは生成されたプロファイルパス
• フレームワーク
• 入手可能な場合はモデル／サーバーの引数
• カーネルの表
• オーバーラップの機会に関する表
• 融合パターンの表
• 完全一致で判断できない場合は、high／medium／low を付けた任意の類似性に関する注記
• 実行の大部分を占めるものの短い要約を1つ
• オーバーラップ分析が、単一トレースのトリアージによるものか、マッピング／正式な2トレースのトリアージによるものか