optimization-catalog

最適化カタログルーター

このスキルはディスパッチャーとして使用します。共有ルートのナレッジベースは、実装言語をまたいで応用できるアルゴリズムパターンの正式な保存場所です。言語固有のオーバーレイには、特定のDSLやプログラミングモデルに紐づく実装の詳細を記録します。

読み込み順

1. パターンがアルゴリズムに関するものである場合は、共有ルートのナレッジベースである docs/knowledge/optimizations/ と docs/knowledge/anti-patterns/ を読みます。
2. 選択した実装言語に対応する言語固有の最適化カタログスキルを読み込みます。
3. 実装の詳細がその言語固有の領域に依存する場合にのみ、docs/knowledge/languages/<language>/... の言語オーバーレイを読みます。

言語固有のカタログスキル

言語キー	読み込むスキル	言語固有のナレッジルート
cutile-dsl	/optimization-catalog-cutile-dsl	docs/knowledge/languages/cutile-dsl/
cute-dsl	/optimization-catalog-cute-dsl	docs/knowledge/languages/cute-dsl/

分類ルール

• 共有ルートのカタログには、DSLをまたいで応用できるアルゴリズムパターン、ワークロード形状のルール、アンチパターンを記載します。
• 言語オーバーレイには、特定のAPI、コンパイラーの動作、コード生成の領域、またはスケジューリングモデルに依存する実装の詳細を記載します。
• 判断に迷う場合は、再利用可能な仕組みを共有ルートに保持し、実装領域に固有の内容に限って言語固有のオーバーレイを追加します。

現在の移行状況

• docs/knowledge/optimizations/ と docs/knowledge/anti-patterns/ にある共有ルートのカタログは、互換性を維持する基準として引き続き使用されます。
• 言語固有の新しいオーバーレイを docs/knowledge/languages/ 以下に追加しています。
• 移行中も、従来のルートパスへの既存の参照は引き続き機能します。

ナレッジベースの原則

このカタログの目的は、デバイスにまつわる経験則を蓄積することではなく、再利用可能な cuTile カーネル設計の知識を構築することです。

そのため、各項目は次の条件を満たす必要があります。

• カーネルをまたいで応用できるパターンまたはアンチパターンであること
• 適用される状況を説明する明確なコンテキストがあること
• 影響を受けるパフォーマンス指標が明示されていること
• 該当する場合は、根拠をローカルでの検証と一般化した要点に分けて記載すること

ルールを明確にできる場合は、デバイスやアーキテクチャに関する事実を記載することを推奨します。

• Blackwell や Hopper などのアーキテクチャファミリー
• Tensor Cores、TMA、スレッドブロッククラスター、スケジューラーの動作、共有メモリーの上限などのアーキテクチャ機能
• FP16/BF16 のピーク TFLOP/s、ピークメモリ帯域幅、リッジポイント、SM 数、SM あたりのレジスター数、SMEM 容量などのデバイス仕様

ただし、こうした事実は再利用可能な指針に落とし込む必要があります。ある観察結果をより広いパターンの根拠としてのみ使用するのでない限り、「デバイス Y 上のカーネル X では設定 Z が効果的だった」という記述に終始しないようにしてください。

このカタログの使い方

1. 以下のインデックスで、トリガー条件 → 最適化 → 詳細ファイルの対応を確認します
2. オーケストレーターはインデックスを参照し、プロファイリング結果に基づいて最適化を選択します
3. カーネル設計者は詳細ファイルを読み、具体的な最適化を実装します
4. 新しい最適化：docs/knowledge/optimizations/ に詳細ファイルを作成し、インデックスに行を追加します
5. 失敗した最適化：docs/knowledge/anti-patterns/ にアンチパターンを作成し、以下に行を追加します

最適化インデックス

ID	最適化	適用条件	推定効果	注意点	詳細ファイル
O1	Split-KV による比例ブロック割り当て	デュアルパスカーネルで潜在表現と展開後の処理量に大きな偏りがあり、ブロックを均等に分割すると一方のパスで処理が不足する	非常に高い	リダクションカーネルと中間テンソルが必要です	docs/knowledge/optimizations/split-kv.md
O2	オペランド共有再利用のためのヘッドグループ化	同じオペランド（例：潜在表現 Z）を複数のヘッドで再利用し、Bh=1 によってヘッドごとの MMA が細長くなるか、TC の利用率がほぼゼロになる	非常に高い	レジスター圧力が高まります。展開後の K/V のようにヘッドごとにしか使われないオペランドには適していません	docs/knowledge/optimizations/head-grouping.md
O3	パスごとの独立したスケジューリング	Split-KV の後も、潜在表現パスと展開後のパスで異なるストリーミング粒度やロードスケジューリングが必要	低～中	レジスター圧力と占有率が改善しない場合、効果はわずかです	docs/knowledge/optimizations/independent-tiles.md
O4	スウィズルスケジューリング	タイル化カーネルが隣接する CTA 間でオペランドを再利用し、ブロック順序が L2 の局所性に明確な影響を与える	低い	コンピュートバウンドのカーネルでは効果がわずかな場合があります。1D の再マッピングではインデックス計算のオーバーヘッドが加わります	docs/knowledge/optimizations/swizzle.md
O5	レイテンシヒント	カーネル構造が適切な状態でロードと計算のオーバーラップを調整する必要があり、パスごとの DRAM 圧力に十分な差があるため、コンパイラーへの指示でスケジューリングを改善できる可能性がある	低い	効果の切り分けが困難です。ヒントは提案であり、保証ではありません	docs/knowledge/optimizations/latency-hints.md
O6	CGA スレッドブロッククラスター	Hopper 以降のカーネルに CTA 間でデータを共有する実質的な機会がある、または num_ctas の意味とクラスター起動の動作を正しく把握する必要がある	中程度	ハードウェア固有であり、実際の共有効果がない場合は誤用しやすいです	docs/knowledge/optimizations/cga.md
O7	オンラインソフトマックスの高速数学演算	オンラインソフトマックスループで exp2 と除算の負荷が高く、大きなタイルで計算スループットが低下し、推論での精度低下を許容できる	高い	適切なタイル設定の代わりにはなりません。スピルや帯域幅がボトルネックの場合、効果は小さくなります	docs/knowledge/optimizations/fast-math-online-softmax.md
O8	因果的 K ループの分割	因果的注意機構にマスク不要の K タイルが多数あり、マスク処理が必要なのは対角タイルと末尾タイルのみで、将来のタイルをスキップできる	中～高	対象のボトルネックに対してマスク処理が重要でなくなった場合、効果がないか、性能が低下することがあります	docs/knowledge/optimizations/causal-k-loop-split.md
O9	因果的 ProgramId の再マッピング	三角形状の処理によって CTA 間でウェーブ末尾の負荷が不均衡になり、起動順序を単純に逆転できる	低～中	処理の分散がすでに均一な場合やグリッドが小さい場合、効果はわずかです	docs/knowledge/optimizations/causal-program-id-remap.md
O10	タイルと占有率の適応型自動チューニング	シーケンス長やデバイスの能力に応じて最適なタイル／占有率が変わり、固定の手動設定では短い形状でリソースが不足するか、長い形状で過剰に使用する	高い	検索空間は、対象を絞らないと急増する可能性があります。構造的に問題のあるカーネルは修復できません	docs/knowledge/optimizations/adaptive-tile-autotuning.md
O11	パイプライン主導の低占有率スケジューリング	回避できない CTA ごとの大きな状態によって CTA が 1 つ／SM になるか占有率が非常に低くなり、常駐ワープを増やすのではなく、オーバーラップとスケジューリングで性能を高める必要がある	高い	細粒度スケジューリングを行うには、アーキテクチャまたは DSL のサポートが必要です。単一の巨大な CTA で代用することはできません	docs/knowledge/optimizations/pipeline-driven-low-occupancy.md

アンチパターン一覧

ID	アンチパターン	失敗モード	出典	詳細ファイル
A1	異種パス間でブロックを均等に分割	潜在処理と展開処理の作業量が異なるのにブロックを50/50で割り当てると、オーバーラップせずに逐次的なボトルネックが発生します	MLA-var6+ V0	docs/knowledge/anti-patterns/equal-block-split.md
A2	TILE_M=1 の結合／展開	単一行の結合GEMMではTensor Coreが無効になり、小さな s で末尾の処理が残り続けます	MLA-var6+ V0/V2/V3	docs/knowledge/anti-patterns/tile-m-one-combine.md
A3	永続カーネルの並行実行数不足	常駐ブロック数がSM数を下回るとGPUがアイドル状態になり、オーバーラップが効果を発揮しません	MLA-var6+ V4	docs/knowledge/anti-patterns/underfilled-persistent.md
A4	レジスター上限に達する永続ステージ	永続カーネルがレジスター上限（スレッドあたり 255 レジスター）に達すると、占有率が低下し、レイテンシがボトルネックになります	MLA-var6+ V4	docs/knowledge/anti-patterns/spill-heavy-persistent.md
A5	大きなタイルをそのまま移植	別のデバイスのタイル形状を、レジスター、SMEM、ローカルメモリのトラフィック、グリッドサイズを再検証せずにコピーすると、リソースの限界を超えます	FlashAttention の学習チェーン	docs/knowledge/anti-patterns/blind-large-tile-port.md
A6	一様な因果マスキング	Kタイルごとに因果マスクの処理をすべて実行すると、ほとんどのタイルが完全に有効か、完全にスキップされるにもかかわらず、無駄な処理が発生します	FlashAttention の学習チェーン	docs/knowledge/anti-patterns/uniform-causal-masking.md
A7	16未満のMMA次元	有効なMMA次元（M、N、K）のいずれかを 16 未満に縮小すると、通常Tensor Coreのカバレッジが損なわれ、占有率を改善するどころかレイテンシが急増します	FlashMLA V1 の手動プローブ＋Tensor Core の形状制約	docs/knowledge/anti-patterns/sub-16-mma-dimension.md
A8	データフローを安易に反転	リソースに敏感なTensor Coreカーネルを、代数的に等価なオペランドの向きに書き換えると、コード生成が大きく変わり、スピルが再発したりSMEMの挙動が悪化したりします	FlashMLA V1 → V2	docs/knowledge/anti-patterns/blind-dataflow-flip.md

相互参照：メトリクス → 最適化

プロファイリングメトリクスの状態	想定される最適化
処理量が明らかに異なるのに、カーネルの実行時間が同じ	O1（Split-KV の比例ブロック割り当て）
Bh=1、または共有オペランドを使うヘッドごとの細長い MMA	O2（ヘッドのグループ化）
Split-KV 後のデュアルパスカーネルがリッジポイント付近で性能の頭打ちになる	O3（独立パスのスケジューリング）
L2 ヒット率が 90% 未満で、隣接する CTA が同じオペランドタイルを再読み込みする	O4（スウィズルスケジューリング）
カーネル構造は同じでも、パスレベルのメモリ負荷が異なるため、コンパイラのスケジューリング変更が有効な可能性がある	O5（レイテンシヒント）
Hopper 以降で CTA 間のデータ共有が必要、または num_ctas が実際に制御する対象が不明	O6（CGA スレッドブロッククラスター）
Tensor Core/MMA の構造に問題はないが、オンラインソフトマックスの特殊関数がホットループの大部分を占める	O7（オンラインソフトマックスの高速演算）
多くの K タイルが完全に有効で、後続のタイルは完全にスキップされるのに、因果カーネルがマスク処理や制御フローに相当な時間を費やす	O8（因果 K ループの分割）
因果的／三角形のワークロードで CTA 間の末尾の負荷に偏りがある、またはウェーブごとに完了時刻が異なる	O9（因果的 ProgramId の再マッピング）
短い形状では GPU の稼働率が低く、長い形状では異なるタイルや占有率ヒントが適している	O10（適応型タイルと占有率の自動チューニング）
レジスター／SMEM の制約で 1 SM あたりの CTA が 1 つになり、実行可能なワープ数が非常に少ない。カーネルは計算律速だが、Tensor Core の使用率も低い	O11（パイプライン駆動の低占有率スケジューリング）
Combine ステージの TILE_M=1 かつ TC Util = 0%	A2（TILE_M=1 の Combine／展開）
常駐する Persistent ブロック数が SM 数を下回る、または 1 SM あたりのウェーブ数が 1 未満	A3（Persistent 並列性の不足）
Persistent ステージでスレッドあたりのレジスター数が 255 となり、占有率が一桁台	A4（レジスター上限に達する Persistent ステージ）
大きなタイルを移植した結果、対象デバイスでレジスター／SMEM の急激な制約、ローカルメモリのトラフィック、またはグリッドサイズの急減が発生する	A5（大きなタイルの無検討な移植）
明らかに全要素が有効な領域とスキップされる領域があるのに、すべての K タイルで一律に因果マスキングの処理が発生する	A6（一律の因果マスキング）
候補タイルにより実効 MMA 次元のいずれかが 16 未満になる、または「小さいタイル」への変更後に Tensor Core の FLOP 数がアルゴリズム上の FLOP 数を大幅に下回る	A7（16 未満の MMA 次元）
提案する最適化が、特にレジスターまたは SMEM の制約に近い状況で、代数的なオペランド／データフローの入れ替えだけである	A8（データフローの無検討な入れ替え）

ナレッジベース更新プロトコル

更新プロトコルの全容、詳細ファイルのテンプレート、および手順ごとの説明については、/orchestration-workflow スキルを読み込んでください。