WINDOWS_GPU_DEPLOYMENT_GUIDE.md

# 🖥️ Windows GPU 환경 배포 가이드

## 📋 사전 요구사항

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

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

#### NVIDIA 드라이버 설치
1. **NVIDIA 웹사이트 방문**: https://www.nvidia.com/Download/index.aspx
2. **GPU 모델 선택**: 사용 중인 GPU 모델 선택
3. **드라이버 다운로드**: 최신 드라이버 다운로드 및 설치
4. **재부팅**: 설치 완료 후 시스템 재부팅

#### Docker Desktop 설치
1. **Docker Desktop 다운로드**: https://www.docker.com/products/docker-desktop
2. **설치 실행**: 다운로드한 파일 실행
3. **WSL 2 설정**: Windows Subsystem for Linux 2 활성화
4. **재부팅**: 설치 완료 후 시스템 재부팅

#### Python GPU 라이브러리 설치
```cmd
# 가상환경 활성화
lily_llm_env\Scripts\activate

# PyTorch GPU 버전 설치
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# Hugging Face 라이브러리 설치
pip install transformers huggingface_hub

# 추가 GPU 라이브러리 설치
pip install accelerate bitsandbytes
```

## 🔧 환경 설정

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

### 2. Windows GPU 설정
```cmd
# Windows GPU 환경 설정 스크립트 실행
windows_gpu_setup.bat
```

### 3. Hugging Face 설정
```cmd
# Hugging Face 토큰 설정
huggingface-cli login

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

## 🚀 배포 실행

### 1. 자동 배포 (권장)
```cmd
# Windows GPU 배포 스크립트 실행
deploy_gpu_windows.bat
```

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

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

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

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

## 🧪 테스트

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

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

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

## 📊 모니터링

### 1. GPU 사용량 확인
```cmd
# GPU 정보 확인
nvidia-smi

# 실시간 모니터링
nvidia-smi -l 1
```

### 2. 컨테이너 상태 확인
```cmd
# 실행 중인 컨테이너 확인
docker ps

# 컨테이너 리소스 사용량 확인
docker stats
```

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

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

## 🔧 문제 해결

### 1. NVIDIA 드라이버 문제
```cmd
# 드라이버 버전 확인
nvidia-smi

# 문제 발생 시 드라이버 재설치
# 1. 기존 드라이버 제거
# 2. 최신 드라이버 다운로드 및 설치
# 3. 시스템 재부팅
```

### 2. Docker 문제
```cmd
# Docker Desktop 재시작
# Docker Desktop > Settings > General > Restart

# WSL 2 확인
wsl --list --verbose

# Docker 권한 문제 해결
# Docker Desktop > Settings > Resources > WSL Integration
```

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

# CUDA 버전에 맞는 PyTorch 재설치
pip uninstall torch torchvision torchaudio
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
```

### 4. 메모리 부족
```cmd
# GPU 메모리 확인
nvidia-smi

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

# 메모리 최적화 적용
python performance_optimization.py
```

## 📈 성능 최적화

### 1. Windows 전용 최적화
```cmd
# 가상 메모리 증가
# 제어판 > 시스템 > 고급 시스템 설정 > 성능 > 설정 > 고급 > 가상 메모리

# 전원 설정 최적화
# 제어판 > 전원 옵션 > 고성능 선택
```

### 2. Docker 최적화
```cmd
# Docker Desktop 설정 최적화
# Docker Desktop > Settings > Resources
# - Memory: 8GB 이상 할당
# - CPUs: 4개 이상 할당
# - Disk image size: 64GB 이상
```

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

# 배치 크기 조정
# config.yaml에서 batch_size 조정
```

## 🔄 업데이트

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

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

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

## 📞 지원

### 문제 발생 시 확인사항
1. **GPU 드라이버**: `nvidia-smi` 명령어 실행 가능 여부
2. **Docker Desktop**: WSL 2 통합 활성화 여부
3. **CUDA 버전**: PyTorch와 CUDA 버전 호환성
4. **시스템 메모리**: 16GB 이상 여유 메모리
5. **GPU 메모리**: 8GB 이상 GPU 메모리

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

## 🎯 Windows 전용 팁

### 1. WSL 2 최적화
```cmd
# WSL 2 메모리 제한 설정
# %UserProfile%\.wslconfig 파일 생성
[wsl2]
memory=8GB
processors=4
```

### 2. Windows Defender 예외 설정
```cmd
# 프로젝트 폴더를 Windows Defender 예외에 추가
# Windows 보안 > 바이러스 및 위협 방지 > 설정 > 예외 추가
```

### 3. 전원 관리 최적화
```cmd
# 고성능 전원 계획 선택
powercfg /setactive 8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c
```

## 🚀 빠른 시작

### 1단계: 환경 확인
```cmd
windows_gpu_setup.bat
```

### 2단계: Hugging Face 설정
```cmd
python huggingface_gpu_setup.py
```

### 3단계: GPU 배포
```cmd
deploy_gpu_windows.bat
```

### 4단계: 테스트
```cmd
python test_gpu_deployment.py
```

## 🎉 성공 확인

배포가 성공적으로 완료되면 다음 서비스들이 실행됩니다:

- ✅ **Lily LLM API**: http://localhost:8001
- ✅ **Hearth Chat**: http://localhost:8000
- ✅ **LaTeX-OCR Service**: 별도 컨테이너로 실행
- ✅ **GPU 가속**: NVIDIA GPU 활용
- ✅ **Hugging Face 모델**: 최적화된 모델 로드