firecrawl/pdf-inspector

Fast Rust library for PDF inspection, classification, and text extraction. Intelligently detects scanned vs text-based PDFs to enable smart routing decisions.

기능

pdf‑inspector 는 빠르고 Rust 기반의 라이브러리로, PDF를 분석하여 문서의 유형(일반 텍스트, 스캔된 이미지, 혼합 등)을 판단한 후 구조화된 방식으로 텍스트를 추출합니다. PDF를 깔끔한 Markdown으로 변환할 수 있으며, 제목, 목록, 코드 블록, 표, 그리고 각 텍스트 조각의 정확한 X/Y 위치를 유지합니다. 실제 텍스트가 아닌 이미지만 포함된 PDF의 경우, 선택적으로 가벼운 OCR 모델(PP‑OCRv6 Small)을 필요로 하는 페이지에만 적용하여 전체 문서에 대한 OCR 처리를 피할 수 있습니다.

왜 중요한가

당신이 접하는 대부분의 PDF는 이미 텍스트 기반입니다. 그러나 많은 파이프라인은 모든 파일을 고비용 OCR 서비스에 통과시킵니다. pdf‑inspector는 PDF 분류를 10–50 ms 내에, 대부분의 파일에 대해 텍스트 추출을 200 ms 미만으로 수행하여 컴퓨팅 비용과 지연 시간을 크게 절감합니다. 위치 정보를 유지한 추출은 검색 가능한 인덱스 구축, LLM에 데이터 제공, 문서를 구조화된 데이터로 변환하는 등의 후속 작업을 훨씬 더 신뢰할 수 있게 만듭니다.

누구에게 적합한가

문서 처리 파이프라인을 구축하는 개발자 (예: 웹 크롤러, 기업용 인제스트 서비스)로, OCR이 필요한지 판단하기 위한 저비용의 첫 번째 단계가 필요한 경우.
LLM 중심 애플리케이션에서 PDF를 인입하고, 외부 OCR API 비용을 지불하지 않고도 깔끔한 Markdown이나 구조화된 텍스트를 원하는 경우.
데이터 과학 팀으로서 연구 논문, 재무 보고서, 청구서, 법적 계약서에서 표, 제목, 코드 스니펫을 추출하고자 하는 경우.
프론트엔드 엔지니어로서 WebAssembly를 통해 브라우저에서 직접 PDF 파싱을 수행하고자 하는 경우.

작동 방식 (개요)

빠른 분류 – PDF의 콘텐츠 스트림을 샘플링하여 텍스트(Tj/TJ)와 이미지(Do) 연산자를 확인하고, 신뢰도 점수와 OCR이 필요한 페이지 목록을 반환합니다.
단일 패스 파싱 – 파일은 한 번만 로드되며, 분류와 추출에 동일한 메모리 내 표현이 재사용되어 중복 I/O를 피합니다.
추출 파이프라인 – 폰트 분석, CID 인코딩 디코드, PDF 연산자 순회를 통해 TextItem(폰트, 크기, X/Y 좌표 포함)를 생성하고, 이를 줄로 그룹화, 열 탐지, 읽기 순서 결정을 수행합니다.
표 탐지 – 두 가지 전략을 사용: (a) 그리기 명령에서 나온 사각형 기반 탐지(사각형의 유니온-파인드)와 (b) 텍스트 위치에서 나온 히ュ리스틱 정렬 탐지. 다중 페이지 표 및 재무 레이아웃을 처리합니다.
Markdown 변환 – 폰트 크기 비율로 제목 분석, 폰트 이름으로 굵게/기울임꼴 감지, 등폭 폰트로 코드 블록, 목록 마커, URL 등을 식별하고, 선택적으로 페이지 구분 마커를 포함한 깔끔한 Markdown을 출력합니다.
옵션 OCR – ocr 기능을 활성화하면, 텍스트가 아닌 페이지만 래스터화되어 PP‑OCRv6 Small 모델에 전달되며, 나머지 빠른 Rust 파이프라인은 그대로 유지됩니다.

시작하기 (빠른 단계)

Rust: cargo add pdf-inspector 후 process_pdf("file.pdf") 호출.
Python: maturin 빌드 도구 설치 후 maturin develop --release 실행, 이후 import pdf_inspector; pdf_inspector.process_pdf("file.pdf").
Node.js: npm install @firecrawl/pdf-inspector 설치 후 processPdf 사용.
브라우저: WASM 패키지 @firecrawl/pdf-inspector-wasm 설치 후 init() 호출 후 PDF의 Uint8Array에 대해 processPdf 실행.
CLI: cargo install pdf-inspector 설치 후 pdf2md file.pdf 실행 (분류만 원하면 detect-pdf).

제한 사항 및 미해결 과제

OCR는 선택 사항이며 추가적인 네이티브 종속성(PDFium, ONNX Runtime, PP‑OCR 모델)이 필요합니다. ocr 기능 없이선 순수 이미지 PDF에서 텍스트 추출이 불가능합니다.
복잡한 레이아웃(예: 깊이 중첩된 표, 특이한 열 구조)은 여전히 수동 후처리가 필요할 수 있습니다. 히ュ리스틱 표 탐지기는 대부분의 재무 및 보고서 스타일 표에는 잘 작동하지만, 완전한 레이아웃 엔진은 아닙니다.
언어 지원 – 핵심 추출은 언어에 독립적이지만, OCR 품질은 PP‑OCR 모델에 따라 달라지며, 주로 라틴 문자에 최적화되어 있어 CJK 또는 손글씨 텍스트에서는 정확도가 낮을 수 있습니다.
거대 PDF 성능 – 분류는 ScanStrategy 옵션(전체 스캔 vs. 샘플링)으로 조정 가능하여 매우 큰 문서에서 속도와 정밀도의 균형을 맞출 수 있습니다.

모든 세부 정보는 리포지토리의 README에서 직접 가져왔습니다.