라이선스 고지 Copyright © 2025 Advanced Micro Devices, Inc. All rights reserved.

이 프로젝트는 다음과 같은 조건 하에 MIT License를 따릅니다. 귀하는 소프트웨어의 복사본을 사용, 복사, 수정, 병합, 게시, 배포, 서브라이선스 부여 및/또는 판매할 수 있는 자유가 있습니다:

• 위의 저작권 고지 및 본 라이선스 고지는 소프트웨어의 모든 복사본 또는 상당 부분에 포함되어야 합니다.
• 소프트웨어는 상품성, 특정 목적에 대한 적합성 및 비침해에 대한 보증을 포함하되 이에 국한되지 않고, 명시적이든 묵시적이든 어떠한 종류의 보증 없이 "있는 그대로" 제공됩니다.

제3자 의존성(ROCm 라이브러리, vLLM, Triton, Magpie 등)은 각자의 라이선스를 따릅니다. 최종 사용자는 이 소프트웨어와 함께 사용되는 모든 의존성의 라이선스 약관을 검토하고 준수할 책임이 있습니다.

AI 에이전트(AI Agent) 고지 — 이 소프트웨어는 커널 최적화(kernel optimization)를 수행하기 위해 제3자 AI 코딩 에이전트를 오케스트레이션(orchestrate)합니다:

각 사용자는 독립적으로 자신의 자격 증명(credentials)을 확보해야 하며 각 제공자의 라이선스 및 이용 약관을 준수해야 합니다.

이 프로젝트는 어떠한 AI 모델이나 API에 대한 액세스도 포함, 번들링 또는 서브라이선스 제공하지 않습니다. 이러한 에이전트의 사용에는 제공업체에서 직접 청구하는 비용이 발생할 수 있습니다.

AMD ROCm 하드웨어를 위한 GPU 커널 최적화 작업을 LLM 에이전트에게 부여하는 강화학습 (RL) 훈련 환경입니다. 에이전트는 베이스라인 커널(baseline kernel), 관련 소스 코드 및 문서가 포함된 샌드박스(sandbox)를 전달받으며, 컴파일(compilation), 정확성(correctness) 및 런타임 속도 향상(runtime speedup)을 기준으로 점수가 매겨집니다.

baseline kernel → prompt constructor → LLM agent → grader (Magpie) → score + reinjection

Benchmark (벤치마크)— 병목 커널 (bottleneck kernels)을 식별하기 위해 모델을 엔드 투 엔드 (end-to-end)로 프로파일링합니다.
Identify (식별)— GPU 시간 기준으로 커널의 순위를 매기고 후보를 선택합니다.
Optimize (최적화)— LLM 에이전트 (LLM agent)가 output/<task_id>/solution.{py,hip} 경로에 최적화된 커널을 작성합니다.

Grade (채점)— Magpie가 컴파일, 정확성을 확인하고 속도 향상 (speedup)을 측정합니다.
Integrate (통합)— 속도 향상 임계값 (>1.05×)을 초과하는 커널은 site-packages에 핫패치 (hot-patched)됩니다.
Benchmark (final) (최종 벤치마크)— 패치가 적용된 상태로 E2E 벤치마크를 다시 실행하여 실제 처리량 (throughput) 개선을 측정합니다.
Score & Report (점수 및 보고)— 보상 (rewards)을 계산하고, 리더보드 (leaderboard)를 업데이트하며, 보고서를 생성합니다.

OS: Linux (Ubuntu 22.04+ 권장)
Python: 3.10+
Node.js: 18+ (에이전트 CLI 용)
System packages (시스템 패키지): git, curl, jq

GPU (선택 사항): ROCm 6.x+가 설치된 AMD Instinct GPU (실제 커널 채점을 위해 필요하며, CPU 전용 평가 시에는 필요하지 않음)

git clone <repo-url> Apex
cd Apex

사용할 에이전트 (agent)를 설치하세요:

# Claude Code
npm install -g @anthropic-ai/claude-code
claude login
...

bash setup.sh

이 단일 명령어가 모든 과정을 처리합니다:

CLI selection (CLI 선택)— Claude Code, Codex, Cursor Agent 또는 모두를 선택합니다.
Python venv (Python 가상 환경)— .venv/를 생성하거나 (또는 기존 환경을 재사용합니다).
Python dependencies (Python 의존성)— numpy, PyYAML, pytest, MCP 패키지, SDK 등을 설치합니다.
PyTorch for ROCm— ROCm 7.2 휠 (wheel) 인덱스에서 torch 및 torchvision을 설치합니다.
Triton— Triton 컴파일러를 설치합니다.
ROCm source repos (ROCm 소스 저장소)— AMD 커널 소스 코드를 tools/rocm/로 클론 (clone)합니다 (소스 탐색기 및 RAG 용, 선택 사항).
Documentation (문서)— RAG 서버를 위한 AMD 아키텍처 PDF를 다운로드합니다 (선택 사항).
MCP servers (MCP 서버)— 선택한 CLI와 함께 5개의 MCP 서버를 설치하고 등록합니다.
Magpie— 커널 평가 프레임워크를 tools/magpie/에 클론하고 설치합니다.

Skills (기술)— 에이전트가 13개의 도메인 특화 최적화 기술을 발견할 수 있도록 합니다.
— Cursor IDE가 .mcp.json을 통해 MCP 서버를 자동으로 발견할 수 있도록 워크스페이스 설정을 생성합니다.

bash setup.sh # 대화형 (선택 사항을 프롬프트로 요청)
bash setup.sh --non-interactive # CLI 자동 감지, 모든 기본값 수락
bash setup.sh --skip-downloads # ROCm 저장소 클로닝 + 문서 다운로드 건너뛰기
...

source .venv/bin/activate
export MAGPIE_ROOT=$(pwd)/tools/magpie
# 대화형 에이전트 세션 (Interactive agent session)
...

Apex/
├── workload_optimizer.py # 메인 파이프라인 CLI (Main pipeline CLI)
├── eval.py # 미니 평가 (CPU 전용, GPU 불필요)
...

전체 최적화 루프를 엔드 투 엔드 (end-to-end)로 실행합니다:

source .venv/bin/activate
export MAGPIE_ROOT=$(pwd)/tools/magpie
RESULTS=./results
...

# 1. 벤치마크 (또는 --skip-benchmark <기존-리포트-경로.json>)
python3 workload_optimizer.py benchmark -r $RESULTS -b $BENCH_CONFIG
# 2. 상위 병목 커널 식별 (Identify top bottleneck kernels)
...

전체 파이프라인을 실행하지 않고 단일 커널을 최적화합니다:

python3 workload_optimizer.py optimize-kernel \
-r ./results \
--kernel path/to/baseline_kernel.py \
...

독립적인 최적화를 위한 정확성 모드 (Correctness modes):

# PyTorch 참조 (기본값) — PyTorch 구현체와 대조하여 검증
--correctness-mode pytorch
# 라이브러리 테스트 — 기존 라이브러리의 유닛 테스트 스위트 실행
...

탐색적 최적화 (exploratory optimization)를 위해 에이전트를 직접 실행합니다:

# Claude Code
cd Apex && claude
# OpenAI Codex
...

이 프롬프트들은 테스트를 마쳤으며 엔드 투 엔드 (end-to-end)로 작동합니다. Apex 디렉토리에서 Claude Code CLI를 열고 프롬프트를 붙여넣으세요:

다음 설정으로 Qwen3.5 27B에 대한 전체 최적화 파이프라인을 실행하세요:
triton 커널만 사용, 상위 3개 병목 커널, 3회 최적화 반복, 
반복당 에이전트 턴 최대 25회, claude 에이전트 백엔드, 그리고 리더보드 활성화.
...

다음 설정으로 GPT OSS 20B에 대한 전체 최적화 파이프라인을 실행하세요:
triton 커널만 사용, 상위 3개 병목 커널, 3회 최적화 반복, 
반복당 에이전트 턴 최대 25회, claude 에이전트 백엔드, 그리고 리더보드 활성화.
...

MI355X에서 rms_norm Triton 커널을 최적화하십시오.
해결책을 output/ 디렉토리에 작성하고, 완료되면 채점하십시오. 점수 세부 내역을 표시하십시오.

에이전트는 CLAUDE.md와 AGENTS.md를 읽고, MCP 도구들을 발견하며, 프롬프트를 올바른 workload_optimizer.py 명령어로 변환합니다.

사용 방법:

# Apex 디렉토리에서 Claude Code를 실행한 후, 위의 프롬프트 중 아무거나 붙여넣으세요:
cd Apex && claude

동일한 직접 명령 (에이전트가 내부적으로 실행하는 명령):

# Qwen3.5 27B를 위한 전체 파이프라인
python3 workload_optimizer.py run \
-r ./results_qwen35_27b \
...

CPU 전용 작업(naive Python RMSNorm → NumPy)에 대해 전체 파이프라인을 실행합니다:

pip install -r requirements-eval.txt
python3 eval.py # Claude API 사용
python3 eval.py --dry-run # API 호출을 건너뛰고 사소한 해결책을 채점
...

python3 prompts/kernel_prompt.py --list # 모든 커널 작업 ID 목록 표시
python3 prompts/kernel_prompt.py --task-id llama-3-1-8b-instruct__rms_norm # 단일 프롬프트 출력
python3 prompts/kernel_prompt.py --all > prompts.jsonl # 모든 내용을 JSONL로 덤프
...

python3 graders/kernel_grader.py # output/ 내의 모든 커널 작업 채점
python3 graders/model_grader.py # 모델 수준 작업 채점

# 궤적(trajectory) 데이터를 RL (강화학습) 훈련 작업으로 내보내기
python3 workload_optimizer.py export-rl -r ./results --export-output-dir ./datasets
# SFT (지도 미세 조정) 웜스타트 쌍 포함
...

pytest tests/ -v
pytest tests/test_prompts.py -v # 프롬프트 테스트만 수행
pytest tests/test_graders.py -v # 채점기(grader) 테스트만 수행

--agent-backend claude # Claude Code 사용 (기본값)
--agent-backend codex # OpenAI Codex 사용
--agent-backend cursor # Cursor Agent 사용

파이프라인은 Docker 컨테이너 내부에서 E2E (End-to-End) 벤치마크를 실행합니다. vLLM 이미지를 재정의하려면:

--docker-image vllm/vllm-openai-rocm:v0.19.0

또는 환경 변수를 설정하십시오:

export APEX_VLLM_ROCM_IMAGE=vllm/vllm-openai-rocm:v0.19.0

반복 실행 시 약 30분이 소요되는 벤치마크를 건너뛰기 위해 E2E 베이스라인 결과를 캐싱하십시오:

--benchmark-cache-hours 4

run 서브커맨드(전체 파이프라인)를 사용할 때는, 최대 N개의 커널을 동시에 최적화하십시오 (에이전트 추론 (agent reasoning)은 API 바운드(API-bound)이며, GPU 채점 (GPU grading)은 직렬화됩니다):

python3 workload_optimizer.py run ... --parallel-kernels 2

참고: 독립형 optimize 서브커맨드는 이 플래그와 관계없이 커널을 순차적으로 처리합니다.

커널 난이도에 따라 서로 다른 모델을 할당하십시오:

--agent-model-simple claude-sonnet-4-20250514 \\
--agent-model-complex claude-opus-4-6

AST 기반 탐지는 벤치마크 결과를 조작하는 솔루션(sys.exit(), 하드코딩된 PASS, 조작된 타이밍 등)에 페널티를 부여합니다. 가속도 상한(speedup cap)을 설정하십시오:

--tampering-speedup-cap 1.0

score = compiled × 20 + correct × 100 + speedup_score(S)

여기서 S = baseline_time / optimized_time 입니다. 컴파일(compiled) 및 정답(correct) 솔루션만이 가속도(speedup) 구성 요소를 획득합니다.

Compiled (+20점): 솔루션이 예상되는 함수를 임포트(import)하고 정의함
Correct (+100점): 베이스라인(baseline)에 대해 모든 유닛 테스트(unit tests)를 통과함
Speedup (구간별 적용):

• S ≥ 1.0:
  100 + (S − 1) × 200 점 (예: 1.2× → 140, 2× → 300, 3× → 500)

• S < 1.0:
  max(0, 100 × S − 50) 점 (성능 저하 페널티)

• S ≥ 1.0:

reward = 0.7 × normalized_kernel_score + 0.3 × (optimized_tps / baseline_tps − 1)

커널 점수(Kernel score)는 420점(컴파일 + 정답 + 2배 가속)을 기준으로 [0, 1]로 정규화(normalized)됩니다. 모델 수준의 채점(grading)에는 전체 AMD GPU 환경이 필요합니다.

기본 타겟: AMD Instinct MI355X (gfx950 / CDNA4).

GPU는 rocm-smi가 사용 가능한 경우 자동으로 감지되며, 그렇지 않으면 gfx950으로 폴백(fallback)됩니다.

파이프라인이 최종 E2E 벤치마크를 위해 최적화된 커널을 통합할 때, 설치된 site-packages 내의 Python 모듈을 핫패치(hot-patch)합니다. 모든 패치는 벤치마킹 후에 복구됩니다.

지원 대상 (핫패칭):

aiter, vllm, sglang— Python/Triton.py

커널을 site-packages 내에서 교체할 수 있습니다. Triton JIT는 다음 호출 시 자동으로 재컴파일(re-compile)됩니다.

aiter HIP— 독립적인 .so 파일은 hipcc로 재컴파일하여 교체할 수 있습니다.

지원되지 않음 (소스 재빌드 필요):

시스템 C/C++ 라이브러리— hipBLASLt, rocBLAS, composable_kernel (CK), MIOpen, rccl은 개별적으로 핫패칭(hot-patch)할 수 없는 시스템 수준의 공유 라이브러리입니다.

모놀리식 (Monolithic)— vLLM, sglang, PyTorch HIP 커널은 단일 바이너리로 컴파일되므로 개별적으로 교체할 수 없습니다.

Apex는 에이전트가 도메인 특화 도구에 접근할 수 있도록 5개의 MCP 서버를 함께 제공합니다:

MCP 서버는 다음 환경에 대해 자동 구성됩니다:

Claude Code— 설정 중 claude mcp add를 통해 등록

Codex— 설정 중 codex mcp add를 통해 등록

Cursor IDE— 프로젝트 루트의 .mcp.json에서 자동 검색 (수동 등록 불필요)

에이전트가 커널을 최적화할 때 Apex는 두 계층의 프롬프트(prompt) 시스템을 사용합니다:

시스템 프롬프트 (System prompt) (workload_optimizer.py 내의 SYSTEM_PROMPT)는 에이전트의 역할과 제약 사항을 정의합니다:

• AMD ROCm 전문성을 갖춘 GPU 커널 엔지니어 페르소나
• MCP 도구 목록 및 각 도구의 사용 시점
• 스킬 경로 (에이전트가 도메인 지식을 위해 읽을 수 있는 13개의 SKILL.md 파일)
• Magpie를 통한 제출 전 비교(compare-before-submit) 워크플로 필수 적용
• 속도 향상(speedup) 보정 가이드 및 변조 방지 규칙

태스크 프롬프트 (Task prompt) (prompts/kernel_prompt.py 내의 KERNEL_PROMPT_TEMPLATE)

)은 다음과 같은 정보를 커널별로 구축합니다:

전체 파이프라인을 통해 실행할 때, 프롬프트는 다음과 같은 정보로 더욱 풍부해집니다:

기본 소스 코드 (Baseline source code) 마크다운 (markdown) 형식으로 인라인 삽입
프로파일링 데이터 (Profiling data) (GPU 시간 %, 바운드 유형 (bound type), 대역폭/연산 활용도 (bandwidth/compute utilization))
지식 베이스 통찰 (Knowledge base insights) 이전 최적화 실행 결과로부터 추출
정확성 참조 (Correctness reference) (PyTorch 참조 코드 또는 라이브러리 테스트 명령)

모든 태스크 프롬프트 미리보기:

python3 prompts/kernel_prompt.py --task-id llama-3-1-8b-instruct__rms_norm

이 커널들은 그라운드 트루스 레지스트리 (ground truth registry)에 명시적인 라이브러리 테스트 명령을 포함하고 있어, aiter 자체의 pytest 스위트와 비교 검증하기 위한 --correctness-mode library_test 모드를 사용할 수 있습니다: