# onpod — AI 에이전트 운영 매뉴얼

당신은 onpod이라는 GPU 클라우드에 접근할 수 있어요. 한국 서울 리전 GPU
(L4 / A100 / H100 / H200 / B200)를 시간 단위로 빌려 학습·추론을 돌릴 수 있어요.

## 셋업

1. CLI 바이너리가 PATH에 없으면 한 번만 설치합니다:
       curl -fsSL https://onpod.ai/install.sh | sh
2. 토큰 환경 변수를 export 하거나 onpod login을 실행하세요:
       export ONPOD_TOKEN="op_u_..."
       export ONPOD_URL="https://api.onpod.ai"   # 옵션, 기본값 동일
3. 검증:
       onpod whoami       # 200 + 본인 이메일이면 성공

## 멘탈 모델

- Pod = 가상 컴퓨터 1대 (= Docker 컨테이너 + GPU N장 + 로컬 디스크).
- 가격은 model × sku 매트릭스.
  sku = burst (분 단위 후불) / reserved (장기 잠금) / spot (할인·회수 가능).
- 켜둔 시간 = 비용. 일시정지하면 GPU 요금은 0, 디스크만 남아요.
- 모든 비용 발생 작업은 idempotent. 같은 요청을 재시도해도 중복 청구되지 않아요.

## 자주 쓰는 명령

자원 보기:
    onpod ls gpus                        모델별 가용 + 가격
    onpod pod ls                         내 Pod 목록 (--json 옵션)

Pod 생성 (가장 단순):
    onpod pod create --gpu h100_80gb:1 \
      --image pytorch/pytorch:2.6.0-cuda12.4-cudnn9-runtime

Pod 생성 (학습 잡):
    onpod pod create \
      --name train-llama \
      --gpu h100_80gb:8 \
      --image pytorch/pytorch:2.6.0-cuda12.4-cudnn9-runtime \
      --disk 200 \
      --env HF_TOKEN=hf_xxx \
      --env WANDB_API_KEY=... \
      --command "python -m torch.distributed.run --nproc_per_node=8 train.py"

Pod 생성 (vLLM 추론 서버, 30일 reserved):
    onpod pod create \
      --name vllm-1 \
      --gpu h100_80gb:1 \
      --image vllm/vllm-openai:latest \
      --port 8000 \
      --sku reserved --term-secs 2592000 \
      --env MODEL_NAME=meta-llama/Llama-3-8B-Instruct \
      --command "python -m vllm.entrypoints.openai.api_server --model \$MODEL_NAME --port 8000"

Pod 생명주기:
    onpod pod get <name>                 상세 상태 (JSON)
    onpod pod logs <name> --tail 200     스냅샷
    onpod pod logs <name> -f             follow (2s 폴링)
    onpod pod exec <name> -- nvidia-smi  컨테이너 안에서 명령 실행
    onpod pod pause <name>               GPU 해제, 디스크 보존
    onpod pod resume <name>              같은 호스트 새 lease로 재시작
    onpod pod migrate <name>             다른 호스트로 디스크째 이전
    onpod pod rm <name>                  영구 삭제 (디스크 wipe)

빌링:
    onpod bill summary                   이번 달 사용

## 안전 패턴 (AI 에이전트가 꼭 지킬 것)

1. 자원 확인 먼저. 새 Pod 만들기 전에 onpod ls gpus 로 가용 모델·가격을 확인.
2. 이름 충돌 시 409. onpod pod ls 로 먼저 확인하거나 고유 이름(UNIX timestamp
   suffix 등)을 쓰세요.
3. 에러 코드 의미:
   - 409 no_capacity      → 그 모델 가용 GPU 부족. --allow-preempt --wait 로
                            자동 폴백 (spot 회수 후 burst 슬롯 확보).
   - 429 quota_exceeded   → 사용자 active Pod 50개 제한 도달.
   - 429 preempt_cooldown → 5분 cooldown. 그대로 기다리면 됨.
   - 503 + Retry-After    → 헤더 값만큼 sleep 후 재시도.
4. 비용 의식. 학습 잡 끝나면 즉시 pod rm 또는 pod pause. 까먹지 마세요.
   파라미터 검색 같은 단발성 잡엔 spot (--sku spot)이 50%+ 저렴해요.
5. 체크포인트. pod pause / pod resume 은 컨테이너 entrypoint 를 재실행해요.
   학습 잡은 자체 체크포인트로 resume 가능한 --command 를 짜세요.
6. 포트 노출. --port 8000 을 주면 외부 IP:포트로 접근 가능. onpod pod get 의
   endpoints 필드에 URL 이 나와요.
7. 환경 변수. --env KEY=value 는 컨테이너 안에만 보입니다. 콘솔 UI엔 값을
   노출하지 않아요 (멀티 테넌트 누수 방지). 토큰·비밀번호 넣어도 안전.

## 흔한 워크플로

[7B 모델 학습 (1시간 미만)]
1. onpod ls gpus → H100 가용 확인.
2. onpod pod create --gpu h100_80gb:1 --image pytorch/... --command "...".
3. onpod pod logs <name> -f 로 모니터.
4. 학습 끝나면 onpod pod exec <name> -- aws s3 sync ./outputs s3://....
5. onpod pod rm <name>  (또는 pod pause 로 잔여 상태 보존).

[추론 서버 (장기)]
1. onpod pod create --sku reserved --term-secs 2592000 --port 8000 ...
2. onpod pod get <name> 으로 endpoint URL 확인.
3. 외부에서 그 URL로 요청.

[데이터 큰 잡 (수십 GB)]
1. --disk 500 정도로 충분히 잡기.
2. 다른 호스트로 디스크째 이전 가능: onpod pod migrate <name>.

## 출력 형식

기본은 사람용 표/요약. --json 플래그(또는 -o json)를 붙이면 JSON 출력 →
스크립트·다음 명령 입력으로 파이프 가능:

    POD_ID=$(onpod pod create --gpu h100_80gb:1 --image ... --json | jq -r .pod.id)
    onpod pod logs "$POD_ID" -f

## 추가 정보

- 전체 명령/플래그: onpod --help, onpod pod --help, onpod pod create --help.
- 가격·정책: onpod ls gpus, onpod pod policy <name>.
- 사용 내역: onpod bill summary.
- 매뉴얼 최신본: onpod manual 또는 curl https://api.onpod.ai/v1/manual.
- 문서 사이트: https://docs.onpod.ai

이 매뉴얼을 컨텍스트에 두고, 사용자 요청을 위 명령으로 변환해서 실행하세요.
실패하면 에러 메시지를 그대로 사용자에게 보여주지 말고, 위 "에러 코드 의미"
대로 해석해서 다음 조치를 제시하세요.