# 🖼️ 고성능 인페인팅 서버

FastAPI와 딥러닝을 활용한 병렬 처리 인페인팅 서버입니다. Simple LAMA, MIGAN, REMBG 모델을 TensorRT와 CUDA를 활용하여 FP16 방식으로 최적화된 서버를 제공합니다.

**🚀 Jetson Xavier (ARM64) 및 x86_64 시스템을 모두 지원합니다!**

## ✨ 주요 기능

- **🚀 고성능 병렬 처리**: 동적 워커 관리로 최적의 성능 제공
- **🎯 다중 모델 지원**: Simple LAMA, MIGAN, REMBG 인페인팅 모델
- **⚡ GPU 최적화**: TensorRT와 CUDA FP16을 활용한 빠른 추론
- **📊 실시간 모니터링**: 웹 기반 대시보드로 서버 상태 실시간 확인
- **🔧 동적 스케일링**: VRAM 사용량에 따른 자동 워커 조정
- **🛡️ 안정성**: 세션 풀과 에러 복구 메커니즘
- **🚁 Jetson 최적화**: ARM64 아키텍처 전용 성능 튜닝

## 🏗️ 아키텍처

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   FastAPI       │    │   워커 매니저    │    │   세션 풀       │
│   엔드포인트     │◄──►│   (동적 스케일링) │◄──►│   (모델 관리)    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   모니터링       │    │   GPU 모니터     │    │   모델 인스턴스  │
│   대시보드       │    │   (VRAM 추적)    │    │ (Simple LAMA,   │
└─────────────────┘    └─────────────────┘    │  MIGAN, REMBG)  │
                                              └─────────────────┘
```

## 📋 요구사항

### 시스템 요구사항

#### Jetson Xavier (ARM64)
- Ubuntu 18.04 이상
- Python 3.8 이상
- CUDA 11.8
- cuDNN 8
- TensorRT 8.6
- 4GB 이상 RAM 권장
- 10GB 이상 저장공간

#### x86_64 시스템
- Ubuntu 18.04 이상
- Python 3.8 이상
- NVIDIA GPU (GTX 1060 이상 권장)
- CUDA 11.8 이상
- 8GB 이상 RAM 권장
- 10GB 이상 저장공간

### GPU 요구사항
- **Jetson Xavier**: 내장 Volta GPU (8GB VRAM)
- **x86**: NVIDIA GPU (4GB 이상 VRAM)

## 🚀 설치 및 실행

### 1. 프로젝트 클론 및 가상환경 설정

프로젝트가 이미 `/home/ckh08045/work/inpaintServer`에 설정되어 있습니다.

### 2. 의존성 설치

#### Jetson Xavier 전용 설치
```bash
# Jetson 최적화와 함께 설치
./scripts/install_deps.sh --jetson-optimize

# 또는 기본 설치
./scripts/install_deps.sh
```

#### x86 시스템 설치
```bash
# 기본 설치
./scripts/install_deps.sh

# 개발 도구 포함
./scripts/install_deps.sh --extras
```

#### 수동 설치
```bash
source bin/activate
pip install -r requirements.txt
```

### 3. 환경 설정

```bash
# 환경 설정 파일 복사 및 수정
cp .env.example .env

# Jetson Xavier의 경우 자동으로 최적화된 설정이 적용됩니다
# 필요한 경우 .env 파일에서 세부 설정 조정
```

### 4. 서버 시작

#### Jetson Xavier 최적화 모드
```bash
# Jetson 최적화와 함께 시작
./scripts/start_server.sh --jetson-optimize

# 또는 기본 시작
./scripts/start_server.sh
```

#### x86 시스템
```bash
# 기본 모드로 시작
./scripts/start_server.sh

# 프로덕션 모드로 시작
./scripts/start_server.sh --production

# 워커 수 지정
./scripts/start_server.sh --workers 4

# GPU 디바이스 지정
./scripts/start_server.sh --gpu 0
```

### 5. 서버 상태 확인

```bash
# 상태 확인
./scripts/status.sh

# 상세 정보
./scripts/status.sh --detailed

# 실시간 모니터링
./scripts/status.sh --watch
```

### 6. 서버 중지

```bash
# 정상 종료
./scripts/stop_server.sh

# 강제 종료
./scripts/stop_server.sh --force
```

## 🚁 Jetson Xavier 전용 기능

### 자동 시스템 감지
- ARM64 아키텍처 자동 감지
- Tegra 커널 자동 인식
- Jetson 전용 설정 자동 적용

### 성능 최적화
- **전력 모드**: MAXN 모드로 최고 성능
- **GPU 클럭**: 1200MHz로 최적화
- **메모리 클럭**: 1600MHz로 최적화
- **팬 제어**: 온도 기반 자동 조정

### 메모리 관리
- **VRAM 임계값**: 70%/30% (x86 대비 보수적)
- **파일 크기 제한**: 25MB (x86: 50MB)
- **워커 수**: 최대 4개 (x86: 최대 8개)

### 모니터링 도구
- **jtop**: Jetson 전용 시스템 모니터링
- **nvpmodel**: 전력 모드 관리
- **온도 센서**: 실시간 온도 모니터링

## 📡 API 엔드포인트

### 인페인팅 API

#### Simple LAMA 인페인팅
```http
POST /inpaint/simple-lama
Content-Type: multipart/form-data

- image: 원본 이미지 파일
- mask: 마스크 이미지 파일 (흰색 영역이 제거될 부분)
- format: 출력 형식 (PNG/JPEG, 기본값: PNG)
```

#### MIGAN 인페인팅
```http
POST /inpaint/migan
Content-Type: multipart/form-data

- image: 원본 이미지 파일
- mask: 마스크 이미지 파일
- format: 출력 형식 (PNG/JPEG, 기본값: PNG)
```

### 배경 제거 API

```http
POST /remove-background
Content-Type: multipart/form-data

- image: 원본 이미지 파일
- model_name: REMBG 모델명 (u2net/u2netp/silueta, 기본값: u2net)
- return_mask: 마스크 반환 여부 (기본값: false)
- background_color: 새 배경색 (hex 형식, 예: #ffffff)
- format: 출력 형식 (PNG/JPEG, 기본값: PNG)
```

### 관리 API

```http
GET /health          # 헬스 체크
GET /status          # 서버 상태
GET /                # API 정보
GET /docs            # Swagger UI
POST /scale-sessions # 세션 풀 크기 조정
```

## 📊 모니터링

### 웹 대시보드
서버 시작 후 `http://localhost:8001`에서 실시간 모니터링 대시보드에 접근할 수 있습니다.

### 모니터링 항목
- **서버 상태**: 메인 서버, 모니터링 서버 상태
- **GPU 정보**: VRAM 사용량, GPU 사용률
- **시스템 리소스**: CPU, 메모리, 디스크 사용량
- **워커 상태**: 활성 워커 수, 작업 큐 상태
- **세션 풀**: 각 모델별 세션 사용 현황

### Jetson 전용 모니터링
- **온도 정보**: 각 thermal zone별 온도
- **클럭 주파수**: GPU, CPU, 메모리 클럭
- **전력 소비**: 실시간 전력 사용량
- **팬 속도**: PWM 팬 제어 상태

## ⚙️ 설정

### 세션 풀 비율
기본 설정: Simple LAMA:MIGAN:REMBG = 2:2:1

```python
# .env 파일에서 조정 가능
SIMPLE_LAMA_SESSIONS=2
MIGAN_SESSIONS=2
REMBG_SESSIONS=1
```

### 동적 스케일링
VRAM 사용량에 따른 자동 워커 조정:

#### Jetson Xavier
```python
VRAM_THRESHOLD_HIGH=0.7  # 70% 이상시 스케일 다운
VRAM_THRESHOLD_LOW=0.3   # 30% 이하시 스케일 업
VRAM_CHECK_INTERVAL=20    # 20초마다 체크
```

#### x86 시스템
```python
VRAM_THRESHOLD_HIGH=0.8  # 80% 이상시 스케일 다운
VRAM_THRESHOLD_LOW=0.4   # 40% 이하시 스케일 업
VRAM_CHECK_INTERVAL=30    # 30초마다 체크
```

## 🔧 개발 모드

```bash
# 개발 모드로 실행 (자동 리로드)
python main.py --dev

# 또는
uvicorn app.api.endpoints:app --reload
```

## 📝 로그

로그 파일들은 `logs/` 디렉토리에 저장됩니다:

- `main_server.log`: 메인 서버 로그
- `monitoring.log`: 모니터링 서버 로그
- `error.log`: 에러 로그
- `access.log`: 액세스 로그

## 🛠️ 문제해결

### 일반적인 문제

1. **CUDA 관련 오류**
   ```bash
   # CUDA 설치 확인
   nvidia-smi
   nvcc --version
   
   # PyTorch CUDA 호환성 확인
   python -c "import torch; print(torch.cuda.is_available())"
   ```

2. **메모리 부족**
   ```bash
   # VRAM 사용량 확인
   nvidia-smi
   
   # 세션 수 줄이기
   ./scripts/start_server.sh --workers 1
   ```

3. **포트 충돌**
   ```bash
   # 포트 사용 확인
   lsof -i :8000
   lsof -i :8001
   
   # 다른 포트 사용
   python main.py --port 8080
   ```

### Jetson 전용 문제

1. **전력 모드 문제**
   ```bash
   # 전력 모드 확인
   nvpmodel -q
   
   # MAXN 모드로 설정
   sudo nvpmodel -m 0
   ```

2. **온도 문제**
   ```bash
   # 온도 확인
   cat /sys/devices/virtual/thermal/thermal_zone*/temp
   
   # 팬 속도 조정
   echo 255 | sudo tee /sys/devices/pwm-fan/target_pwm
   ```

3. **메모리 클럭 문제**
   ```bash
   # 메모리 클럭 확인
   cat /sys/kernel/debug/clk/emc/clk_rate
   
   # 클럭 재설정
   echo 1600000000 | sudo tee /sys/kernel/debug/clk/emc/clk_rate
   ```

### 로그 확인

```bash
# 실시간 로그 확인
tail -f logs/main_server.log

# 에러 로그 확인
tail -f logs/error.log
```

## 🤝 기여

1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 `LICENSE` 파일을 참조하세요.

## 🙏 감사의 말

- [FastAPI](https://fastapi.tiangolo.com/) - 현대적인 웹 프레임워크
- [PyTorch](https://pytorch.org/) - 딥러닝 프레임워크
- [Simple LAMA](https://github.com/advimman/lama) - 인페인팅 모델
- [REMBG](https://github.com/danielgatis/rembg) - 배경 제거 도구
- [TensorRT](https://developer.nvidia.com/tensorrt) - GPU 추론 최적화
- [NVIDIA Jetson](https://developer.nvidia.com/embedded-computing) - 엣지 AI 플랫폼

---

**💡 팁**: 
- **Jetson Xavier**: `--jetson-optimize` 옵션으로 최고 성능을 얻으세요!
- **x86 시스템**: GPU 메모리와 워커 수를 적절히 조정하세요
- 모니터링 대시보드를 통해 실시간으로 성능을 확인할 수 있습니다!
- Jetson 사용자는 `jtop` 명령어로 시스템 상태를 모니터링하세요!