ComputeEval은 정확성과 성능 측면에서 LLM이 생성한 CUDA 코드를 평가하기 위한 벤치마크입니다.

ComputeEval은 커널(kernels), 런타임 API, GPU 라이브러리를 아우르는 방대한 수작업 CUDA 프로그래밍 과제 세트를 제공하며, 모든 LLM의 솔루션을 생성, 컴파일 및 평가할 수 있는 도구도 함께 제공합니다. 각 문제에는 기능적 정확성을 위한 분리된 테스트 하네스(held-out test harness)가 포함되어 있으며, 선택적으로 기준선 솔루션 대비 GPU 실행 시간을 측정하는 성능 벤치마크를 포함할 수 있습니다.

이 벤치마크는 활발하게 개발되고 있으며 빈번한 업데이트가 이루어지고 있습니다. 새로운 문제, 도메인 그룹, 평가 기능은 매 릴리스마다 추가되므로 자세한 내용은 변경 로그(changelog)를 참고하십시오.

우리가 구축한 것, 배운 것, 그리고 나아갈 방향에 대한 주기적인 기술 글을 보려면 Engineering Diaries를 확인해 주십시오.

ComputeEval의 각 문제는 data 디렉토리 아래에 저장되어 있으며, 다음과 같은 구조를 가집니다:

CUDA-0/
├── problem-spec.yaml # 문제 메타데이터 및 설정
├── context/ # 테스트 대상 모델/시스템에 보이는 파일 (헤더, 헬퍼)
...

문제들은 도메인별로 **그룹(groups)**으로 구성됩니다. 각 문제는 정확히 하나의 그룹에 속하며, 이 그룹이 해당 문제가 테스트하는 CUDA API와 프로그래밍 개념을 결정합니다. 현재의 그룹은 다음과 같습니다:

솔루션을 생성할 때 --include 또는 --exclude를 사용하여 그룹별로 필터링할 수 있습니다. 전체 커버리지 맵과 도메인 백로그는 DOMAIN_MAP.md를 참고하십시오.

문제 사양(problem-spec.yaml)

이 파일은 각 문제의 메타데이터와 구성을 정의합니다:

task_id: "CUDA/0" # 고유 식별자 (일반적으로 디렉토리 이름과 일치)
date: "2024-12-19" # 문제 생성 날짜
problem_type: cuda_cpp # 유형: cuda_cpp 또는 cuda_python
...

특정 CUDA API를 요구하는 소스 참조가 필요한 예시:

source_references:
all: [cudaMalloc, cudaFree] # malloc과 free 둘 다 사용해야 함
any: [cudaMemcpy, cudaMemcpyAsync] # 복사 방법 중 최소 하나를 사용해야 함

ComputeEval은 시스템/모델이 생성 시점에 보는 것과 평가 시에 실제로 사용되는 것 사이에 엄격한 분리를 따릅니다:

시스템/모델이 보는 것 (생성 시간):

• Problem prompt
  • 작업을 설명하고 요구 사항을 기술합니다. context_files
• 헤더 파일: 인터페이스, 선택적 헬퍼 유틸리티 정의 build_command
  • 컴파일 지침 및 플래그 - 최소 CUDA 툴킷 버전 및 아키텍처 요구 사항

시스템/모델이 보지 못하는 것:

test_files

• 정확성을 검증하는 격리된 테스트 하네스 solution
• 참조 구현 디렉토리

평가 중:

• 임시 작업 공간(workspace)이 생성됩니다.
  context_files는 이 작업 공간에 작성되고, test_files도 작업 공간에 작성됩니다 (이제 가시적임).
• 모델이 생성한 솔루션 파일은 작업 공간에 작성됩니다.
• build_command가 실행되어 통합된 작업 공간을 컴파일합니다. - 컴파일에 성공하면, test_command가 실행됩니다. - 테스트 종료 코드가 통과/실패를 결정합니다.

이를 통해 모델이 테스트 케이스에 과적합(overfit)하는 것을 방지하고, 오직 문제 설명과 인터페이스 계약만을 기반으로 문제를 해결하도록 합니다.

리포지토리의 모든 문제는 알려진 좋은 참조 솔루션을 포함하고 있습니다. 우리의 CI 파이프라인은 다음을 통해 벤치마크의 무결성을 지속적으로 검증합니다:

• 각 문제의 참조 솔루션에 대해 평가 절차를 실행하는 것
• 빌드 명령어가 성공적으로 컴파일되는지 확인하는 것
• 테스트 하네스가 올바르게 실행되고 통과하는지 보장하는 것
• 문제 사양이 잘 구성되었는지 검증하는 것

이는 모든 배포된 문제가 해결 가능하며 올바르게 명시되었음을 보장합니다.

문제는 problem-spec.yaml 파일에 benchmark_command를 선언하여 성능 측정에 참여할 수 있습니다. 이를 통해 LLM이 생성한 솔루션을 실제 GPU 워크로드의 알려진 기준선(baseline)과 비교하는 것이 가능해집니다.

문제 사양에 benchmark_command와 선택적으로 timing_mode를 추가하세요:

# 기능적 정확성 (필수)
test_command: "./test.out"
# 성능 측정 (선택)
...

benchmark_command는 근본적으로 test_command와 다릅니다:

• validates correctness: 엣지 케이스, 경계 조건 및 오류 처리를 테스트하여 정확성을 검증합니다. (test_command)
• exercises a typical workload: 프로파일링하고 기준선 솔루션과 비교할 수 있는 현실적인 GPU 작업을 시뮬레이션합니다. (benchmark_command)

벤치마크 명령어는 솔루션이 모든 기능 테스트를 통과한 후에만 실행됩니다. 문제에 baseline_solution이 제공된 경우, 프레임워크는 속도 향상(speedup)을 baseline_time / solution_time으로 계산합니다.

timing_mode 필드는 성능 타이밍이 추출되는 방식을 제어합니다. 모든 모드에서 값은 밀리초(milliseconds) 단위로 보고됩니다.

# 기본값: 전체 애플리케이션 벽시계 시간
# (timing_mode가 생략된 경우 "process"로 기본 설정됨)
timing_mode:
...

region

timing mode는 NVTX(NVIDIA Tools Extension)를 사용하여 주석이 달린 코드 범위를 측정합니다. 문제 작성자는 벤치마크의 성능에 중요한 섹션을 NVTX push/pop 호출로 감싸고, 프로파일러가 해당 범위에 커널 실행 시간과 벽시계 시간을 속성으로 부여합니다.

C++ (NVTX는 CUDA Toolkit에 포함됨):

#include <nvToolsExt.h>
// 벤치마크 하네스에서:
nvtxRangePushA("matmul_benchmark");
...

Python (nvtx 패키지는 평가 컨테이너에 사전 설치됨):

import nvtx
# 컨텍스트 관리자로 사용:
with nvtx.annotate("matmul_benchmark"):
...

custom

timing mode는 벤치마크 프로그램이 자체 벽시계 시간을 보고하도록 합니다. 이는 타이밍에 대한 완전한 제어(예: CUDA 이벤트를 사용하거나, 워밍업 반복을 제외하거나, 호스트 측 로직의 시간을 측정하는 경우)가 필요할 때 유용합니다.

벤치마크 프로그램은 다음 형식을 일치하는 줄을 STDOUT에 출력해야 합니다:

COMPUTE_EVAL_TIME_MS: <값>

이 값은 밀리초(milliseconds) 단위여야 합니다. 여러 개의 일치하는 줄이 출력되는 경우(예: 워밍업 반복), 마지막 값이 사용됩니다.

C++:

cudaEvent_t start, stop;
cudaEventCreate(&start);
cudaEventCreate(&stop);
...

Python:

import torch
start = torch.cuda.Event(enable_timing=True)
end = torch.cuda.Event(enable_timing=True)
...

솔루션을 평가할 때, --profile_mode 플래그는 GPU 메트릭을 수집하는 데 사용되는 프로파일러를 제어합니다. 이는 custom 외의 모든 타이밍 모드에 적용됩니다.

운영 환경(production use)에서 ComputeEval은 문제를 **데이터팩(datapacks)**으로 배포합니다. 데이터팩은 버전 관리되고 불변하며 압축된 tarball(.tar.gz) 형태로 저장됩니다:

data/releases/
├── 2025-1-problems.tar.gz
├── 2025-2-problems.tar.gz
...

각 데이터팩은 다음을 포함합니다:

• 릴리스 버전, 생성 타임스탬프, 문제 개수 및 무결성 해시가 포함된 metadata.json 또는 problems.jsonl
• 각 문제/해결책을 나타내는 한 줄의 JSON 객체인 solutions.jsonl

데이터팩 내의 문제는 디렉터리가 아닌 JSON 객체로 직렬화됩니다. 각 문제는 다음을 포함합니다:

• problem-spec.yaml의 모든 필드
• 임베디드된 context_files ( {path, content} 객체 목록)
• 임베디드된 test_files (평가 전용으로 보류됨)

이 형식은 다음을 제공합니다:

불변성(Immutability) - 릴리스된 벤치마크는 절대 변경되지 않습니다
무결성(Integrity) - MD5 해시로 문제의 일관성을 검증합니다
이식성(Portability) - 배포하기 쉬운 자체 포함 아카이브입니다
버전 관리(Versioning) - 릴리스 간 명확한 분리가 가능합니다

ComputeEval은 지속적 배포 모델(continuous delivery model)을 따릅니다. 새로운 문제와 개선 사항은 버전이 지정된 데이터팩으로 정기적으로 릴리스됩니다.

저희는 모든 이전 릴리스를 영구적으로 지원할 것을 약속드립니다. 모델 개발자는 다음을 위해 모든 릴리스 버전을 대상으로 벤치마크를 수행할 수 있습니다:

• 고정된 기준선(baseline) 대비 시간 경과에 따른 진행 상황 추적

• 공개된 벤치마크와 결과 비교

• 평가 결과의 재현성 보장

• Python 3.10 이상

• NVIDIA GPU 및 CUDA Toolkit 12 이상 (평가용)

PyPI에서 릴리스된 패키지를 설치하세요:

pip install nvidia-compute-eval

또는 소스 체크아웃에서 개발 목적으로 사용할 경우, uv를 이용해 설치하세요:

uv sync

코드 품질을 위한 pre-commit 훅을 설정하세요:

uv sync --group dev
uv run pre-commit install

LLM에 질의하려면 먼저 해당 서비스에서 API 키를 발급받아야 합니다.

ComputeEval을 NVIDIA가 호스팅하는 모델과 함께 사용하려면 build.nvidia.com에서 API 키가 필요합니다.

• build.nvidia.com으로 이동

• 계정으로 로그인

• 호스팅된 모델 호출에 충분한 크레딧이 있는지 확인

• 원하는 모델로 이동하여 클릭

• Get API Key를 클릭

• 생성된 API 키 복사

• 환경 변수로 내보내기:

export NEMO_API_KEY="<your-nvidia-key>"

OpenAI 문서를 따르고, 다음을 실행하세요:

export OPENAI_API_KEY="<your-openai-key>"

Anthropic 문서를 따라, 다음을 실행하세요:

export ANTHROPIC_API_KEY="<your-anthropic-key>"

참고: 이 저장소는 기계가 생성한 CUDA 코드를 실행합니다.
코드가 악성일 가능성은 낮지만, 여전히 잠재적인 위험을 초래할 수 있습니다. 따라서 모든 코드 실행에는 --mode 플래그를 명시적으로 docker 또는 local로 설정해야 합니다.
생성된 코드를 실행하여 보안 위험을 최소화하려면 Docker 모드나 샌드박스 환경(예: 가상 머신) 사용을 강력히 권장합니다.

NVIDIA가 호스팅하는 모델을 사용하여 솔루션을 생성하려면:

uv run compute_eval generate_samples \
--release=2026-1 \
--base_url=https://integrate.api.nvidia.com/v1 \
...

참고: 사전 설정된 NIM 모델을 사용할 때는 NEMO_API_KEY 환경 변수를 설정해야 합니다.
이것은 다음 작업을 수행합니다:

• 2026-1 릴리스 데이터 패키지에서 문제를 읽음
• openai/gpt-oss-120b 모델을 사용하여 문제당 3개의 솔루션을 생성하고 모든 솔루션을 다음 위치에 작성함:
  2026-1-openai-gpt-oss-120b-solutions.tar.gz

사용 가능한 모델 목록은 NVIDIA NIM Model Catalog에서 확인할 수 있습니다.

OpenAI와 호환되는 API 엔드포인트를 가진 모델의 경우:

uv run compute_eval generate_samples \
--release=2026-1 \
--model=gpt-5 \
...

참고: OPENAI_API_KEY를 설정하세요

사용자 정의 OpenAI 호환 엔드포인트를 사용할 때 환경 변수입니다.

이것은 다음을 수행합니다:

• 2026-1 릴리스 데이터 패크에서 문제를 읽습니다.
• gpt-5 모델을 사용하여 문제당 3개의 솔루션을 생성합니다.
• 모든 솔루션을 2026-1-gpt-5-solutions.tar.gz에 작성합니다.

편의를 위해 YAML 설정 파일을 사용할 수도 있습니다:

# config.yaml
release: 2026-1
model: gpt-5
...

uv run compute_eval generate_samples --config_file=config.yaml

CLI 인수가 설정 파일 값을 재정의합니다.

솔루션을 생성한 후(위 예시 참조), 다음을 사용하여 평가합니다:

uv run compute_eval evaluate_functional_correctness \
--release=2026-1 \
--solutions_datapack=2026-1-gpt-5-solutions.tar.gz \
...

보안 참고: 평가를 실행하려면 반드시 --mode=docker (또는 --mode=local)를 전달해야 합니다. '평가 참여 규칙(Evaluation Rules of Engagement)' 섹션에 설명된 바와 같이, 이는 신뢰할 수 없는 모델 생성 코드를 실행하므로 적절한 샌드박싱을 사용해야 합니다. Docker 모드가 권장됩니다.

이것은 다음을 수행합니다: