Primus-Turbo-Entwicklungsleitfaden

Primus-Turbo ist eine Hochleistungs-Trainingsoperator-Bibliothek für AMD-GPUs (gfx942 / gfx950). Diese Skill-Anleitung ist der Einstiegspunkt für die Entwicklung eines Features und die Validierung seiner Genauigkeit und Leistung.

Wählen Sie Ihre Aufgabe

Ziel	Hier starten
Operator / Modul End-to-End hinzufügen oder ändern	develop-feature/SKILL.md
Numerische Korrektheit überprüfen	verify-accuracy/SKILL.md
Latenz / Durchsatz messen	verify-performance/SKILL.md
Autonome Kernel-Optimierungskampagne durchführen	optimize-handoff/SKILL.md → `kernel-optimize/SKILL.md`
Hot Kernel mit Laufzeitnachweisen profilieren	run_profile/tool-rocprof/SKILL.md

Der Rest dieser Datei ist die gemeinsame Referenz (Build, Architektur, Code-Map, Backend-System), auf die diese Dokumente verweisen. Lesen Sie sie einmal durch und springen Sie dann zur aufgabenspezifischen Datei. (run_profile/ ist ein Kategorieordner für Profiling-Werkzeuge und enthält derzeit die einzelne Skill tool-rocprof/.)

Build & Iterieren

Installation

# Installieren Sie immer zuerst die festgelegten Abhängigkeiten (Triton / PyTorch-Versionen sind entscheidend).
pip install -r requirements.txt

# Editierbare Installation (für die Entwicklung empfohlen).
GPU_ARCHS=gfx942 pip install --no-build-isolation -e . -v

GPU_ARCHS: gfx942 (MI300X/MI325X), gfx950 (MI350X/MI355X), native (automatische Erkennung) oder "gfx942;gfx950".
--no-build-isolation ist erforderlich, damit der Build die bereits installierten torch / triton-Pakete sieht.
pip install . kopiert in site-packages (Quellcode-Änderungen haben keine Wirkung); pip install -e . ist editierbar.
Der Build installiert auch automatisch die festgelegten Pakete amd-aiter und origami (siehe setup.py).

Was einen Neubau erfordert

Sie haben geändert	Neubau erforderlich?
Python / Triton (`primus_turbo/**.py`)	Nein (editierbare Installation übernimmt es sofort)
C++ / HIP (`csrc/**`) oder Operator-Schema in `bindings_pytorch.cpp`	Ja: Editierbares Installationskommando erneut ausführen

Architektur-spezialisierte Quellen werden nach Dateinamensuffix gefiltert: *_gfx942.{cu,hip} und *_gfx950.{cu,hip} werden nur kompiliert, wenn diese Architektur in GPU_ARCHS enthalten ist (siehe setup.py: filter_files_by_arch).

Build-Artefakte (3 Schichten, Kernel-Bibliothek entkoppelt von Frontends)

Artefakt	Quelle	Hinweise
`libprimus_turbo_kernels.so`	`csrc/kernels/`	Alle HIP/CK/hipBLASLt/turbo Kernel, frontend-unabhängig
`primus_turbo.pytorch._C`	`csrc/pytorch/`	PyTorch-Bindungen, verknüpft die `.so`-Datei oben
`primus_turbo.jax._C`	`csrc/jax/`	JAX-Bindungen (`PRIMUS_TURBO_FRAMEWORK=JAX`)

Wichtige Umgebungsvariablen

Variable	Zweck	Standard
`GPU_ARCHS`	Zielarchitektur(en)	automatische Erkennung
`ROCM_HOME`	ROCm-Pfad	`/opt/rocm`
`MAX_JOBS`	Parallele Kompilierjobs	`64`
`PRIMUS_TURBO_FRAMEWORK`	`PYTORCH` / `JAX` (`;`-getrennt)	`PYTORCH`
`PRIMUS_TURBO_LOG_LEVEL`	Logger-Level	`WARNING`

Überprüfen Sie eine funktionierende editierbare Installation mit pip show primus_turbo (suchen Sie nach dem Feld Editable project location) oder python -c "import primus_turbo; print(primus_turbo.__file__)" (es sollte in diesen Quellbaum zeigen, nicht in site-packages); installieren Sie im editierbaren Modus neu, falls nicht.

Architektur: Das geschichtete Design

Jeder Operator ist ein vertikaler Schnitt durch diese Schichten. Zu wissen, welche Schicht berührt werden muss, ist der Kern der schnellen Entwicklung.

modules/   nn.Module-Wrapper (Linear, GroupedLinear, Attention, ...)
   │ ruft auf
ops/       Python-API + torch.autograd.Function (forward/backward)     ← benutzerseitig
   │ ruft auf
kernels/   AutoKernelDispatcher + KernelBackend  (wählt ein Backend aus)  ← Multi-Backend-Ops
   │ dispatches an
triton/    Triton-Kernel (Python, kein Neubau)        csrc/  HIP/CK/hipBLASLt-Kernel (Neubau)
                                                          │ gebunden via TORCH_LIBRARY in csrc/pytorch/
                                                          └→ torch.ops.primus_turbo_cpp_extension.*

Es gibt drei Op-Verdrahtungsmuster (siehe develop-feature/SKILL.md für die kanonische Datei, die für jedes kopiert werden soll):

Multi-Backend (gemm, gemm_fp8, grouped_gemm): ops → kernels Dispatcher → Triton und/oder csrc.
Direkt C++ (rmsnorm): ops autograd Function → torch.ops.primus_turbo_cpp_extension.* (kein Dispatcher).
Direkt Triton (swiglu_with_probs): ops autograd Function → einen Triton-gestützten Helfer in kernels/ (kein Dispatcher).

Code-Map

Die Spaltenwurzeln unterscheiden sich: ops/ = primus_turbo/pytorch/ops/, kernels/ = primus_turbo/pytorch/kernels/, triton/ = primus_turbo/triton/ (oberste Ebene, nicht unter pytorch/); csrc/kernels/, tests/, benchmark/ sind auf Repository-Ebene. Die Benutzer-API befindet sich in ops/; die kernels/-Schicht enthält den Dispatcher oder die Backend-Implementierung (*_impl.py).

Operator-Familie	API (`ops/`)	`kernels/` (Dispatcher/Impl.)	Triton (`triton/`)	C++/HIP (`csrc/kernels/`)	Tests	Bench
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`
Quantisierung	`quantization.py`	`quantization/`	`quantization/`	`quantization/`	`ops/test_quantization.py`	`accuracy/eval_sf_accuracy.py`
Aktivierung (swiglu/geglu)	`activation.py`	`activation/`	`activation/`	—	`ops/test_activation.py`	—
Normalisierung (rmsnorm)	`normalization.py`	— (direkt 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++-Binding-Infrastruktur (von allen csrc-Operatoren gemeinsam genutzt): Deklarationen in csrc/pytorch/extensions.h, Schema + CUDA + Meta-Registrierung in csrc/pytorch/bindings_pytorch.cpp.

Backend-System

Zwei Klassen in primus_turbo/pytorch/core/backend.py:

GlobalBackendManager — globale Auswahl nach Operator × Genauigkeit.
AutoKernelDispatcher — Pro-Operator-Basis mit Autotune, Standard und Fallback.

Auswahlpriorität (hoch → niedrig): Code-Setter → Umgebungsvariable → Autotune → Code-Standard → Fallback (alle can_handle ausprobieren).

`BackendType`	Verwendet von	Hinweise
`HIPBLASLT`	GEMM (bf16, fp8 tensorweise)	Standard für dichte GEMM
`TRITON`	GEMM, GroupedGEMM, Attention, ...	konfigurierbar, kein Neubau
`CK`	GEMM/GroupedGEMM FP8 (zeilen-/blockweise)	Composable Kernel
`TURBO`	MXFP8/MXFP4 GEMM, Attention	hauseigen (gfx950)
`AITER`	Attention	Standard Attention
`DEEP_EP`	MoE dispatch/combine	benötigt DeepEP-Installation
`FLYDSL` (geplant)	GEMM / Attention (Autoren-DSL)	kommendes AMD-Tile-DSL-Backend; noch kein `BackendType`-Member

FLYDSL befindet sich auf der Roadmap — eine in Python eingebettete Tile-DSL, die über MLIR → ROCDL heruntergeht. Sein Optimierungswissen befindet sich bereits in der Kernel-Optimierungs-Wissensdatenbank unter knowledge/backend/flydsl/, es ist jedoch noch nicht in BackendType registriert, daher ist GlobalBackendManager.set_*_backend(BackendType.FLYDSL) derzeit nicht verfügbar.

from primus_turbo.pytorch.core.backend import BackendType, GlobalBackendManager
GlobalBackendManager.set_gemm_backend(BackendType.CK)   # erzwingen
GlobalBackendManager.set_auto_tune(True)                # oder PRIMUS_TURBO_AUTO_TUNE=1
GlobalBackendManager.reset()                            # Einstellungen + Autotune-Cache löschen

Umgebungsvariablen (pro Genauigkeit, Form "fp8:CK,other:TRITON" unterstützt): PRIMUS_TURBO_GEMM_BACKEND, PRIMUS_TURBO_GROUPED_GEMM_BACKEND, PRIMUS_TURBO_ATTENTION_BACKEND, PRIMUS_TURBO_MOE_DISPATCH_COMBINE_BACKEND, PRIMUS_TURBO_AUTO_TUNE.

Test & Bench Kurzreferenz

# Korrektheit (Einzel-GPU, parallel; jeder xdist-Arbeiter bindet eine GPU über conftest.py)
pytest tests/pytorch/ -n 8
pytest tests/pytorch/ops/test_gemm_fp8.py -v -k "blockwise and TRITON"   # Op+Backend filtern
pytest tests/pytorch/ -n 8 --deterministic-only                          # Bitweise-Determinismus-Suite
pytest tests/pytorch/ --dist-only                                        # Multi-GPU-Tests

# Leistung
python benchmark/ops/training/bench_gemm_turbo.py --dtype fp8 --granularity blockweise
python benchmark/ops/training/run_suite.py -d output/ -g gemm_fp8                  # Batch-Suite

Korrektheits-Gates: bf16/fp16 rtol=atol=1e-2, fp32 1e-4 (allclose-Toleranzen aus get_tolerances in tests/pytorch/test_utils.py); FP8 SNR ≥ 25 dB (E4M3) / 20 dB (E5M2), FP4 SNR ≥ 10 dB (SNR via compute_snr; Schwellenwerte sind in den Test-/Bench-Dateien fest codiert, nicht in get_tolerances); Determinismus rtol=atol=0. Details und Muster: verify-accuracy/SKILL.md.

Zusätzliche Referenzen

README.md — Schnellstart, Installation, Paketierung
docs/examples.md — Pro-Operator-API-Nutzung (GEMM, Attention, GroupedGEMM, FP8/FP4, Backend/AutoTune)
benchmark/README.md, benchmark/accuracy/README.md — DeepEP-Bench, plattformübergreifende Genauigkeit
CONTRIBUTING.md — Branch-Namens- und Commit-Konventionen
Kernel-Optimierungs-Schleife: kernel-optimize/SKILL.md (steuern über optimize-handoff/SKILL.md)

Primus-Turbo-Entwicklung

Was ist Primus-Turbo-Entwicklung?

In Ihrer bevorzugten KI fragen

Dokumentation