# OCR 파이프라인 개선 테스트 (ko+eng PDF)

- 일시(KST): 2025-10-22 22:30–23:00
- 작성자: Claude (51124)
- 대상: rb8001 + skill-rag-file (RAG 파일 서비스)

---

## 배경/문제
- NAVER WORKS에서 수신된 이미지 위주 IR PDF가 텍스트 추출 품질이 낮아, RAG 질의(사업분야/매출/팀규모 등) 결과가 미검출(0건)로 이어짐.
- 예시 파일: WORKVISA_IR(2025.10.14).pdf → document_id=611938b0-0cbf-4f32-8765-ffabb90a85b0

## 환경/사전 조건
- 저장 위치: `/mnt/51123data/documents/<team_id>/YYYY-MM/<doc_id>.pdf`
  - 실제 경로: `/mnt/51123data/documents/79441171-3951-4870-beb8-916d07fe8be5/2025-10/611938b0-0cbf-4f32-8765-ffabb90a85b0.pdf`
- 스토리지/임베딩: skill-rag-file 컨테이너(8508) + ChromaDB(내부)

## 재현 절차 및 결과
1) 텍스트 확인(API)
   - `GET http://localhost:8508/api/text/611938b0-...`
   - 결과: chunk_count=4, length≈3226, unique_chars=103, garbage_ratio=0.009, `ocr_used`: 초기 False → 재색인 후 True
   - 본문은 난독 텍스트가 다수(스캔 이미지/비표준 폰트 추정)

2) 재색인(OCR 강제)
   - `POST /api/reindex {"document_id": "611938b0-...", "force_ocr": true}`
   - 결과: `ocr_used: true`, 청크 수 4 그대로(품질 지표 유사)

3) OCRmyPDF 사이드카 비교 테스트
   - 스크립트: `rb8001/tests/test_ocr_pipeline_sidecar.py`
   - 시나리오: Docker 이미지(ocrmypdf)로 `kor+eng` 시도→언어팩 미탑재로 실패, `eng`로 재시도 성공
   - 메트릭 비교(서비스 baseline vs OCRmyPDF-eng):
     - length: 3226 → 2752 (-474)
     - unique_chars: 103 → 98 (-5)
     - korean_ratio: 0.000 → 0.000 (변화 없음)
   - 1차(eng only): 개선 없음 → 한글 언어팩 미탑재 이슈 확인
   - 2차(kor 패키지 설치 후 kor+eng):
     - 실행: `docker run --entrypoint /bin/sh jbarlow83/ocrmypdf:latest -lc "apt-get update && apt-get install -y tesseract-ocr-kor && ocrmypdf ... -l kor+eng --sidecar ..."`
     - 사이드카 텍스트 메트릭: length 3282, unique_chars 317, korean_ratio 0.269
     - 베이스라인 대비: unique_chars +214, korean_ratio +0.269 → 유의미 개선
   - 결론: kor 언어팩 추가 시 품질 개선 확인(ko+eng 조합 필수)

4) RAG 질의 테스트
   - IR 지표 질의(사업 분야/성장률/팀 구성 등): 대부분 0건(문장 구조/키워드 부재)
   - 식별 키워드 질의(예: "workvisa", "Team Building"): 해당 문서 포함해 검색됨(단, 의미 문장 근거는 빈약)

## 추가 테스트: PaddleOCR 사이드카(일회성)
- 스크립트: `rb8001/tests/test_paddleocr_sidecar.py`
- 방법: python:3.11-slim 컨테이너 내에 poppler + `pip install paddlepaddle paddleocr` 설치 → 첫 실행 시 모델 다운로드 후 `/tmp` 이미지 디렉터리 대상으로 CLI 실행
- 결과: 의존성(libGL, glib, gomp) 보완 및 CLI 플래그 정정 후에도 최신 PaddleOCR CLI/모델과 런타임 메모리 제약으로 실패(Exit 137, 타입 에러). 고정 버전 조합이 필요.
- 권장 재시도 환경(고정):
  - 패키지: `paddleocr==2.7.*`, `paddlepaddle==2.5.*`
  - 시스템: `libgl1`, `libglib2.0-0`, `libgomp1`, `poppler-utils`
  - 실행: `paddleocr ocr -i /tmp --lang korean --ocr_version PP-OCRv3 --text_det_limit_side_len 960 --rec_batch_num 1`

## 추가 테스트: CLOVA OCR 사이드카(일회성)
- 스크립트: `rb8001/tests/test_clova_ocr_sidecar.py`
- 방법: 첫 페이지를 300DPI PNG로 변환(poppler) → `CLOVA_OCR_SECRET`(평문/BASE64) + `CLOVA_OCR_URL` 환경변수로 호출 → 라인 텍스트를 `rb8001/state/ocr_tests/<doc>.clova.txt` 저장
- 실행 변수 예시(사용자 제공 기준):
  - `export CLOVA_OCR_SECRET='glQlTOgJtgPQiekrHMXatLpfjVsYDCjv'`
  - `export CLOVA_OCR_URL='http://clovaocr-api-kr.ncloud.com/external/v1/47060/bb80a363f469cf0ac9d46ebbb1b43605105f1348377483de31dbfb3b10ca9b2a'`
  - `python3 rb8001/tests/test_clova_ocr_sidecar.py --team 79441171-3951-4870-beb8-916d07fe8be5 --month 2025-10 --doc 611938b0-0cbf-4f32-8765-ffabb90a85b0`
- 비고: 네트워크/엔드포인트 정책에 따라 응답이 제한될 수 있음. 정상 시 `status: 200`과 라인 수가 출력됨.

## 분석
- 파일은 PDF 내부에 텍스트 레이어가 거의 없고 이미지(XObject) 위주. 
- 현재 강제 OCR(추출 품질 휴리스틱 기반) 수행해도 의미 문장 수준으로 복원되지 않아 IR 질의가 실패.
- 인덱싱 타이밍: 09:06:02 청킹/임베딩 완료 직후 09:06:03 검색 수행(로그 근거) → “인덱싱/OCR 전 검색”은 아님.

## 권장 개선(코드 변경은 별도 PR)
1) OCR 엔진/옵션 고도화
   - ocrmypdf+Tesseract(ko+eng)로 강제 OCR, 데스큐/회전/해상도(300–600DPI) 표준화(한글 언어팩 설치 필수).
   - PaddleOCR(PP-OCRv4) angle classifier 적용(표/도형/한글 자모 분리·잡음 보정 강화).

2) 품질 휴리스틱 상향 및 폴백
   - `garbage_ratio/unique_chars/length` 임계 재조정, OCR 우선 적용 범위 확대.
   - RAG 미검출 시 `/api/text` 요약 폴백(질의→요약→추출)로 최소 정보 확보.

3) 클라우드 OCR 조건부 폴백(선택)
   - Google Vision/NAVER CLOVA/AWS Textract를 저품질 페이지에만 호출(캐시/레이트리밋/비용 상한 포함).

## 검증 포인트(배포 후)
- 동일 문서 재업로드/재색인 시 IR 질의 최소 2개 항목 이상 근거 텍스트 반환.
- `/api/text` 품질 메타(garbage_ratio↓, unique_chars↑) 개선 확인.
- 검색 스니펫이 숫자/표만이 아닌 자연어 문장 포함.

## 교훈 ✍️
- 스캔 기반 한국어 PDF는 단일 OCR로 품질 확보가 어려워, 다단계 하이브리드(OCR 옵션→딥러닝 OCR→클라우드 폴백) 설계가 필요.
- RAG 미검출 시 요약 폴백 경로를 두어 사용자 응답 공백을 줄여야 함.
- 업로드→인덱싱→검색 파이프라인은 상태 확인(청크 수/컬렉션 존재) 후 검색 실행이 안정적.

---

## 조치 완료 (2025-10-23)

권장 개선 사항을 skill-rag-file에 적용 및 배포 완료.

**적용 내역**:
- tesseract-ocr-kor 한글 언어팩 설치 (Dockerfile)
- DPI 200 → 250 상향, kor+eng → eng 폴백 로직 추가 (text_extractor.py)
- 품질 임계값 강화: unique_chars < 50, garbage_ratio > 0.30, korean_ratio 메트릭 추가 (upload.py)
- /api/reindex 엔드포인트 추가 (force_ocr 옵션 지원)

**검증 결과**:
- 동일 문서(611938b0-0cbf-4f32-8765-ffabb90a85b0) 재색인 시:
  - Text Length: 3,226 → 6,327 chars (+96%)
  - Unique Characters: 103 → 390 (+279%)
  - Korean Ratio: 0.0 → 0.194 (+19.4%)
  - Chunk Count: 4 → 10 (+150%)

상세 내역: `251023_claude_skill-rag-file_OCR_품질_개선_배포.md`

---
문서 규칙: `DOCS/300_architecture/312_writing-principles.md` 준수