> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloud.vessl.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# autoresearch를 병렬로 돌리기

> VESSL Cloud 배치 잡으로 karpathy/autoresearch를 K개 병렬 실행해요. 캐시 볼륨 한 번 채우고, 매 라운드 K배의 실험을 돌려요.

[karpathy/autoresearch](https://github.com/karpathy/autoresearch)는 "AI 에이전트가 밤새 LLM 학습 실험을 돌린다"는 실험이에요. 원래 루프는 순차적이에요. 로컬 GPU 한 대에서 한 번에 한 실험씩만 돌릴 수 있어요.

이 가이드는 같은 워크로드를 VESSL Cloud에서 돌리는 방법을 다뤄요. 매 실험을 배치 잡 하나로 만들면, K개를 동시에 팬아웃(fan-out)할 수 있어요. 이 예제는 에이전트 기반 학습 루프 어디에든 다시 쓸 수 있는 VESSL Cloud 패턴 세 가지를 보여줘요.

* **Object storage 볼륨 하나를 공유 read-only 캐시로 사용해요.** 실험마다 데이터 준비를 다시 하지 않아도 돼요.
* **Workspace 대신 배치 잡으로 실험을 제출해요.** 스크립트로 자동화할 수 있고, 에이전트가 GPU를 점유하고 있을 필요가 없어요.
* **K-way fan-out으로 N개 실험 사이클의 실제 소요 시간(wall time, 사용자가 실제로 기다리는 시간)을 약 N/K로 압축해요.**

전체 코드(에이전트 프로그램, 헬퍼 스크립트, 결과 노트북)는 [autoresearch 쿡북 레시피](https://github.com/vessl-ai/vessl-cloud-cookbook/tree/main/autoresearch)에 있어요. 이 페이지에서는 VESSL Cloud 워크플로우를 중심으로 설명해요.

<div>
  <Frame>
    <img src="https://mintcdn.com/dora/LUWzC5lx5RwOccfw/images/autoresearch-architecture.png?fit=max&auto=format&n=LUWzC5lx5RwOccfw&q=85&s=ba53fc45165ca8f14a8664432b9df444" alt="karpathy의 순차 루프와 VESSL Cloud의 K-병렬 fan-out을 비교한 다이어그램" width="857" height="570" data-path="images/autoresearch-architecture.png" />
  </Frame>

  <small>위: karpathy 원본(로컬 GPU 1대, 순차 루프). 아래: VESSL Cloud 변형(K개 Job 병렬, 공유 read-only 캐시 볼륨 마운트).</small>
</div>

## 클라우드에서는 왜 실험이 빨라질까요

karpathy의 루프는 단순해요. 에이전트가 코드를 고치고, 약 5분 학습한 뒤, `val_bpb`를 확인해서 좋아졌으면 변경을 유지하고 아니면 되돌려요. 그리고 반복해요. 로컬 GPU 한 대에서는 병목이 GPU 성능이 아니라 순서예요. 한 번에 한 실험씩만 돌아가니까요.

VESSL Cloud에서는 같은 코드가 배치 잡으로 돌아가요. Job 1개가 약 10 GB 데이터 캐시를 담은 Object storage 볼륨을 마운트하고, 시작 준비 3-4분(이미지 다운로드, 의존성 설치, JIT(Just-In-Time) 컴파일)을 거쳐 약 5분 학습하고 `val_bpb`를 로그에 남겨요.

여기서 차이가 생겨요. Job끼리 독립이라 한 번에 K개를 같이 던질 수 있거든요. H100 SXM ×1에서 순차로 돌리면 16개 실험 사이클이 약 2시간 걸려요. K=4로 fan-out하면 같은 16개를 약 40분 만에 끝낼 수 있어요. 비용은 똑같은데 처리량(throughput)이 약 5배가 되는 셈이에요. 컴퓨트가 빨라진 게 아니라, 스케줄링이 한꺼번에 펼쳐지는 거예요.

<Info>
  **숫자로 풀어보면.** H100 한 대로 순차 autoresearch를 돌리면 시간당 약 12개 실험이 나와요. VESSL에서 K=4 fan-out으로 돌리면 라운드마다 4개를 동시에 던지고 가장 늦게 끝나는 Job을 기다리니, 전체로 보면 시간당 약 28개예요. 한도가 "GPU를 확보할 수 있느냐"에서 "내가 한꺼번에 몇 개까지 돌리겠다고 할 거냐"로 옮겨와요.
</Info>

## 사전 준비

* 크레딧이 충전된 VESSL Cloud 계정([가입하기](https://cloud.vessl.ai/~/signup))
* **H100 SXM ×1**(또는 A100 SXM ×1, 아래 수치는 H100 기준)에 접근 가능한 조직
* 인증된 `vesslctl` (`vesslctl auth status`)
* Git, Python 3.11 이상, 그리고 셸 명령어를 실행할 수 있는 코딩 에이전트(Claude Code, Codex, Cursor 등)

<Tip>
  VESSL Cloud가 처음이라면 [멤버 퀵스타트](/ko/guides/get-started/quickstart-user)를 먼저 완료해서 계정, 결제, 스토리지를 설정해 주세요.
</Tip>

## 레시피 세팅하기

<Steps>
  <Step title="Object storage 볼륨에 공유 데이터 캐시 만들기">
    루프의 모든 실험이 같은 약 10 GB 사전학습 데이터를 읽어요. Object storage 볼륨에 한 번 채워두면, 그 뒤로는 모든 Job이 같은 캐시를 read-only로 마운트해요.

    ```bash theme={null}
    vesslctl volume create \
      --name autoresearch-cache \
      --storage <object-storage-slug> \
      --teams <team-slug>

    vesslctl volume list
    export AUTORESEARCH_CACHE_VOLUME=objvol-...
    ```

    Object storage 슬러그(slug, 고유 식별자)는 `vesslctl storage list`로 찾을 수 있어요. 전체 생성 과정은 [볼륨 만들기](/ko/member/volume/create)를 참고해 주세요.

    <Note>
      이 시나리오에서 Object storage가 알맞은 이유는 읽기 속도는 느리지만 비용이 저렴하고, 초기 적재 후 데이터가 read-only이기 때문이에요. 학습 데이터 핫 패스(hot path, 매번 빠르게 읽어야 하는 경로)에는 빠른 스토리지가 필요하지만, 한 번 채워서 수천 번 재사용하는 캐시에는 공유성이 더 중요해요.
    </Note>
  </Step>

  <Step title="데이터 준비 한 번만 돌리기">
    쿡북을 로컬에 클론하고 데이터 준비 스크립트를 실행해 주세요. FineWeb-Edu 데이터 샤드(shard, 분할 단위)를 받아서 볼륨에 써요.

    ```bash theme={null}
    git clone https://github.com/vessl-ai/vessl-cloud-cookbook.git
    cd vessl-cloud-cookbook/autoresearch
    bash batch-job/prep.sh
    ```

    `prep.sh`는 캐시 볼륨을 마운트한 일회성 배치 잡을 제출해서 `prepare.py`를 실행해요. 이 Job이 끝난 뒤로는 다음에 제출하는 모든 학습 Job이 다운로드 단계를 건너뛰어요.

    <Tip>
      데이터 자체가 바뀌지 않는 한 `prep.sh`는 한 번만 돌리면 돼요. 에이전트 루프는 이 단계 이후로 캐시를 다시 건드리지 않아요.
    </Tip>
  </Step>

  <Step title="배치 잡 한 개로 연결 확인하기">
    에이전트 루프를 시작하기 전에, 직접 배치 잡 하나를 제출해서 레시피가 제대로 동작하는지 확인해 주세요.

    ```bash theme={null}
    git checkout -b autoresearch/sanity-check
    bash batch-job/submit.sh > run.log 2>&1
    grep "^val_bpb:\|^peak_vram_mb:" run.log
    ```

    `submit.sh`는 브랜치를 푸시하고, 캐시 볼륨을 마운트한 채로 `vesslctl job create`를 호출하고, Job이 종료될 때까지 폴링(polling, 주기적으로 상태를 조회)하고, 로그를 로컬로 가져와요. `run.log`에 `val_bpb`가 찍혀 있다면 레시피가 제대로 연결된 거예요.
  </Step>

  <Step title="K개 병렬 실험으로 fan-out 하기">
    배치 잡 하나가 잘 돌아가면, 에이전트가 K개 후보를 동시에 제출할 수 있어요. 쿡북에 두 개 헬퍼 스크립트가 들어 있어요.

    | 스크립트                                     | 하는 일                                                            |
    | ---------------------------------------- | --------------------------------------------------------------- |
    | `batch-job/submit-async.sh`              | 배치 잡 하나를 제출하고 슬러그를 즉시 반환해요.                                     |
    | `batch-job/wait-jobs.sh slug1 slug2 ...` | N개 슬러그를 모두 종료될 때까지 폴링하고 각 Job의 `val_bpb`와 `peak_vram_mb`를 출력해요. |

    전형적인 "Mode B" 라운드는 이렇게 생겼어요.

    ```bash theme={null}
    SLUGS=$(for cfg in cfg1 cfg2 cfg3 cfg4; do
      git commit --allow-empty -m "try $cfg"
      bash batch-job/submit-async.sh
    done)

    bash batch-job/wait-jobs.sh $SLUGS
    ```

    4개의 배치 잡이 4개 GPU에서 동시에 돌아가요. 가장 늦게 끝나는 Job이 끝날 때 라운드도 끝나요.

    <Warning>
      모든 병렬 라운드가 가용 GPU 풀 전체를 쓰기를 원하지 않는다면, VESSL Cloud의 동시 실행 한도를 미리 설정해 주세요. 이 스크립트는 한도를 직접 강제하지 않아요. 클라우드는 제출된 Job을 그대로 스케줄링해요.
    </Warning>
  </Step>
</Steps>

## 실제 연구 사이클은 이렇게 돼요

H100 SXM ×1(deneb-kr)에서 16개 실험을 4라운드 Mode B로(K=4) 돌린 실제 결과가 레시피에 같이 들어 있어요. 전체 데이터는 [`results.example.tsv`](https://github.com/vessl-ai/vessl-cloud-cookbook/blob/main/autoresearch/results.example.tsv)에 있고, 요약 내용은 다음과 같아요.

| 라운드 | 에이전트가 시도한 노브(knob, 조절 변수)                        | 최고 `val_bpb` | 결과                         |
| --- | ------------------------------------------------ | ------------ | -------------------------- |
| 1   | `EMBEDDING_LR`, `WEIGHT_DECAY`, `WINDOW_PATTERN` | 1.0107       | 베이스라인 못 넘김                 |
| 2   | `MATRIX_LR 0.04 → 0.05`                          | 1.0081       | 첫 개선                       |
| 3   | `TOTAL_BATCH_SIZE 2^19 → 2^18`                   | 0.9986       | 작은 배치가 더 나음                |
| 4   | 라운드 3 위에 `DEPTH 8 → 10`                          | **0.9856**   | karpathy 레퍼런스 0.9979를 뛰어넘음 |

총 비용은 **약 \$5.10**이에요(실험 16개 × 약 \$0.33, 시간당 \$2.39 H100 기준). 실제 소요 시간은 **약 40분**이에요(4라운드 × 약 10분, 라운드당 K=4 Job). 로컬 H100 한 대에서 순차로 돌리면 같은 작업이 약 2시간 걸려요.

<div>
  <Frame>
    <img src="https://mintcdn.com/dora/LUWzC5lx5RwOccfw/images/autoresearch-progress.png?fit=max&auto=format&n=LUWzC5lx5RwOccfw&q=85&s=5d9a1df0d3bbfc4c1ed42b6195b3b07a" alt="K=4 fan-out으로 16개 실험을 4라운드 돌린 진행 차트, 베이스라인 대비 라운드별 최저 val_bpb 추이" width="2378" height="1180" data-path="images/autoresearch-progress.png" />
  </Frame>

  <small>실제 16개 실험의 라운드별 최저 `val_bpb` 추이. 베이스라인(1.0107)에서 시작해 라운드 4에서 0.9856으로 karpathy 레퍼런스(0.9979)를 넘었어요.</small>
</div>

<Tip>
  분석 노트북([`analysis.ipynb`](https://github.com/vessl-ai/vessl-cloud-cookbook/blob/main/autoresearch/analysis.ipynb))은 쿡북 레시피에 들어 있어요. 내 `results.tsv`를 노트북에 넣고 차트를 다시 그려보세요.
</Tip>

## 알아두면 좋은 것들

* **Job 1개당 오버헤드.** Job 1개는 학습 5분 외에 시작 준비 3-4분이 더 들어요(이미지 다운로드, `uv sync` 또는 torch 재설치, `train.py` 컴파일). 순차 모드는 시간당 약 7개, 로컬 GPU는 시간당 약 12개 실험을 돌려요. 클라우드의 우위는 Job 1개의 속도가 아니라 K-way fan-out에서 와요.
* **브랜치 운영.** 에이전트는 `autoresearch/<tag>` 브랜치 위에서만 동작하고 origin으로 강제 푸시(force-push)해요. 같은 태그에 두 에이전트를 동시에 붙이지 마세요. 두 번째 에이전트가 첫 번째의 커밋을 덮어써요. 에이전트 세션마다 다른 태그를 쓰는 걸 권장해요(예: `opt-may7`, `arch-may7`).
* **비용은 기본적으로 무제한이에요.** 루프가 폭주하면 그대로 비용이 나가요. VESSL Cloud에서 일일 동시 실행 한도를 걸어두고, 걱정되면 `vesslctl billing show`로 사용량을 확인해 주세요.
* **GPU 선택.** 쿡북 기본값은 H100 SXM ×1(deneb-kr, 시간당 \$2.39)이에요. 더 저렴하게 돌리려면 `AUTORESEARCH_RESOURCE_SPEC`을 A100 스펙으로 바꿔주세요. 다만 non-Hopper GPU에서는 flash-attn이 대체 구현(fallback)으로 동작하기 때문에 karpathy 레퍼런스 수치와 직접 비교가 어려워요.

## 다음 단계

* **전체 레시피 읽어보기**: 코드, 에이전트 프로그램, 분석 노트북은 [vessl-ai/vessl-cloud-cookbook/autoresearch](https://github.com/vessl-ai/vessl-cloud-cookbook/tree/main/autoresearch)에 있어요.
* **여러 에이전트 동시에 돌리기**: 다른 연구 방향마다 N개 에이전트 세션을 다른 태그로 띄워 주세요. 에이전트당 K-way fan-out과 결합하면 라운드당 N × K개 실험을 돌릴 수 있어요.
* **내 루프에 패턴 적용하기**: submit/wait 스크립트는 범용이에요. `train.py` 자리에 단일 GPU 학습 엔트리포인트를 넣고, 캐시 볼륨에 내 데이터를 넣으면 같은 K-fan-out 패턴을 하이퍼파라미터 스윕(hyperparameter sweep), NAS(Neural Architecture Search), 다른 에이전트 기반 실험 루프에 그대로 쓸 수 있어요.
* **CLI에서 배치 잡 제출하기**: 전체 배치 잡 제출 흐름은 [`vesslctl job create`](/ko/cli/quickstart)을 참고해 주세요.