GPU_DEPLOYMENT_GUIDE.md

# 🚀 GPU 환경 배포 가이드

## 📋 사전 요구사항

### 1. 하드웨어 요구사항
- **GPU**: NVIDIA GPU (RTX 3060 이상 권장)
- **메모리**: 최소 16GB RAM, 권장 32GB RAM
- **저장공간**: 최소 50GB 여유 공간

### 2. 소프트웨어 요구사항

#### NVIDIA 드라이버 설치
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install nvidia-driver-470

# Windows
# NVIDIA 웹사이트에서 최신 드라이버 다운로드
```

#### CUDA 설치
```bash
# CUDA 11.8 설치 (권장)
wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run
sudo sh cuda_11.8.0_520.61.05_linux.run
```

#### Docker 설치
```bash
# Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# Windows
# Docker Desktop 설치
```

#### NVIDIA Docker 설치
```bash
# NVIDIA Container Toolkit 설치
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt-get update
sudo apt-get install -y nvidia-docker2
sudo systemctl restart docker
```

## 🔧 환경 설정

### 1. GPU 환경 확인
```bash
cd C:\Project\lily_generate_project\lily_generate_package
python check_gpu_environment.py
```

### 2. Hugging Face 설정
```bash
# Hugging Face 토큰 설정
huggingface-cli login

# 또는 Python 스크립트로 설정
python huggingface_gpu_setup.py
```

## 🚀 배포 실행

### 1. 자동 배포 (권장)
```bash
# 배포 스크립트 실행
chmod +x deploy_gpu_huggingface.sh
./deploy_gpu_huggingface.sh
```

### 2. 수동 배포
```bash
# 1. 기존 컨테이너 정리
docker-compose -f docker-compose.gpu.yml down --volumes --remove-orphans

# 2. GPU 메모리 정리
nvidia-smi --gpu-reset

# 3. 이미지 빌드
docker-compose -f docker-compose.gpu.yml build --no-cache

# 4. 컨테이너 시작
docker-compose -f docker-compose.gpu.yml up -d

# 5. 서비스 상태 확인
docker-compose -f docker-compose.gpu.yml logs -f
```

## 🧪 테스트

### 1. GPU 배포 테스트
```bash
python test_gpu_deployment.py
```

### 2. Hugging Face 모델 테스트
```bash
python huggingface_gpu_setup.py
```

### 3. API 테스트
```bash
curl http://localhost:8001/health
```

## 📊 모니터링

### 1. GPU 사용량 확인
```bash
nvidia-smi
nvidia-smi -l 1  # 1초마다 업데이트
```

### 2. 컨테이너 상태 확인
```bash
docker ps
docker stats
```

### 3. 로그 확인
```bash
# 전체 로그
docker-compose -f docker-compose.gpu.yml logs -f

# 특정 서비스 로그
docker-compose -f docker-compose.gpu.yml logs -f lily-llm-api-gpu
```

## 🔧 문제 해결

### 1. GPU 메모리 부족
```bash
# GPU 메모리 정리
nvidia-smi --gpu-reset

# 컨테이너 재시작
docker-compose -f docker-compose.gpu.yml restart
```

### 2. CUDA 버전 충돌
```bash
# CUDA 버전 확인
nvcc --version

# PyTorch CUDA 버전 확인
python -c "import torch; print(torch.version.cuda)"
```

### 3. Docker 권한 문제
```bash
# Docker 그룹에 사용자 추가
sudo usermod -aG docker $USER

# 재로그인 후 확인
docker ps
```

### 4. Hugging Face 토큰 문제
```bash
# 토큰 재설정
huggingface-cli logout
huggingface-cli login
```

## 📈 성능 최적화

### 1. 메모리 최적화
```bash
# 4-bit 양자화 적용
python huggingface_gpu_setup.py

# 성능 최적화 적용
python performance_optimization.py
```

### 2. 배치 크기 조정
```python
# config.yaml에서 배치 크기 조정
batch_size: 4  # GPU 메모리에 따라 조정
```

### 3. 모델 캐싱
```bash
# Hugging Face 캐시 설정
export HF_HOME="/path/to/cache"
export TRANSFORMERS_CACHE="/path/to/cache"
```

## 🔄 업데이트

### 1. 모델 업데이트
```bash
# 최신 모델 다운로드
python huggingface_gpu_setup.py

# 컨테이너 재시작
docker-compose -f docker-compose.gpu.yml restart
```

### 2. 코드 업데이트
```bash
# 코드 변경 후 재빌드
docker-compose -f docker-compose.gpu.yml build --no-cache
docker-compose -f docker-compose.gpu.yml up -d
```

## 📞 지원

### 문제 발생 시 확인사항
1. GPU 드라이버 버전
2. CUDA 버전
3. Docker 버전
4. 시스템 메모리 사용량
5. GPU 메모리 사용량

### 로그 파일 위치
- Docker 로그: `docker-compose -f docker-compose.gpu.yml logs`
- 애플리케이션 로그: `logs/` 디렉토리
- GPU 로그: `nvidia-smi`

## 🎯 성능 벤치마크

### 권장 사양별 성능
- **RTX 3060 (12GB)**: 기본 모델 실행 가능
- **RTX 3080 (10GB)**: 중간 크기 모델 실행 가능
- **RTX 3090 (24GB)**: 대용량 모델 실행 가능
- **RTX 4090 (24GB)**: 최고 성능, 모든 모델 실행 가능

### 메모리 사용량 가이드
- **4-bit 양자화**: 모델 크기의 약 25%
- **8-bit 양자화**: 모델 크기의 약 50%
- **16-bit (FP16)**: 모델 크기의 약 100%
- **32-bit (FP32)**: 모델 크기의 약 200%