pdf-inspector: OCR 없이 PDF를 분류하고 마크다운으로 추출하는 Rust 라이브러리 (feat. firecrawl)

9bow · 7월 14, 2026, 11:30오후

pdf-inspector 소개

문서를 다루는 파이프라인에서 PDF는 가장 까다로운 입력 중 하나입니다. 어떤 PDF는 이미 본문 텍스트가 그대로 들어 있는 반면, 어떤 PDF는 종이를 스캔한 이미지 덩어리라 광학 문자 인식(OCR)을 거쳐야 글자를 얻을 수 있습니다. 둘을 구분하지 않고 모든 PDF를 OCR 서비스로 보내면, 이미 텍스트가 있는 문서에까지 불필요한 비용과 수 초 단위의 지연이 붙습니다.

pdf-inspector는 이 구분을 앞단에서 빠르게 처리하는 라이브러리입니다. OCR이나 머신러닝 모델 없이 순수 Rust로 PDF의 콘텐츠 스트림을 샘플링해 문서가 텍스트 기반인지 스캔본인지 밀리초 단위로 판별하고, 텍스트 기반이면 위치 정보를 유지한 채 본문을 추출해 마크다운으로 변환합니다. 웹 크롤링·데이터 수집 도구를 만드는 Firecrawl 이 자사 파이프라인을 위해 만들었으며, 텍스트 기반 PDF를 200ms 안에 로컬에서 처리해 "OCR이 필요 없는 약 54%의 PDF" 에 대한 외부 OCR 호출을 건너뛰는 것을 목표로 합니다.

핵심 기능은 크게 세 가지입니다. PDF 타입 분류, 위치 인식 텍스트 추출, 그리고 제목·목록·표·코드 블록을 인식하는 마크다운 변환입니다. Rust 라이브러리 본체와 함께 Python 및 Node.js 바인딩, 그리고 명령줄 도구를 제공하며, PDF 파싱을 위한 lopdf 하나 외에는 외부 의존성이 없습니다.

pdf-inspector의 문서 처리 파이프라인

pdf-inspector는 문서를 한 번만 파싱한 뒤 그 결과를 분류 단계와 추출 단계가 공유하는 구조로 설계되어 있습니다. load_document_from_path 또는 load_document_from_mem 로 문서를 한 차례 로드하고, 이후 감지(detector)와 추출(extractor)이 같은 파싱 결과를 재사용하므로 중복 I/O가 발생하지 않습니다.

추출 단계는 여러 하위 모듈로 나뉩니다. 폰트 정보(폭·인코딩)를 읽고, 콘텐츠 스트림의 PDF 연산자를 순회해 텍스트 조각(TextItem)과 사각형(PdfRect)을 수집하며, Form XObject·하이퍼링크·AcroForm 필드를 처리합니다. 레이아웃 분석은 단(column) 감지와 줄 그룹화를 거쳐 읽기 순서를 결정하는데, 신문처럼 여러 단으로 나뉜 지면이나 오른쪽에서 왼쪽으로 읽는 텍스트(RTL)도 다룹니다. 이렇게 정리된 텍스트는 표 감지와 마크다운 변환으로 넘어갑니다.

pdf-inspector의 PDF 타입 분류

분류는 전체 문서를 완전히 로드하지 않고 이뤄집니다. 먼저 상호 참조 테이블(xref)과 페이지 트리를 파싱한 뒤, ScanStrategy 에 따라 검사할 페이지를 고르고, 콘텐츠 스트림에서 텍스트 연산자(Tj/TJ) 와 이미지 연산자(Do) 의 존재 여부를 확인해 페이지별로 판정합니다. 이 방식으로 300페이지가 넘는 PDF도 밀리초 단위로 분류할 수 있습니다.

분류 결과는 TextBased, Scanned, ImageBased, Mixed 네 가지 타입과 0.0~1.0 범위의 신뢰도 점수(confidence score)로 반환됩니다. 특히 pages_needing_ocr 필드에 텍스트가 없는 페이지 번호 목록이 담기므로, 문서 전체를 일괄로 OCR에 보내는 대신 텍스트가 없는 페이지만 골라 OCR로 라우팅할 수 있습니다. 또한 폰트 인코딩이 깨진 경우를 자동으로 표시(flag)해, 호출하는 쪽에서 그 문서만 OCR로 되돌리는 판단을 내릴 수 있게 합니다.

검사 범위는 ScanStrategy 로 조절합니다. 기본값인 EarlyExit 는 모든 페이지를 훑되 텍스트가 아닌 첫 페이지에서 멈추고, Full 은 조기 종료 없이 전체를 검사해 Mixed와 Scanned를 더 정확히 구분하며, Sample(n) 은 균등하게 분포된 n개 페이지만, Pages(vec) 는 지정한 페이지만 검사합니다.

pdf-inspector의 마크다운 변환과 표 감지

마크다운 변환기는 폰트 크기 비율을 기준으로 제목(H1~H4)을 구분하고, 글머리표·번호·문자 목록, 모노스페이스 폰트로 감지한 코드 블록, 굵게·기울임 서식, URL 링크, 페이지 구분을 처리합니다. 저자에 따르면 제목 계층은 본문 텍스트 대비 폰트 크기 단계를 0.5pt 단위로 군집화해 판별하며, 코드 블록은 Courier·Consolas·Monaco·Menlo·Fira Code·JetBrains Mono 같은 모노스페이스 폰트와 키워드 감지로 인식합니다.

표 감지는 두 가지 방식을 함께 씁니다. PDF 드로잉 연산으로 그려진 사각형을 union-find로 묶어 찾는 방식과, 텍스트 정렬에서 표 구조를 추정하는 휴리스틱 방식입니다. 이를 통해 재무 문서의 숫자 표, 각주, 여러 페이지에 걸쳐 이어지는 표를 다룹니다. 또한 Type0/Identity-H 같은 CID 폰트의 ToUnicode CMap을 해석해 UTF-16BE·UTF-8·Latin-1 인코딩 텍스트를 복원합니다.

pdf-inspector의 벤치마크 성능

저자는 opendataloader-bench 말뭉치(200개 PDF)로 평가한 결과를 공개했습니다. 아래 표는 OCR이나 ML 모델을 쓰지 않는 직접 텍스트 추출 엔진만 비교한 것으로, 점수는 0~1 범위이며 높을수록 좋습니다.

엔진	종합	읽기 순서 (NID)	표 (TEDS)	제목 (MHS)	속도 (200개)
pdf-inspector	0.83	0.88	0.66	0.74	4초
opendataloader	0.84	0.91	0.49	0.74	11초
pymupdf4llm	0.73	0.89	0.40	0.41	18초
markitdown	0.58	0.88	0.00	0.00	8초

저자의 설명에 따르면 pdf-inspector는 비교 대상 중 가장 빠르면서 표 감지 점수가 가장 높고, 종합 점수는 opendataloader와 0.01 차이로 약 2.5배 빠릅니다. 다만 읽기 순서는 opendataloader에 약간 뒤지고, 표 구조 정확도는 시각 레이아웃을 볼 수 있는 OCR 기반 엔진에는 미치지 못한다고 밝히고 있습니다. 참고로 OCR·ML을 쓰는 엔진(docling, marker, mineru)은 같은 말뭉치에서 종합 0.83~0.88을 기록하지만 2분에서 180분이 걸린다고 합니다.

pdf-inspector 설치 및 사용법

Python에서는 maturin 으로 빌드한 뒤 process_pdf 로 분류와 마크다운 변환을 한 번에 얻을 수 있습니다.

import pdf_inspector

result = pdf_inspector.process_pdf("document.pdf")
print(result.pdf_type)   # "text_based", "scanned", "image_based", "mixed"
print(result.markdown)   # 마크다운 문자열 또는 None

Node.js는 npm install @firecrawl/pdf-inspector, Rust는 cargo add pdf-inspector 로 설치합니다. 명령줄 도구도 함께 설치되어, PDF를 마크다운으로 변환하거나 타입만 빠르게 감지할 수 있습니다.

# PDF를 마크다운으로 변환
pdf2md document.pdf

# 특정 페이지만 처리
pdf2md document.pdf --select-pages 1,3,5-10

# 타입 감지 + 레이아웃 분석(표·단)을 JSON으로
detect-pdf document.pdf --analyze --json

pdf-inspector의 라이선스

pdf-inspector는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

pdf-inspector 공식 홈페이지

pdf-inspector 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~