pdf-inspector 딥다이브
— 스캔본이냐 진짜 텍스트냐, PDF의 정체를 밀리초에 판별한다

1한 줄 정체

pdf-inspector는 "OCR을 돌리기 전에, 이 PDF가 OCR이 필요한 스캔본인지 아니면 이미 텍스트가 들어있는 문서인지를 밀리초 단위로 판별해 주고, 텍스트 문서라면 위치까지 아는 추출과 Markdown 변환을 로컬에서 끝내 주는 순수 Rust 라이브러리"다. 한마디로 PDF 처리 파이프라인의 "문지기(gatekeeper)"다. 값비싼 방(OCR)에 아무나 들여보내지 않고, 표를 먼저 검사해서 정말 필요한 문서만 통과시킨다.

사용자(또는 상위 파이프라인)가 PDF 한 개를 던졌을 때 pdf-inspector 안에서 벌어지는 일을 압축하면 이렇다:

여기서 결정적인 건 ⑥에서 반환하는 정보의 정밀도다. 단순히 "스캔이다/아니다"가 아니라, "문서 전체 중 3, 7, 12페이지만 OCR이 필요하다"는 페이지 단위 라우팅(pages_needing_ocr)까지 준다. 300페이지 문서에서 스캔된 3페이지만 골라 OCR하면 되니, 비용이 100배 차이 난다.

2왜 주목받는가 — "판별이 먼저"라는 각도

첫째, 발상의 전환이다. PDF에서 텍스트를 뽑는 도구(pymupdf4llm, markitdown, marker 등)는 이미 많다. 그런데 그 도구들은 대부분 "일단 다 처리하고 본다". pdf-inspector는 그 앞단에 "이 문서를 처리할 가치가 있나(=OCR이 필요한가)"를 먼저 묻는 얇고 빠른 판별기를 끼운다. 대량 문서 파이프라인을 굴리는 회사(Firecrawl 자신, RAG 서비스, 문서 검색 스타트업)에게 이건 곧바로 비용 절감으로 이어져서 실용 가치가 즉시 와닿는다.

둘째, 속도 숫자가 압도적이다. README의 2026-07-31 벤치마크(Apple M4 Pro, opendataloader-bench 200개 PDF, OCR 끄고 로컬 엔진만 비교):

같은 코퍼스를 35배 이상 빠르게 처리하면서 정확도(읽기 순서 0.915, 표 0.814)까지 1위다. "빠른데 부정확"이 아니라 "빠르면서 정확"이라, 벤치마크를 본 개발자들이 곧장 관심을 보였다.

셋째, 순수 Rust + 단일 의존이라는 공학적 매력이다. PDF 파싱을 lopdf 크레이트 하나로만 하고 네이티브 pdfium/mupdf FFI도, 머신러닝 모델도 쓰지 않는다. 덕분에 빌드가 가볍고, 크로스 컴파일이 쉽고, 브라우저 WASM으로도 나간다. "무거운 C++ 라이브러리에 링크하지 않는 PDF 도구"라는 점이 Rust 커뮤니티에 특히 어필했다.

3기술 스택 전체 지도

코어: 순수 Rust (edition 2021)

본체는 pdf_inspector라는 이름의 Rust 라이브러리 크레이트다. Cargo.toml의 crate-type은 ["lib", "cdylib"] — Rust에서 쓸 lib과, 다른 언어(Python/Node)에서 링크할 C 호환 동적 라이브러리(cdylib)를 동시에 뽑는다. PDF를 실제로 뜯어보는 유일한 의존이 lopdf다.

하나의 코어, 네 개의 얼굴 (바인딩)

이 저장소의 가장 배울 만한 설계는 Rust 코어 하나를 4가지 배포 형태로 내보내는 구조다. 로직은 한 곳에 있고, 각 언어의 얇은 포장만 따로 있다.

각 바인딩의 진입점은 이렇게 대응된다:

• CLI(src/bin/) — pdf2md(→Markdown), detect-pdf(분류만), dump_ops(연산자 덤프 디버그). Cargo.toml에 autobins=false로 명시 등록.
• Python(src/python.rs, ~642줄) — pyo3 + maturin 빌드. 타입 스텁 pdf_inspector.pyi 제공. 여기선 PdfType이 문자열 "text_based"|"scanned"|"image_based"|"mixed"로 나온다.
• Node/Bun(napi/) — napi-rs. linux-x64, darwin-arm64, win32-x64 프리빌트 바이너리 3종을 npm에 올려서, 사용자는 Rust 툴체인 없이 설치만 하면 된다.
• 브라우저 WASM(wasm/) — wasm-bindgen + serde-wasm-bindgen. 릴리스 프로파일이 lto=true, opt-level="s", strip=true로 바이너리 크기 최적화. 파일 없이 브라우저 안에서 PDF 판별이 돈다.

CI / 배포 파이프라인

.github/workflows/에 6개 워크플로가 있다: ci(테스트+fmt+clippy), pages(랜딩 사이트), 그리고 채널별 배포 4종(publish-crate·publish-pypi·publish-wasm·publish[npm]). 특히 clippy를 -D warnings로 강제해서 경고 하나만 있어도 CI가 깨진다 — Rust 프로젝트의 품질 규율을 볼 수 있는 대목이다.

4아키텍처 심화 — 분류 결정 트리와 휴리스틱

pdf-inspector의 심장은 src/detector.rs(약 3,645줄)다. 핵심 아이디어는 "PDF 전체를 렌더링하지 말고, content stream의 연산자만 세라"는 것. PDF 페이지는 결국 "글자 그려라(Tj/TJ), 이미지 붙여라(Do), 선 그어라(path)" 같은 명령의 목록이다. 이 명령의 비율만 보면 렌더링 없이도 문서의 정체가 드러난다.

1단계 — 페이지마다 신호를 수집한다 (PageAnalysis)

표본으로 뽑힌 각 페이지에서 PageAnalysis 구조체에 십수 가지 신호를 채운다. 그중 판별에 쓰이는 핵심만:

2단계 — "이 페이지는 텍스트 페이지인가?" 판정

단순히 "글자 명령이 있으면 텍스트"가 아니다. 이미지가 있으면 기준을 높이는 등, 실전 함정을 피하는 조건이 겹쳐 있다(실제 코드):

// 이미지가 있는 페이지는 글자 명령을 더 많이(10개↑) 요구 — 
// 로고 옆 캡션 몇 글자만 있는 스캔본을 '텍스트'로 오판하지 않기 위해
let effective_min_ops = if analysis.has_images || analysis.image_count > 0 {
    config.min_text_ops_per_page.max(10)   // 이미지 有 → 최소 10
} else {
    config.min_text_ops_per_page           // 이미지 無 → 최소 3 (기본값)
};

if analysis.text_operator_count >= effective_min_ops
    && !is_image_dominated                 // image_count>10 && image>text*3 이면 이미지 지배
    && analysis.unique_text_chars >= 5     // 글자 종류가 5개는 넘어야
    && !analysis.has_vector_text           // 도형으로 그린 가짜 글자 아니고
    && !analysis.has_only_type3_fonts      // 비트맵 글꼴만 있는 것도 아니면
{
    pages_with_text += 1;                   // → 진짜 '텍스트 페이지'로 카운트
}

3단계 — 문서 전체 분류 결정 트리

페이지별 카운트가 모이면, 아래 순서대로 흘러가며 최종 PdfType과 신뢰도(confidence, 0~1)를 정한다(실제 코드):

// 위에서부터 순서대로 검사, 처음 걸리는 가지가 결정
let (pdf_type, confidence) = if has_template_images && pages_with_text > 0 {
    ocr_recommended = true;                          // 큰 배경이미지 + 약간의 글자
    (PdfType::Mixed, 0.5 + (0.3 * (1.0 - template_ratio)))
} else if text_ratio >= config.text_page_ratio_threshold {   // 텍스트 페이지 비율 ≥ 0.6
    ocr_recommended = false;
    (PdfType::TextBased, text_ratio)                 // ★ 로컬 추출로 라우팅
} else if pages_with_text == 0 && (pages_with_images > 0 || pages_with_vector_text > 0) {
    ocr_recommended = true;
    if total_text_ops == 0 && pages_with_vector_text == 0 {
        (PdfType::Scanned, 0.95)                     // 글자 0 + 이미지뿐 → 확실한 스캔
    } else {
        (PdfType::ImageBased, 0.8)
    }
} else if pages_with_text > 0 && (pages_with_images > 0 || pages_with_vector_text > 0) {
    ocr_recommended = true;
    (PdfType::Mixed, 0.7)                            // 글자도 이미지도 섞임
} else if total_text_ops == 0 {
    ocr_recommended = true;
    (PdfType::Scanned, 0.9)
} else {
    ocr_recommended = false;
    (PdfType::TextBased, text_ratio.max(0.5))
};

읽는 법: 위에서 아래로 순서대로 검사해서 처음 참이 되는 가지가 결과다. 가장 중요한 지름길은 두 번째 가지 — "텍스트 페이지 비율이 60% 이상이면 무조건 TextBased, OCR 불필요". 반대로 "글자 명령이 아예 0이고 이미지만 있으면" 신뢰도 0.95로 Scanned. 애매한 중간(글자+이미지 혼재)은 전부 ocr_recommended=true로 안전하게 OCR을 권한다 — "확실할 때만 OCR을 건너뛴다"는 보수적 설계다.

실전 함정을 잡는 특수 휴리스틱들

기본 결정 트리 위에, "겉보기론 텍스트인데 실은 못 읽는" 위장 케이스를 잡는 규칙이 얹혀 있다. 이게 정확도의 비결이다.

let has_vector_text =
    path_ops >= 1000
    && path_ops > text_ops.saturating_mul(200)   // 글자 대비 선이 200배↑
    && unique_alphanum_chars < 30;               // 실제 글자 종류는 30 미만

ScanStrategy — "몇 페이지를 볼 것인가"

초대형 PDF에서 모든 페이지를 검사하면 느리다. 그래서 표본 전략을 고른다(기본은 Sample(8)):

detection과 extraction은 문서를 한 번만 로드한다

판별(detection)과 추출(extraction)이 각각 PDF를 열면 I/O가 두 배다. pdf-inspector는 load_document_from_path/load_document_from_mem로 한 번 로드한 문서를 둘이 공유한다. 추출 파이프라인은 이렇게 이어진다:

표 감지(tables/)는 3가지 전략을 우선순위대로 시도해 처음 유효한 결과가 이긴다: ① rect-based(셀 사각형을 union-find로 클러스터링) → ② line-based(수평·수직 선으로 격자 복원) → ③ heuristic(선이 없는 표를 간격·정렬로 추론). Markdown 변환은 폰트 크기를 0.5pt 단위로 클러스터링해 본문 대비 크기로 H1~H4 heading을 판정하고, 태그드 PDF면 structure tree의 역할(H1~H6·P·L·Code)을 우선 사용한다.

5디렉토리 구조 해부

구조에서 읽히는 힌트 두 가지. 첫째, 가장 큰 파일이 adobe_korea1.rs(1.7만 줄)인데 이건 로직이 아니라 CJK(한중일) 문자 코드맵 데이터다 — 한국어·일본어 PDF의 CID 폰트를 유니코드로 복원하려면 이 방대한 표가 필요하다. 즉 이 라이브러리는 처음부터 동아시아 문서를 진지하게 다룬다. 둘째, detector.rs는 3,645줄로 크지 않다 — 판별 로직 자체는 "얇고 빠른" 설계 의도가 파일 크기에도 드러난다. 무게는 오히려 추출·표·폰트 쪽에 실려 있다.

6학습 포인트 — 기술별 배울 것

① PDF 내부 구조 (가장 값진 배움)

대부분의 개발자는 PDF를 "그냥 열리는 파일"로만 안다. 이 레포는 PDF가 사실은 객체 그래프 + content stream(그리기 대본)이라는 진실을 코드로 가르쳐 준다. Tj/TJ(텍스트), Do(XObject/이미지), path 연산자, CID 폰트와 ToUnicode 매핑, Identity-H 인코딩 — 이 개념들을 실전 판별 로직 안에서 만나니 교과서보다 훨씬 잘 붙는다.

② 규칙 기반(휴리스틱) 분류 설계

ML 없이 신호를 세고 임계값과 결정 트리로 분류하는 법. 특히 "엣지 케이스가 기본값과 임계값을 정한다"는 실전 감각(연차보고서 표지, 타일드 스캔, 신문 다단)을 소스 주석의 캘리브레이션 데이터와 함께 볼 수 있다. 데이터 없이도 견고한 분류기를 짜는 사고법의 표본.

③ Rust 크로스 플랫폼 배포 (1 코어 → 4 언어)

cdylib + pyo3(Python) + napi-rs(Node) + wasm-bindgen(브라우저)로 하나의 로직을 네 채널에 내보내는 전체 그림. cfg(target_arch="wasm32")로 같은 코드를 타깃별로 다르게 조립(rayon 병렬 vs 싱글스레드, 파일 로드 vs include_dir 임베드)하는 조건부 컴파일도 좋은 교재다.

④ 성능을 의식한 파싱 설계

"전체를 렌더링하지 않고 표본 연산자만 센다", "detection과 extraction이 문서를 한 번만 로드해 공유한다", "ScanStrategy로 검사량을 조절한다" — 일을 덜 하도록 설계해서 속도를 얻는 사고를 구체적 코드로 배운다. 35배 속도차의 정체가 마법이 아니라 이 절약들의 합이라는 걸 확인할 수 있다.

⑤ 라이브러리 품질 규율

clippy -D warnings 강제, thiserror 에러 설계, 손으로 조립한 최소 PDF 픽스처로 하는 결정적 테스트(858개+), 스냅샷 회귀 테스트, 비밀번호를 Debug에서 [REDACTED]로 가리는 보안 습관 — 프로덕션 Rust 크레이트의 위생을 통째로 훑을 수 있다.

7시스템 / 빌드 요구사항

• GPU·모델 파일 불필요 — ML이 없으니 다운로드할 가중치가 없다. CPU만으로 돈다.
• 네트워크 불필요 — 순수 로컬 처리. 외부 API 호출 없음(OCR은 별도로 당신이 붙이는 것).
• external/bcmaps/는 런타임 의존 — CJK CMap을 실행 중 상대 경로(CARGO_MANIFEST_DIR 기준)로 읽는다. crates.io 10MiB 제한 때문에 테스트 픽스처는 크레이트에서 빼지만 이 CMap은 포함시킨다. WASM은 파일시스템이 없어 include_dir로 바이너리에 임베드.

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 로드맵 (주차별)

10핵심 키워드 사전

11참고 링크

• GitHub 저장소: github.com/firecrawl/pdf-inspector
• 만든 곳: Firecrawl — 웹 스크래핑·문서 인제스트 스타트업
• 1차 소스: README.md(개요·벤치마크) · src/detector.rs(분류 두뇌) · src/lib.rs(공개 API) · AGENTS.md(개발 관례) · docs/rust-api.md·docs/python.md·docs/benchmarking.md
• PDF 파서: lopdf(순수 Rust) · ttf-parser
• 바인딩 도구: pyo3(Python) · napi-rs(Node) · wasm-bindgen(브라우저)
• 비교/후속 도구: pymupdf4llm · markitdown · marker(추출 도구들) · Tesseract · PaddleOCR(이 판별기 뒤에 붙일 OCR)
• 참고 개념: PDF content stream, CID 폰트/ToUnicode, 다단 레이아웃 감지, TEDS(표 구조 평가), 조건부 컴파일, FFI