PDF 检查器

概述

pdf-inspector 是一个用 Rust 编写的 PDF 分类与文本提取库，专注于在 200ms 以内本地处理原生文本型 PDF，避免对约 54% 无需 OCR 的文档调用昂贵的识别服务。同时提供 Python、Node.js 与浏览器 WebAssembly 多语言绑定。

核心特性

• 智能分类：通过采样内容流判断 PDF 属于 TextBased（文本型）、Scanned（扫描型）、ImageBased（图像型）或 Mixed（混合型），耗时约 10–50ms，返回 0.0–1.0 置信度，并给出需走 OCR 的页码列表，支持按页路由而非全量识别。
• 位置感知文本提取：输出包含字体、X/Y 坐标的文本项，并自动识别多栏报纸式排版与 RTL 文本，输出合理阅读顺序。
• Markdown 转换：基于字体大小比例识别 H1–H4 标题；自动识别项目符号、数字、字母列表；通过等宽字体与关键字检测代码块；支持粗体/斜体、URL 链接、页分隔符、连字符接续、目录点引导符折叠等。
• 表格检测：采用矩形检测（基于 PDF 绘制算子）+ 启发式检测（基于文本对齐）双模式，支持财务报表、跨页续表、单元格合并与脚注。
• CID 字体支持：解析 ToUnicode CMap，兼容 Type0 / Identity-H 字体，涵盖 UTF-16BE、UTF-8、Latin-1 编码。
• 编码异常检测：自动标记损坏的字体编码，便于上层回退到 OCR。
• 轻量化：纯 Rust 实现，无 ML 模型与外部服务，仅依赖 lopdf 解析 PDF；浏览器端 WASM 内嵌 CMap，无需服务端往返。

性能基准

在 opendataloader-bench 语料（200 份 PDF，关闭 OCR）上：综合得分 0.875，超越 liteparse（0.873）、opendataloader（0.831）、pymupdf4llm（0.735）、markitdown（0.589）；阅读顺序 0.915、表格 TEDS 0.814、200 份文档处理耗时 0.470s，为所有对比引擎中最快。

架构

文档仅加载一次（load_document_from_path / load_document_from_mem），由检测与提取两个阶段共享，避免重复 I/O。处理流水线为：

PDF 字节
  ├─ detector  →  PdfType
  └─ extractor
        ├─ fonts / content_stream / xobjects / links
        └─ layout（栏检测 → 行分组 → 阅读顺序）
              ├─ tables（rects 矩形 + heuristic 对齐 + grid 网格化）
              └─ markdown（analysis → preprocess → convert → classify → postprocess）

快速上手

Rust

use pdf_inspector::process_pdf;

let result = process_pdf("document.pdf")?; // 加载 PDF
println!("Type: {:?}", result.pdf_type);
if let Some(markdown) = &result.markdown {
    println!("{}", markdown);
}

CLI

cargo install pdf-inspector

pdf2md document.pdf            # 转 Markdown
pdf2md document.pdf --json     # 输出 JSON
pdf2md document.pdf --items-json   # 输出位置感知的 TextItem JSON
pdf2md document.pdf --raw      # 原始 Markdown
pdf2md document.pdf --compact  # 折叠长点引导符，节省 token
pdf2md document.pdf --pages    # 插入页分隔注释
pdf2md document.pdf --select-pages 1,3,5-10  # 仅处理指定页

detect-pdf document.pdf        # 仅分类
detect-pdf document.pdf --analyze --json  # 分类 + 布局分析

Python / Node.js / WASM

分别通过 maturin develop 构建 PyO3 绑定，安装 @firecrawl/pdf-inspector（napi-rs）与 @firecrawl/pdf-inspector-wasm（wasm-bindgen）。三个绑定都暴露 processPdf / process_pdf 入口，返回相同的 pdfType / pdf_type 与 markdown 字段。

扫描策略

典型用法：智能 PDF 路由

在大规模 PDF 流水线中，先用 pdf-inspector 分类（约 20ms）：若为 TextBased 且置信度高，则本地提取（约 150ms）完成；否则回退到 OCR 服务（2–10s）。这种“按需 OCR”模式可显著降低文本型报告、论文、发票、法律文档的处理成本与延迟。