# 1단계 — 환경 구축 (GPU 불필요)

**GPU가 다른 작업에 물려 있어도 지금 돌릴 수 있다.**
오래 걸리는 작업(확장 빌드 50분 + 데이터 30분)이 전부 여기 들어 있다.

끝나면 [TRAIN.md](TRAIN.md)로 간다.

---

## 왜 나눴나

CUDA 확장 빌드는 **`nvcc` 컴파일이지 GPU 실행이 아니다.** 데이터 다운로드도 마찬가지다.
즉 카드가 남의 작업으로 바빠도 이 단계는 전부 끝낼 수 있다.

| 작업 | GPU 필요 | 시간 |
|---|---|---|
| miniconda 설치 · 업스트림 clone | ✗ | 5분 |
| conda 환경 · CUDA 11.8 · torch 2.0.1 | ✗ | 20분 |
| **CUDA 확장 5종 빌드** | ✗ (nvcc만) | 25분 |
| 소스 패치 3건 | ✗ | 10초 |
| import 검증 | ✗ | 30초 |
| 데이터 다운로드·전개 (5.3 → 18 GB) | ✗ | 30분 |
| split 정리 · 링크 | ✗ | 10초 |

**합계 약 80분.** 이걸 미리 해두면 GPU가 비는 순간 바로 학습에 들어간다.

---

## 전제

| 항목 | 필요 |
|---|---|
| OS | Windows + WSL2 (Ubuntu 22.04) 또는 네이티브 Linux |
| 디스크 | `$HOME`에 **35 GB 이상** |
| 도구 | `git` `curl` `python3` `tar` (sudo 불필요) |
| 계정 | HuggingFace 토큰 |

GPU는 **없어도 된다.** 있으면 정보로만 표시한다.

### 디스크 내역

| 항목 | 크기 |
|---|---|
| miniconda + 환경 | 12 GB |
| 업스트림 소스 | 1.7 GB |
| 데이터셋 (아카이브 포함) | 18 GB |

---

## 1. HF 토큰 — 유일한 수동 작업

데이터셋에 게이트가 걸려 있다. 수락은 브라우저에서만 되고 **자동화 불가**다.
다만 **수락은 계정 단위**라, 이미 수락한 계정의 토큰만 옮기면 된다.

기존 머신에서 값 확인:

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

이 머신 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/selfcheck.sh                    # 스크립트 무결성
RUN_DRYRUN=1 bash scripts/run_setup.sh       # 전제조건만 검사
```

**`preflight OK` 가 나와야 한다.** 검사 항목:

| 항목 | 실패하면 |
|---|---|
| `git` `curl` `python3` `tar` | 설치 |
| `$HOME` 여유 35 GB | 공간 확보 |
| HF 토큰 + 게이트 통과 | 위 1번 |

GPU는 검사하지 않는다 — 이 단계엔 필요 없다.

---

## 3. 실행

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

터미널을 닫아도 계속 돈다. 약 80분.

### 아키텍처가 8.6이 아니라면

확장은 특정 아키텍처로 컴파일된다. GPU를 조회할 수 없을 수도 있으니 **명시**한다.

| GPU | 값 |
|---|---|
| RTX 3060 / 3070 / 3080 / **3090** | `8.6` (기본값) |
| RTX 4090 | `8.9` |
| A100 | `8.0` |

3090이면 기본값 그대로 두면 된다. 다르면:

```bash
TORCH_CUDA_ARCH_LIST=8.9 setsid nohup bash scripts/keepalive.sh setup \
  > ~/keepalive-setup.out 2>&1 &
```

---

## 4. 확인

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

```
state    : DONE
phase    : done
arch     : 8.6
```

| state | 뜻 |
|---|---|
| `DONE` | 완료 → [TRAIN.md](TRAIN.md)로 |
| `running` / `retrying` | 진행 중 |
| `FAILED` | `note` 줄에 원인 |

로그:

```bash
tail -60 ~/sum-parts/runs/setup/setup.log
cat ~/sum-parts/runs/setup/keepalive.log
```

---

## 멈춰도 계속 도는 구조

| 층 | 담당 |
|---|---|
| `keepalive.sh setup` | 프로세스 전체 사망 시 재기동 (최대 40회) |
| `run_setup.sh` | 단계 실패 시 지수 백오프 재시도 (4회, 60→120→240초) |

**전 단계 멱등이다.** conda 환경·clone·패치·다운로드 아카이브를 각각 감지해서 건너뛴다.
처음부터 다시 돌려도 안전하다.

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

HF 토큰 없음은 재시도해도 안 고쳐진다. 무의미하게 반복하느니
1분 만에 실패하고 `FAILED`를 남기는 게 낫다.

---

## 중단

```bash
pkill -f keepalive.sh
pkill -f run_setup.sh
```

다시 켜면 중단 지점부터 이어간다.

---

## 다음

[TRAIN.md](TRAIN.md) — GPU가 필요한 학습 단계.
`SETUP_DONE` 마커가 없으면 실행을 거부한다.