Primus-Turbo 개발 가이드

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 (백엔드 선택)              ← 다중 백엔드 op
   │ 디스패치
──────┼────────────────────────────────────────────────────────────────
triton/    Triton 커널 (Python, 재빌드 불필요)        csrc/  HIP/CK/hipBLASLt 커널 (재빌드 필요)
                                                          │ TORCH_LIBRARY를 통해 바인딩 (csrc/pytorch/)
                                                          └→ torch.ops.primus_turbo_cpp_extension.*

세 가지 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 op 공유): csrc/pytorch/extensions.h의 선언, csrc/pytorch/bindings_pytorch.cpp의 스키마 + CUDA + Meta 등록.

백엔드 시스템

primus_turbo/pytorch/core/backend.py의 두 클래스:

• 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입니다. 해당 튜닝 지식은 이미 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를 통해 하나의 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, Backend/AutoTune)
• benchmark/README.md, benchmark/accuracy/README.md — DeepEP 벤치, 크로스 플랫폼 정확성
• CONTRIBUTING.md — 브랜치 명명 및 커밋 규칙
• 커널 최적화 루프: kernel-optimize/SKILL.md (optimize-handoff/SKILL.md를 통해 실행)