본문으로 건너뛰기

한국어 도서 OCR 파이프라인 — 환경 구성 가이드

이 문서는 홈서버의 작업 환경이 사라졌을 때 Codex가 한국어 이미지 PDF를 OCR·전체 페이지 이미지 검수·EPUB3 변환할 수 있는 상태로 복구하는 순서다. 도서 처리 절차와 구현은 실행 흐름·구현 현황에 있다. PDF를 직접 처리하는 셸·PaddleOCR CLI 사용법은 이 운영 방식에 포함하지 않는다.

1. 복구 대상과 전제​

항목현재 기준
운영체제Ubuntu/Xubuntu 24.04 계열, x86_64, CPU 처리
도서 작업 루트/ext001/book001
스킬·스크립트/ext001/book001/.agents/skills/
OCR 가상환경/home/sleepzz/book-ocr/.venv
Python / uv3.12.3 / 0.11.13
PaddlePaddle / PaddleOCRCPU 3.2.0 / 3.7.0
Pandoc / Codex CLI3.1.3 / 0.163.0-alpha.11.1
PDF 도구Poppler의 pdfinfo, pdftoppm

설치 명령만으로 원본 PDF나 프로젝트의 스킬 소스는 복구되지 않는다. 먼저 백업에서 /ext001/book001/.agents/skills/와 필요한 books/를 복원한다. 이 작업 루트는 현재 Git 저장소가 아니므로, 별도 백업 없이 패키지 재설치만 해서는 스크립트·검수 보고서·삽화 자산을 되찾을 수 없다. 기존 작업을 이어가려면 책별 PDF·TXT·JSON·MD·EPUB·.ocr-report.md 및 .<도서명>.ocr-assets/도 함께 복원한다. 특히 보고서의 artwork.asset과 epub_cover_asset이 서로 다른 파일을 가리킬 수 있으므로 자산 디렉터리 안의 원본 표지와 시각 자료 추출본을 모두 보존한다. 의도적으로 일시 정지한 실행의 정지 상태까지 유지하려면 보고서 옆의 .ocr-report.md.pause 파일도 복원한다. .run.lock 파일은 실행 중 프로세스의 잠금 자체를 복원하지 않으므로 재개 판단의 근거로 사용하지 않는다. 새 책부터 시작한다면 스킬 소스와 새 PDF만 있으면 된다.

아래 경로와 버전은 현재 서버를 복구하기 위한 기준이다. 사용자 이름이나 마운트 위치가 달라진 서버에서는 스킬·스크립트에 박혀 있는 경로까지 맞추거나 수정해야 한다. 새 서버에서 /ext001 저장소가 정상 마운트됐는지 먼저 확인한다.

2. 시스템 도구와 uv 설치​

sudo apt update
sudo apt install -y curl ca-certificates python3-venv python3-pip \
poppler-utils libgl1 libglib2.0-0t64 pandoc

Ubuntu 24.04의 GLib 패키지 이름은 libglib2.0-0t64다. libgl1과 GLib는 PaddleOCR/OpenCV 실행에, Poppler는 페이지 수 확인과 이미지 렌더링에, Pandoc은 EPUB3 생성에 필요하다.

uv가 없다면 uv 공식 설치 안내에 따라 설치한다. 현재 버전을 재현하려면 버전 지정 설치 URL을 사용한다.

curl -LsSf https://astral.sh/uv/0.11.13/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
uv --version

3. OCR Python 환경 복구​

현재 스크립트가 사용하는 Python 경로는 /home/sleepzz/book-ocr/.venv/bin/python이다. 새 환경에서 아래 순서로 만든다. 이미 정상 설치된 환경이라면 다시 만들지 말고 5장의 확인 명령부터 실행한다.

mkdir -p /home/sleepzz/book-ocr
uv venv --python 3.12 /home/sleepzz/book-ocr/.venv
uv pip install --python /home/sleepzz/book-ocr/.venv/bin/python setuptools
uv pip install --python /home/sleepzz/book-ocr/.venv/bin/python 'paddlepaddle==3.2.0'
uv pip install --python /home/sleepzz/book-ocr/.venv/bin/python 'paddleocr==3.7.0'

PaddlePaddle CPU 휠을 기본 인덱스에서 찾지 못하면 Paddle 공식 CPU 설치 안내에서 해당 Python·CPU 조합의 인덱스를 확인한다. Python 3.12에서 No module named 'setuptools'가 나오면 위 가상환경에 setuptools만 추가한다. 별도 paddleocr[all] 기능은 이 파이프라인에 필요하지 않다. 첫 OCR 때 PP-OCRv5 모델이 다운로드될 수 있으므로 네트워크와 모델 저장 공간이 필요하다.

4. Codex CLI와 스킬 연결​

페이지별 이미지 검수 스크립트는 별도 codex exec 프로세스를 호출한다. Codex 데스크톱 앱이 열려 있어도 이 CLI가 PATH에서 실행되고 인증돼 있어야 한다. CLI가 없다면 OpenAI 공식 Codex CLI 안내의 Linux 설치 절차로 설치한다.

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version
codex login
codex login status

브라우저가 없는 홈서버라면 OpenAI 인증 안내에 따라 codex login --device-auth를 사용할 수 있다. 인증 정보는 비밀 정보이므로 문서나 도서 작업 폴더에 복사하지 않는다. 위의 Codex 버전은 현재 확인값이며 공식 설치기로 복구한 버전이 다를 수 있다. 이 경우 codex exec --help에서 이미지 입력과 구조화 출력 옵션 지원을 확인한다.

자동 검수는 기본적으로 동시에 3개의 codex exec를 실행한다. 복구한 서버에서 이 동시 실행에 필요한 메모리·네트워크·계정 사용 가능 상태를 확인한다. 모델과 추론 수준은 Codex 사용자 설정을 사용하며 명시적으로 지정한 실행에서만 바뀐다. Python의 fcntl 잠금은 이 Linux 환경의 표준 라이브러리를 사용하므로 별도 패키지 설치가 필요하지 않다. /tmp와 /ext001이 다른 파일시스템이어도 삽화 자산은 최종 저장 디렉터리의 임시 파일로 복사·해시 확인 후 게시한다. /tmp/ocr-review-*는 임시 검수 작업 공간이며 백업·복구의 필수 원본이 아니다. 실패 진단이 남아 있다면 필요한 로그를 별도로 보존한다.

/ext001/book001/.agents/skills/에는 다음이 모두 있어야 한다.

경로역할
ocr-pdf-to-txt/PaddleOCR 추출
ocr-txt-to-md/Codex 전체 페이지 이미지 검수
ocr-md-to-epub/Pandoc EPUB3 변환·검증과 PDF 원본 대비 최종 EPUB 대조 절차
ocr-dev-finalize/스킬·스크립트 변경 후 환경 복구 가이드와 실행·구현 현황 문서 동기화
_ocr_pipeline/계획, EPUB 대조 결과를 포함한 단일 보고서, 연속 실행

Codex에서 /ext001/book001을 작업 폴더로 열어 스킬을 사용한다. 다른 폴더를 열면 이 프로젝트의 .agents/skills/가 검색되지 않을 수 있다. 스크립트 실행에는 위 OCR 가상환경의 Python을 사용하며 uv run으로 다른 프로젝트 환경을 자동 선택하게 하지 않는다.

5. 복구 확인​

아래 확인은 설치 상태만 읽는다. 원본 PDF나 도서 결과물을 생성·수정하지 않는다.

test -f /ext001/book001/.agents/skills/_ocr_pipeline/common.py
test -f /ext001/book001/.agents/skills/ocr-pdf-to-txt/scripts/extract.py
test -f /ext001/book001/.agents/skills/ocr-txt-to-md/scripts/run_batches.py
test -f /ext001/book001/.agents/skills/ocr-txt-to-md/scripts/proofread.py
test -f /ext001/book001/.agents/skills/ocr-txt-to-md/references/review.md
test -f /ext001/book001/.agents/skills/_ocr_pipeline/report.py
test -f /ext001/book001/.agents/skills/_ocr_pipeline/run_pipeline.py
test -f /ext001/book001/.agents/skills/ocr-md-to-epub/scripts/to_epub.py
test -f /ext001/book001/.agents/skills/ocr-dev-finalize/SKILL.md
uv --version
/home/sleepzz/book-ocr/.venv/bin/python -c 'import sys, paddle, paddleocr; print(sys.version.split()[0], paddle.__version__, paddleocr.__version__)'
pdfinfo -v
pdftoppm -v
pandoc --version
codex --version
codex login status
codex exec --help

모든 파일이 존재하고 Python·Paddle 두 패키지의 import가 성공하며 Codex가 인증 상태라면 실행 흐름·구현 현황에 따라 Codex에게 실행 계획 작성부터 요청한다. 기존 도서의 보고서를 복원했다면 PDF·TXT·JSON의 해시가 기존 기록과 일치하는지 계획·검수 단계에서 확인해야 이어서 처리할 수 있다.