최적화 핸드오프 (kernel-optimize)은(는) 무엇을 하나요?
커널을 하드웨어 한계까지 밀어붙이는 것이 목표일 때(단순 성능 확인이 아닌 경우), 이 파일은 Primus-Turbo와 ../../kernel-optimize/SKILL.md의 자율 최적화 루프 사이의 인터페이스 역할을 합니다. 이 루프가 필요로 하는 전제 정보를 제공합니다. 먼저 허브 ../SKILL.md를 읽으십시오.
프로세스
- 환경 확인 —
pip show primus_turbo; 편집 가능한 설치가 아니면 재설치(허브SKILL.md→ 빌드). kernel-optimize/SKILL.md"전제 정보" 읽기 — 루프가 필요한 사항을 확인합니다.- 대상 연산에 대한 전제 조건 수집 (아래 표 + 허브
SKILL.md의 코드 맵/명령). - 핸드오프 —
kernel-optimize/SKILL.md로 전달; 루프는 DEFINE_TARGET → PREPARE_ENVIRONMENT → BASELINE → (ANALYZE → OPTIMIZE → VALIDATE)* → REPORT를 실행합니다. - 수락 — 프로젝트로 돌아와서 전체 스위트
pytest tests/pytorch/ -v를 실행하고, 보고서를 검토하며, 깔끔한 diff/커밋을 확인합니다.
루프가 시작되기 전에 ../../../rules/iteration_rules.mdc를 읽으십시오: 라운드당 하나의 가설, 성능 전 정확성 게이트, 수용/롤백 계보, 모든 수용된 개선은 실제 훈련 단계로 전이되어야 함(id(...)-키 기반 활성화/grad_out 캐시 없음, 균일 분포 전용 GroupGemm 단축 금지).
전제 정보 (연산별)
| 요구 사항 | 획득 위치 |
|---|---|
| 커널 소스 파일 경로 | 허브 SKILL.md → 코드 맵 |
| 집중 테스트 명령 | 허브 SKILL.md → 테스트 및 벤치마크; 예: pytest tests/pytorch/ops/test_gemm_fp8.py -v -k "blockwise and TRITON" |
| 집중 벤치마크 명령 | ../verify-performance/SKILL.md; 예: PRIMUS_TURBO_GEMM_BACKEND=TRITON python benchmark/ops/training/bench_gemm_turbo.py --dtype fp8 --granularity blockwise |
| 벤치마크 출력 형식 / 메트릭 | ../verify-performance/SKILL.md(Forward/Backward TFLOPS, Check 게이트) |
| 빠른 검증 도구 | 아래 "빠른 검증" 참조 |
| 점수 측정 규칙 | 아래 "최적화 점수 측정" 참조 |
execution_mode + 재빌드 | 아래 "최적화 환경" 참조 |
최적화 환경
| 백엔드 / 언어 | 권장 execution_mode | 변경 후 재빌드 |
|---|---|---|
| Triton (Python) | repo-mode | 없음 (편집 가능한 설치) |
| HIP / CK (C++), 소규모/파라미터 변경 | repo-mode | GPU_ARCHS=<arch> pip install --no-build-isolation -e . -v |
| HIP / CK (C++), 새 커널 / 많은 시행착오 | workspace-mode | kernel-optimize/SKILL.md의 최소 스택 참조 |
최적화 점수 측정
Check 열은 하드 게이트입니다 — FAIL/ERROR shape은 후보를 거부합니다.
| 캠페인 유형 | primary_metric (집계 = PASS shape들의 기하 평균) |
|---|---|
| 계산 집약적, 순전파 전용 | Forward TFLOPS |
| 계산 집약적, 순전파 + 역전파 (훈련) | Combined Step TFLOPS (순전파/역전파는 진단용으로 유지) |
| 메모리 집약적 (원소별, 양자화) | Forward GB/s / Backward GB/s |
결합 단계 유도(순전파+역전파 GEMM-클래스 연산에 권장)는 ../verify-performance/SKILL.md에 있습니다. DEFINE_TARGET에서 사용자와 primary_metric을 확인하십시오.
빠른 검증
두 도구, 별도 역할 — 절대값을 서로 비교하지 마십시오(다른 타이밍 엔진 사용):
quick_test_bench.py(이 폴더, 캠페인 디렉토리로 복사됨)는 라운드 간 per-shape 회귀 게이트의 권위 있는 소스입니다. BASELINE(1라운드)과 모든 VALIDATE 라운드는 이 스크립트를 실행하고--summary-csv출력을 비교합니다. 수제time.perf_counter루프를 사용합니다.- 전체
bench_<op>_turbo.py(../verify-performance/SKILL.md,torch.utils.benchmark.Timer참조)는 (i) 전체 shape 집합에서representative_shapes를 선택하고 (ii) 캠페인 후 최종 수락을 수행하는 데만 사용됩니다.
두 검증 수준 모두 quick_test_bench.py를 통해 실행되며, SHAPES만 다릅니다:
- 전체 검증 (BASELINE + 최종 수락) →
SHAPES= 모든target_shapes. - 빠른 검증 (각 VALIDATE 라운드) →
SHAPES= 3~5개의representative_shapes하위 집합.
representative_shapes: BASELINE 실행에서 Check=PASS인 shape만, 작은 규모(런치 오버헤드) + 큰 규모(계산/메모리)를 모두 포함하며, 분산이 큰 shape을 선호합니다. manifest.yaml: representative_shapes에 기록합니다.
도구: 템플릿 quick_test_bench.py가 표준 참조입니다. PREPARE_ENVIRONMENT 중에 <campaign_dir>/quick_test_bench.py로 복사하고 SHAPES는 비워두고 <target_backend>를 설정합니다; BASELINE을 위해 SHAPES를 모든 target_shapes로 채운 다음, VALIDATE 라운드를 위해 representative_shapes로 좁힙니다. 대상에 맞게 연산/설정을 조정하십시오; --summary-csv 작성기와 열 스키마를 유지하십시오(비-GEMM 연산의 경우 아래 스키마 범위 참고 참조).
측정 일관성 계약: BASELINE(1라운드)과 모든 VALIDATE는 동일한 권위 있는 CSV를 --summary-csv를 통해 읽으며, 라운드 간에 동일한 CSV 리더로 동일하게 파싱됩니다 — 구성된 경우 선택적 mcp__turbo__parse_bench_csv MCP 도우미, 그렇지 않으면 아래 열을 키로 하는 직접 csv.DictReader. 특정 리더는 중요하지 않습니다. 스키마를 고정하는 것이 중요합니다. 스키마는 이 열들을 문자 그대로 일치시켜야 합니다(드리프트 발생 시 per-shape 회귀 게이트가 자동으로 비활성화됨):
label,B,M,N,K,Check,Forward TFLOPS,Forward TFLOPS_stddev,Backward TFLOPS,Backward TFLOPS_stddev,Forward Time (ms),Backward Time (ms),out_snr,da_snr,db_snr
Check는 PASS / FAIL을 사용합니다; *_stddev는 해당 메트릭 단위의 절대 표준편차입니다. 호출을 manifest.yaml에 quick_command: "python <campaign_dir>/quick_test_bench.py"로 기록합니다; BASELINE과 모든 VALIDATE는 --summary-csv <round_dir>/artifacts/benchmark.csv를 추가합니다.
스키마 범위: 위 열은 GEMM-클래스 전용입니다(M,N,K 차원, Forward/Backward TFLOPS, out_snr/da_snr/db_snr). 비-GEMM 연산의 경우 label, Check, *_stddev 규칙은 유지하되, GEMM 전용 열을 primary_metric에 필요한 열로 대체하십시오 — 예를 들어 메모리 집약적 연산(위 "최적화 점수 측정" 참조)은 TFLOPS 대신 Forward GB/s / Backward GB/s를 사용하고, 단일 출력 연산은 out_snr/da_snr/db_snr를 자체 정확성 메트릭으로 대체합니다. 어떤 스키마를 선택하든 BASELINE에서 고정하고, 모든 라운드에서 바이트 단위로 동일하게 유지하며, 사용하는 CSV 리더(구성된 경우 mcp__turbo__parse_bench_csv 매핑, 그렇지 않으면 직접 csv.DictReader)를 일치하도록 업데이트하십시오 — per-shape 회귀 게이트는 정확한 열 이름에 의존합니다.