🖼️ 고성능 인페인팅 서버

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

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

✨ 주요 기능

🎯 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. 프로젝트 클론

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

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

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

플랫폼 자동 감지 설치

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

플랫폼별 직접 설치

🚀 Jetson Xavier (ARM64):

# Jetson Xavier 전용 최적화 설치
bash scripts/setup_jetson.sh

🖥️ x86-64 Desktop:

# x86-64 데스크톱 최적화 설치
bash scripts/setup_x86.sh

📁 가상환경 설정 방식

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

방식 1: 표준 venv 디렉토리 (기본)

python3 -m venv venv
source venv/bin/activate

방식 2: 프로젝트 자체를 가상환경으로 사용

# 프로젝트 디렉토리에서 직접 가상환경 생성
python3 -m venv .
source bin/activate

💡 스마트 감지: 설치 스크립트가 자동으로 감지하고 처리합니다

• venv/ 디렉토리 존재 → 표준 venv 사용
• pyvenv.cfg 파일 존재 → 프로젝트 자체가 가상환경
• 둘 다 없음 → 새로운 venv/ 디렉토리 생성

자동 설치가 수행하는 작업:

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

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

수동 설치 과정 보기

가상환경 설정

# 가상환경 생성
python -m venv venv

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

의존성 설치

# Jetson Xavier
./scripts/install_deps.sh --jetson-optimize

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

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

환경 설정

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

서버 시작

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

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

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

🌐 서버 접속 정보

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

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

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

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

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

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)	서버에서 적절히 처리	✅ 호환

🧪 호환성 테스트

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

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

📡 API 엔드포인트

🎨 인페인팅 API

기본 사용법 (기존 클라이언트 호환)

POST /api/v1/inpaint
Content-Type: application/json

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

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

고급 사용법 (새로운 기능)

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

기본 사용법 (기존 클라이언트 호환)

POST /api/v1/remove_bg
Content-Type: application/json

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

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

고급 사용법 (새로운 기능)

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

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

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

# 헬스 체크
GET /health

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

응답 형식 선택 (response_format)

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

이미지 포맷 선택 (image_format)

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

사용 예시

# 기존 방식 (바이너리 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

# 간단한 상태 정보
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

🧪 테스트 및 검증

자동 테스트 실행

# 전체 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

성능 벤치마크

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

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

🛠️ 서버 관리

서버 시작

# 기본 시작 (메인 + 모니터링)
./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

서버 상태 확인

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

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

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

서버 중지

# 정상 종료
./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: 전력 모드 관리
• 온도 센서: 실시간 온도 모니터링

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

🔧 고급 설정

환경 변수 설정

# .env 파일 편집
cp .env.example .env
nano .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

모델 설정

# 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"]
    }
}

🐛 문제 해결

일반적인 문제

서버가 시작되지 않는 경우

# 로그 확인
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 메모리 부족

# VRAM 사용량 확인
nvidia-smi

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

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

모델 파일 누락

# 모델 디렉토리 확인
ls -la app/models/pt/
ls -la app/models/onnx/

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

Jetson 전용 문제

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

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

# 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']

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

전력 모드 설정

# MAXN 모드로 설정
sudo nvpmodel -m 0

# 현재 모드 확인
nvpmodel -q

온도 문제

# 온도 확인
cat /sys/devices/virtual/thermal/thermal_zone*/temp

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

📚 추가 리소스

문서

• API 문서 - Swagger UI
• 모니터링 대시보드 - 실시간 모니터링
• 개발자 가이드
• 배포 가이드

커뮤니티

• GitHub Issues - 버그 리포트 및 기능 요청
• Discussions - 질문 및 토론

라이선스

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

---

🎉 빠른 시작 요약

# 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