`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 파일에 필요한 라이브러리가 명시되어 있습니다.

pip install -r requirements.txt

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

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 설정을 무시하고 순차 처리 모드로 강제 실행됩니다.

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

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

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

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

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

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