ascend-profiling-anomaly について
Ascend NPU のプロファイリングデータを分析する、パフォーマンスエンジニア向けスキルです。デバイスのアイドル区間検出、構造の分解、モデルアーキテクチャ分析を組み合わせ、観測された異常と推定原因を分けて示し、独立したアーキテクチャレポートを生成します。
主な機能
- 01ステップ、構造、ブロック、演算子の分解
- 02デバイス区間の統合とアイドル検出
- 03ホストイベントによる原因の推定
- 04異常タグと周期性指標の集計
- 05独立したアーキテクチャレポートの生成
活用シーン
- 01学習や推論ステップのデバイス待機時間の特定
- 02構造内部やレイヤー境界の空白時間の調査
- 03ホストイベントから同期や通信リスクを評価
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/ / github.com/ ascend/ agent-skills --skill ascend-profiling-anomalyインストール後、Claude Code で/ascend-profiling-anomalyを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
references/architecture_report_template.mdkernel_data_guide.mdrulebook.mdschema.jsonscripts/reference_host_gap_branch.py詳細
Ascend プロファイリング異常検出スキル
目的
Ascend NPU のプロファイリングデータを、次の3つの並列パイプラインで分析します。
- 構造の内訳:ステップ → 構造(レイヤー)→ ブロック/サイド → 演算 → PMU 判定 — 時間がどこに費やされているかを明らかにします。
- 異常検出:ステップ → デバイスビジー区間の統合 → バブル検出 → 異常タグ → 暫定的な原因推定 — 不自然に見える箇所と、潜在的な問題の可能性がある場所を明らかにします。
- モデルアーキテクチャ分析:FIA タイムライン → パス境界 → レイヤー分類 → レイヤーごとのサブ構造 → 通信パイプライン → アーキテクチャの概要 — モデルの種類と各コンポーネントの実行方法を明らかにします。独立した Markdown レポートファイルを出力します。
中核となる考え方は、関心事の分離です。「異常が存在する」ことはデバイス区間から導かれる確定的な事実ですが、「なぜ存在するか」は追加の証拠が必要になる場合がある暫定的な原因推定です。スタック情報やシェイプ情報がなく、ホストイベントが少ないなど、プロファイリング設定が不十分な場合でも、このスキルではデバイスのアイドルバブルとリスクラベルを確実に検出する必要があります。
参照ファイル — 読み込むタイミング
分析を開始する前に、次のファイルを読み込んでください。
| ファイル | 読み込むタイミング | 内容 |
|---|---|---|
references/kernel_data_guide.md | 必ず最初に読む | kernel_details.csv、op_summary、trace_view.json の生データ列スキーマ、ステップ → 構造 → ブロック/サイド → 演算の階層、各レベルでのカーネルの解析・フィルタリング・割り当て方法、マルチストリームの処理、レベルごとの時間集計 |
references/rulebook.md | 必ず読む | 異常のしきい値、タグ付けルール、判定表、暫定的な原因推定のルール、AICPU の分類、待機アンカーのルール |
references/architecture_report_template.md | アーキテクチャレポートの作成前に必ず読む | 単独の Markdown アーキテクチャレポートの完全なテンプレート:必須セクション、書式ルール、レイヤー分類の分析手法、通信のオーバーラップ測定、レイヤーごとの時間内訳 |
references/schema.json | 構造化 JSON 出力を作成する場合 | anomaly_discovery 出力オブジェクトの完全な JSON スキーマ |
scripts/reference_host_gap_branch.py | 分析スクリプトを作成する場合 | 区間統合、バブル指標、暫定的な原因推定、待機アンカーのスコアリングを実装した Python の参考実装 |
パイプラインの概要
完全な状態機械:
INGEST → INVENTORY → FACT_EXTRACTION → CANDIDATE_STEP_DETECTION →
STEP_GROUPING → MACRO_STEP_RESOLUTION → SEGMENTATION →
CLOCK_ACCOUNTING → ANOMALY_DISCOVERY → PERF_JUDGEMENT →
RECOMMENDATION → RENDER → DONE
↘
ARCHITECTURE_ANALYSIS → ARCH_REPORT_RENDER → ARCH_REPORT_SAVE
ANOMALY_DISCOVERY は CLOCK_ACCOUNTING の後、PERF_JUDGEMENT の前に位置します。すでにセグメント化されたステップと構造を受け取り、その上でバブル検出パイプラインを実行します。
ARCHITECTURE_ANALYSIS は PERF_JUDGEMENT と並行して実行され、CLOCK_ACCOUNTING からの同じセグメント化データと FIA タイムライン分析を使用します。プロファイリングデータと同じ場所に保存される独立した Markdown レポートファイルを出力します。
データ階層:ステップ → 構造 → ブロック/サイド → 演算
生のカーネルデータが各レベルにどう対応するかを理解することが重要です。列スキーマと解析の詳細については、references/kernel_data_guide.md をお読みください。概念の概要は次のとおりです。
レベル0:生のカーネル
kernel_details.csv の各行は、単一のデバイスカーネル実行を表します。これは、AI Core タスク、AI CPU タスク、または HCCL 通信タスクの1回の呼び出しです。主なフィールド:Name、Task Type、Start Time(us)、Duration(us)、Wait Time(us)、Accelerator Core、Stream ID、Input Shapes、Output Shapes。
レベル1:ステップ
ステップは、学習または推論の1回のイテレーションです。ステップは、trace_view.json の ProfilerStep#N ユーザー注釈または Iteration#N マーカーによって識別されます。各ステップは、サービスウィンドウ [S_i, S_{i+1}) を定義します。開始時刻がこのウィンドウ内にあるすべてのカーネルは、ステップ i に属します。
ステップレベルでは、次の項目を計算します。
- 合計サービス時間、デバイスビジー区間の統合、供給不足率
- 起動前ギャップ、末尾ギャップ、内部バブル
- ステップごとの異常タグと暫定的な根本原因ラベル
レベル 2:構造(レイヤー)
ステップ内では、カーネルが繰り返し現れる構造を形成します。通常、これはモデルのレイヤー(例:トランスフォーマーブロック、アテンションレイヤー、MLP ブロック)に対応します。セグメンテーションでは、次の情報を使って構造を特定します。
- カーネルのタイムラインで繰り返される名前パターンの並び
- カーネルグループ間の大きな時間ギャップ
- レイヤー境界を示すユーザー注釈(ある場合)
各構造には、ステップのウィンドウ内にある連続したカーネル区間が含まれます。
構造レベルでは、次の項目を計算します。
- 構造のウォールタイム、構造区間内のデバイスビジー時間の和集合
- ステップ全体の時間に対する構造の割合
- 構造ごとのバブル指標(バブルはこの構造内にあるか、構造間にあるか)
レベル 3:ブロック/サイド
各構造内で、カーネルは次のように分かれます。
- ブロック(主要な計算経路):このレイヤーの順伝播または逆伝播を形成する、主要な AI Core カーネルの連鎖です。これらはメインの計算ストリーム上で実行されます。
- サイド(補助演算):それ以外のすべてです。小規模な要素単位の演算、通信(HCCL)、AI CPU フォールバック演算、メモリーコピー、同期イベントなどが含まれます。これらは別のストリーム上で実行される場合があります。
ブロック/サイドのレベルでは、次の4 つの時間指標を同時に維持します。
wall_ms— 最初のカーネルの開始から最後のカーネルの終了までのウォールクロック時間busy_union_ms— デバイスビジー時間の統合値(複数ストリームの重複を考慮)kernel_sum_ms— すべてのカーネル時間の算術合計(重複を無視)total_cost_ms— すべてのカーネルのduration + waitの合計
指標を1つだけ使った結論は不完全です。kernel_sum は大きくても wall は小さいブロックは、ストリーム並列性が高いことを意味します。total_cost は大きくても duration は小さいサイドは、wait-anchor による偽のホットスポットであるリスクを意味します。
レベル 4:演算(個別の演算子)
最も細かい粒度です。各演算は、1つまたは複数のデバイスカーネルを生成する場合があります。演算レベルの分析では、次の項目を扱います。
- 総コストの上位演算とカーネル時間の上位演算(この2つの順位は異なることがよくあります)
- wait-anchor の検出:
wait_ratio > 0.95で、durationはごく短い一方、total_costが大きい演算 - AICPU の分類:
masked_ratioに基づき、AI Core ではなく AI CPU 上で実行される演算を分類します - 小規模演算の初期判定:個々の小規模演算が実際の非効率なのか、ノイズなのかを判定します
異常検出パイプライン(詳細)
フェーズ 1:BUILD_DEVICE_INTERVALS
各ステップについて、kernel_details.csv からすべてのデバイスカーネル区間を収集します。
device_intervals = []
for each kernel row where Start_Time_us is within step window:
s = max(step_start_us, row.Start_Time_us)
e = min(step_end_us, row.Start_Time_us + row.Duration_us)
if e > s:
device_intervals.append(Interval(s, e))
主なルール:
- カーネル区間をステップウィンドウの境界に合わせて切り取ります
- 区間の統計を計算する前に、通信の重複排除ルールを適用します(通信の重複排除については
references/kernel_data_guide.mdのセクションを参照) - AI_CORE、AI_CPU、HCCL のタスクを含めます。すべて「デバイスビジー」としてカウントされます
- 複数のストリームがある場合、すべてのストリームの区間を同じ集合に収集します
フェーズ 2:MERGE_INTERVALS
区間を開始時刻で並べ替え、重複する区間を統合します。
merged = merge(device_intervals) # see scripts/reference_host_gap_branch.py
busy_union = sum of merged segment durations
これにより統合済みのビジー区間が生成され、すべてのバブル指標はこれを基に算出されます。
フェーズ 3:GAP_CLASSIFICATION
統合済みの区間から、ステップごとの指標を計算します。
service_ms= ステップウィンドウの長さdevice_busy_union_ms= 統合済み区間の長さの合計underfeed_ms= service − busy_unionunderfeed_ratio= underfeed / serviceprelaunch_gap_ms= start(first_merged_segment) − step_starttail_gap_ms= step_end − end(last_merged_segment)internal_bubble_total_ms= 隣接する統合済み区間の間のギャップの合計largest_internal_bubble_ms= 隣接する統合済み区間の間の最大ギャップbubble_count= 区間間のギャップの数
フェーズ 4:HOST_EVIDENCE_COLLECTION
各バブルウィンドウ(マージされたセグメント間のギャップ、または起動前/末尾のギャップ)について、trace_view.json 内のホストイベントを対象に、同じ時間範囲をスキャンします。
収集するホストイベントのカテゴリ:
cpu_op/python_function/user_annotation— 一般的なホストアクティビティAscendCL@*— ACL ランタイムイベントHostToDevice/torch_to_npu/aclrtMemcpy*/aclrtSynchronize*— 同期/コピーのマーカーc10d/Hccl/hcom/StreamWaitEvent/Notify_Wait— 通信のマーカー
重複率を計算します:
host_visible_coverage_ratio= ホストイベントが占めるバブルの割合sync_marker_overlap_ratio= 同期/コピーマーカーが占める割合comm_marker_overlap_ratio= 通信マーカーが占める割合
フェーズ 5:SOFT_ATTRIBUTION
重要なバブルごとに、重複率に基づいて確率レベルのラベルを割り当てます:
| 条件 | ラベル |
|---|---|
| sync_overlap ≥ 0.20 | possible_sync_or_h2d |
| comm_overlap ≥ 0.20 | possible_comm_wait |
| host_coverage < 0.05 | possible_untraced_host_blocking |
| host_coverage ≥ 0.10 で、同期/通信が支配的でない | possible_host_launch_lag |
| host_parallelism < 1.2 で、上記のいずれにも該当しない | possible_python_serialization_or_lock |
| どれにも該当しない | insufficient_evidence |
複数のラベルが同時に該当する場合があります。これらは一意な根本原因を示すものではありません。
フェーズ 6:ANOMALY_TAGGING
references/rulebook.md の判定表に記載された異常タグを適用します。主なタグ:
バブルの重大度:DEVICE_IDLE_GAP_HEAVY、PRELAUNCH_GAP_HEAVY、TAIL_GAP_HEAVY、INTERNAL_BUBBLE_HEAVY
リスクタグ:HOST_ORIGINATED_RISK、COMM_SYNC_RISK、WAIT_POLLUTION_RISK、WAIT_ANCHOR_FALSE_HOTSPOT、AICPU_EXPOSED_RISK、UNTRACED_HOST_BLOCKING_RISK、PARTIAL_CAPTURE_BOUNDARY、VARIABLE_SHAPE_SAME_TEMPLATE
フェーズ 7:WAIT_ANCHOR_SCAN
op レベルで誤検出されたホットスポットをスキャンします:
wait_ratio = wait_us / (duration_us + wait_us)
if wait_ratio > 0.95 and duration_us < 10.0 and total_cost_rank <= 10:
tag WAIT_ANCHOR_FALSE_HOTSPOT
これらの op はアイドル待機時間を吸収するため、高コストに見えますが、カーネル実行時間はごくわずかです。根本原因の順位付けでは、これらの優先度を下げます。
フェーズ 8:GROUP_AGGREGATION
step_group_id ごとにステップレベルの指標を集計します:
- 各バブル指標の平均値、中央値、P90、P95 を計算します
recurring_bubble_pattern= グループ内のステップの 60% 以上でbubble_count > 0の場合は truedominant_idle_pattern= prelaunch/internal_bubble/tail のうち、最も大きな割合を占めるもの
フェーズ 9:PRODUCE_OUTPUT
異常の結果を構造の内訳と統合します。レポートには必ず次を含めてください:
隠れた問題の検出セクション
- 支配的なステップ/グループのバブル指標(service、busy_union、underfeed_ratio)
- カーネルの生データのエビデンステーブル:上位の各バブルウィンドウについて、ギャップの直前と直後にあるカーネルを列挙します。名前、タスクタイプ、実行時間、ストリームを記載し、人間の専門家がタイムライン上の正確な位置を特定できるようにします
- タイムスタンプ、スコープ、ホストのエビデンスを含む上位 5 件のバブルウィンドウ
- ステップグループ全体におけるバブルの周期性に関する統計
- ホストのエビデンスの網羅性に関する評価
- エビデンスの連鎖を伴う、確率レベルの根本原因ラベル
- 追加サンプリングの推奨事項
バブル優先の概要(固定の 5 つの質問テンプレート)
- 重要なデバイスアイドルバブルはありますか?
- どのステップタイプ/グループに集中していますか?
- 主に起動前/末尾/内部/ステップ間のどれですか?
- ホスト起因の重大なリスクはありますか?
- 根本原因を特定するのに十分なエビデンスはありますか?不十分な場合は、その旨を明記してください。
構造レベルのバブル詳細分析
支配的なステップについて、構造ごとのバブル寄与を内訳します:
- 最大の内部バブルを含む構造はどれですか?
- バブルは構造の境界(レイヤー間)に集中していますか、それとも構造内にありますか?
- 大きなバブルがある構造について、周囲にあるカーネル名とタスクタイプは何ですか?
モデルアーキテクチャ分析パイプライン(独立した Markdown レポート)
このパイプラインは、プロファイリングデータからリバースエンジニアリングしたモデルアーキテクチャを記録する独立した Markdown レポートファイルを生成します。完全なテンプレート、書式ルール、分析手法については、references/architecture_report_template.md を参照してください。
レポートは、プロファイリングディレクトリまたは出力ディレクトリに model_architecture_report_<profiling_dir_name>.md として保存されます。
アーキテクチャレポートを作成するタイミング
常に作成します。 すべてのプロファイリング分析では、異常検出の出力と併せて、このレポートを必ず作成する必要があります。アーキテクチャレポートは、異常検出結果を解釈するための重要なコンテキストを提供します。
アーキテクチャ分析フェーズ
Phase A1: FIA_TIMELINE_ANALYSIS
FusedInferAttentionScore(FIA)の呼び出しを、主要な構造マーカーとして使用します。
kernel_details.csvからすべての FIA カーネルを抽出します(名前にFusedInferAttentionScoreを含むものを照合します)Start Time(us)で並べ替えます- 各 FIA をプリフィル(実行時間 > 10ms)またはデコード(実行時間 < 1ms)に分類します
- パス数を算出します:
num_passes = total_FIA / FIA_per_pass - プリフィルとデコードの FIA クラスター間のタイムスタンプ差からフェーズ遷移を特定します
Phase A2: PASS_BOUNDARY_DETECTION
各フォワードパスについて、次の項目を特定します。
- FIA のインデックス範囲(例:#0–#94)
- 時間範囲(絶対タイムスタンプ)
- 最初のカーネルから最後のカーネルまでの実時間
- プリフィル FIA の平均実行時間
- カーネルの合計数
パス間の差異(FIA の実行時間、実時間)を記録してください。KV キャッシュの増大やメモリ圧迫の影響が明らかになる可能性があります。
Phase A3: LAYER_CLASSIFICATION
各レイヤー(連続する FIA 呼び出しで区切られます)について、カーネルシーケンスを抽出し、分類します。
| 分類用カーネル | レイヤータイプ |
|---|---|
| MoE マーカーなし(MoeGatingTopK、DFC、GroupedMatmul なし) | Dense |
| DispatchFFNCombine が存在 | MoE+DFC |
| GroupedMatmul と alltoallv が存在(DFC なし) | MoE+GMM |
| サンプリング演算(ArgMax、rejection_*)が存在 | デコード/サンプリングロジックを含む |
要約表を作成します:レイヤータイプ | レイヤー範囲 | 数 | 特徴
Phase A4: CROSS_VERIFICATION
パスごとに主要な演算を数え、レイヤー分類と一致することを確認します。
- FIA の数はレイヤー数と一致する必要があります
- DispatchFFNCombine の数は MoE+DFC レイヤー数と一致する必要があります
- GroupedMatmul の数は MoE+GMM レイヤー数とデコードレイヤー数の合計と一致する必要があります
- MoeGatingTopK の数はすべての MoE レイヤー(DFC + GMM + デコード)と一致する必要があります
不一致は分類エラーを示しています。先に進む前に解決してください。
Phase A5: PER_LAYER_SUBSTRUCTURE
レイヤータイプごとに、カーネルの実行シーケンスを分析します。
- カーネルを機能上の役割(アテンション、プロジェクション、TP 通信、MoE ルーティング、エキスパートディスパッチ、エキスパート FFN、MoE 後の正規化、次レイヤーの準備、EP 通信、サンプリング)ごとにグループ化します
- 各機能グループの実時間を測定します
- 各グループが実行されるストリームを特定します
- タイミングの内訳を算出します:コンポーネント | 実時間 | レイヤーに占める割合
- レイヤータイプ固有の異常(レイヤー 0 のウォームアップオーバーヘッド、遷移レイヤーの追加カーネル、AI_CORE 上で動作すべき AICPU 演算)を記録します
タイミング注釈とストリームラベルを付けたカーネルシーケンスツリーとして提示します。正確なツリー表記形式についてはテンプレートを参照してください。
Phase A6: DECODE_ANALYSIS
デコードレイヤーはコスト特性が根本的に異なるため、個別に分析する必要があります。
- FIA の実行時間が大幅に短縮されます(プリフィル 28ms → デコード 0.2ms)
- 通信(特に EP の all-to-all)が支配的になることがよくあります
- エキスパート計算は融合形式(DFC)から明示的な形式(GroupedMatmul)に変化します
支配的なコストの表を作成し、コスト特性がプリフィルと異なる理由を説明します。
Phase A7: COMMUNICATION_PIPELINE
複数のストリームによるオーバーラップ戦略を文書化します。
- 各ストリームの用途を対応付けます(メイン計算、AI_CPU 通信、HCCL、alltoall)
- ストリーム間のオーバーラップ率を測定します
- 通信が計算に隠れる様子を示す ASCII パイプライン図を描きます
- 通信全体のうち、隠れている(オーバーラップしている)割合を算出します
- kernel_sum >> wall の関係を説明します
Phase A8: ARCH_REPORT_RENDER
references/architecture_report_template.md のテンプレートに従って、すべての調査結果を Markdown レポートにまとめます。必須の 10 セクションをすべて含めてください。
- Configuration Context
- Model Architecture Determination(根拠チェーンの表)
- Forward Pass Boundaries(パスごとの表)
- Layer Classification(タイプ別の表)
- Cross-Verification Table
- Per-Layer Sub-Structure(各レイヤータイプのカーネルシーケンスツリー+タイミング内訳)
- Decode Phase Analysis(支配的なコスト+プリフィルとデコードの比較)
- Communication Pipeline Structure(ストリームの表+ASCII パイプライン図)
- Layer-to-Layer Variation(比較表)
- Model Architecture Summary(ASCII モデル図+実行タイムライン)
Phase A9: ARCH_REPORT_SAVE
レポートを model_architecture_report_<profiling_dir_name>.md として保存します。ファイルの場所をユーザーに伝えてください。
Critical Constraints
- 根本原因が不明だからといって、異常の検出を決して省略しないでください。 バブルの事実は確定的な結論であり、根本原因のラベルは暫定的な結論です。どちらも必ず報告してください。
- 待機時間が長く実行時間が短い演算を、待機アンカーのリスクを確認せずに実際のホットスポットと呼ばないでください。
- ステップ全体がデバイスバウンドだからといって、局所的なバブルを無視しないでください。
- タイミング指標を 1 つだけ使わないでください — ブロック/側ごとに、wall_ms + busy_union_ms + kernel_sum_ms + total_cost_ms の二重クロック計測を必ず維持してください。
- ホスト側の根拠が乏しい場合は、必ず
insufficient_evidenceまたはpossible_untraced_host_blockingを出力してください — 異常セクションを黙って省略しないでください。 - 報告するバブルの前後の生カーネル情報を必ず含めてください — 各バブルギャップの直前と直後にあるカーネル名、タスクタイプ、実行時間、ストリーム ID を記載してください。
- 確実性を段階的に表現してください — 事実には断定的な表現を使い、根本原因には
possible / probable / insufficient evidenceを使ってください。 - モデルアーキテクチャの Markdown レポートを必ず別ファイルとして作成してください — 異常の出力だけにまとめないでください。
- レイヤーごとのサブ構造分析を決して省略しないでください。 異なるレイヤータイプごとに、タイミング内訳とストリーム注釈付きのカーネルシーケンスツリーを用意してください。
- アーキテクチャレポートには根拠チェーンの表を必ず含めてください — 読者が、生の FIA データからレイヤー数とパス構造をどのように判定したか確認できるようにしてください。
- アーキテクチャレポートを確定する前に、演算数をレイヤー分類と必ず相互検証してください。 不一致がある場合は解消するか、明示してください。
グレースフルデグラデーション
| 不足データ | 影響 | 対応 |
|---|---|---|
record_shapes=false | 形状の変動を検出できません | バブル検出は継続します。タグ VARIABLE_SHAPE_SAME_TEMPLATE はスキップします |
with_stack=false | ソフト帰属の特定性が低下します | 信頼度が下がります。バブル検出への影響はありません |
| ホストイベントが疎 | 根本原因の分類を絞り込めません | UNTRACED_HOST_BLOCKING_RISK、requires_host_followup=true |
| キャプチャ境界の切り詰め | 境界付近のギャップがアーティファクトの可能性があります | 境界に隣接するギャップに PARTIAL_CAPTURE_BOUNDARY を付与します |
communication.json がない | 通信待ちを評価できません | 通信との重なりの分析をスキップし、エビデンスの欠落に記載します。アーキテクチャレポートでは通信パイプラインの帯域幅統計を省略しますが、ストリームの役割は引き続き記録します |
| ステップマーカーがない | ステップウィンドウを定義できません | フォールバックとして、キャプチャ全体の範囲を単一の擬似ステップとして扱います |
op_summary のみ(kernel_details なし) | 粒度が粗くなります | 代わりにオペレーションレベルの区間を使用し、制限事項に記載します。アーキテクチャレポートでは、レイヤー分類にオペレーション数を使用しますが、レイヤーごとのカーネルシーケンスツリーは作成できません |
| FIA カーネルが検出されない | FIA によるレイヤー境界の判定ができません | アーキテクチャレポートでは、代替の構造マーカー(例:反復するカーネルパターン、通信境界)を使用します。レイヤー数の信頼度が低下することを記載します |
| フォワードパスを 1 回だけキャプチャ | パス間の一貫性を相互検証できません | アーキテクチャレポートでは単一パスであることを記載し、パス間の変動分析が利用できないことを明記します |
| デコードの FIA が検出されない | 推論のみ、またはプレフィルのみのキャプチャです | アーキテクチャレポートではデコードフェーズの分析セクションを省略し、キャプチャ範囲の制限を記載します |
出力仕様の概要
すべての分析で、次の 2 つの出力を生成する必要があります。
1. 異常検出の出力
トップレベルオブジェクト anomaly_discovery に、enabled、dominant_group_id、global_device_gap_analysis、step_group_anomalies、bubble_windows、wait_anchor_ops、soft_root_cause_summary、requires_host_followup、confidence を含めます。
各ステップの結果には、バブルの指標、異常タグ、ソフトな根本原因ラベルを含める必要があります。
完全な JSON スキーマについては、references/schema.json を参照してください。
2. モデルアーキテクチャレポート(Markdown ファイル)
アーキテクチャテンプレートにある必須の 10 セクションをすべて含む、単独の Markdown ファイルを model_architecture_report_<profiling_dir_name>.md として保存します。完全な仕様については、references/architecture_report_template.md を参照してください。
レポートには、少なくとも次の内容を含める必要があります。
- レイヤー数とパス構造を裏付けるエビデンスチェーン
- 異なるレイヤータイプをすべて含むレイヤー分類テーブル
- 各レイヤータイプのすべてのレイヤーについて、時間の内訳を含むレイヤーごとのカーネルシーケンスツリー
- ストリームの重なりを示す図を含む通信パイプラインの構造
- モデルアーキテクチャの ASCII 概要図と、パスごとの実行タイムライン
モデルアーキテクチャレポートは、モデル構造を理解するための主要な成果物です。異常出力を参照しなくても、読者がモデルの実行全体を理解できるよう、レポートは自己完結している必要があります。
推奨事項
各推奨事項には、scope(global/step_group/structure/side/op)、followup_required、evidence_gap、priority(P0–P3)を含める必要があります。
よくあるフォローアップのパターン:
- バブルが多く、スタック情報が不足 →
with_stack=trueで再プロファイルします - 形状情報が不足し、グループ化が不安定 →
record_shapes=trueにします - ホストリスクが高く、エビデンスが少ない → ホスト側のサンプリング/スレッドビューを行います
- 待ちによる汚染が多い → 通信パスと同期パスを確認します
- 構造間のバブルが大きい → ホスト側のレイヤーディスパッチ遅延を確認します