diff --git a/README.md b/README.md index 2d41090..4da35b3 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,8 @@ | 경로 | 내용 | |---|---| -| [SETUP.md](SETUP.md) | **새 머신에서 시작하는 절차** — 여기부터 | +| [RUN.md](RUN.md) | **무인 실행 — 명령 하나로 학습까지. 여기부터** | +| [SETUP.md](SETUP.md) | 단계별 수동 실행 (문제 생겼을 때 확인용) | | [docs/pipeline.html](docs/pipeline.html) | 6단계 공정 정의 (브라우저로 열 것) | | [docs/SUM-Parts-검토노트.md](docs/SUM-Parts-검토노트.md) | 트러블슈팅 16건, 데이터 스키마 실측, 라이선스 | | [scripts/](scripts/) | 환경 구축 · 학습 · 평가 · 변환 스크립트 47개 | @@ -23,24 +24,27 @@ - **제약**: 저자가 학습 가중치를 공개하지 않아 직접 학습이 유일한 경로 - **VRAM**: 논문 설정 `voxel_max 64000`은 16.5GB 필요 → 12GB 카드 불가, 24GB 필요 -## 빠른 시작 +## 빠른 시작 (무인) ```bash -bash scripts/setup_env.sh -bash scripts/setup_pointnext.sh -bash scripts/patch_numpy_aliases.sh -bash scripts/patch_unlabeled_test.sh -bash scripts/patch_val_mode.sh -python scripts/verify_env.py # ALL OK 확인 +# 1. HF 토큰 (게이트는 계정 단위 — 이미 수락한 계정 토큰을 복사) +mkdir -p ~/.cache/huggingface && echo hf_xxxxx > ~/.cache/huggingface/token -bash scripts/download_data.sh all # HF 게이트 수동 수락 선행 -bash scripts/prepare_full_split.sh -bash scripts/link_data.sh +# 2. 사전점검 — OK 안 나오면 여기서 해결하고 갈 것 +bash scripts/test_preflight.sh -bash scripts/launch_overnight.sh pointvector-xl +# 3. 실행. 베어 머신 → 학습 완료까지 5~8시간, 멈춰도 이어간다 +setsid nohup bash scripts/keepalive.sh > ~/keepalive.out 2>&1 & ``` -자세한 것은 [SETUP.md](SETUP.md). +확인: + +```bash +cat ~/sum-parts/runs/run_all/STATUS +cat ~/sum-parts/runs/coarse_eval/coarse.txt # 4클래스 통합 성적 +``` + +자세한 것은 [RUN.md](RUN.md). ## 라이선스 diff --git a/RUN.md b/RUN.md new file mode 100644 index 0000000..eeeacf8 --- /dev/null +++ b/RUN.md @@ -0,0 +1,207 @@ +# 무인 실행 — 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건