`run_ocr3.py` - 비동기 OCR 실행 스크립트

개요

run_ocr3.py는 지정된 디렉토리 내의 문서 파일(이미지, PDF 등)에 대해 OCR(광학 문자 인식) 작업을 비동기적으로 수행하는 파이썬 스크립트입니다. OCR 서버 API와 연동하여 파일을 업로드하고, 작업 상태를 주기적으로 확인한 후, 최종 텍스트 추출 결과를 JSON 파일로 저장합니다.

이 스크립트는 여러 파일을 효율적으로 처리하기 위해 병렬 처리(기본값)와 순차 처리 모드를 모두 지원합니다.

주요 기능

비동기 OCR 요청: 파일을 서버에 전송하고 즉시 다음 파일 처리를 시작할 수 있습니다.
자동 상태 폴링: 작업이 완료될 때까지 서버에 진행 상태를 자동으로 확인합니다.
결과 추출 및 저장: OCR이 완료되면 filename, ocr_model, duration_sec, parsed 필드를 포함하는 JSON 파일을 생성합니다.
병렬 및 순차 처리:
- 병렬 처리 (기본): 여러 파일을 동시에 처리하여 작업 시간을 단축합니다.
- 순차 처리: 서버 부하를 줄이기 위해 각 파일 요청 사이에 지연 시간을 두고 하나씩 처리합니다.
재시도 로직: 네트워크 오류나 일시적인 서버 오류 발생 시, 자동으로 재시도하여 안정성을 높입니다.
다양한 OCR 모델 지원: pp-ocr, pp-structure, upstage 모델을 선택할 수 있습니다.

사용법

스크립트는 터미널에서 다음 명령어를 사용하여 실행합니다.

python workspace/run_ocr3.py [INPUT_DIR] [OUTPUT_DIR] [OPTIONS]

인수 (Arguments)

INPUT_DIR (필수): OCR을 수행할 원본 파일(이미지, PDF 등)이 들어있는 입력 디렉토리 경로입니다.
OUTPUT_DIR (필수): OCR 결과가 저장될 출력 디렉토리 경로입니다. 디렉토리가 없으면 자동으로 생성됩니다.

옵션 (Options)

--model [MODEL_NAME]
- 사용할 OCR 모델을 지정합니다.
- 선택 가능: pp-ocr, pp-structure, upstage
- 기본값: upstage
--workers [NUMBER]
- 병렬 처리 시 동시에 실행할 스레드(워커)의 수를 지정합니다.
- 숫자가 클수록 더 많은 파일을 동시에 처리하지만, 시스템과 서버에 부하를 줄 수 있습니다.
- 기본값: 4
- --delay 옵션이 0보다 큰 값으로 설정되면 이 옵션은 무시됩니다.
--delay [SECONDS]
- 순차 처리 모드를 활성화하고, 각 파일 요청 사이의 대기 시간(초)을 설정합니다.
- 서버의 동시 요청 제한이 있거나 부하를 최소화해야 할 때 유용합니다.
- 기본값: 0 (병렬 처리 모드)
- 0보다 큰 값을 설정하면 --workers 옵션은 무시되고 순차적으로 처리됩니다.

사용 예시

예시 1: 기본 설정으로 실행 (병렬 처리)

모델: upstage (기본값)
동시 작업: 4개 (기본값)
./source_docs 디렉토리의 파일들을 처리하여 ./ocr_results 디렉토리에 결과를 저장합니다.

python workspace/run_ocr3.py ./source_docs ./ocr_results

예시 2: 다른 모델과 워커 수 지정 (병렬 처리)

모델: pp-ocr
동시 작업: 8개
./invoices 디렉토리의 파일들을 처리하여 ./invoices_json 디렉토리에 결과를 저장합니다.

python workspace/run_ocr3.py ./invoices ./invoices_json --model pp-ocr --workers 8

예시 3: 순차 처리 모드로 실행

모델: pp-structure
처리 방식: 순차 처리 (하나씩)
요청 간 대기: 각 파일 처리 요청 사이에 3초씩 대기합니다.
./pdfs_to_process 디렉토리의 파일들을 처리하여 ./processed_pdfs 디렉토리에 결과를 저장합니다.

python workspace/run_ocr3.py ./pdfs_to_process ./processed_pdfs --model pp-structure --delay 3

출력 결과

스크립트 실행이 완료되면 OUTPUT_DIR에 원본 파일명과 동일한 이름의 .json 파일들이 생성됩니다. 예를 들어, document1.pdf 파일을 처리했다면 document1.json 파일이 생성됩니다.

각 JSON 파일의 구조는 다음과 같습니다.

{
  "filename": "document1.pdf",
  "ocr_model": "upstage",
  "duration_sec": 15.72,
  "parsed": "추출된 텍스트 내용...\n여기에 문서에서 인식된 모든 텍스트가 들어갑니다."
}

filename: 처리된 원본 파일의 이름입니다.
ocr_model: OCR 처리에 사용된 모델의 이름입니다.
duration_sec: 파일 업로드 시작부터 결과 수신 완료까지 걸린 총 시간(초)입니다.
parsed: OCR을 통해 추출된 전체 텍스트 결과입니다.

4.8 KiB Raw Permalink Blame History

run_ocr3.py - 비동기 OCR 실행 스크립트

개요