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 배포

# requirements.txt 사용 (자동)
# PyTorch 2.2.0 (ZeroGPU 호환)

로컬 개발

# 가상환경 생성
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 지원!

설치

# 가상환경 생성 및 활성화
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)

# M1/M2/M3/M4
pip install -r requirements-local.txt
# MPS 가속 지원

Linux (NVIDIA GPU)

pip install -r requirements-local.txt
# CUDA 12.x 지원

Windows (NVIDIA GPU)

pip install -r requirements-local.txt
# CUDA 12.x 지원

HF Spaces (자동)

# requirements.txt 자동 사용
# 수동 설치 불필요

---

검증

설치 확인

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

nvidia-smi
# 출력: Failed to initialize NVML: Driver/library version mismatch

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

해결책:

# 시스템 재부팅 (가장 간단하고 효과적)
sudo reboot

재부팅 후 다시 확인:

nvidia-smi
python setup.py  # PyTorch 재설치

증상 2: PyTorch가 CPU 버전으로 설치됨

import torch
print(torch.__version__)  # 출력: 2.9.0+cpu (CUDA 없음)

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

해결책:

# 현재 PyTorch 제거
pip uninstall torch torchvision torchaudio -y

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

증상 3: CUDA 버전 불일치

# 시스템 CUDA: 12.8
# PyTorch CUDA: 12.4
# 오류: forward compatibility was attempted on non supported HW

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

해결책:

# 1. 드라이버 재부팅 (우선 시도)
sudo reboot

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

# 3. PyTorch 재설치
python setup.py

증상 4: nvidia-smi는 작동하지만 PyTorch에서 GPU 인식 안 됨

nvidia-smi  # ✅ 작동
python -c "import torch; print(torch.cuda.is_available())"  # ❌ False

해결책:

# 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 버전 충돌

pip uninstall torch torchvision torchaudio -y
python setup.py  # 자동 CUDA 감지 및 설치

설치 검증

# 완전한 환경 검증
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