# `run_ocr.py` 스크립트 사용법

이 문서는 `workspace/run_ocr.py` 스크립트를 사용하여 디렉토리 내의 여러 이미지 및 PDF 파일에 대해 OCR(광학 문자 인식)을 일괄 수행하는 방법을 설명합니다.

## 개요

`run_ocr.py`는 지정된 입력 폴더에 있는 모든 파일을 비동기 OCR API 서버로 전송하고, 처리 완료된 결과를 지정된 출력 폴더에 JSON 파일로 저장하는 커맨드 라인 도구입니다. **병렬 처리**와 **순차 처리** 두 가지 모드를 모두 지원합니다.

## 주요 기능

- **듀얼 모드 지원**:
  - **병렬 처리 (기본)**: 여러 파일을 동시에 처리하여 작업 시간을 대폭 단축합니다.
  - **순차 처리**: 초당 요청 수(RPS) 제한이 있는 API를 위해, 각 요청 사이에 지정된 시간만큼 대기하며 파일을 하나씩 처리합니다.
- **OCR 공급자 선택**: `paddle`과 `upstage` 두 가지 OCR 엔진을 선택할 수 있습니다.
- **자동 재시도**: 네트워크 오류나 서버의 일시적인 문제가 발생하면, "Exponential Backoff + Jitter" 방식으로 지능적으로 재시도하여 안정성을 높였습니다.
- **진행 상황 및 결과 요약**: 전체 진행 상황과 최종 성공/실패/건너뜀 건수를 명확하게 보여줍니다.

## 전제 조건

스크립트를 실행하기 위해서는 Python과 `requests` 라이브러리가 필요합니다. 프로젝트의 `requirements.txt` 파일에 필요한 라이브러리가 명시되어 있습니다.

```bash
pip install -r requirements.txt
```

## 사용법

스크립트는 프로젝트 루트 디렉토리에서 다음 형식의 명령어로 실행합니다.

```bash
python workspace/run_ocr.py [입력_디렉토리] [출력_디렉토리] [옵션...]
```

### 인자 설명

- `입력_디렉토리` (필수): OCR을 수행할 원본 이미지/PDF 파일들이 들어있는 폴더의 경로입니다.
- `출력_디렉토리` (필수): OCR 결과 JSON 파일이 저장될 폴더의 경로입니다. 폴더가 존재하지 않으면 자동으로 생성됩니다.
- `--provider` (선택): 사용할 OCR 공급자를 지정합니다. (기본값: `paddle`)
  - `paddle`: Paddle OCR 사용
  - `upstage`: Upstage OCR 사용
- `--workers` (선택): **병렬 처리 시** 동시에 처리할 파일의 개수(스레드 수)를 지정합니다. (기본값: 4)
  - `--delay` 옵션이 활성화되면 이 값은 무시됩니다.
- `--delay` (선택): **순차 처리 시** 각 요청 사이의 대기 시간(초)을 설정합니다. (기본값: 0)
  - 이 값을 0보다 크게 설정하면, 스크립트는 `--workers` 설정을 무시하고 순차 처리 모드로 강제 실행됩니다.

## 실행 예시

### 예시 1: 병렬 처리 (기본)

`source_documents` 폴더의 파일들을 **Paddle OCR**로, **4개씩 동시에** 처리하여 `result_jsons` 폴더에 저장합니다.

```bash
python workspace/run_ocr.py ./source_documents ./result_jsons
```

### 예시 2: 병렬 처리 (옵션 지정)

`source_documents` 폴더의 파일들을 **Upstage OCR**로, **10개씩 동시에** 처리하여 `result_jsons_upstage` 폴더에 저장합니다.

```bash
python workspace/run_ocr.py ./source_documents ./result_jsons_upstage --provider upstage --workers 10
```

### 예시 3: 순차 처리 (RPS 제한 대응)

`source_documents` 폴더의 파일들을 **Upstage OCR**로, **하나씩 순서대로** 분리하되 **각 요청 사이에 3초씩 대기**하여 `result_jsons_upstage` 폴더에 저장합니다.

```bash
python workspace/run_ocr.py ./source_documents ./result_jsons_upstage --provider upstage --delay 3
```