Image Worker API (FastAPI)

개요

• 이미지 번역 파이프라인을 별도 프로세스로 격리한 로컬 API 서버입니다.
• 단일 워커 프로세스가 순차 처리하며, OCR 이후에는 번역(I/O)과 마스크 생성(CPU)을 동시 실행해 성능을 높입니다.
• 재시작/메모리 이슈를 대비해 워커 롤링(메모리/건수/업타임), 잡 타임아웃, 롤링 중 버퍼링, 429 백프레셔를 제공합니다.

아키텍처

• FastAPI 서버(가벼움) + 워커 프로세스(무거운 모듈)
• 모듈별 프로바이더 전략(DirectML 우선 → 실패 시 CPU 폴백) 및 성공 프로바이더 캐시
  • OCR: modules/onnx_ocr_module/src/onnx_ocr_wrapper.py
  • MIGAN: modules/migan_module.py
  • Rembg(BriaAI): modules/bria_background_removal_module.py
• 데이터 전달은 파일 경로 기반(대용량 base64 불사용)
• ProgramData 경로 표준화
  • 작업/임시: C:\ProgramData\ImgWorker\work
  • 출력: C:\ProgramData\ImgWorker\outputs

환경변수(.env)

• IMGWK_MAX_PENDING=200 # 큐 대기 한도(가득 차면 429)
• IMGWK_ROLL_MAX_RSS_MB=1800 # 워커 RSS 임계(MB)
• IMGWK_ROLL_MAX_JOBS=500 # 워커 재시작 처리 건수 임계
• IMGWK_ROLL_MAX_UPTIME_SEC=7200 # 워커 업타임 임계(초)
• IMGWK_JOB_TIMEOUT_SEC=600 # 잡 타임아웃(초)
• IMGWK_TEST_ROLL_EVERY_2=0 # (테스트) 2건마다 롤링
• IMGWK_OCR_PROVIDER=auto # auto|dml|cpu (강제 가능)
• IMGWK_REMBG_PROVIDER=auto # rembg용 provider 강제(auto|dml|cpu)
• (선택) 기타 모델 경로/스레드 설정은 토글로 전달

기본 토글(default)

• Rembg: 자체 로컬 사용(use_local_rembg=True)
• Inpaint: MIGAN을 기본(GPU 시도; DirectML→CPU 폴백)
• OCR provider override: .env IMGWK_OCR_PROVIDER(없으면 auto)

프로바이더 선택/폴백/캐시

• 순서: DirectML 우선 → 실패 시 CPU 폴백
• 성공한 프로바이더는 캐시 파일에 저장되어 이후 재초기화 시 재검증 생략
  • OCR: user_data/ocr_provider.json
  • MIGAN: user_data/migan_provider.json
  • Rembg: user_data/rembg_provider.json
• 모델별 강제 설정
  • OCR: 토글 ocr_provider_override = auto|dml|cpu
  • MIGAN: 토글 migan_provider_override = auto|dml|cpu
  • Rembg: 환경변수 IMGWK_REMBG_PROVIDER = auto|dml|cpu

엔드포인트

• GET /health
  • ready 여부, 워커 PID
• GET /info
  • 환경/경로/워커 상태 정보
• POST /v1/process-image
  • Body: { file_path, index, file_prefix?, toggle_overrides?, group_id?, seq? }
  • Return: { accepted: true, job_id }
• POST /v1/remove-background
  • Body: { file_path, file_prefix?, toggle_overrides? }
  • Return: { accepted: true, job_id }
• GET /v1/jobs/{job_id}
  • 상태: queued|running|done|error|cancelled, 결과/오류 포함
• DELETE /v1/jobs/{job_id}
  • queued 상태일 때만 취소
• 제어 엔드포인트
  • POST /v1/ocr/reinit { provider?: 'auto'|'dml'|'cpu' } → OCR 재초기화(프로바이더 반영/캐시)
  • POST /v1/migan/reset { use_cuda?: true|false } → MIGAN 세션 재설정(DirectML 시도/폴백)

파이프라인(1 이미지)

1. 로드/검증 → 2) OCR → 3) [번역, 마스크] 병렬 → 4) 인페인트(MIGAN 기본) → 5) 렌더링 → 6) 저장

• 그룹 순서 보장: 클라이언트는 group_id + seq로 정렬, 서버는 무순서 완료 허용

런타임 변경

• OCR 프로바이더: /v1/ocr/reinit 로 dml/cpu/auto 적용 가능(재초기화)
• MIGAN: /v1/migan/reset 으로 DirectML 사용 여부 전환 가능

운영 팁

• DML 미지원 VM/환경에서는 자동으로 CPU 폴백
• 큐 가득 차면 429 반환 → 재시도 로직 구현 권장
• 롤링 임계는 .env 로 조정
• 로그는 logs/에서 롤링 저장, 자세한 타이밍/프로바이더 사용 내역 확인 가능