INSTALL.md

# 설치 가이드

## PyTorch 버전 제약 문제

**문제**: HF Spaces의 ZeroGPU는 PyTorch 2.0.0-2.2.0만 지원하지만, 로컬 환경에서는 최신 버전을 사용하고 싶습니다.

**해결책**: 환경별로 다른 requirements 파일 사용

---

## 방법 비교

| 방법 | 장점 | 단점 | 추천 |
|------|------|------|------|
| **requirements-local.txt** | 간단, 명확 | 수동 선택 필요 | ⭐⭐⭐ |
| **setup.py** | 자동 감지 | 복잡도 증가 | ⭐⭐ |
| **requirements.txt** | HF Spaces 호환 | 구버전 강제 | ⭐ |

---

## 방법 1: requirements-local.txt (권장)

### HF Spaces 배포
```bash
# requirements.txt 사용 (자동)
# PyTorch 2.2.0 (ZeroGPU 호환)
```

### 로컬 개발
```bash
# 가상환경 생성
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 로컬용 requirements 설치
pip install -r requirements-local.txt
# PyTorch >=2.2.0 (최신 버전)
```

### 파일 구조
```
requirements.txt          # HF Spaces용 (PyTorch 2.2.0)
requirements-local.txt    # 로컬용 (PyTorch >=2.2.0)
```

---

## 방법 2: setup.py (자동 감지) ⭐ 새로운 CUDA 지원!

### 설치
```bash
# 가상환경 생성 및 활성화
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 스마트 설치 실행
python setup.py
```

### 동작 방식 (NEW! CUDA 자동 감지)
1. **환경 감지**: `SPACE_ID` 환경 변수 확인
2. **HF Spaces**: PyTorch 2.2.0 설치 (ZeroGPU 호환)
3. **로컬 환경**:
   - 🔍 **NVIDIA GPU 감지**: `nvidia-smi` 실행
   - 🔍 **CUDA 버전 감지**: `nvcc --version` 또는 nvidia-smi에서 추출
   - ✅ **CUDA별 PyTorch 설치**:
     - CUDA 11.8 → PyTorch cu118
     - CUDA 12.1-12.3 → PyTorch cu121
     - CUDA 12.4-12.8 → PyTorch cu124
   - 🍎 **Apple Silicon**: MPS 지원
   - 💻 **GPU 없음**: CPU 전용 PyTorch

### 지원하는 CUDA 버전
| CUDA 버전 | PyTorch 변형 | Index URL |
|-----------|--------------|-----------|
| 11.8 | cu118 | https://download.pytorch.org/whl/cu118 |
| 12.1-12.3 | cu121 | https://download.pytorch.org/whl/cu121 |
| 12.4-12.8 | cu124 | https://download.pytorch.org/whl/cu124 |

### 장점
- ✅ **완전 자동 CUDA 감지** (NEW!)
- ✅ 한 명령으로 설치
- ✅ 플랫폼별 최적화
- ✅ 설치 후 자동 검증
- ✅ 실패 시 CPU로 폴백

---

## PyTorch 버전별 기능

### PyTorch 2.2.0 (HF Spaces ZeroGPU)
- ✅ ZeroGPU 호환
- ✅ 기본 LLM 기능
- ✅ 안정성 검증됨

### PyTorch >=2.2.0 (로컬)
- ✅ 최신 기능
- ✅ 성능 개선
- ✅ 최신 GPU 지원
- ✅ MPS 최적화 (Apple Silicon)

---

## 플랫폼별 권장 설치

### Mac (Apple Silicon)
```bash
# M1/M2/M3/M4
pip install -r requirements-local.txt
# MPS 가속 지원
```

### Linux (NVIDIA GPU)
```bash
pip install -r requirements-local.txt
# CUDA 12.x 지원
```

### Windows (NVIDIA GPU)
```bash
pip install -r requirements-local.txt
# CUDA 12.x 지원
```

### HF Spaces (자동)
```bash
# requirements.txt 자동 사용
# 수동 설치 불필요
```

---

## 검증

### 설치 확인
```python
import torch
print(f"PyTorch: {torch.__version__}")
print(f"CUDA: {torch.cuda.is_available()}")
print(f"MPS: {torch.backends.mps.is_available()}")
```

### 예상 출력

**로컬 (최신)**:
```
PyTorch: 2.5.1
CUDA: True / False
MPS: True / False
```

**HF Spaces (ZeroGPU)**:
```
PyTorch: 2.2.0
CUDA: True
MPS: False
```

---

## FAQ

### Q: 로컬에서 PyTorch 2.2.0을 사용해야 하나요?
A: 아니요. 로컬에서는 `requirements-local.txt`로 최신 버전을 사용하세요.

### Q: requirements.txt와 requirements-local.txt 차이는?
A:
- `requirements.txt`: HF Spaces용 (PyTorch 2.2.0)
- `requirements-local.txt`: 로컬용 (PyTorch >=2.2.0)

### Q: setup.py를 사용해야 하나요?
A: 선택 사항입니다. 자동 감지를 원하면 사용하세요.

### Q: 두 파일을 동기화해야 하나요?
A: PyTorch 버전만 다르고 나머지는 동일하게 유지하세요.

---

## 문제 해결

### 🔥 GPU가 감지되지 않음 (torch.cuda.is_available() = False)

#### 증상 1: Driver/library version mismatch
```bash
nvidia-smi
# 출력: Failed to initialize NVML: Driver/library version mismatch
```

**원인**: NVIDIA 드라이버 업데이트 후 재부팅하지 않음

**해결책**:
```bash
# 시스템 재부팅 (가장 간단하고 효과적)
sudo reboot
```

재부팅 후 다시 확인:
```bash
nvidia-smi
python setup.py  # PyTorch 재설치
```

#### 증상 2: PyTorch가 CPU 버전으로 설치됨
```python
import torch
print(torch.__version__)  # 출력: 2.9.0+cpu (CUDA 없음)
```

**원인**: pip install torch가 기본 CPU 버전을 설치함

**해결책**:
```bash
# 현재 PyTorch 제거
pip uninstall torch torchvision torchaudio -y

# setup.py로 재설치 (자동 CUDA 감지)
python setup.py
```

#### 증상 3: CUDA 버전 불일치
```python
# 시스템 CUDA: 12.8
# PyTorch CUDA: 12.4
# 오류: forward compatibility was attempted on non supported HW
```

**원인**: PyTorch CUDA 버전과 드라이버 CUDA 버전 불일치

**해결책**:
```bash
# 1. 드라이버 재부팅 (우선 시도)
sudo reboot

# 2. 드라이버 재설치 (재부팅으로 안 되면)
sudo ubuntu-drivers autoinstall
sudo reboot

# 3. PyTorch 재설치
python setup.py
```

#### 증상 4: nvidia-smi는 작동하지만 PyTorch에서 GPU 인식 안 됨
```bash
nvidia-smi  # ✅ 작동
python -c "import torch; print(torch.cuda.is_available())"  # ❌ False
```

**해결책**:
```bash
# PyTorch를 CUDA 버전으로 강제 재설치
pip uninstall torch torchvision torchaudio -y

# CUDA 버전 확인
nvidia-smi | grep "CUDA Version"  # 예: CUDA Version: 12.1

# 해당 CUDA 버전의 PyTorch 설치
# CUDA 12.1-12.3
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# CUDA 12.4+
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

# 검증
python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"
```

### ImportError: spaces
**로컬 환경**:
```
정상 동작 - app.py가 자동으로 감지하고 CPU/GPU 모드로 전환
```

### PyTorch 버전 충돌
```bash
pip uninstall torch torchvision torchaudio -y
python setup.py  # 자동 CUDA 감지 및 설치
```

### 설치 검증
```python
# 완전한 환경 검증
import torch
print(f"PyTorch: {torch.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"CUDA compiled: {torch.version.cuda}")
if torch.cuda.is_available():
    print(f"GPU name: {torch.cuda.get_device_name(0)}")
    print(f"GPU count: {torch.cuda.device_count()}")
```

**예상 출력 (GPU 환경)**:
```
PyTorch: 2.5.1+cu124
CUDA available: True
CUDA compiled: 12.4
GPU name: NVIDIA GeForce RTX 4090
GPU count: 1
```