Primus-Turbo 開発ガイドは何をしますか？

Primus-Turbo は、AMD GPU（gfx942 / gfx950）向けの高性能トレーニングオペレーターライブラリです。このスキルは、機能の開発とその精度・性能の検証のエントリポイントです。

タスクの選択

目標	開始場所
オペレーター/モジュールの追加・変更（エンドツーエンド）	develop-feature/SKILL.md
数値的正確性の検証	verify-accuracy/SKILL.md
レイテンシ/スループットの計測	verify-performance/SKILL.md
自律的なカーネル最適化キャンペーンの実行	optimize-handoff/SKILL.md → `kernel-optimize/SKILL.md`
実行時証拠に基づくホットカーネルのプロファイリング	run_profile/tool-rocprof/SKILL.md

このファイルの残りの部分は、上記の文書が依存する共通リファレンス（ビルド、アーキテクチャ、コードマップ、バックエンドシステム）です。一度読んでから、タスク固有のファイルに進んでください。（run_profile/ はプロファイリングツールのカテゴリフォルダで、現在は tool-rocprof/ スキルのみを含みます。）

ビルドと反復

インストール

# 最初に固定された依存関係を必ずインストール（Triton / PyTorch のバージョンは重要）。
pip install -r requirements.txt

# 開発用の編集可能インストール（推奨）。
GPU_ARCHS=gfx942 pip install --no-build-isolation -e . -v

GPU_ARCHS: gfx942（MI300X/MI325X）、gfx950（MI350X/MI355X）、native（自動検出）、または "gfx942;gfx950"。
--no-build-isolation は必須で、ビルドが既にインストールされた torch/triton を認識できるようにします。
pip install . は site-packages にコピーします（ソース編集は反映されません）。pip install -e . は編集可能です。
ビルドは固定された amd-aiter と origami も自動インストールします（setup.py 参照）。

再ビルドが必要なケース

変更点	再ビルド必要？
Python / Triton（`primus_turbo/**.py`）	いいえ（編集可能インストールですぐに反映）
C++ / HIP（`csrc/**`）または `bindings_pytorch.cpp` の op スキーマ	はい：編集可能インストールコマンドを再実行

アーキテクチャ特化ソースはファイル名サフィックスでフィルタリングされます：*_gfx942.{cu,hip} と *_gfx950.{cu,hip} は、そのアーキテクチャが GPU_ARCHS に含まれる場合のみコンパイルされます（setup.py: filter_files_by_arch 参照）。

ビルド成果物（3層、カーネルライブラリはフロントエンドから独立）

成果物	ソース	備考
`libprimus_turbo_kernels.so`	`csrc/kernels/`	すべての HIP/CK/hipBLASLt/turbo カーネル、フロントエンド非依存
`primus_turbo.pytorch._C`	`csrc/pytorch/`	PyTorch バインディング、上記 `.so` をリンク
`primus_turbo.jax._C`	`csrc/jax/`	JAX バインディング（`PRIMUS_TURBO_FRAMEWORK=JAX`）

主要な環境変数

変数	目的	デフォルト
`GPU_ARCHS`	ターゲットアーキテクチャ	自動検出
`ROCM_HOME`	ROCm パス	`/opt/rocm`
`MAX_JOBS`	並列コンパイルジョブ数	`64`
`PRIMUS_TURBO_FRAMEWORK`	`PYTORCH` / `JAX`（`;` 区切り）	`PYTORCH`
`PRIMUS_TURBO_LOG_LEVEL`	ロガーレベル	`WARNING`

編集可能インストールが動作していることを pip show primus_turbo（Editable project location フィールドを確認）または python -c "import primus_turbo; print(primus_turbo.__file__)"（site-packages ではなくこのソースツリーを指すはず）で確認してください。そうでない場合は編集可能モードで再インストールしてください。

アーキテクチャ：階層化設計

すべてのオペレーターは、これらの階層を垂直に貫くスライスです。どの階層を触るべきかを知ることが、高速開発の中核です。

modules/   nn.Module ラッパー（Linear, GroupedLinear, Attention, ...）
   │ 呼び出し
ops/       Python API + torch.autograd.Function（forward/backward）        ← ユーザー向け
   │ 呼び出し
kernels/   AutoKernelDispatcher + KernelBackend（バックエンドを選択）      ← マルチバックエンド ops
   │ ディスパッチ
Triton/    Triton カーネル（Python、再ビルド不要）        csrc/  HIP/CK/hipBLASLt カーネル（再ビルド必要）
                                                          │ csrc/pytorch/ の TORCH_LIBRARY を介してバインド
                                                          └→ torch.ops.primus_turbo_cpp_extension.*

3つの op 配線パターンがあります（各パターンのコピー元となる正規ファイルについては develop-feature/SKILL.md を参照）：

マルチバックエンド（gemm、gemm_fp8、grouped_gemm）：ops → kernels ディスパッチャ → Triton および/または csrc。
直接 C++（rmsnorm）：ops autograd Function → torch.ops.primus_turbo_cpp_extension.*（ディスパッチャなし）。
直接 Triton（swiglu_with_probs）：ops autograd Function → kernels/ 内の Triton ベースのヘルパー（ディスパッチャなし）。

コードマップ

列のルートが異なります：ops/ = primus_turbo/pytorch/ops/、kernels/ = primus_turbo/pytorch/kernels/、triton/ = primus_turbo/triton/（トップレベル、pytorch/ の下ではない）；csrc/kernels/、tests/、benchmark/ はリポジトリルート。ユーザー API は ops/ にあります；kernels/ 階層にはディスパッチャまたはバックエンド実装（*_impl.py）があります。

オペレーターファミリー	API（`ops/`）	`kernels/`（ディスパッチャ/実装）	Triton（`triton/`）	C++/HIP（`csrc/kernels/`）	テスト	ベンチマーク
GEMM（bf16/fp16/fp32）	`gemm.py`	`gemm/gemm_impl.py`	`gemm/gemm_kernel.py`	`gemm/`（hipBLASLt）	`ops/test_gemm.py`	`bench_gemm_turbo.py`
GEMM FP8	`gemm_fp8.py`	`gemm/gemm_fp8_impl.py`	`gemm/gemm_fp8_kernel.py`	`gemm/ck`、`gemm/turbo`	`ops/test_gemm_fp8.py`	`bench_gemm_turbo.py --dtype fp8`
GEMM FP4	`gemm_fp4.py`	`gemm/gemm_fp4_impl.py`	—	`gemm/`（hipBLASLt fp4）	`ops/test_gemm_fp4.py`	`bench_gemm_turbo.py --dtype fp4`
Grouped GEMM	`grouped_gemm.py`、`grouped_gemm_fp8.py`	`grouped_gemm/`	`grouped_gemm/`	`grouped_gemm/ck`	`ops/test_grouped_gemm*.py`	`bench_grouped_gemm_turbo.py`
Attention	`attention/`	`attention/`（aiter/triton/turbo）	`attention/attention_kernel.py`	`attention/turbo`	`ops/test_attention*.py`	`bench_attention_turbo.py`
量子化	`quantization.py`	`quantization/`	`quantization/`	`quantization/`	`ops/test_quantization.py`	`accuracy/eval_sf_accuracy.py`
活性化（swiglu/geglu）	`activation.py`	`activation/`	`activation/`	—	`ops/test_activation.py`	—
正規化（rmsnorm）	`normalization.py`	—（直接 C++）	—	`normalization/`	`ops/test_normalization.py`	—
MoE permute / router / dispatch	`moe/`	`moe/`、`moe_permute`	`moe/`	`moe_permute/`、`deep_ep/`	`ops/test_moe_permute.py`、`test_fused_moe_router.py`	`bench_deepep_intranode.py`
Async-TP（gemm+comm）	`async_tp.py`	`async_tp/`	`async_tp/`	—	`ops/test_fused_*.py`	—

C++ バインディング配管（すべての csrc ops で共有）：宣言は csrc/pytorch/extensions.h、スキーマ + CUDA + Meta 登録は csrc/pytorch/bindings_pytorch.cpp。

バックエンドシステム

primus_turbo/pytorch/core/backend.py の2つのクラス：

GlobalBackendManager — オペレーター × 精度によるグローバル選択。
AutoKernelDispatcher — オペレーターごとのベースで、オートチューン、デフォルト、フォールバックを備える。

選択優先順位（高 → 低）：コードセッター → 環境変数 → オートチューン → コード内デフォルト → フォールバック（すべての can_handle を試行）。

`BackendType`	使用される場所	備考
`HIPBLASLT`	GEMM（bf16、fp8 tensorwise）	密 GEMM のデフォルト
`TRITON`	GEMM、GroupedGEMM、Attention、...	チューニング可能、再ビルド不要
`CK`	GEMM/GroupedGEMM FP8（row/block）	Composable Kernel
`TURBO`	MXFP8/MXFP4 GEMM、Attention	社内（gfx950）
`AITER`	Attention	デフォルトの Attention
`DEEP_EP`	MoE ディスパッチ/コンバイン	DeepEP インストールが必要
`FLYDSL` （計画中）	GEMM / Attention（オーサリング DSL）	今後の AMD タイル DSL バックエンド；まだ `BackendType` のメンバーではありません

FLYDSL はロードマップ上にあります — MLIR → ROCDL に低減する Python 埋め込みタイル DSL。そのチューニング知識は既に kernel-optimize 知識ベースの knowledge/backend/flydsl/ にありますが、まだ BackendType に登録されていないため、GlobalBackendManager.set_*_backend(BackendType.FLYDSL) は現在利用できません。

from primus_turbo.pytorch.core.backend import BackendType, GlobalBackendManager
GlobalBackendManager.set_gemm_backend(BackendType.CK)   # 強制
GlobalBackendManager.set_auto_tune(True)                # または PRIMUS_TURBO_AUTO_TUNE=1
GlobalBackendManager.reset()                            # 設定とオートチューンキャッシュをクリア

環境変数（精度ごとの形式 "fp8:CK,other:TRITON" 対応）：PRIMUS_TURBO_GEMM_BACKEND、PRIMUS_TURBO_GROUPED_GEMM_BACKEND、PRIMUS_TURBO_ATTENTION_BACKEND、PRIMUS_TURBO_MOE_DISPATCH_COMBINE_BACKEND、PRIMUS_TURBO_AUTO_TUNE。

テストとベンチマークのクイックリファレンス

# 正確性（シングルGPU、並列；各 xdist ワーカーは conftest.py を介して1つのGPUを固定）
pytest tests/pytorch/ -n 8
pytest tests/pytorch/ops/test_gemm_fp8.py -v -k "blockwise and TRITON"   # op+バックエンドでフィルタ
pytest tests/pytorch/ -n 8 --deterministic-only                          # ビット単位決定性スイート
pytest tests/pytorch/ --dist-only                                        # マルチGPUテスト

# パフォーマンス
python benchmark/ops/training/bench_gemm_turbo.py --dtype fp8 --granularity blockwise
python benchmark/ops/training/run_suite.py -d output/ -g gemm_fp8                  # バッチスイート

正確性の基準：bf16/fp16 rtol=atol=1e-2、fp32 1e-4（tests/pytorch/test_utils.py の get_tolerances からの allclose 許容誤差）；FP8 SNR ≥ 25 dB（E4M3）/ 20 dB（E5M2）、FP4 SNR ≥ 10 dB（compute_snr による SNR；しきい値はテスト/ベンチファイルにハードコードされており、get_tolerances にはありません）；決定性 rtol=atol=0。詳細とパターンは verify-accuracy/SKILL.md を参照。

追加リファレンス

README.md — クイックスタート、インストール、パッケージング
docs/examples.md — オペレーターごとの API 使用例（GEMM、Attention、GroupedGEMM、FP8/FP4、バックエンド/オートチューン）
benchmark/README.md、benchmark/accuracy/README.md — DeepEP ベンチマーク、クロスプラットフォーム精度
CONTRIBUTING.md — ブランチ命名規則とコミット規則
カーネル最適化ループ：kernel-optimize/SKILL.md（optimize-handoff/SKILL.md を介して実行）

Primus-Turbo 開発ガイド