Autoresearch: 5분 만에 배우는 AI 자율 학습 GPT 입문

상상해 보세요. 당신이 잠든 사이 AI가 스스로 하이퍼파라미터를 조정하고, 학습하며, 실험을 수행합니다. 아침에 일어나면 수많은 실험 로그와 개선된 모델을 마주하게 됩니다. 이것이 바로 autoresearch입니다. 이는 극도로 단순화된 자율 연구 프레임워크로, AI 에이전트가 직접 GPT 학습 스크립트를 수정하고, 실험을 실행하며, 결과를 평가하고, 자동으로 반복합니다. 당신이 할 일은 옆에서 지켜보는 것뿐입니다.

대상 독자

• AI 자율 연구 에이전트에 관심 있는 개발자
• 엔지니어링 관점에서 LLM 학습 과정을 이해하고 싶은 분
• AI가 스스로 발전하는 모습을 보고 싶은 분

핵심 의존성 및 환경

• Python 3.10+
• NVIDIA GPU (H100에서 테스트 완료)
• uv 패키지 관리자

프로젝트 구조

autoresearch/
├── prepare.py      # 고정 상수, 데이터 준비, 토크나이저 (수정 금지)
├── train.py        # 모델, 옵티마이저, 학습 루프 (에이전트가 수정하는 파일)
├── program.md      # 에이전트 지침 (사람이 수정하는 파일)
├── pyproject.toml  # 의존성
└── results.tsv     # 실험 기록 (자동 생성)

전체 저장소는 의도적으로 매우 심플하게 유지됩니다. 정말 중요한 파일은 단 3개뿐입니다. 이는 실험 범위를 제어하고 코드 차이(diff)를 쉽게 리뷰하기 위함입니다.

단계별 튜토리얼

1단계: uv 설치

먼저 uv 패키지 관리자를 설치합니다:

curl -LsSf https://astral.sh/uv/install.sh | sh

2단계: 의존성 설치

저장소를 복제하고 의존성을 설치합니다:

git clone https://github.com/karpathy/autoresearch.git
cd autoresearch
uv sync

이 단계에서 PyTorch 등 필요한 패키지들이 설치됩니다.

3단계: 데이터 및 토크나이저 준비

일회성 데이터 준비 스크립트를 실행합니다:

uv run prepare.py

학습 데이터를 다운로드하고 BPE 토크나이저를 학습시킵니다. 약 2분 정도 소요되며, 데이터는 ~/.cache/autoresearch/에 저장됩니다.

4단계: 베이스라인 학습 실행

기준점을 잡기 위해 먼저 수동으로 학습을 한 번 실행합니다:

uv run train.py

학습은 정확히 5분 동안 진행됩니다(시작 및 컴파일 시간 제외). 평가 지표는 val_bpb(검증 세트 바이트당 비트 수)이며, 낮을수록 좋습니다.

실행이 끝나면 다음과 같은 출력을 볼 수 있습니다:

---
val_bpb:          0.997900
training_seconds: 300.1
total_seconds:    325.9
peak_vram_mb:     45060.2
mfu_percent:      39.80
total_tokens_M:   499.6
num_steps:        953
num_params_M:     50.3
depth:            8

이 베이스라인이 우리의 시작점입니다. 이제 이를 AI에게 맡겨봅시다.

5단계: AI 에이전트 연결

실험을 위한 새 브랜치를 생성합니다:

git checkout -b autoresearch/mar15

결과 파일을 초기화합니다:

echo -e "commit\tval_bpb\tmemory_gb\tstatus\tdescription" > results.tsv

이제 AI 에이전트(Claude, Codex 등 무엇이든 가능하며, 모든 권한 설정을 확인하세요)를 시작합니다:

claude

그다음 에이전트에게 이렇게 말하세요:

Hi have a look at program.md and let's kick off a new experiment! let's do the setup first.

에이전트는 program.md를 읽고 실험 흐름을 이해한 뒤, train.py를 자율적으로 반복 수정하기 시작합니다.

6단계: 실험 루프 이해하기

에이전트는 다음 단계를 계속 반복합니다:

1. train.py 수정 — 아키텍처 변경, 하이퍼파라미터 튜닝, 옵티마이저 수정 등
2. Git commit — 변경 사항 저장
3. 실험 실행 — uv run train.py > run.log 2>&1
4. 결과 읽기 — grep "^val_bpb:\|^peak_vram_mb:" run.log
5. results.tsv 기록 — 실험 결과 기록
6. 의사 결정:
   • val_bpb 감소 → 커밋 유지 및 계속 진행
   • val_bpb 악화 → git reset 후 다른 아이디어 시도

program.md 핵심 지침 분석

program.md는 AI 연구원의 두뇌 역할을 합니다. 주요 포인트는 다음과 같습니다:

• 고정된 시간 예산 — 항상 5분으로 설정하여 실험 간 비교 가능성 확보
• 단일 파일 수정 — 오직 train.py만 수정 가능
• 새로운 의존성 추가 금지 — pyproject.toml에 있는 패키지만 사용
• 단순성 원칙 — 미세한 성능 향상을 위해 복잡성을 크게 높이는 것은 지양함

첫 번째 실험은 항상 비교 기준을 세우기 위한 베이스라인 실행이어야 합니다.

출력 형식

실험 결과는 탭으로 구분된 results.tsv에 기록됩니다:

commit	val_bpb	memory_gb	status	description
a1b2c3d	0.997900	44.0	keep	baseline
b2c3d4e	0.993200	44.2	keep	increase LR to 0.04
c3d4e5f	1.005000	44.0	discard	switch to GeLU activation

설명문 안에 쉼표가 들어갈 수 있으므로 쉼표가 아닌 **탭(tab)**을 사용해야 함에 유의하세요.

자주 발생하는 문제 해결(Troubleshooting)

1. 데이터 준비 미비

오류: 캐시 파일을 찾을 수 없다는 FileNotFoundError 발생 해결: uv run prepare.py를 먼저 실행하여 데이터 다운로드 및 토크나이저 학습을 완료하세요.

2. 메모리 부족 (OOM)

오류: CUDA out of memory 해결: 에이전트가 이를 감지하고 results.tsv에 "crash"로 기록해야 합니다. 일반적인 수정 방법:

• train.py의 TOTAL_BATCH_SIZE 축소
• 모델 레이어 수(DEPTH) 축소
• 더 짧은 시퀀스 길이 사용

3. 학습 시간 초과

오류: 10분 이상 실행됨 해결: 수동으로 프로세스를 종료(kill)하세요. 해당 실험은 "discard"로 기록하고 롤백합니다.

4. 에이전트가 작동하지 않음

문제: 에이전트가 파일만 읽고 실험을 실행하지 않음 해결: 에이전트를 올바른 디렉토리에서 시작했는지, 에이전트에게 쉘 명령 실행 권한이 있는지 확인하세요.

5. 베이스라인보다 계속 결과가 나쁨

문제: 모든 실험 결과가 비슷하거나 더 나빠짐 해결:

• 더 공격적인 아키텍처 변경 시도 (어텐션 메커니즘, 활성화 함수 등)
• 학습률(Learning Rate) 조정 — 기본값이 최적이 아닐 수 있음
• 다른 옵티마이저 시도 (Muon vs AdamW)

6. 플랫폼 호환성

오류: "No CUDA GPUs available" 해결: 이 코드는 NVIDIA GPU가 필요합니다. 다른 플랫폼은 다음 포크(fork) 버전을 사용하세요:

• autoresearch-macos — MacOS
• autoresearch-mlx — MacOS Apple Silicon
• autoresearch-win-rtx — Windows

심화 학습 방향

저사양 그래픽카드 활용 팁

H100이 없다면 다음과 같이 조정해 보세요:

1. TinyStories 데이터셋 사용 (도메인이 좁아 작은 모델로도 효과적임)
2. vocab_size를 8192에서 2048 또는 256(바이트 단위)으로 축소
3. prepare.py의 MAX_SEQ_LEN을 256 이하로 축소
4. TOTAL_BATCH_SIZE를 2**14(약 16K) 정도로 축소
5. WINDOW_PATTERN을 "L"로 설정하여 단순한 어텐션 사용

확장하기

익숙해진 후에는 다음을 시도해 보세요:

• program.md를 수정하여 서로 다른 역할을 가진 여러 에이전트 추가
• 다양한 데이터셋 시도
• 더 복잡한 평가 지표 도입
• 멀티 GPU 학습 구현 (prepare.py의 대폭 수정 필요)

관련 리소스

• 공식 저장소
• Karpathy 공지 트윗
• nanochat — 더 많은 플랫폼을 지원하는 상위 프로젝트
• 신경망 입문 "Dummy's Guide"