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

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

**🚀 Jetson Xavier (ARM64) 및 x86_64 시스템을 모두 지원합니다!**  
**🔄 기존 클라이언트 코드와 100% 호환됩니다!**

[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://python.org)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-green.svg)](https://fastapi.tiangolo.com)
[![CUDA](https://img.shields.io/badge/CUDA-11.8+-orange.svg)](https://developer.nvidia.com/cuda-toolkit)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## ✨ 주요 기능

### 🎯 AI 모델 지원
- **Simple LAMA**: 빠르고 정확한 인페인팅
- **MIGAN**: 고품질 인페인팅
- **REMBG**: 배경 제거 (u2net, u2netp, silueta)

### 🚀 성능 최적화
- **병렬 처리**: 동적 워커 관리로 최적의 성능 제공
- **GPU 가속**: TensorRT와 CUDA FP16 활용
- **동적 스케일링**: VRAM 사용량에 따른 자동 워커 조정
- **세션 풀**: 모델 로딩 시간 최소화

### 📊 실시간 모니터링
- **웹 대시보드**: 실시간 서버 상태 확인
- **성능 지표**: CPU, GPU, 메모리 사용률
- **API 통계**: 엔드포인트별 요청/응답 분석
- **워커 관리**: 실시간 워커 상태 추적

### 🔄 기존 클라이언트 호환성
- **100% 호환**: 기존 코드 수정 없이 사용 가능
- **자동 기본값**: `model_name` 누락 시 자동 처리
- **바이너리 응답**: 기존 PNG 바이너리 응답 지원
- **에러 처리**: 기존 클라이언트 에러 처리 방식 유지

### 🌐 다양한 응답 형식
- **Binary** (기본값): 바이너리 이미지 (기존 호환)
- **JSON**: iopaint 호환 JSON 응답
- **Stream**: 대용량 파일 스트리밍

### 🖼️ 다양한 이미지 포맷
- **PNG** (기본값): 무손실, 투명도 지원
- **WebP**: 25-35% 압축률 개선
- **JPEG**: 최고 호환성

## 🏗️ 아키텍처

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

## 📋 시스템 요구사항

### Jetson Xavier (ARM64)
- **OS**: Ubuntu 18.04 이상
- **Python**: 3.8 이상
- **CUDA**: 11.8
- **cuDNN**: 8
- **TensorRT**: 8.6
- **GCC**: 11 이상 (ONNX Runtime GPU 호환성용)
- **RAM**: 4GB 이상 권장
- **저장공간**: 10GB 이상

> **중요**: Jetson Xavier에서 GPU 가속을 위해서는 GCC 11과 특별한 ONNX Runtime 버전이 필요합니다. 자동 설치 스크립트가 이를 자동으로 처리합니다.

### x86_64 시스템
- **OS**: Ubuntu 18.04 이상
- **Python**: 3.8 이상 (3.10 권장)
- **GPU**: NVIDIA GPU (RTX 3060 12GB 이상 권장)
- **CUDA**: 11.8 이상
- **RAM**: 8GB 이상 권장
- **저장공간**: 10GB 이상

#### RTX 3060 12GB 최적화 설정
- **워커 수**: 4-12개 (자동 조정)
- **세션 풀**: Simple LAMA 4개, MIGAN 4개, REMBG 2개
- **VRAM 관리**: 85% 사용률까지 허용, 25% 이하 시 확장
- **이미지 크기**: 최대 8K (8192x8192) 지원
- **파일 크기**: 최대 100MB 지원

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

## 🚀 빠른 시작

### 1. 프로젝트 클론

```bash
# 프로젝트 클론
git clone <repository-url> inpaintServer
cd inpaintServer

# 실행 권한 부여
chmod +x scripts/*.sh
```

### 2. 🚀 원클릭 자동 설치 (권장)

#### 플랫폼 자동 감지 설치
```bash
# 🎯 플랫폼 자동 감지 후 최적 설치
bash scripts/install.sh
```

#### 플랫폼별 직접 설치

**🚀 Jetson Xavier (ARM64):**
```bash
# Jetson Xavier 전용 최적화 설치
bash scripts/setup_jetson.sh
```

**🖥️ x86-64 Desktop:**
```bash
# x86-64 데스크톱 최적화 설치
bash scripts/setup_x86.sh
```

### 📁 가상환경 설정 방식

이 프로젝트는 **유연한 가상환경 설정**을 지원합니다:

#### 방식 1: 표준 venv 디렉토리 (기본)
```bash
python3 -m venv venv
source venv/bin/activate
```

#### 방식 2: 프로젝트 자체를 가상환경으로 사용
```bash
# 프로젝트 디렉토리에서 직접 가상환경 생성
python3 -m venv .
source bin/activate
```

> **💡 스마트 감지**: 설치 스크립트가 자동으로 감지하고 처리합니다
> - `venv/` 디렉토리 존재 → 표준 venv 사용
> - `pyvenv.cfg` 파일 존재 → 프로젝트 자체가 가상환경
> - 둘 다 없음 → 새로운 `venv/` 디렉토리 생성

**자동 설치가 수행하는 작업:**
- ✅ 플랫폼 자동 감지 (Jetson Xavier vs x86-64)
- ✅ 가상환경 자동 생성/감지
- ✅ GPU 최적화 의존성 설치
- ✅ ONNX Runtime GPU 설치 (플랫폼별)
- ✅ PyTorch CUDA 설치
- ✅ 모델 호환성 확인
- ✅ 설치 검증 및 테스트

### 3. 수동 설치 (고급 사용자)

<details>
<summary>수동 설치 과정 보기</summary>

#### 가상환경 설정
```bash
# 가상환경 생성
python -m venv venv

# 가상환경 활성화
source venv/bin/activate  # Linux/Mac
```

#### 의존성 설치
```bash
# Jetson Xavier
./scripts/install_deps.sh --jetson-optimize

# x86_64 시스템
./scripts/install_deps.sh

# 수동 설치
pip install -r requirements.txt
```

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

#### 서버 시작
```bash
# 기본 시작 (메인 + 모니터링)
./scripts/start_server.sh

# Jetson 최적화
./scripts/start_server.sh --jetson-optimize

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

</details>

## 🌐 서버 접속 정보

설치 완료 후 다음 URL로 접속할 수 있습니다:

| 서비스 | URL | 설명 |
|--------|-----|------|
| **메인 API** | http://localhost:8000 | 인페인팅/배경제거 API |
| **API 문서** | http://localhost:8000/docs | Swagger UI 문서 |
| **모니터링** | http://localhost:8001 | 실시간 대시보드 |
| **헬스 체크** | http://localhost:8000/health | 서버 상태 확인 |

## 🔄 기존 클라이언트 100% 호환

### ✅ 기존 코드 그대로 사용 가능!

기존 클라이언트 코드를 **한 글자도 수정하지 않고** 그대로 사용할 수 있습니다:

```python
def request_inpaint(self, image: np.ndarray, mask: np.ndarray) -> np.ndarray:
    try:
        # 서버 상태 확인
        if not self.is_server_alive(self.inpaint_base_url):
            return None

        # 이미지를 base64로 인코딩
        _, img_encoded = cv2.imencode('.png', image)
        _, mask_encoded = cv2.imencode('.png', mask)
        img_b64 = base64.b64encode(img_encoded).decode('utf-8')
        mask_b64 = base64.b64encode(mask_encoded).decode('utf-8')
        
        payload = {
            "image": img_b64,
            "mask": mask_b64
            # model_name 누락 시 자동으로 "simple-lama" 사용
        }
        
        response = requests.post(self.inpaint_api_url, json=payload, timeout=(5, 45))
        
        if response.status_code != 200:
            return None
        
        # 바이너리 PNG 응답 처리 (기존과 동일)
        nparr = np.frombuffer(response.content, np.uint8)
        result = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
        return result
        
    except Exception as e:
        return None
```

### 🎯 호환성 보장 기능

| 기능 | 기존 동작 | 서버 처리 | 상태 |
|------|-----------|-----------|------|
| **model_name 누락** | 필드 없음 | 자동으로 기본값 사용 | ✅ 호환 |
| **바이너리 PNG 응답** | `response.content` 직접 사용 | 기본값으로 바이너리 반환 | ✅ 호환 |
| **에러 처리** | `status_code != 200` 확인 | 동일한 HTTP 상태 코드 | ✅ 호환 |
| **타임아웃** | `timeout=(5, 45)` | 서버에서 적절히 처리 | ✅ 호환 |

### 🧪 호환성 테스트

```bash
# 기존 클라이언트 호환성 테스트 실행
python tests/scripts/test_compatibility.py

# 예상 결과:
# 🎯 테스트 결과
# 성공: 2/2
# 성공률: 100.0%
# 🎉 모든 테스트가 성공했습니다!
```

## 📡 API 엔드포인트

### 🎨 인페인팅 API

#### 기본 사용법 (기존 클라이언트 호환)
```http
POST /api/v1/inpaint
Content-Type: application/json

{
  "image": "base64_encoded_image",
  "mask": "base64_encoded_mask"
  // model_name 생략 시 자동으로 "simple-lama" 사용
}

# 응답: 바이너리 PNG 이미지 (기본값)
```

#### 고급 사용법 (새로운 기능)
```http
POST /api/v1/inpaint?response_format=json&image_format=webp
Content-Type: application/json

{
  "image": "base64_encoded_image",
  "mask": "base64_encoded_mask",
  "model_name": "migan",           // 모델 선택
  "sd_seed": 42,                   // 시드 설정
  "prompt": "",                    // 프롬프트 (향후 확장)
  "negative_prompt": "",           // 네거티브 프롬프트
  "num_inference_steps": 20,       // 추론 스텝
  "guidance_scale": 7.5,           // 가이던스 스케일
  "strength": 1.0                  // 인페인팅 강도
}

# 응답: JSON 형식
{
  "success": true,
  "image": "base64_encoded_result",
  "processing_time": 1.23
}
```

### 🖼️ 배경 제거 API

#### 기본 사용법 (기존 클라이언트 호환)
```http
POST /api/v1/remove_bg
Content-Type: application/json

{
  "image": "base64_encoded_image"
  // model_name 생략 시 자동으로 "rembg" 사용
}

# 응답: 바이너리 PNG 이미지 (기본값)
```

#### 고급 사용법 (새로운 기능)
```http
POST /api/v1/remove_bg?response_format=json&image_format=webp
Content-Type: application/json

{
  "image": "base64_encoded_image",
  "model_name": "rembg"
}

# 응답: JSON 형식 (이미지 + 마스크)
{
  "success": true,
  "image": "base64_encoded_result",
  "mask": "base64_encoded_mask",
  "processing_time": 0.45
}
```

### 🔧 시스템 API

```http
# 서버 설정 정보
GET /api/v1/server-config

# 사용 가능한 샘플러 목록
GET /api/v1/samplers

# 헬스 체크
GET /health
```

## 🎛️ 응답 형식 및 이미지 포맷

### 응답 형식 선택 (`response_format`)

| 형식 | 설명 | 용도 | 기본값 |
|------|------|------|--------|
| `binary` | 바이너리 이미지 | 기존 클라이언트 호환 | ✅ |
| `json` | JSON 형식 | iopaint 호환, 메타데이터 포함 | |
| `stream` | 스트리밍 | 대용량 파일, 실시간 전송 | |

### 이미지 포맷 선택 (`image_format`)

| 포맷 | 압축률 | 품질 | 투명도 | 호환성 | 권장 용도 |
|------|--------|------|--------|--------|-----------|
| `png` | 낮음 | 무손실 | ✅ | 최고 | 기존 클라이언트, 정확성 중요 |
| `webp` | 높음 | 무손실/손실 | ✅ | 좋음 | 새 클라이언트, 대역폭 절약 |
| `jpeg` | 높음 | 손실 | ❌ | 최고 | 사진, 호환성 중요 |

### 사용 예시

```python
# 기존 방식 (바이너리 PNG) - 기본값
response = requests.post("http://localhost:8000/api/v1/inpaint", json=payload)

# WebP로 25-35% 용량 절약
response = requests.post("http://localhost:8000/api/v1/inpaint?response_format=binary&image_format=webp", json=payload)

# JSON 응답으로 처리 시간 정보 포함
response = requests.post("http://localhost:8000/api/v1/inpaint?response_format=json", json=payload)
data = response.json()
print(f"처리 시간: {data['processing_time']:.2f}초")

# 스트리밍 응답 (대용량 파일)
response = requests.post("http://localhost:8000/api/v1/inpaint?response_format=stream", json=payload)
```

## 📊 실시간 모니터링 대시보드

### 접속 URL
**http://localhost:8001**

### 주요 기능

#### ⚡ 성능 지표
- **RPS**: 초당 요청 수
- **동시 요청**: 현재/최대 동시 요청 수
- **응답 시간**: 최소/최대/평균 응답시간
- **가동시간**: 서버 가동 시간

#### 🌐 엔드포인트 분석
- **API별 통계**: 인페인팅, 배경제거 각각의 요청 수
- **응답시간 분석**: 엔드포인트별 성능 비교
- **진행 중인 요청**: 실시간 요청 추적
- **성공률**: 성공/실패 통계

#### 🖥️ 시스템 모니터링
- **CPU**: 사용률, 온도, 클럭
- **메모리**: RAM/SWAP 사용량
- **GPU**: 사용률, VRAM, 온도
- **네트워크**: I/O 통계
- **디스크**: 사용량, I/O

#### 👥 워커 관리
- **워커 상태**: 활성/유휴/에러 워커 수
- **작업 큐**: 대기 중인 작업 수
- **워커 통계**: 워커별 처리 통계

#### 🎯 모델 세션 풀
- **LAMA 세션**: 사용 중/대기 중 세션
- **MIGAN 세션**: 세션 풀 상태
- **REMBG 세션**: 세션 효율성
- **메모리 사용**: 세션별 VRAM 사용량

#### 🚨 실시간 알림
- **리소스 경고**: CPU/GPU/메모리 임계값 초과
- **에러 알림**: API 에러 발생 시 알림
- **성능 경고**: 응답시간 임계값 초과

### 모니터링 API

```http
# 간단한 상태 정보
GET /api/simple
{
  "timestamp": 1234567890.123,
  "system_type": "Jetson Xavier",
  "cpu_percent": 15.2,
  "memory_percent": 45.8,
  "status": "running"
}

# 전체 상태 정보
GET /api/status

# 워커 상태
GET /api/worker-status

# 세션 풀 상태  
GET /api/session-status

# WebSocket 실시간 데이터
WebSocket /ws
```

## 🧪 테스트 및 검증

### 자동 테스트 실행

```bash
# 전체 iopaint 호환성 테스트
python tests/scripts/test_api.py

# 기존 클라이언트 호환성 테스트
python tests/scripts/test_compatibility.py

# 특정 기능 테스트
python tests/scripts/test_api.py --single inpaint
python tests/scripts/test_api.py --single rembg
python tests/scripts/test_api.py --single health
```

### 성능 벤치마크

```bash
# API 성능 테스트
python tests/scripts/benchmark.py

# 동시 요청 테스트
python tests/scripts/stress_test.py --concurrent 10
```

## 🛠️ 서버 관리

### 서버 시작

```bash
# 기본 시작 (메인 + 모니터링)
./scripts/start_server.sh

# Jetson Xavier 최적화
./scripts/start_server.sh --jetson-optimize

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

# 모니터링 없이 메인만
./scripts/start_server.sh --no-monitoring

# 워커 수와 GPU 지정
./scripts/start_server.sh --workers 4 --gpu 0
```

### 서버 상태 확인

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

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

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

### 서버 중지

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

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

## 🚁 Jetson Xavier 전용 기능

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

### 성능 최적화
- **전력 모드**: MAXN 모드로 최고 성능
- **GPU 클럭**: 1377MHz로 최대 성능
- **메모리 클럭**: 1600MHz 고속 설정
- **팬 제어**: 자동 온도 관리

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

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

```bash
# Jetson 전용 모니터링 명령어
jtop                    # 실시간 시스템 모니터링
nvpmodel -q            # 현재 전력 모드 확인
tegrastats             # GPU/CPU 통계
```

## 🔧 고급 설정

### 환경 변수 설정

```bash
# .env 파일 편집
cp .env.example .env
nano .env
```

```env
# 서버 설정
MAIN_SERVER_PORT=8000
MONITORING_PORT=8001
WORKERS=1

# GPU 설정
GPU_DEVICE=0
MAX_VRAM_USAGE=0.7

# 파일 설정
MAX_FILE_SIZE=50
MAX_IMAGE_SIZE=2048

# Jetson 최적화
JETSON_OPTIMIZE=true
FAN_CONTROL=true
```

### 모델 설정

```python
# app/core/config.py에서 모델 설정 변경
AVAILABLE_MODELS = {
    "simple-lama": {
        "type": "inpainting",
        "path": "app/models/pt/big-lama.pt",
        "device": "cuda"
    },
    "migan": {
        "type": "inpainting", 
        "path": "app/models/onnx/migan_pipeline_v2.onnx",
        "device": "cuda"
    },
    "rembg": {
        "type": "background_removal",
        "models": ["u2net", "u2netp", "silueta"]
    }
}
```

## 🐛 문제 해결

### 일반적인 문제

#### 서버가 시작되지 않는 경우
```bash
# 로그 확인
tail -f logs/main_server.log
tail -f logs/monitoring.log

# 포트 사용 확인
netstat -tlnp | grep -E "(8000|8001)"

# 의존성 재설치
pip install -r requirements.txt --force-reinstall
```

#### GPU 메모리 부족
```bash
# VRAM 사용량 확인
nvidia-smi

# 워커 수 줄이기
./scripts/start_server.sh --workers 1

# 이미지 크기 제한 확인
# .env 파일에서 MAX_IMAGE_SIZE 조정
```

#### 모델 파일 누락
```bash
# 모델 디렉토리 확인
ls -la app/models/pt/
ls -la app/models/onnx/

# 모델 파일 다운로드 (수동)
# README의 모델 다운로드 섹션 참조
```

### Jetson 전용 문제

#### ONNX Runtime GPU 설치 (GLIBCXX 호환성 문제)

Jetson Xavier에서 ONNX Runtime GPU를 사용하려면 특별한 절차가 필요합니다:

```bash
# 1. GCC 11 업그레이드 (필수)
sudo apt install software-properties-common
sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt update
sudo apt install gcc-11 g++-11

# 2. Jetson 전용 ONNX Runtime GPU 휠 다운로드 및 설치
wget https://nvidia.box.com/shared/static/zostg6agm00fb6t5uisw51qi6kpcuwzd.whl \
   -O onnxruntime_gpu-1.17.0-cp38-cp38-linux_aarch64.whl
pip install --force-reinstall onnxruntime_gpu-1.17.0-cp38-cp38-linux_aarch64.whl

# 3. 설치 확인
python -c "import onnxruntime as ort; print('ONNX Runtime 버전:', ort.__version__); print('Available providers:', ort.get_available_providers())"
```

**예상 출력**:
```
ONNX Runtime 버전: 1.17.0
Available providers: ['TensorrtExecutionProvider', 'CUDAExecutionProvider', 'CPUExecutionProvider']
```

> **참고**: 자동 설치 스크립트를 사용하면 위 과정이 자동으로 수행됩니다.

#### 전력 모드 설정
```bash
# MAXN 모드로 설정
sudo nvpmodel -m 0

# 현재 모드 확인
nvpmodel -q
```

#### 온도 문제
```bash
# 온도 확인
cat /sys/devices/virtual/thermal/thermal_zone*/temp

# 팬 속도 확인
cat /sys/devices/pwm-fan/target_pwm
```

## 📚 추가 리소스

### 문서
- [API 문서](http://localhost:8000/docs) - Swagger UI
- [모니터링 대시보드](http://localhost:8001) - 실시간 모니터링
- [개발자 가이드](docs/developer_guide.md)
- [배포 가이드](docs/deployment_guide.md)

### 커뮤니티
- [GitHub Issues](https://github.com/your-repo/issues) - 버그 리포트 및 기능 요청
- [Discussions](https://github.com/your-repo/discussions) - 질문 및 토론

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

---

## 🎉 빠른 시작 요약

```bash
# 1. 프로젝트 클론
git clone <repository-url> inpaintServer && cd inpaintServer

# 2. 원클릭 설치 및 실행
chmod +x scripts/*.sh && ./scripts/setup_and_run.sh

# 3. 접속 확인
curl http://localhost:8000/health
curl http://localhost:8001/api/simple

# 4. 기존 클라이언트 호환성 테스트
python tests/scripts/test_compatibility.py
```

**🎯 결과**: 기존 클라이언트 코드 수정 없이 100% 호환! 🚀

---

*Made with ❤️ for high-performance AI inference*