sum-parts-test/RUN.md

무인 실행 — 3090 머신

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

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

---

퇴근 전 — 3단계

1. HF 토큰 옮기기

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

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

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

3090 머신 WSL에서:

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

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

2. 클론 + 사전점검

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. 실행

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

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

---

월요일 확인

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

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

state가 볼 값이다:

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

로그:

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

결과:

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분	✓

---

설정 변경

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

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 재기동 상한

---

중단

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

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

---

Claude는 필요 없다

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

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

---

관련 문서

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