# GPU/CUDA 가속 설정 가이드

## 개요

이 프로그램은 이제 NVIDIA GPU의 CUDA를 활용하여 이미지 번역 작업을 가속화할 수 있습니다. CUDA를 사용하면 CPU 대비 상당한 성능 향상과 메모리 효율성을 얻을 수 있습니다.

## 지원되는 모듈

### 1. MIGAN 인페인팅 모듈
- **기능**: 텍스트 영역 제거 및 배경 복원
- **CUDA 효과**: 인페인팅 속도 2-5배 향상
- **메모리 효율성**: GPU VRAM 활용으로 시스템 RAM 절약

### 2. RemoveBG (rembg) 모듈  
- **기능**: 배경 제거 
- **CUDA 효과**: 배경 제거 속도 3-10배 향상
- **지원 모델**: 모든 rembg 모델 (birefnet, u2net, sam 등)

### 3. PaddleOCR 모듈
- **기능**: 텍스트 감지 및 인식
- **CUDA 효과**: OCR 처리 속도 향상
- **메모리 효율성**: 대량 이미지 처리 시 안정성 개선

## 시스템 요구사항

### 하드웨어
- **GPU**: NVIDIA GPU (RTX 시리즈 권장)
- **VRAM**: 최소 4GB (8GB 이상 권장)
- **시스템 RAM**: 8GB 이상

### 소프트웨어
- **OS**: Windows 10/11 (현재 지원)
- **CUDA Toolkit**: 11.0 이상 (12.1 권장)
- **NVIDIA Driver**: 최신 버전 권장

## 설정 방법

### 1. toggle_states 설정

```python
toggle_states = {
    # CUDA 전역 활성화
    "use_cuda": True,
    
    # 기존 설정들...
    "migan_onnx_path": "path/to/migan/model.onnx",
    "request_rembg_server_url": "http://localhost:35756",
    # ... 기타 설정
}
```

### 2. 설정 키 설명

| 키 | 타입 | 기본값 | 설명 |
|---|------|--------|------|
| `use_cuda` | bool | False | CUDA 전역 활성화 여부 |
| `migan_use_cuda` | bool | auto | MIGAN CUDA 사용 (자동 설정됨) |
| `migan_intra_threads` | int | 0 | MIGAN 내부 스레드 수 |
| `migan_inter_threads` | int | 0 | MIGAN 간 스레드 수 |

## 동작 과정

### 1. 초기화 단계
```
1. GPU 하드웨어 감지 (nvidia-smi)
2. CUDA 설치 확인 (nvcc --version) 
3. ML 프레임워크 CUDA 지원 확인
4. 전역 상태 설정
```

### 2. 런타임 동작
```
- CUDA 사용 가능 → GPU 가속 모드
- CUDA 실패 → CPU 폴백 (자동)
- 매 작업마다 GPU 메모리 사용량 모니터링
```

## 로그 예시

### CUDA 활성화 성공
```
[INFO] === GPU 상태 초기화 시작 ===
[INFO] 사용자 CUDA 사용 요청: True
[INFO] GPU 하드웨어 감지됨: 1개
[INFO]   gpu_0: NVIDIA GeForce RTX 3050 (8192MB, 드라이버 565.90)
[INFO] CUDA 컴파일러 감지됨
[INFO] CUDA 버전: release 12.1, V12.1.66
[INFO] ✅ ONNXRuntime CUDA 지원 확인됨
[INFO] ✅ PyTorch CUDA 지원 확인됨 (1개 디바이스, 현재: NVIDIA GeForce RTX 3050)
[INFO] ✅ CUDA 사용 가능 - GPU 가속 모드로 동작
[INFO] === GPU 상태 초기화 완료 ===
```

### 모듈별 CUDA 활성화
```
[INFO] MIGAN CUDA 사용 설정: True
[INFO] [MIGAN] 세션 준비 완료. providers=['CUDAExecutionProvider', 'CPUExecutionProvider']
[INFO] ✅ rembg birefnet-general-lite CUDA 가속 활성화
[INFO] OCR 모듈 CUDA 모드 활성화
[INFO] ✅ PaddleOCR 초기화 성공 (CUDA 모드)
```

### 성능 모니터링
```
[INFO] ✅ 배경 제거 성공: birefnet-general-lite (CUDA, 0.85초)
[INFO] GPU 0 메모리 사용량: 2847MB/8192MB (34.7%)
[INFO] MIGAN 인페인팅 시작
[INFO] MIGAN 인페인팅 완료
[INFO] GPU 0 메모리 사용량: 3124MB/8192MB (38.1%)
```

## 메모리 효율성 개선

### CUDA 사용 시 장점
1. **시스템 RAM 절약**: GPU VRAM 활용으로 시스템 메모리 압박 완화
2. **병렬 처리**: 여러 작업 동시 수행 가능
3. **재시작 빈도 감소**: 메모리 부족으로 인한 이미지워커 재시작 빈도 감소

### 성능 비교 (예상)
| 작업 | CPU 모드 | CUDA 모드 | 개선 효과 |
|------|----------|-----------|-----------|
| 배경 제거 | 3-5초 | 0.5-1초 | 3-5배 빠름 |
| 인페인팅 | 2-4초 | 0.3-0.8초 | 5-10배 빠름 |
| OCR 처리 | 1-2초 | 0.5-1초 | 2배 빠름 |

### 메모리 사용량
- **CPU 모드**: 시스템 RAM 85% → 재시작 트리거
- **CUDA 모드**: 시스템 RAM 60-70% + GPU VRAM 30-40%

## 문제 해결

### 1. CUDA 감지 실패
```
# 확인 명령어
nvidia-smi
nvcc --version

# 해결 방법
- NVIDIA 드라이버 최신 업데이트
- CUDA Toolkit 재설치
- 시스템 재부팅
```

### 2. 메모리 부족
```
[ERROR] CUDA out of memory

# 해결 방법
- GPU VRAM 용량 확인
- 다른 GPU 사용 프로그램 종료
- 배치 크기 조정
```

### 3. 성능 저하
```
# 확인 사항
- GPU 온도 및 클럭 속도
- 전력 설정 (고성능 모드)
- 백그라운드 프로세스 확인
```

## 향후 개선 계획

1. **더 많은 모델 지원**
   - Tesseract OCR CUDA 지원
   - 추가 인페인팅 모델 지원

2. **멀티 GPU 지원**
   - 여러 GPU 사용 시 로드 밸런싱
   - GPU별 작업 분산

3. **메모리 최적화**
   - 동적 배치 크기 조정
   - 메모리 풀링 구현

4. **실시간 모니터링**
   - GPU 온도/클럭 모니터링
   - 성능 메트릭 대시보드

## 참고 자료

- [NVIDIA CUDA 설치 가이드](https://developer.nvidia.com/cuda-downloads)
- [ONNXRuntime CUDA Provider](https://onnxruntime.ai/docs/execution-providers/CUDA-ExecutionProvider.html)
- [PaddleOCR GPU 지원](https://github.com/PaddlePaddle/PaddleOCR/blob/release/2.7/doc/doc_en/installation_en.md)