306 lines
7.1 KiB
Markdown
306 lines
7.1 KiB
Markdown
# MIGAN 인페인팅 모듈 설정 안내
|
|
|
|
## 개요
|
|
MIGAN ONNX 파이프라인을 사용한 전체 이미지 인페인팅 모듈이 추가되었습니다. 기존 ROI 기반 인페인팅과 함께 사용할 수 있으며, `toggle_states`를 통해 선택할 수 있습니다.
|
|
|
|
## 모델 파일 설정
|
|
|
|
### 1. 모델 디렉토리 생성
|
|
```bash
|
|
mkdir -p worker/models
|
|
```
|
|
|
|
### 2. MIGAN 모델 파일 배치
|
|
`migan_pipeline_v2.onnx` 파일을 다음 경로에 배치하세요:
|
|
```
|
|
worker/models/migan_pipeline_v2.onnx
|
|
```
|
|
|
|
### 3. TensorRT 캐시 디렉토리 (선택사항)
|
|
TensorRT 엔진 캐시를 위한 디렉토리:
|
|
```bash
|
|
mkdir -p /app/temp_files/trt_cache
|
|
```
|
|
|
|
## 사용 방법
|
|
|
|
### 인페인팅 방법 선택
|
|
`toggle_states`에서 `inpaint_method` 키를 통해 인페인팅 방법을 선택할 수 있습니다:
|
|
|
|
```python
|
|
# ROI 기반 인페인팅 (기본값)
|
|
toggle_states = {
|
|
"inpaint_method": "roi"
|
|
}
|
|
|
|
# MIGAN 전체 이미지 인페인팅
|
|
toggle_states = {
|
|
"inpaint_method": "migan"
|
|
}
|
|
```
|
|
|
|
### MIGAN 설정 옵션
|
|
|
|
#### 기본 설정
|
|
```python
|
|
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)
|
|
|
|
#### 직접 모듈 사용 (개발/테스트용)
|
|
```python
|
|
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() 호출하지 말 것 - 전역 인스턴스는 계속 유지
|
|
```
|
|
|
|
#### 전역 인스턴스 사용 (권장)
|
|
```python
|
|
# 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 모듈 장점
|
|
1. **내장 전처리**: 리사이즈, 정규화 등이 ONNX 모델에 포함
|
|
2. **TensorRT 최적화**: FP16, 엔진 캐시를 통한 성능 향상
|
|
3. **세션 재사용**: 메모리 효율성 및 초기화 시간 단축
|
|
4. **자동 폴백**: MIGAN 실패 시 ROI 방식으로 자동 전환
|
|
5. **크기 제한**: 메모리 사용량 제어를 위한 이미지 크기 제한
|
|
6. **🔥 전역 인스턴스**: 모델은 한 번만 로딩되어 메모리에 상주
|
|
7. **🔥 동적 설정**: 실행 중 설정 변경 가능 (필요시 세션 재생성)
|
|
|
|
## 환경 변수
|
|
|
|
```bash
|
|
# 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의 전역 인스턴스를 사용하세요
|
|
- 개발/테스트에서만 직접 인스턴스 생성을 사용하세요
|
|
|
|
## 성능 최적화 팁
|
|
|
|
1. **TensorRT 활용**: GPU가 있는 환경에서는 TensorRT를 활성화하여 성능 향상
|
|
2. **엔진 캐시**: 첫 실행 후 생성되는 TensorRT 엔진을 캐시하여 재시작 시 빠른 로딩
|
|
3. **크기 제한**: 메모리 부족 시 `migan_max_image_size`를 조정하여 처리 가능한 크기로 제한
|
|
4. **출력 크기**: 클라이언트 요구사항에 맞춰 `migan_output_max_width` 조정
|
|
|
|
## 문제 해결
|
|
|
|
### 일반적인 문제들
|
|
|
|
1. **모델 파일 없음**
|
|
- 에러: `FileNotFoundError: ONNX 파일을 찾을 수 없습니다`
|
|
- 해결: `worker/models/migan_pipeline_v2.onnx` 파일 확인
|
|
|
|
2. **CUDA 메모리 부족**
|
|
- 에러: GPU 메모리 관련 오류
|
|
- 해결: `migan_max_image_size` 값을 줄이거나 `migan_use_cuda: False`로 설정
|
|
|
|
3. **TensorRT 초기화 실패**
|
|
- 에러: TensorRT Provider 초기화 실패
|
|
- 해결: `migan_use_tensorrt: False`로 설정하여 CUDA Provider만 사용
|
|
|
|
4. **세션 생성 실패**
|
|
- 에러: ONNX Runtime 세션 생성 실패
|
|
- 해결: CPU 모드로 폴백 (`migan_use_cuda: False`)
|
|
|
|
### 디버깅
|
|
|
|
1. **로그 레벨 조정**: 디버그 로그를 활성화하여 상세 정보 확인
|
|
2. **아티팩트 저장**: 디버그 이미지를 저장하여 각 단계별 결과 확인
|
|
3. **성능 모니터링**: GPU 메모리 사용량 및 처리 시간 모니터링
|
|
|
|
## 업데이트 및 확장
|
|
|
|
새로운 MIGAN 모델 버전을 사용하려면:
|
|
1. 새 ONNX 파일을 `worker/models/` 디렉토리에 배치
|
|
2. `toggle_states`에서 `migan_onnx_path` 업데이트
|
|
3. 필요시 입출력 형태에 맞춰 모듈 코드 수정 |