Skip to main content

한국어 도서 OCR 파이프라인 — 실행 흐름·구현 현황

이 문서는 /ext001/book001의 현재 Codex·AI 기반 도서 처리 방식과 스킬 소스의 역할을 설명한다. 환경을 다시 설치해야 한다면 환경 구성 가이드를 먼저 본다. 사용자는 PDF를 직접 PaddleOCR·Pandoc 명령으로 처리하지 않고 Codex에게 작업을 맡긴다.

1. 사용자가 Codex에 맡기는 흐름​

Codex에서 /ext001/book001을 작업 폴더로 열고 PDF의 절대 경로와 원하는 단계를 알려준다. 한 권 전체를 만들 때는 다음처럼 요청한다.

/ext001/book001/books/작가/작품명/작품명.pdf를 이 프로젝트의 OCR 3단계 스킬로 처리해 줘. 먼저 대상 도서와 신규·덮어쓰기 파일의 전체 경로가 담긴 실행 계획을 보여줘. 그다음 OCR 추출, 모든 물리 페이지의 원본 이미지 대조 검수, EPUB3 변환·보고서 우려 사항의 원본 대조·최종 표본 검증까지 진행해 줘. EPUB 단계의 전체 체크리스트를 진행에 따라 갱신하고, 마지막에는 확인 범위를 밝힌 도서별 한 줄 평가를 남겨줘. 제목·저자는 확인된 정보만 사용하고, 중단 시 보고서 상태에서 재개해 줘.

이미 TXT·JSON이 있으면 검수부터, 검수 완료 MD가 있으면 EPUB만 요청한다. 일부 페이지만 시험하려면 그 범위를 명시한다. 여러 PDF가 들어 있는 디렉터리를 지정하면 하위 폴더까지 재귀적으로 검색하므로 계획의 도서 목록을 확인한다.

Codex가 쓰는 스킬은 $ocr-pdf-to-txt → $ocr-txt-to-md → $ocr-md-to-epub이며, 공통 규칙은 스킬 공통 사용법에 있다. 단계가 일부만 필요하면 해당 단계만 계획한다. 기존 출력이 있으면 계획에서 대상과 덮어쓰기 파일의 전체 경로를 확인한 뒤 승인된 범위에만 --approve-overwrite를 적용한다. 같은 계획에서 승인된 출력 범위는 보고서에 보존되며, 새 계획에서 생긴 충돌은 다시 확인한다. 원본 PDF 및 검수 입력 TXT·JSON은 해당 후속 단계에서 읽기만 한다.

2. 산출물과 상태 기준​

기본 출력은 입력 옆에 생성된다. --output-dir를 사용하면 출력 루트를 바꿀 수 있고 디렉터리 입력의 상대 하위 경로를 유지한다.

파일현재 역할
작품명.pdf원본 이미지 PDF, 읽기 전용
작품명.txt페이지별 인식 텍스트; 페이지 사이 폼 피드 구분
작품명.jsonocr-extract-1; PDF SHA-256·전체/선택 페이지·완료 표시·PaddleOCR 공식 결과
작품명.md이미지 대조를 마친 독서용 본문과 원본 삽화 참조
작품명.epub검증을 통과한 EPUB3
작품명.ocr-report.md계획·검수 상태·교정 근거·오류·삽화 결정·최종 EPUB 원본 대조·표본 검수 상태의 단일 기록
.작품명.ocr-assets/<PDF 해시 앞부분>/MD·EPUB에서 참조하는 삽화 파일

OCR 완료와 이미지 대조 검수 완료는 다른 상태다. 검수 보고서의 image_checked도 실제 이미지를 입력해 결과를 기록했다는 작업 상태이며 문자 하나하나의 정확성을 보증하지 않는다. 본문 MD에 작업 로그나 물리 페이지 관리 문구를 넣지 않는다. *.ocr-report.md는 EPUB 입력 목록에서 제외된다.

3. 실행기와 단계별 구현​

구현 파일현재 동작
common.py단계·입력별 계획 JSON과 출력 충돌 목록 생성; 기존 파일의 크기·수정 시각 확인; 승인 범위 밖 출력 차단; 대상 디렉터리의 임시 파일로 원자적 교체; 삽화 자산 복사·SHA-256 확인 후 게시
run_pipeline.py요청한 단계만 순서대로 호출; 결과 파일과 입력/출력 해시가 맞는 완료 단계는 건너뜀; 검수 미완료 종료 상태를 받으면 EPUB으로 진행하지 않음
extract.pypdfinfo로 물리 페이지 수 확인; 300 DPI 임시 PNG로 각 페이지 렌더링; 한국어 PP-OCRv5 CPU 모델을 한 번 초기화해 OCR; TXT·JSON을 함께 검증·반영
run_batches.py기본 3개 병렬 작업자에 연속 15쪽 배치를 동적 배정; 담당 쪽을 200 DPI 이미지와 해당 OCR 줄·점수·좌표로 codex exec 검수; 부모만 보고서·MD 기록; 보류 재검수·배치 경계 이미지 검증·일시 정지·재개 관리
proofread.pyPDF·TXT·JSON 페이지 대응과 SHA-256 검사; 리뷰 버전·삽화 결정·페이지 상태 관리; 본문 앞·뒤·내부 이미지 위치를 검증하며 모든 대상 페이지 검수 후 MD 조립
to_epub.py확인된 제목·저자·언어로 Pandoc EPUB3 생성; Markdown의 raw HTML·smart 해석을 꺼 원문의 꺾쇠 괄호와 따옴표 방향 보존; epub_cover_asset이 있으면 본문 삽화와 별도 원본 표지를 표지로 사용; ZIP·메타데이터·XHTML·목차·이미지 참조·본문 문구 검증 후 최종 파일 반영; 검증 경고·Pandoc 진단을 구조화 기록하고 EPUB 해시가 바뀌면 이전 원본 대조 기록 무효화
report.py책별 단일 보고서 렌더링과 실행·오류·검수 기록 보존; 판독 보류·기술적 실패 페이지 및 epub_audit의 항목별 판정·표본 결과 표시

OCR JSON은 각 물리 페이지의 텍스트·점수·좌표를 포함한 PaddleOCR 결과를 보관한다. 텍스트가 0건인 페이지는 실제 빈 페이지나 텍스트 없는 그림인지 원본 이미지와 대조한다. 일부 페이지 추출은 JSON의 complete: false로 남아 전체 책 검수·EPUB 완료로 취급하지 않는다.

자동 검수의 각 작업자는 별도 /tmp/ocr-review-* 하위 디렉터리에 담당 배치의 이미지·구조화 JSON·진단 로그를 만든다. 부모 실행기만 결과를 물리 PDF 페이지 번호로 검증·기록하고, 중복 또는 담당 범위 밖 페이지를 거부한다. 빠르게 끝난 작업자에는 다음 미처리 배치를 배정한다. 기본 배치·동시 실행 수는 각각 15쪽·3개이며 --batch-size, --workers로 조정한다. 기본 모델·추론 수준은 Codex 사용자 설정을 그대로 쓰고 명시적 --model, --reasoning-effort가 있을 때만 바꾼다. 확인할 수 없는 토큰 사용량은 확정 수치로 쓰지 않는다.

4. 이미지 검수와 EPUB 완료 조건​

검수는 첫 물리 페이지부터 마지막 페이지까지 모든 원본 이미지를 OCR TXT·JSON과 대조한다. 인쇄된 문장부호·옛맞춤법·오탈자·인명·숫자·부정 표현·대사·줄과 문단 순서를 보존한다. 페이지 사이 연결은 direct·space·paragraph 중 하나로 기록한다. 삽화의 본문 내 위치는 before·after·inline으로 기록하며, inline이면 해당 페이지의 검수 Markdown에 동일한 이미지 참조가 실제로 있어야 한다. 원본에 실제 인쇄된 장 제목만 Markdown 제목으로 만든다. 뜻이 달라질 수 있는 교정에는 물리 페이지·이미지 근거와 risk_kinds를 보고서에 남긴다. 판독 불가 페이지는 추측하지 않고 blocked 또는 uncertain으로 둔다.

표지·장 구분 그림·본문 삽화도 원본 이미지를 확인한다. 표지 펼침면에 저자 사진과 인쇄 글자가 함께 있으면 본문에는 사진만 추출하고, 원본 표지는 보고서의 epub_cover_asset으로 별도 지정할 수 있다. 기본적으로 실제 시각 자료를 자산으로 포함하며, 사용자 요청으로 제외할 때만 omit한다. /tmp의 렌더링 이미지와 도서 저장소가 다른 파일시스템이어도 대상 자산 디렉터리의 임시 파일로 복사하고 SHA-256을 확인한 뒤 게시한다. 기존 자산의 내용이 다르면 덮어쓰지 않는다.

내부 페이지 상태는 pending(미검수), processing(진행 중), reviewed(이미지 대조 완료), uncertain(이미지 대조 후 판독 보류), failed(기술적 실패), blocked(추가 조치 필요)다. 기존 보고서의 페이지별 리뷰 버전은 유지하고, 실행 상태는 보고서의 proofread.page_state에 기록한다. 판독 보류는 원래 리뷰를 보존한 채 기본 1회, 350 DPI로 해당 페이지와 OCR 위치·신뢰도·문맥을 다시 확인한다. 확정할 수 없으면 uncertain으로 남기고 다른 배치는 계속한다. 기술적 오류는 기본 2회까지 재시도하며, 실패 페이지만 다음 실행에서 다시 처리한다. 재시도 횟수는 --retries, --uncertain-retries로 바꿀 수 있다. 입력 해시 불일치, 승인 범위 문제, 인증·사용량 제한, 저장 공간·권한·보고서 무결성 문제는 전체 실행을 멈춘다.

인접 배치 경계는 양쪽 원본 이미지를 250 DPI로 별도 확인하고, 불확실하면 해당 두 경계 이미지만 350 DPI로 다시 확인한다. 문장·대사·문단·제목·장식과 누락·중복을 확인한 결과를 보고서의 boundary_targets·boundaries에 남긴다. 자동 배치 실행기는 경계 미확정, pending·processing·failed·uncertain·blocked 중 하나라도 남으면 최종 MD를 만들지 않고 미완료 종료 상태를 돌려준다. proofread.py build는 전 페이지 reviewed·image_checked: true, 판독 보류 없음, 삽화 결정 완료를 검사한다. 상태 조회에는 boundary_unverified, image_unchecked, boundary_missing, artwork_pending, md_verified도 포함된다. 원본 이미지 대조를 했다는 상태만으로 의미적 정확성이 보장되지는 않는다.

EPUB 단계는 부분 검수나 보고서·MD 해시 불일치를 거부한다. 제목은 확인된 YAML 또는 파일명에서, 저자는 확인된 YAML 또는 작가 - 제목 파일명에서 가져오며 필요하면 Codex에 정확한 제목·저자를 알려준다. 언어는 ko-KR이다. Pandoc이 만든 목차와 장 제목, 포함 이미지, 패키지 구조를 검사하고 실패 시 기존 EPUB을 유지한다. 원본 Markdown의 .unlisted 제목은 목차 대상에서 제외하고, 문단 문구 비교 시 Markdown의 목록·인용·강조·이스케이프 표기를 가시 문자 기준으로 정규화한다. 자동 구조 검사는 원문과 EPUB의 의미적 일치를 보증하지 않는다.

$ocr-md-to-epub 실행 시 Codex는 입력·계획 확인부터 최종 결과 공지까지 전체 절차 체크리스트를 먼저 보여주고, 각 단계 종료 때 완료 상태를 갱신한다. EPUB 생성 뒤 단일 보고서의 최신 미해결 우려와 변환 경고만 추려 PDF 물리 페이지와 최종 EPUB의 해당 문구·이미지·목차를 대조한다. 각 항목을 실제 문제·문제 없음·판정 불가로 나누고 근거와 권장 해결안을 기록한다. 실제 문제 수정은 항목별 사용자 승인 후 수행한다. 본문 문제는 해당 페이지의 검수 기록을 수정해 MD를 다시 조립하고 해시 정합성을 확인한다. MD·자산 변경 시 EPUB을 재생성해 각 항목을 다시 대조한다. 새 EPUB 해시가 생기면 종전 epub_audit는 무효가 된다.

포함된 삽화 자산에 PDF 페이지 전체와 전사된 본문이 함께 들어 있으면 EPUB의 텍스트와 중복되는지 대조한다. 실제 중복은 승인 후 원본 PDF에서 시각 자료 영역만 새 자산으로 추출하고 삽화 기록을 바꿔 MD·EPUB을 재생성한다. 도표의 축과 라벨은 그림 내용으로 보존한다.

수정 항목 재검증 뒤 Codex가 최종 EPUB을 PDF 원본과 표본 대조한다. 일반적인 전권은 10쪽, 짧은 책은 5쪽을 권장하며 기존 무작위 목록을 우선 사용하되 시작·중간·끝, 장 경계, 삽화를 포함하도록 조정한다. 항목별 판정·승인·수정·재검증·표본 결과는 보고서의 epub_audit와 EPUB 최종 원본 대조 절에 남긴다. Codex 자체 표본 대조와 사용자의 직접 표본 검수는 별개다. 기존 sample_check는 사용자가 실제 대조 결과를 알려주기 전에는 완료로 표시하지 않는다. 이 표본 검사만으로 전권 무결성을 보증하지 않는다.

모든 체크리스트 상태와 결과를 알린 뒤에는 도서별 최종 한 줄 평가로 마감한다. 해결·재검증과 표본 대조가 통과하면 확인 범위를 밝히고 변환 품질이 양호한 것으로 추정한다고 표현한다. 미해결 문제, 판정 불가, 표본 실패 또는 원본 대조 불가가 있으면 해당 항목과 필요한 조치를 한 문장으로 남기며 완료나 전권 무결성을 단정하지 않는다.

5. 중단·재개와 확인할 곳​

도중에 끊기면 Codex에게 같은 도서의 보고서와 계획을 확인하고 미완료 페이지부터 재개하도록 요청한다. 같은 계획을 재사용하면 완료된 리뷰를 건너뛰고 pending, 중단 당시 processing, failed 페이지를 다시 배정한다. 판독 보류 페이지는 설정된 재검수 상한을 넘겨 무한 반복하지 않는다. 실행 중의 정지 요청은 보고서 옆 .ocr-report.md.pause 신호 파일로 받아 새 배치를 배정하지 않고 진행 중인 결과를 정리한 뒤 멈춘다. 같은 도서의 배치 실행기 중복 기동은 .run.lock의 파일 잠금으로 막는다. Codex가 상태 조회·일시 정지·재개가 필요할 때 run_batches.py --command status|pause|resume을 사용한다. 기존 PDF·TXT·JSON의 SHA-256과 페이지 범위가 달라졌다면 기존 검수 기록에 이어 쓰지 않는다. 완료한 단계는 입력·출력 해시가 맞을 때만 건너뛴다.

증상Codex가 확인할 근거
OCR·PDF 렌더링 실패pdfinfo·pdftoppm 오류, 설치 경로, 모델 초기화, 보고서 오류 이력
이미지 검수 실패·판독 보류보고서의 failed·uncertain·blocked 상태와 보존된 /tmp/ocr-review-* 진단·초안; 실제 이미지 재판독
MD가 생성되지 않음미검수·이미지 미확인·boundary_unverified·삽화 결정·입력 해시
EPUB 실패보고서 오류, 제목·저자, Markdown 및 자산 참조, Pandoc·EPUB 검증 결과
계획 이후 새 충돌새 계획의 전체 출력 경로와 승인 범위

현재 구현의 세부 입력 형식과 예외 조건은 각 SKILL.md, 페이지 리뷰 형식, 공통 사용법 및 위 소스 파일을 기준으로 확인한다.