mukesh
cc1bbd0ab7
Move the GEMM + allreduce sweep/render logic out of scripts/ and tests/
into two self-contained eval benches so a user can regenerate every
result + figure with one command:
kernbench run --bench milestone-1h-gemm (MILESTONE_FAST=1 reuses JSON)
kernbench run --bench milestone-1h-ccl
- benches/milestone_1h_{gemm,ccl}.py: single home for each domain; the
run(torch) entry drives the sweeps and writes figures into
benches/1H_milestone_output/{gemm,ccl}/ (gitignored), then submits a
sentinel tensor to satisfy the run_bench contract.
- tests/gemm + tests/sccl helpers and scripts/gemm_sweep.py become thin
re-export/wrapper shims over the benches (single source preserved); the
pytest-only param builders + _run_distributed wrapper stay in the shim.
- eval-bench pattern: a bench may drive many configs + build its own
per-config engines (extends ADR-0045 D5; reverses ADR-0044 D1/D2).
ADR-0054 (EN+KO) records the design; ADR-0043/0044/0045 + CLAUDE.md CLI
Semantics amended; ADR INDEX regenerated. Verified: milestone benches run
clean (ok=True, all artifacts), full suite 67 passed, lang-pairs OK.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
6.9 KiB
ADR-0054: 마일스톤 평가 bench — 자기완결적 sweep + figure bench
Status
Accepted (2026-05-22).
ADR-0044(D1/D2)와 ADR-0045(D5)를 개정하고, ADR-0043/0044의 "로직이
scripts/ + tests/에 산다" 배치를 대체한다: GEMM/allreduce 평가
하니스가 이제 사용자가 실행하여 모든 결과 + figure를 재생성하는
자기완결적 bench가 된다.
Context
ADR-0043(allreduce 평가)과 ADR-0044(GEMM 평가)는 각 하니스를 sweep
(수동 scripts/ 드라이버, 또는 allreduce의 경우 parametrized 테스트
자체) + committed 데이터를 렌더링하는 figure 테스트로 분리했다.
따라서 sweep/render 로직은 scripts/gemm_sweep.py,
tests/gemm/_gemm_plot_helpers.py, tests/sccl/_allreduce_helpers.py에
존재했다.
마일스톤 요구사항("사용자가 하나의 bench를 실행해 모든 결과와 플롯을
생성하도록 allreduce + GEMM 평가를 리팩터")은 그 배치로는 충족 불가다:
bench는 production 코드이며 tests/를 import할 수 없다(ADR-0007 레이어
방향). 평가 로직은 bench에서 닿을 수 있도록 production으로 이동해야 했다.
선택한 home은 별도 kernbench.eval 패키지가 아니라 bench 모듈 자체다.
bench 파일은 임의의 모듈 레벨 코드를 가질 수 있으며, 하니스를 bench로
합치면 도메인당 파일 하나가 유지되고 패키지 레이어가 하나 줄어든다.
Decision
D1. 두 마일스톤 bench가 평가 로직을 보유
src/kernbench/benches/milestone_1h_gemm.py— GEMM shape×variant sweep- 세 figure renderer(
scripts/gemm_sweep.py+tests/gemm/_gemm_plot_helpers.py에서 이동).
- 세 figure renderer(
src/kernbench/benches/milestone_1h_ccl.py— distributed allreduce 드라이버, latency + buffer-kind sweep, topology diagram, FSIM 비교, 그리고 direct-launch 패리티 레퍼런스(tests/sccl/_allreduce_helpers.py에서 이동).
각 파일은 해당 도메인 평가 로직의 단일 home이다.
D2. "평가 bench" 패턴 (ADR-0045 D5 확장)
ADR-0045 D5는 bench를 단일 구성(single-SIP, 또는 ADR-0024 multi-SIP CCL 예외)으로 고정했다. 본 ADR은 세 번째 패턴을 추가한다:
- 평가 bench는 여러 구성을 구동하고 figure를 렌더링할 수 있다. 외부
run_bench엔진 대신 sweep 지점마다 자체GraphEngine/RuntimeContext를 빌드한다. - 그러면 외부 ctx에 제출된 handle이 없으므로, bench는 마지막에
sentinel 텐서(
torch.zeros((1, 1), …))를 제출하여run_bench의 "최소 한 번 제출" 계약(ADR-0045 D4)을 만족시키고 CLI가 0으로 종료되게 한다.
D3. 출력 위치
두 bench 모두 src/kernbench/benches/1H_milestone_output/{gemm,ccl}/에
쓴다(사용자 요청 — bench 옆 아티팩트). 디렉터리는 생성된 PNG/CSV/JSON만
보유하며(.py/__init__.py 없음), 따라서 eager-import audit(ADR-0045
첫 동작)이 무시한다 — pkgutil.iter_modules는 비-패키지 하위 디렉터리를
yield하지 않는다. committed docs/diagrams/ 아티팩트와 달리
git-ignore된다(요청 시 재생성 가능).
D4. GEMM 무거운 sweep — 기본은 fresh, MILESTONE_FAST로 재사용
milestone-1h-gemm은 기본적으로 전체 24-sim sweep을 실행한다(분 단위;
한 shape는 2048 tile). MILESTONE_FAST=1은 committed
docs/diagrams/gemm_sweep.json을 재사용하고 렌더링만 한다(초 단위). 이는
ADR-0044 D1/D2의 "무거운 sweep은 수동/slow 단계로 유지"를 뒤집는다:
bench 실행이 곧 재생성이다. slow 경로는 @pytest.mark.slow bench
테스트로 행사되고, fast 경로는 기본 실행된다.
D5. 테스트 + 스크립트는 thin re-export shim으로 재사용 (단일 home 유지)
기존 figure 테스트와 scripts/gemm_sweep.py 진입점은 유지되며 이제 bench
모듈을 재사용한다:
tests/gemm/_gemm_plot_helpers.py→ renderer +GEMM_SWEEP_JSON/GEMM_PLOTS_DIR/ROOT를kernbench.benches.milestone_1h_gemm에서 re-export.tests/sccl/_allreduce_helpers.py→ 드라이버 코어, config writer, sweep 상수, renderer, disk aggregator를kernbench.benches.milestone_1h_ccl에서 re-export하고, pytest 전용 조각은 로컬 유지:pytest.param행렬 (CONFIGS/_sweep_params/_bk_params)과 fixture 결합_run_distributed(monkeypatch.chdir+_drive_distributed) wrapper.scripts/gemm_sweep.py→ bench의run_sweep위 thin wrapper.
테스트가 bench 모듈을 import하는 것은 허용된다(테스트는 production 위에
위치, ADR-0007); 이는 전체 패키지 eager audit을 유발하며, 그것은 이미 매
kernbench 실행 시 동작한다. matplotlib는 renderer 내부에서 lazy import로
유지되어 audit의 startup 비용은 불변이다.
D6. 평면 모듈 네이밍 (benches/ 하위 폴더 없음)
1H_milestone…로 명명된 benches/ 하위 패키지는 불가능하다 — Python
패키지 이름은 숫자로 시작할 수 없다. 따라서 bench는 평면 모듈
milestone_1h_gemm.py / milestone_1h_ccl.py이며 bench 이름은
milestone-1h-gemm / milestone-1h-ccl(kebab-case, ADR-0045 D1에 따라
글자로 시작)이다.
Consequences
Positive
kernbench run --bench milestone-1h-gemm(또는…-ccl)이 도메인의 모든 결과 + figure를 한 명령으로 재생성한다 — 마일스톤 요구사항.- 평가 로직의 단일 소스(bench), shim을 통해 테스트와 스크립트가 재사용; 중복 없음.
- figure 테스트와
scripts/gemm_sweep.py는 변경 없이 계속 동작.
Negative / limitations
- 두 bench 파일이 크다(CCL 쪽은 distributed 드라이버, sweep, matplotlib 드로잉을 섞는다). 대부분 평가 하니스인 "bench"는 이례적이며, 본 ADR이 이를 정당화한다.
- 생성 아티팩트가 명시적 요청에 의해 source tree(
src/kernbench/benches/) 안에 산다; 커밋을 피하려 git-ignore. milestone-1h-ccl(및 기본milestone-1h-gemm)은 분 단위 소요 — on-demand 마일스톤 아티팩트에는 수용 가능, 일상 실행에는 아님.
Dependencies
- ADR-0007: 레이어 방향(테스트는 production을 import할 수 있으나 bench는 테스트를 import할 수 없는 이유).
- ADR-0043 / ADR-0044: 본 ADR이 bench로 이전하는 allreduce / GEMM 평가 하니스.
- ADR-0045: bench 모듈 계약; 여기 D2가 그 D5(single-device 규칙)를 평가-bench 패턴으로 확장하고, sentinel을 위해 D4(NO_REQUESTS)에 의존.
- ADR-0024: allreduce sweep이 구동하는 rank = SIP launcher.
Open questions
- GEMM theoretical 모델 상수(ADR-0044 D5)를 복사 대신 ADR-0033/0014에서 소싱해야 하는가? 본 ADR로는 불변.
build_overview_slides.py가 GEMM 막대를 네이티브로 그리는 대신 마일스톤 출력 PNG를 소비해야 하는가? 여전히 open(ADR-0044 D6 / Negative).