7.1 KiB

Raw Permalink Blame History

MIGAN 인페인팅 모듈 설정 안내

개요

MIGAN ONNX 파이프라인을 사용한 전체 이미지 인페인팅 모듈이 추가되었습니다. 기존 ROI 기반 인페인팅과 함께 사용할 수 있으며, toggle_states를 통해 선택할 수 있습니다.

모델 파일 설정

1. 모델 디렉토리 생성

mkdir -p worker/models

2. MIGAN 모델 파일 배치

migan_pipeline_v2.onnx 파일을 다음 경로에 배치하세요:

worker/models/migan_pipeline_v2.onnx

3. TensorRT 캐시 디렉토리 (선택사항)

TensorRT 엔진 캐시를 위한 디렉토리:

mkdir -p /app/temp_files/trt_cache

사용 방법

인페인팅 방법 선택

toggle_states에서 inpaint_method 키를 통해 인페인팅 방법을 선택할 수 있습니다:

# ROI 기반 인페인팅 (기본값)
toggle_states = {
    "inpaint_method": "roi"
}

# MIGAN 전체 이미지 인페인팅
toggle_states = {
    "inpaint_method": "migan"
}

MIGAN 설정 옵션

기본 설정

toggle_states = {
    "inpaint_method": "migan",
    "migan_onnx_path": "/app/worker/models/migan_pipeline_v2.onnx",
    "migan_use_cuda": True,
    "migan_use_tensorrt": True,
    "migan_trt_fp16_enable": True,
    "migan_trt_engine_cache_enable": True,
    "migan_max_image_size": 1600,
    "migan_output_max_width": 800,
    "migan_enable_output_resize": True
}

설정 옵션 설명

ONNX 모델 설정:

migan_onnx_path: ONNX 모델 파일 경로
migan_use_cuda: CUDA 사용 여부 (기본: True)
migan_intra_threads: ONNX Runtime 스레드 수 (기본: 0 = 자동)
migan_inter_threads: ONNX Runtime 스레드 수 (기본: 0 = 자동)

TensorRT 최적화:

migan_use_tensorrt: TensorRT 사용 여부 (기본: True)
migan_trt_fp16_enable: FP16 최적화 활성화 (기본: True)
migan_trt_engine_cache_enable: 엔진 캐시 활성화 (기본: True)

이미지 처리:

migan_max_image_size: 최대 이미지 크기 제한 (긴 변 기준, 기본: 1600px)
migan_output_max_width: 출력 최대 가로 크기 (기본: 800px)
migan_enable_output_resize: 출력 크기 조정 활성화 (기본: True)

직접 모듈 사용 (개발/테스트용)

from worker.migan_inpainting_module import MIGANInpaintingModule

# ⚠️ 프로덕션에서는 celery_worker의 전역 인스턴스 사용 권장
inpainter = MIGANInpaintingModule(config={
    'use_cuda': True,
    'max_image_size': 1600
})

# 인페인팅 실행
result = inpainter.inpaint_with_migan(image, mask)
# cleanup_memory() 호출하지 말 것 - 전역 인스턴스는 계속 유지

전역 인스턴스 사용 (권장)

# celery_worker.py에서 자동으로 처리됨
# toggle_states만 설정하면 됨

toggle_states = {
    "inpaint_method": "migan",
    "migan_use_tensorrt": True,
    "migan_trt_fp16_enable": True,
    "migan_max_image_size": 2048
}

# worker가 자동으로 전역 인스턴스를 사용하고 설정을 동적 업데이트

주요 특징

MIGAN vs ROI 인페인팅 비교

항목	MIGAN	ROI
처리 방식	전체 이미지	영역별 분할
전처리	모델 내장	외부 처리
ROI 분석	불필요	필수
메모리 사용	고정적	적응적
속도	일정	영역 수에 따라 변동
품질	일관적	영역별 최적화

MIGAN 모듈 장점

내장 전처리: 리사이즈, 정규화 등이 ONNX 모델에 포함
TensorRT 최적화: FP16, 엔진 캐시를 통한 성능 향상
세션 재사용: 메모리 효율성 및 초기화 시간 단축
자동 폴백: MIGAN 실패 시 ROI 방식으로 자동 전환
크기 제한: 메모리 사용량 제어를 위한 이미지 크기 제한
🔥 전역 인스턴스: 모델은 한 번만 로딩되어 메모리에 상주
🔥 동적 설정: 실행 중 설정 변경 가능 (필요시 세션 재생성)

환경 변수

# TensorRT 엔진 캐시 디렉토리 (선택사항)
export TRT_ENGINE_CACHE_DIR="/app/temp_files/trt_cache"

# 디버그 아티팩트 저장 디렉토리
export DEBUG_DUMP_DIR="/app/temp_files/debug"

로그 분석

정상 처리 로그 예시

[MIGAN] ONNX Runtime 세션 생성 완료: ['TensorrtExecutionProvider', 'CUDAExecutionProvider', 'CPUExecutionProvider']
[INPAINT] MIGAN 처리 통계: 마스크 커버리지 15.3%, 최대 크기 제한: 1600px
이미지 스케일링: 2000x1500 → 1600x1200 (factor=0.800)
MIGAN 인페인팅 완료: 총 1.234s (추론: 0.987s)

에러 및 폴백 로그 예시

[MIGAN] ONNX 파일을 찾을 수 없습니다: /app/worker/models/migan_pipeline_v2.onnx
[INPAINT] MIGAN 인페인팅 실패, ROI로 폴백: FileNotFoundError

메모리 관리 및 성능

전역 인스턴스 방식

모델 로딩: 워커 프로세스 시작 시 한 번만 로딩
메모리 상주: 모델이 메모리에 계속 유지되어 초기화 오버헤드 없음
세션 재사용: ONNX Runtime 세션이 캐시되어 반복 사용
동적 설정: 필요시에만 세션 재생성 (경로 변경 등)

주의사항

cleanup_memory() 메소드를 전역 인스턴스에서 호출하지 마세요
프로덕션 환경에서는 celery_worker의 전역 인스턴스를 사용하세요
개발/테스트에서만 직접 인스턴스 생성을 사용하세요

성능 최적화 팁

TensorRT 활용: GPU가 있는 환경에서는 TensorRT를 활성화하여 성능 향상
엔진 캐시: 첫 실행 후 생성되는 TensorRT 엔진을 캐시하여 재시작 시 빠른 로딩
크기 제한: 메모리 부족 시 migan_max_image_size를 조정하여 처리 가능한 크기로 제한
출력 크기: 클라이언트 요구사항에 맞춰 migan_output_max_width 조정

문제 해결

일반적인 문제들

모델 파일 없음
- 에러: FileNotFoundError: ONNX 파일을 찾을 수 없습니다
- 해결: worker/models/migan_pipeline_v2.onnx 파일 확인
CUDA 메모리 부족
- 에러: GPU 메모리 관련 오류
- 해결: migan_max_image_size 값을 줄이거나 migan_use_cuda: False로 설정
TensorRT 초기화 실패
- 에러: TensorRT Provider 초기화 실패
- 해결: migan_use_tensorrt: False로 설정하여 CUDA Provider만 사용
세션 생성 실패
- 에러: ONNX Runtime 세션 생성 실패
- 해결: CPU 모드로 폴백 (migan_use_cuda: False)

디버깅

로그 레벨 조정: 디버그 로그를 활성화하여 상세 정보 확인
아티팩트 저장: 디버그 이미지를 저장하여 각 단계별 결과 확인
성능 모니터링: GPU 메모리 사용량 및 처리 시간 모니터링

업데이트 및 확장

새로운 MIGAN 모델 버전을 사용하려면:

새 ONNX 파일을 worker/models/ 디렉토리에 배치
toggle_states에서 migan_onnx_path 업데이트
필요시 입출력 형태에 맞춰 모듈 코드 수정

7.1 KiB Raw Permalink Blame History