Spaces:

gbrabbit
/

lily_fast_api

Sleeping

App Files Files Community

lily_fast_api / WINDOWS_GPU_DEPLOYMENT_GUIDE.md

gbrabbit

Fresh start for HF Spaces deployment

526927a about 1 year ago

preview code

Raw History Blame Contribute Delete

6.52 kB

# 🖥️ 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 모델**: 최적화된 모델 로드 

	# 🖥️ 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 모델: 최적화된 모델 로드