# 무인 실행 — 3090 머신

주말에 손 못 대는 상황에서 **베어 머신 → 학습 완료**까지 한 번에 돌리는 절차.

전체 5~8시간. 멈춰도 알아서 이어간다.

---

## 퇴근 전 — 3단계

### 1. HF 토큰 옮기기

**자동화할 수 없는 유일한 부분이다.** 데이터셋에 게이트가 걸려 있고
수락은 브라우저에서 해야 한다. 다만 **수락은 계정 단위**라 이미 수락한 계정의
토큰만 옮기면 된다.

기존 머신(3060)에서 토큰 확인:

```powershell
type $env:USERPROFILE\.cache\huggingface\token
```

3090 머신 WSL에서:

```bash
mkdir -p ~/.cache/huggingface
echo hf_xxxxx > ~/.cache/huggingface/token
```

아직 어느 계정으로도 수락한 적이 없다면 브라우저에서 1회:
https://huggingface.co/datasets/gwxgrxhyz/SUM-Parts → 로그인 → CC BY-NC 4.0 수락

### 2. 클론 + 사전점검

```bash
git clone https://gitea.hmac.kr/kimminsung/sum-parts-test.git
cd sum-parts-test
bash scripts/test_preflight.sh
```

**`preflight OK` 가 나와야 한다.** 확인하는 것:

| 항목 | 실패하면 |
|---|---|
| `git` `curl` `python3` `tar` | 설치 필요 |
| `nvidia-smi` + GPU 인식 | WSL 드라이버 문제 — 여기서 해결하고 가야 함 |
| `$HOME` 여유 35 GB | 공간 확보 |
| HF 토큰 + 게이트 통과 | 위 1번 |

**여기서 실패한 채로 나가면 주말을 날린다.** 오래 걸리는 단계는 전부 이 뒤에 있다.

### 3. 실행

```bash
setsid nohup bash scripts/keepalive.sh > ~/keepalive.out 2>&1 &
```

터미널을 닫아도, 로그아웃해도 계속 돈다.
(`wsl --shutdown`이나 Windows 재부팅은 못 버틴다 — WSL 안에서 도는 건 다 마찬가지다.
그 경우 월요일에 같은 명령을 다시 치면 중단 지점부터 이어간다.)

---

## 월요일 확인

```bash
cat ~/sum-parts/runs/run_all/STATUS
```

```
state    : DONE
phase    : done
cfg      : pointvector-xl
voxel_max: 64000
```

`state`가 볼 값이다:

| state | 뜻 |
|---|---|
| `DONE` | 완료 |
| `running` / `retrying` | 진행 중 |
| `FAILED` | 재시도로 안 고쳐지는 문제 — `note` 줄에 원인 |

로그:

```bash
tail -80 ~/sum-parts/runs/run_all/run.log      # 전체 진행
cat ~/sum-parts/runs/run_all/keepalive.log     # 재기동 이력
bash scripts/check_training.sh                 # 학습 상세
```

결과:

```bash
cat ~/sum-parts/runs/coarse_eval/coarse.txt    # 4클래스 통합 성적 ← 핵심
```

---

## 멈춰도 계속 도는 구조

3중으로 감싸져 있다.

| 층 | 담당 | 동작 |
|---|---|---|
| `keepalive.sh` | 프로세스 전체 사망 | VM 재시작·OOM kill 후 재기동 (최대 40회, 90초 간격) |
| `run_all.sh` | 단계 실패 | 지수 백오프 재시도 (단계당 4회, 60→120→240초) |
| `train_watchdog.sh` | 학습 크래시 | 최신 체크포인트에서 재개 (최대 8회) |

**전 단계가 멱등이라 처음부터 다시 돌려도 안전하다.**
conda 환경·소스 clone·패치·다운로드 아카이브·학습 체크포인트를 각각 감지해서 건너뛴다.
학습은 `RESUME_CKPT`로 이어받으므로 재시작해도 epoch 1로 돌아가지 않는다.

### preflight만 재시도하지 않는다 — 의도적이다

HF 토큰 없음이나 GPU 미인식은 재시도해도 고쳐지지 않는다.
주말 내내 무의미하게 재시도하는 것보다 1분 만에 실패하고 `FAILED`를 남기는 게 낫다.

---

## voxel_max 자동 결정

논문 설정은 `voxel_max: 64000`이고 약 16.5 GB가 필요하다.
3060(12 GB)에서는 못 들어가서 24000으로 낮췄고, **그게 3090으로 옮기는 이유다.**

스크립트가 높은 값부터 내려가며 **실측**해서 실제로 들어가는 첫 값을 쓴다.

```
64000 → 48000 → 40000 → 32000 → 24000
```

> ⚠️ **WSL2에서 VRAM 초과는 OOM을 내지 않는다.**
> 드라이버가 호스트 RAM으로 흘려서 **조용히 완주한다 — 25~100배 느리게.**
> 12 GB 카드에서 `peak 15.47 GB`가 찍힌다. 그래서 "돌아가더라"를 믿지 않고
> peak 할당량으로 판정한다.
>
> 판별 보조 지표는 **전력**이다. 사용률 100 %인데 전력이 낮으면
> (3060 기준 60 W대) 연산이 아니라 PCIe 전송 대기다. 정상이면 140 W대.

---

## 실행 순서와 소요

| # | 단계 | 시간 | 재시도 |
|---|---|---|---|
| 1 | preflight | 10초 | ✗ 즉시 실패 |
| 2 | bootstrap (miniconda + 업스트림 clone) | 5분 | ✓ |
| 3 | conda 환경 (CUDA 11.8 + torch 2.0.1) | 20분 | ✓ |
| 4 | CUDA 확장 5종 빌드 | 25분 | ✓ |
| 5 | 소스 패치 3건 | 10초 | ✓ |
| 6 | 환경 검증 | 30초 | ✓ |
| 7 | 데이터 다운로드·전개 (5.3 → 18 GB) | 30분 | ✓ |
| 8 | split 정리 + 링크 | 10초 | ✓ |
| 9 | voxel_max 측정 | 10분 | ✓ |
| 10 | **학습 100 epoch** | **3~6시간** | ✓ 체크포인트 재개 |
| 11 | 평가 (val + test + 4클래스 통합) | 10분 | ✓ |

---

## 설정 변경

기본값으로 두면 된다. 바꾸려면 환경변수로:

```bash
CFG=pointnext-xl \
EPOCHS=50 \
VOXEL_CANDIDATES="64000 48000" \
  setsid nohup bash scripts/keepalive.sh > ~/keepalive.out 2>&1 &
```

| 변수 | 기본 | 뜻 |
|---|---|---|
| `CFG` | `pointvector-xl` | 모델 (논문 mIoU 70.0 %, 번들 최고이자 최속) |
| `EPOCHS` | `100` | |
| `VAL_FREQ` | `5` | 검증 주기 |
| `VOXEL_CANDIDATES` | `64000 48000 40000 32000 24000` | 높은 값부터 시도 |
| `STEP_RETRIES` | `4` | 단계별 재시도 |
| `MAX_RESTARTS` | `40` | keepalive 재기동 상한 |

---

## 중단

```bash
pkill -f keepalive.sh      # 감시자 먼저 — 안 그러면 다시 살린다
bash scripts/stop_training.sh
```

체크포인트는 남는다. 다시 켜면 이어간다.

---

## Claude는 필요 없다

이 스크립트들은 순수 bash다. Claude 승인이 필요 없고, 직접 돌리는 게 확실하다.

Claude로 감독시키고 싶다면 `--dangerously-skip-permissions`가 필요한데,
무인 실행에는 스크립트가 더 안전하다.

---

## 관련 문서

- [SETUP.md](SETUP.md) — 단계별 수동 실행 (문제 생겼을 때 하나씩 확인용)
- [docs/pipeline.html](docs/pipeline.html) — 전체 공정 정의
- [docs/SUM-Parts-검토노트.md](docs/SUM-Parts-검토노트.md) — 트러블슈팅 16건