리드미 업데이트
This commit is contained in:
132
README.md
132
README.md
@@ -1,73 +1,117 @@
|
||||
# OCR Macro: 정답셋 워크플로우
|
||||
# OCR 정답셋 구축 워크플로우
|
||||
|
||||
이 프로젝트는 여러 OCR 모델의 결과물을 효율적으로 비교하고 수정하여, 고품질의 정답셋(Ground Truth) 데이터셋을 구축하기 위한 일련의 도구와 워크플로우를 제공합니다.
|
||||
이 프로젝트는 다양한 OCR 모델의 결과물을 효율적으로 비교하고 수정하여, 고품질의 정답셋(Ground Truth) 데이터셋을 구축하기 위한 워크플로우와 도구를 제공합니다.
|
||||
|
||||
## 프로젝트 개요
|
||||
## ✨ 주요 기능
|
||||
|
||||
프로젝트는 크게 두 가지 핵심 도구로 구성됩니다.
|
||||
### OCR 실행 스크립트
|
||||
|
||||
1. **`run_ocr.py`**: 대량의 문서를 OCR API로 보내고 결과를 자동으로 저장하는 CLI 스크립트.
|
||||
2. **`app.py`**: OCR 결과물을 원본과 비교하며 수정하고, 정답셋을 생성하는 Streamlit 기반 웹 애플리케이션.
|
||||
- **일괄 처리**: 디렉토리 내의 모든 문서(이미지, PDF)에 대해 OCR 작업을 한 번에 수행합니다.
|
||||
- **다중 모델 지원**: `upstage`, `pp-ocr`, `pp-structure` 등 여러 OCR 엔진을 선택하여 사용할 수 있습니다.
|
||||
- **유연한 실행 방식**: 여러 파일을 동시에 처리하는 **병렬 모드**와 API 요청 제한(RPS)에 대응하기 위한 **순차 모드**를 모두 지원합니다.
|
||||
- **안정적인 실행**: API 요청 실패 시 자동으로 재시도하는 로직이 포함되어 안정성을 높였습니다.
|
||||
|
||||
## 구성 요소 상세
|
||||
### 정답셋 검수 웹앱 (Streamlit)
|
||||
|
||||
### 1. `workspace/run_ocr.py`
|
||||
- **3-Way 비교 뷰**: **원본 문서**, **AI 모델 결과**, **정답셋 편집기**를 한 화면에서 직관적으로 비교하며 작업할 수 있습니다.
|
||||
- **세션 기반 협업**: 생성된 고유 URL을 공유하여 여러 작업자가 동일한 환경에서 협업할 수 있습니다.
|
||||
- **작업 상태 추적**: 완료된 파일은 목록에 `✅` 아이콘으로 표시되어 작업 현황을 쉽게 파악하고 중복 작업을 방지합니다.
|
||||
- **결과물 간편 다운로드**: 작업이 완료된 모든 정답셋을 `.zip` 파일 하나로 간편하게 내려받을 수 있습니다.
|
||||
|
||||
대량의 문서에 대한 OCR을 자동화하는 커맨드 라인 인터페이스(CLI) 스크립트입니다.
|
||||
## 🗂️ 권장 디렉토리 구조
|
||||
|
||||
- **주요 기능**: 병렬 처리, 자동 재시도(Exponential Backoff), OCR 공급자 선택(`paddle`/`upstage`), 순차 처리 모드(API의 RPS 제한 대응).
|
||||
- **사용법**: `docs/run_ocr_readme.md` 파일 참조.
|
||||
```
|
||||
ocr_macro/
|
||||
├── source_documents/ # 원본 이미지/PDF 파일
|
||||
├── results/
|
||||
│ ├── pp-ocr/ # pp-ocr 결과 JSON 파일
|
||||
│ └── upstage/ # upstage 결과 JSON 파일
|
||||
├── workspace/
|
||||
│ ├── app.py # 정답셋 검수 웹앱
|
||||
│ ├── run_ocr3.py # OCR 자동화 스크립트 (최신 버전)
|
||||
│ ├── shared_sessions/ # 웹앱 작업 세션 데이터 (자동 생성)
|
||||
│ └── ...
|
||||
├── docker-compose.yml
|
||||
├── requirements.txt
|
||||
└── README.md # 현재 파일
|
||||
```
|
||||
|
||||
### 2. `workspace/app.py`
|
||||
## 🚀 시작하기
|
||||
|
||||
OCR 결과물을 시각적으로 비교하고 수정하여 정답셋을 생성하는 Streamlit 기반 웹 애플리케이션입니다.
|
||||
### 1. 사전 준비
|
||||
|
||||
- **주요 기능**: 세션 기반 협업, 3-Way 비교 뷰, 동적 레이아웃, 작업 완료 상태 추적, 정답셋 재수정, 결과물 zip 다운로드.
|
||||
- **사용법**: `docs/app_readme.md` 파일 참조.
|
||||
- Python (3.8 이상 권장)
|
||||
- Docker 및 Docker Compose
|
||||
|
||||
## 설치 및 실행
|
||||
### 2. 의존성 설치
|
||||
|
||||
### 설치
|
||||
|
||||
프로젝트의 루트 디렉토리에서 다음 명령어를 실행하여 필요한 라이브러리를 설치합니다.
|
||||
프로젝트 루트 디렉토리에서 아래 명령어를 실행하여 필요한 Python 라이브러리를 설치합니다.
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 실행
|
||||
## 🛠️ 사용 방법
|
||||
|
||||
#### OCR 자동화 스크립트
|
||||
### 1단계: OCR 실행 스크립트로 결과 추출하기
|
||||
|
||||
`workspace/run_ocr3.py` 스크립트를 사용하여 원본 문서에서 텍스트를 추출합니다. 이 스크립트는 비동기 API를 호출하고 결과를 JSON 파일로 저장합니다.
|
||||
|
||||
#### 사용 예시
|
||||
|
||||
**예시 1: Upstage 모델로 병렬 처리 (기본)**
|
||||
|
||||
- 4개의 워커(worker)를 사용해 동시에 처리합니다.
|
||||
|
||||
```bash
|
||||
# 예시: upstage 모델을 사용하여 3초 간격으로 순차 처리
|
||||
python workspace/run_ocr.py ./source_documents ./result_jsons/upstage --provider upstage --delay 3
|
||||
python workspace/run_ocr3.py ./source_documents ./results/upstage --model upstage
|
||||
```
|
||||
|
||||
#### 정답셋 생성 웹 애플리케이션
|
||||
**예시 2: pp-ocr 모델 및 워커 수 지정**
|
||||
|
||||
```dockerfile
|
||||
docker compose up
|
||||
- 8개의 워커를 사용해 동시에 처리합니다.
|
||||
|
||||
```bash
|
||||
python workspace/run_ocr3.py ./source_documents ./results/pp-ocr --model pp-ocr --workers 8
|
||||
```
|
||||
|
||||
## 디렉토리 구조 (권장)
|
||||
**예시 3: 순차 처리 (API 요청 제한 대응)**
|
||||
|
||||
- 각 파일 처리 요청 사이에 3초의 간격을 둡니다.
|
||||
|
||||
```bash
|
||||
python workspace/run_ocr3.py ./source_documents ./results/upstage --model upstage --delay 3
|
||||
```
|
||||
ocr_macro/
|
||||
├── source_documents/ # 원본 이미지/PDF 파일
|
||||
├── result_jsons/
|
||||
│ ├── paddle_ocr/ # paddle_ocr 결과 JSON 파일
|
||||
│ └── upstage/ # upstage 결과 JSON 파일
|
||||
├── workspace/
|
||||
│ ├── app.py # 정답셋 생성 웹 앱
|
||||
│ ├── run_ocr.py # OCR 자동화 스크립트
|
||||
│ ├── shared_sessions/ # app.py의 작업 세션 데이터 (자동 생성)
|
||||
│ │ └── {seed}/
|
||||
│ │ ├── docs/
|
||||
│ │ ├── jsons_paddle_ocr/
|
||||
│ │ ├── jsons_upstage/
|
||||
│ │ └── groundtruth/ # 최종 정답셋 (자동 생성)
|
||||
│ └── ...
|
||||
├── requirements.txt
|
||||
└── README.md # 본 파일
|
||||
|
||||
> **참고**: `run_ocr1.py`, `run_ocr2.py`는 이전 버전 또는 다른 API를 위한 스크립트입니다. 특별한 경우가 아니라면 가장 기능이 안정적인 `run_ocr3.py` 사용을 권장합니다.
|
||||
|
||||
### 2단계: 정답셋 검수 웹앱 사용하기
|
||||
|
||||
OCR 결과 생성이 완료되면, `app.py` 웹앱을 사용하여 결과를 비교하고 수정하며 최종 정답셋을 만듭니다.
|
||||
|
||||
**1. 웹앱 실행**
|
||||
|
||||
프로젝트 루트 디렉토리에서 Docker Compose를 사용하여 웹앱을 실행합니다.
|
||||
|
||||
```bash
|
||||
docker-compose up
|
||||
```
|
||||
|
||||
**2. 웹 브라우저 접속**
|
||||
|
||||
터미널에 표시된 주소(예: `http://localhost:8501`)로 접속합니다.
|
||||
|
||||
**3. 작업 흐름**
|
||||
|
||||
1. **파일 업로드**: 사이드바에서 **원본 문서**와 **1단계에서 생성된 OCR 결과 JSON 파일들**을 업로드합니다.
|
||||
2. **세션 생성**: '업로드 및 세션 생성' 버튼을 누르면 작업 가능한 고유 URL이 생성됩니다.
|
||||
3. **검수 및 수정**:
|
||||
- 왼쪽 파일 목록에서 작업할 파일을 선택합니다.
|
||||
- 오른쪽 **정답셋 편집기**에서 내용을 정확하게 수정합니다.
|
||||
4. **저장**: '✅ 정답셋으로 저장' 버튼을 눌러 작업을 완료합니다.
|
||||
5. **다운로드**: 모든 작업이 끝나면 사이드바 하단의 '정답셋 다운로드' 버튼을 눌러 결과물 전체를 `.zip` 파일로 내려받습니다.
|
||||
|
||||
## 📚 상세 문서
|
||||
|
||||
- **[정답셋 검수 웹앱 (`app.py`) 상세 가이드](./docs/app_readme.md)**
|
||||
- **[OCR 실행 스크립트 (`run_ocr3.py`) 상세 가이드](./docs/run_ocr3_readme.md)**
|
||||
Reference in New Issue
Block a user