Doc-OCR 문서 인식 + 구조화은(는) 무엇을 하나요?
PDF / 스캔본 / 이미지 → 편집 가능한 텍스트 → 구조화된 데이터. 텍스트 레이어가 있는 PDF는 바로 추출, 스캔본은 자동 OCR(macOS Vision 내장, 한글/영문), 문단 레이아웃 복원(다단/복잡한 레이아웃을 읽기 순서대로 재배치, 단순 줄 출력 아님), OCR 후 LLM으로 송장/계약서 필드 추출, 표 변환 가능.
📁 설치:
hermes skills install jiawood2006/hermes-skills/skills/doc-ocr또는 README의 방법 2로 복사 → 기본 위치~/.hermes/skills/utilities/doc-ocr/. 아래 명령어는 해당 경로 기준입니다.
트리거 조건
사용자가 PDF/이미지 파일을 제공하며 다음을 요청:
- "텍스트 추출" "글자 변환" "OCR"
- 스캔본, 계약서, 송장, 책 페이지, 스크린샷 처리
- "송장 정보 추출" "계약서 핵심" "표로 변환" (구조화)
사용 단계
1. 단일 파일 → 텍스트
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py 계약서.pdf
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py 송장.jpg
출력은 <입력파일명>_ocr.txt로 저장됩니다.
2. 디렉토리 일괄 처리 (파일별 오류 허용, 손상 파일에도 중단 없음)
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py ./스캔폴더/ -o 전체.txt
# 일괄 완료 후 요약 출력: 성공 N/M + 실패 목록 (손상 파일만 따로 기록, 전체 중단 없음)
3. Markdown 출력 / 다단 PDF 강제 레이아웃 복원
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py 책.pdf --md
# 다단 PDF에서 텍스트 레이어 순서가 뒤섞인 경우, 강제로 Vision OCR로 레이아웃 복원:
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py 2단논문.pdf --md --force-ocr
4. 구조화 추출 (송장/계약서/표, LLM 키 필요)
# 먼저 OCR 수행 후 필드 추출
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py 송장.jpg
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/docstruct.py 송장_ocr.txt --type invoice
# 계약서 필드 (갑/을, 금액, 기간, 위반 조항)
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/docstruct.py 계약서_ocr.txt --type contract
# 표 → CSV
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/docstruct.py 표_ocr.txt --type table -o 표.csv
--type invoice: 송장 번호/날짜/금액/세액/합계/구매자/판매자/사업자등록번호--type contract: 계약명/갑을 당사자/체결일/금액/지급방식/기간/위반 조항--type table: 행·열 구조 자동 인식 → CSV- 출력은 보기 좋게 표시되며
-o옵션으로 JSON/CSV 저장 가능
의존성 (최초 사용 시 설치)
pip3 install pymupdf pyobjc-framework-Vision
# 구조화 추출 시 LLM 키 필요 (환경변수 LLM_API_KEY 또는 ~/.deai_writer.conf)
참고: OCR은 macOS Vision에 의존합니다(macOS 전용). Linux에서는 tesseract 등 다른 엔진을 별도 설치해야 합니다.
알려진 함정
- 스캔본 판단: PDF 텍스트 레이어가 20자 미만이면 자동으로 OCR을 수행, 일반 PDF는 직접 추출.
- 레이아웃 복원: Vision OCR이 텍스트 박스 좌표를 기준으로 재배치(위→아래, 같은 줄 왼→오); 2단 인쇄물은 "왼쪽 단 먼저, 오른쪽 단 나중"으로 처리되어 논문/보고서에 적합하지만, 잡지의 화려한 레이아웃은 여전히 순서가 어긋날 수 있음 —
--force-ocr+ 육안 확인. - 손글씨: Vision은 인쇄체/깔끔한 손글씨에는 좋지만, 흘린 글씨는 보장하지 않음.
- 프라이버시 강점: 파일은 로컬에서 처리되며 제3자에 업로드되지 않음(구조화 추출 시 LLM API 호출되므로 민감 파일 주의).
- 필드 누락: docstruct는 누락된 필드를 null로 채우고 조작하지 않으며, OCR 품질이 낮으면 필드가 적게 나올 수 있음.
- 일괄 오류 허용: 디렉토리 모드에서 단일 파일 실패는 요약에 기록되지만 전체 처리가 중단되지 않음.
빠른 검증 / Smoke Test
# 설치 확인 (문서 없이도 실행 가능)
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py --help
# 실제 PDF/이미지로 검증
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py 임의문서.pdf --md
# 예상 결과: *_ocr.md 출력, 편집 가능한 텍스트 포함