리드미 추가
This commit is contained in:
103
README.md
103
README.md
@@ -1,88 +1,73 @@
|
||||
# 문서 정보 추출 및 비교 도구
|
||||
# OCR Macro: 정답셋 워크플로우
|
||||
|
||||
이 프로젝트는 문서(이미지, PDF)에서 정보를 추출하고, 그 결과를 원본 문서와 나란히 비교할 수 있는 도구를 제공합니다.
|
||||
이 프로젝트는 여러 OCR 모델의 결과물을 효율적으로 비교하고 수정하여, 고품질의 정답셋(Ground Truth) 데이터셋을 구축하기 위한 일련의 도구와 워크플로우를 제공합니다.
|
||||
|
||||
## 구성 요소
|
||||
## 프로젝트 개요
|
||||
|
||||
1. **추출 스크립트 (`workspace/process_directory.py`)**: 지정된 디렉터리의 모든 파일에 대해 정보 추출 API를 호출하고 결과를 JSON 파일로 저장합니다.
|
||||
2. **비교 웹앱 (`workspace/app.py`)**: Streamlit 기반의 웹 애플리케이션으로, 원본 문서와 추출된 JSON 결과를 업로드하여 시각적으로 비교할 수 있습니다.
|
||||
프로젝트는 크게 두 가지 핵심 도구로 구성됩니다.
|
||||
|
||||
---
|
||||
1. **`run_ocr.py`**: 대량의 문서를 OCR API로 보내고 결과를 자동으로 저장하는 CLI 스크립트.
|
||||
2. **`app.py`**: OCR 결과물을 원본과 비교하며 수정하고, 정답셋을 생성하는 Streamlit 기반 웹 애플리케이션.
|
||||
|
||||
## 1. 추출 스크립트 사용법 (`process_directory.py`)
|
||||
## 구성 요소 상세
|
||||
|
||||
### 사전 준비
|
||||
### 1. `workspace/run_ocr.py`
|
||||
|
||||
스크립트를 실행하기 위해서는 Python 3.6 이상이 필요합니다.
|
||||
대량의 문서에 대한 OCR을 자동화하는 커맨드 라인 인터페이스(CLI) 스크립트입니다.
|
||||
|
||||
#### 1.1. 환경 변수 설정
|
||||
- **주요 기능**: 병렬 처리, 자동 재시도(Exponential Backoff), OCR 공급자 선택(`paddle`/`upstage`), 순차 처리 모드(API의 RPS 제한 대응).
|
||||
- **사용법**: `run_ocr_readme.md` 파일 참조.
|
||||
|
||||
API 서버의 정보는 민감 정보이므로, `workspace` 디렉터리 안에 `.env` 파일을 생성하여 관리합니다.
|
||||
### 2. `workspace/app.py`
|
||||
|
||||
`.env` 파일 예시 (`workspace/.env`):
|
||||
OCR 결과물을 시각적으로 비교하고 수정하여 정답셋을 생성하는 Streamlit 기반 웹 애플리케이션입니다.
|
||||
|
||||
```env
|
||||
BASE_URL="http://172.0.0.1:8888"
|
||||
API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
|
||||
```
|
||||
- **주요 기능**: 세션 기반 협업, 3-Way 비교 뷰, 동적 레이아웃, 작업 완료 상태 추적, 정답셋 재수정, 결과물 zip 다운로드.
|
||||
- **사용법**: `workspace/app_readme.md` 파일 참조.
|
||||
|
||||
**중요:** 이 `.env` 파일은 `.gitignore`에 의해 버전 관리에서 자동으로 제외됩니다.
|
||||
## 설치 및 실행
|
||||
|
||||
#### 1.2. 의존성 설치
|
||||
### 설치
|
||||
|
||||
프로젝트 루트 디렉터리에서 다음 명령어를 실행하여 필요한 라이브러리를 설치합니다.
|
||||
프로젝트의 루트 디렉토리에서 다음 명령어를 실행하여 필요한 라이브러리를 설치합니다.
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 실행 방법
|
||||
### 실행
|
||||
|
||||
프로젝트 루트 디렉터리에서 다음 형식으로 스크립트를 실행합니다.
|
||||
#### OCR 자동화 스크립트
|
||||
|
||||
```bash
|
||||
python workspace/process_directory.py [입력_디렉터리] [옵션]
|
||||
# 예시: upstage 모델을 사용하여 3초 간격으로 순차 처리
|
||||
python workspace/run_ocr.py ./source_documents ./result_jsons/upstage --provider upstage --delay 3
|
||||
```
|
||||
|
||||
#### 인자 설명
|
||||
#### 정답셋 생성 웹 애플리케이션
|
||||
|
||||
- `input_dir` (필수): 처리할 파일들이 들어있는 입력 디렉터리의 경로입니다.
|
||||
- `-o, --output_dir` (선택): 결과 JSON 파일들을 저장할 출력 디렉터리입니다. (기본값: `results`)
|
||||
- `--endpoint` (선택): 호출할 API 엔드포인트를 지정합니다. (`i18n` 또는 `d6c`, 기본값: `i18n`)
|
||||
- `--model` (선택): 사용할 특정 LLM 모델의 이름을 지정합니다.
|
||||
|
||||
#### 실행 예시
|
||||
|
||||
```bash
|
||||
# 'source_documents/data'에 있는 파일들을 'i18n' 엔드포인트로 처리
|
||||
python workspace/process_directory.py source_documents/data
|
||||
|
||||
# 'd6c' 엔드포인트를 사용하여 처리하고 결과를 'my_results' 폴더에 저장
|
||||
python workspace/process_directory.py source_documents/data2 --endpoint d6c -o my_results
|
||||
```dockerfile
|
||||
docker compose up
|
||||
```
|
||||
|
||||
---
|
||||
## 디렉토리 구조 (권장)
|
||||
|
||||
## 2. 비교 웹앱 사용법 (`app.py`)
|
||||
|
||||
이 웹앱을 사용하여 원본 문서와 `process_directory.py` 실행 결과로 생성된 JSON 파일을 시각적으로 비교할 수 있습니다.
|
||||
|
||||
### 실행 방법
|
||||
|
||||
프로젝트 루트 디렉터리에서 다음 명령어를 실행합니다.
|
||||
|
||||
```bash
|
||||
streamlit run workspace/app.py
|
||||
or
|
||||
docker copmose up
|
||||
```
|
||||
|
||||
위 명령어를 실행하면 웹 브라우저에서 비교 도구가 열립니다.
|
||||
|
||||
### 사용 절차
|
||||
|
||||
1. 웹앱이 실행되면 사이드바에 파일 업로드 영역이 나타납니다.
|
||||
2. **"원본 문서 파일(들)을 업로드하세요."** 버튼을 클릭하여 하나 이상의 문서 파일(PDF, PNG, JPG 등)을 업로드합니다.
|
||||
3. **"결과 JSON 파일(들)을 업로드하세요."** 버튼을 클릭하여 해당 문서들의 추출 결과인 JSON 파일들을 업로드합니다.
|
||||
4. 파일들이 성공적으로 매칭되면, **"비교할 파일을 선택하세요."** 드롭다운 메뉴에 파일 목록이 나타납니다.
|
||||
5. 목록에서 파일을 선택하면, 왼쪽에는 원본 문서가, 오른쪽에는 JSON 데이터가 표시되어 내용을 비교할 수 있습니다.
|
||||
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 # 본 파일
|
||||
```
|
||||
|
||||
49
docs/app_readme.md
Normal file
49
docs/app_readme.md
Normal file
@@ -0,0 +1,49 @@
|
||||
# `app.py` - 정답셋 생성 및 비교 도구
|
||||
|
||||
이 문서는 `workspace/app.py` Streamlit 애플리케이션의 기능, 설정 방법, 그리고 사용법을 상세히 설명합니다.
|
||||
|
||||
|
||||
## 1. 주요 기능
|
||||
|
||||
- **세션 기반 협업**: 파일 업로드 시 고유한 URL(`seed`)이 생성되어, 이 링크를 공유하면 여러 명의 작업자가 동일한 환경에서 작업할 수 있습니다.
|
||||
- **3-Way 비교 뷰**: **원본 문서**, **참고용 모델 결과**, **정답셋 편집기**를 한 화면에 표시하여 직관적인 비교와 수정이 가능합니다.
|
||||
- **모델 선택 및 편집**: `paddle_ocr`와 `upstage` 모델 중 하나를 정답셋의 기반으로 선택하고, `parsed` 키의 내용을 직접 수정하여 정답셋을 생성합니다.
|
||||
- **작업 상태 추적**: 정답셋 생성이 완료된 파일은 목록에 `✅` 아이콘으로 표시되어 작업 중복을 방지합니다.
|
||||
- **정답셋 재수정**: 이미 완료된 정답셋도 언제든지 다시 불러와 수정할 수 있습니다.
|
||||
- **동적 레이아웃**: '참고용 영역 숨기기' 옵션을 통해 편집 공간을 넓게 확보할 수 있습니다.
|
||||
- **결과물 다운로드**: 현재 세션에서 생성된 모든 정답셋을 하나의 `.zip` 파일로 편리하게 다운로드할 수 있습니다.
|
||||
|
||||
## 2. 설정 및 실행
|
||||
|
||||
### 실행
|
||||
|
||||
프로젝트의 루트 디렉토리에서 다음 명령어를 실행하여 필요한 라이브러리를 설치합니다.
|
||||
|
||||
```dockerfile
|
||||
docker compose up
|
||||
```
|
||||
|
||||
실행 후 웹 브라우저에서 지정된 로컬 주소(예: `http://localhost:8501`)로 접속합니다.
|
||||
|
||||
## 3. 작업 흐름
|
||||
|
||||
1. **애플리케이션 실행**: 위의 명령어로 앱을 시작합니다.
|
||||
2. **파일 업로드**:
|
||||
- 사이드바의 '파일 업로드' 섹션에서 다음 세 종류의 파일을 모두 업로드합니다.
|
||||
1. **원본 문서** (이미지/PDF)
|
||||
2. **paddle_ocr JSON** 결과물
|
||||
3. **upstage JSON** 결과물
|
||||
- 파일 이름(확장자 제외)이 세 종류 모두 동일해야 목록에 정상적으로 표시됩니다.
|
||||
3. **세션 생성**: '업로드 및 세션 생성' 버튼을 누르면, 고유한 `seed`가 포함된 URL이 생성되며 작업 화면으로 전환됩니다.
|
||||
4. **세션 공유 (선택 사항)**: 생성된 URL을 다른 작업자와 공유하여 협업을 시작할 수 있습니다.
|
||||
5. **파일 선택 및 검수**:
|
||||
- 사이드바의 '파일 탐색' 드롭다운 메뉴에서 검수할 파일을 선택합니다.
|
||||
- 화면 상단의 `◀ 이전` / `다음 ▶` 버튼으로 파일을 이동할 수도 있습니다.
|
||||
6. **정답셋 생성**:
|
||||
- 화면 우측 상단의 버튼을 통해 정답셋의 기반이 될 모델(`paddle_ocr` 또는 `upstage`)을 선택합니다.
|
||||
- 오른쪽 '정답셋 편집' 영역에서 `parsed` 키의 텍스트를 정확하게 수정합니다.
|
||||
- '✅ 정답셋으로 저장' 버튼을 눌러 작업을 완료합니다.
|
||||
7. **작업 반복**: 모든 파일에 대해 5~6번 과정을 반복합니다. 완료된 파일은 목록에 `✅` 아이콘이 표시됩니다.
|
||||
8. **정답셋 다운로드**:
|
||||
- 모든 작업이 완료되면, 사이드바 하단의 '내보내기' 섹션에서 '정답셋 다운로드 (.zip)' 버튼을 눌러 결과물을 다운로드합니다.
|
||||
- 다운로드된 파일은 현재 세션의 `groundtruth` 폴더에 저장된 모든 JSON 파일을 포함합니다.
|
||||
62
docs/run_ocr1_readme.md
Normal file
62
docs/run_ocr1_readme.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# 문서 정보 추출 및 비교 도구
|
||||
|
||||
이 프로젝트는 문서(이미지, PDF)에서 정보를 추출하고, 그 결과를 원본 문서와 나란히 비교할 수 있는 도구를 제공합니다.
|
||||
|
||||
## 구성 요소
|
||||
|
||||
1. **추출 스크립트 (`workspace/process_directory.py`)**: 지정된 디렉터리의 모든 파일에 대해 정보 추출 API를 호출하고 결과를 JSON 파일로 저장합니다.
|
||||
2. **비교 웹앱 (`workspace/app.py`)**: Streamlit 기반의 웹 애플리케이션으로, 원본 문서와 추출된 JSON 결과를 업로드하여 시각적으로 비교할 수 있습니다.
|
||||
|
||||
---
|
||||
|
||||
## 1. 추출 스크립트 사용법 (`process_directory.py`)
|
||||
|
||||
### 사전 준비
|
||||
|
||||
스크립트를 실행하기 위해서는 Python 3.6 이상이 필요합니다.
|
||||
|
||||
#### 1.1. 환경 변수 설정
|
||||
|
||||
API 서버의 정보는 민감 정보이므로, `workspace` 디렉터리 안에 `.env` 파일을 생성하여 관리합니다.
|
||||
|
||||
`.env` 파일 예시 (`workspace/.env`):
|
||||
|
||||
```env
|
||||
BASE_URL="http://172.0.0.1:8888"
|
||||
API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
|
||||
```
|
||||
|
||||
**중요:** 이 `.env` 파일은 `.gitignore`에 의해 버전 관리에서 자동으로 제외됩니다.
|
||||
|
||||
#### 1.2. 의존성 설치
|
||||
|
||||
프로젝트 루트 디렉터리에서 다음 명령어를 실행하여 필요한 라이브러리를 설치합니다.
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 실행 방법
|
||||
|
||||
프로젝트 루트 디렉터리에서 다음 형식으로 스크립트를 실행합니다.
|
||||
|
||||
```bash
|
||||
python workspace/process_directory.py [입력_디렉터리] [옵션]
|
||||
```
|
||||
|
||||
#### 인자 설명
|
||||
|
||||
- `input_dir` (필수): 처리할 파일들이 들어있는 입력 디렉터리의 경로입니다.
|
||||
- `-o, --output_dir` (선택): 결과 JSON 파일들을 저장할 출력 디렉터리입니다. (기본값: `results`)
|
||||
- `--endpoint` (선택): 호출할 API 엔드포인트를 지정합니다. (`i18n` 또는 `d6c`, 기본값: `i18n`)
|
||||
- `--model` (선택): 사용할 특정 LLM 모델의 이름을 지정합니다.
|
||||
|
||||
#### 실행 예시
|
||||
|
||||
```bash
|
||||
# 'source_documents/data'에 있는 파일들을 'i18n' 엔드포인트로 처리
|
||||
python workspace/process_directory.py source_documents/data
|
||||
|
||||
# 'd6c' 엔드포인트를 사용하여 처리하고 결과를 'my_results' 폴더에 저장
|
||||
python workspace/process_directory.py source_documents/data2 --endpoint d6c -o my_results
|
||||
```
|
||||
70
docs/run_ocr2_readme.md
Normal file
70
docs/run_ocr2_readme.md
Normal file
@@ -0,0 +1,70 @@
|
||||
# `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
|
||||
```
|
||||
Reference in New Issue
Block a user