firecrawl/pdf-inspector

来源：https://github.com/firecrawl/pdf-inspector

pdf-inspector

Crates.io (https://crates.io/crates/pdf-inspector) npm (https://www.npmjs.com/package/@firecrawl/pdf-inspector) PyPI (https://pypi.org/project/pdf-inspector/) 许可证：MIT

用于 PDF 分类和文本提取的快速 Rust 库。可检测 PDF 是基于文本还是扫描件，提取带位置信息的文本，并转换为干净的 Markdown——全程无需 OCR。包含 Python、Node.js 和浏览器 WebAssembly 绑定。

由 Firecrawl (https://firecrawl.dev) 构建，可在 200ms 内在本地处理基于文本的 PDF，为约 54% 不需要 OCR 的 PDF 跳过昂贵的 OCR 服务。

特性

• 智能分类 — 通过采样内容流，在约 10-50ms 内检测 TextBased、Scanned、ImageBased 或 Mixed PDF。返回置信度分数（0.0-1.0）以及按页的 OCR 路由建议。
• 文本提取 — 带位置信息的提取，包含字体信息、X/Y 坐标，以及自动多栏阅读顺序。
• Markdown 转换 — 标题（通过字体大小比率识别 H1-H4）、项目符号/编号/字母列表、代码块（等宽字体检测）、表格（基于矩形和启发式）、粗体/斜体格式、URL 链接和分页符。
• 表格检测 — 双模式：基于 PDF 绘图操作的矩形检测，以及基于文本对齐的启发式检测。可处理财务报表、脚注和跨页续表。
• CID 字体支持 — 针对 Type0/Identity-H 字体的 ToUnicode CMap 解码，支持 UTF-16BE、UTF-8 和 Latin-1 编码。
• 多栏布局 — 自动检测报纸式分栏、顺序阅读顺序，并支持 RTL 文本。
• 编码问题检测 — 自动标记损坏的字体编码，使调用方可以回退到 OCR。
• 单次文档加载 — 文档仅解析一次，并在检测和提取之间共享，避免冗余 I/O。
• 浏览器 WebAssembly — 在浏览器和 Web Worker 中本地运行相同的 Rust 解析器，内置 CMap，无需服务器往返。
• 轻量级 — 纯 Rust，无 ML 模型，无外部服务。仅依赖 lopdf 进行 PDF 解析。

基准测试

在 opendataloader-bench (https://github.com/opendataloader-project/opendataloader-bench) 语料库（200 个 PDF）上评估。仅展示不使用基于模型的 PDF 解析的本地引擎；OCR 已禁用。分数为 0-1，越高越好。

结果于 2026 年 7 月 31 日在 Apple M4 Pro 上刷新。引擎版本为 pdf-inspector 0.2.6、LiteParse 2.10.1、OpenDataLoader 2.2.1、PyMuPDF4LLM 0.2.0 和 MarkItDown 0.1.5。速度是排除预热运行后五次交替或轮换的完整语料库运行的中位数，每个解析器在单个进程中顺序处理文档。

完整的解析器配置、逐文档预测、评估器输出和生成的图表可在可复现结果分支 (https://github.com/firecrawl/opendataloader-bench/tree/abi/pdf-parser-benchmark-results) 中获取。

最佳适用场景： 需要速度、阅读顺序和表格结构的原生文本 PDF。在此对比中，pdf-inspector 在总体、阅读顺序和表格得分上更高，同时完整运行速度最快。这使得它成为报告、研究论文、财务文档、发票和法律 PDF 的理想本地默认选择，无需增加 OCR 延迟或基础设施即可获得干净、结构化的 Markdown。

使用配对基准测试工具 可在完全相同的语料库和评估器修订版本上比较两个本地构建。

快速开始

Python

bash pip install maturin maturin develop --release

``python import pdf_inspector

result = pdf_inspector.process_pdf(“document.pdf”) print(result.pdf_type) # “text_based”, “scanned”, “image_based”, “mixed” print(result.markdown) # Markdown 字符串或 None ``

完整 API 参考：docs/python.md

Node.js

bash npm install @firecrawl/pdf-inspector

``javascript import { readFileSync } from ‘fs’; import { processPdf, classifyPdf } from ‘@firecrawl/pdf-inspector’;

const result = processPdf(readFileSync(‘document.pdf’)); console.log(result.pdfType); // “TextBased”, “Scanned”, “ImageBased”, “Mixed” console.log(result.markdown); // Markdown 字符串或 null ``

完整 API 参考：napi/README.md

浏览器 WebAssembly

bash npm install @firecrawl/pdf-inspector-wasm

``javascript import init, { processPdf } from ‘@firecrawl/pdf-inspector-wasm’;

await init(); const response = await fetch(‘/document.pdf’); const pdf = new Uint8Array(await response.arrayBuffer()); const result = processPdf(pdf);

console.log(result.pdfType); console.log(result.markdown); ``

完整 API 参考：wasm/README.md

Rust

从 crates.io (https://crates.io/crates/pdf-inspector) 安装：

bash cargo add pdf-inspector

或手动添加：

toml [dependencies] pdf-inspector = "0.1"

``rust use pdf_inspector::process_pdf;

let result = process_pdf(“document.pdf”)?; println!(“Type: {:?}”, result.pdf_type); if let Some(markdown) = &result.markdown { println!(“{}”, markdown); } ``

完整 API 参考：docs/rust-api.md

CLI

``bash

安装 CLI 工具

cargo install pdf-inspector

将 PDF 转换为 Markdown

pdf2md document.pdf

JSON 输出（用于管道）

pdf2md document.pdf –json

带位置信息的 TextItem JSON，包含 is_underline 元数据

pdf2md document.pdf –items-json

仅原始 Markdown（无头部信息）

pdf2md document.pdf –raw

Token 高效输出（折叠长点引导符和类似的源填充）

pdf2md document.pdf –compact

插入分页标记（）

pdf2md document.pdf –pages

仅处理指定页面

pdf2md document.pdf –select-pages 1,3,5-10

仅检测（不提取）

detect-pdf document.pdf detect-pdf document.pdf –json

检测 + 布局分析（表格、分栏）

detect-pdf document.pdf –analyze –json ``

如果从源代码检出，请使用 cargo run --bin pdf2md -- document.pdf 或 cargo run --bin detect-pdf -- document.pdf。

架构

PDF 字节 │ ├─► 检测器 → PdfType (TextBased / Scanned / ImageBased / Mixed) │ └─► 提取器 ├─ 字体 → 字体宽度、编码 ├─ 内容流 → 遍历 PDF 运算符 → TextItems + PdfRects ├─ xobjects → Form XObject 文本、图像占位符 ├─ 链接 → 超链接、AcroForm 字段 └─ 布局 → 分栏检测 → 行分组 → 阅读顺序 │ ├─► 表格 │ ├─ detect_rects → 基于矩形的表格（并查集） │ ├─ detect_heuristic → 基于对齐的表格 │ ├─ grid → 列/行分配 → 单元格 │ └─ format → 单元格 → Markdown 表格 │ └─► Markdown ├─ analysis → 字体统计、标题层级 ├─ preprocess → 合并标题、首字下沉 ├─ convert → 行循环 + 表格/图像插入 ├─ classify → 标题、列表、代码 └─ postprocess → 清理 → 最终 Markdown

文档通过 load_document_from_path / load_document_from_mem 仅加载一次，并在检测和提取阶段之间共享，因此没有冗余解析。

项目结构

src/ lib.rs — 公共 API、PdfOptions 构建器、便捷函数 python.rs — PyO3 Python 绑定 types.rs — 共享类型：TextItem、TextLine、PdfRect、ItemType text_utils.rs — 字符/文本辅助（CJK、RTL、连字、粗体/斜体） process_mode.rs — ProcessMode 枚举（DetectOnly、Analyze、Full） detector.rs — 无需完整加载文档即可快速检测 PDF 类型 glyph_names.rs — Adobe Glyph List → Unicode 映射 tounicode.rs — 用于 CID 编码文本的 ToUnicode CMap 解析 extractor/ — 文本提取流水线 tables/ — 表格检测和格式化 markdown/ — Markdown 转换和结构检测 bin/ — CLI 工具（pdf2md、detect_pdf） napi/ — Node.js/Bun 绑定（napi-rs） wasm/ — 浏览器绑定（wasm-bindgen）

分类工作原理

1. 解析 xref 表和页面树（不完整加载对象）
2. 根据 ScanStrategy 选择页面（默认：所有页面，支持提前退出）
3. 在内容流中查找 Tj/TJ（文本运算符）和 Do（图像运算符）
4. 根据采样页面中文本运算符的出现情况分类

这可在毫秒内检测包含 300+ 页的 PDF。结果包含 pages_needing_ocr —— 一个缺少文本的特定页码列表，支持按页 OCR 路由，而不是全有或全无。

扫描策略

Markdown 输出

转换器处理：

用例：智能 PDF 路由

pdf-inspector 专为大规模处理 PDF 的流水线而构建。无需将每个 PDF 都发送到 OCR：

PDF 到达 → pdf-inspector 分类（约 20ms） → TextBased 且置信度高？ 是 → 本地提取（约 150ms），完成 否 → 发送到 OCR 服务（2-10s）

这为大多数已经是基于文本的 PDF（报告、论文、发票、法律文档）节省了成本和延迟。

调试

有关 RUST_LOG 环境变量的用法，请参阅 docs/debugging.md。

许可证

MIT