## 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/`에서 롤링 저장, 자세한 타이밍/프로바이더 사용 내역 확인 가능