PDF Inspector：基于 Rust 的 PDF 检测、分类与文本提取库

项目地址：https://github.com/firecrawl/pdf-inspector  协议：MIT  Stars：19,190  更新：2026-09-18

一、产品深度介绍

（一）它是什么

PDF Inspector 是一个开源的 Rust 库，核心职责只有两件：一是「看懂」一个 PDF 到底是文本型还是扫描件，二是在不需要 OCR 的前提下，把文本型 PDF 抽取成带结构的干净 Markdown。它的官方定位非常直接：「Fast Rust library for PDF inspection, classification, and text extraction」，即一个用于 PDF 检测、分类与文本提取的快速 Rust 库。

这个定位背后有一个真实的工程动机：Firecrawl 在构建网页/文档抓取管道时发现，大约 54% 的 PDF 其实是文本型，根本不需要昂贵的 OCR 服务。PDF Inspector 因此被设计成在本地 200ms 内完成文本型 PDF 的处理，从而让这部分文档直接跳过 OCR，大幅节省延迟与算力成本。

（二）技术定位与性能

• 智能分类：通过采样内容流，在约 10–50ms 内检测出 TextBased、Scanned、ImageBased 或 Mixed 类型，并返回置信度（0.0–1.0）以及逐页的 OCR 路由建议。
• 位置感知提取：提取文本时保留字体信息与 X/Y 坐标，支持自动多列阅读顺序；对于旋转文本（如页边戳、图表轴标题）会保留真实的轴对齐包围盒，并报告 rotation 角度，而不是把它折叠成零宽字符。
• 默认轻量：Rust 与浏览器构建默认是纯提取，不加载任何 OCR 运行时；原生 Python / Node 包虽然集成了 OCR，但 PDFium、ONNX Runtime 与模型文件保持外置，仅在使用 OCR 时才加载。

小黑配图：一份 PDF 被小黑用放大镜迅速分辨出「文本型」与「扫描件」——文本型直接转成干净 Markdown，扫描件被推上 OCR 的传送带，做到先分类、再路由。

二、主要功能特点与应用场景

PDF Inspector 的能力可以归纳为「分类 + 提取 + 转换 + 表格 + OCR 路由」五个层次，全部围绕「本地、快速、可路由」展开。

• 智能分类 Smart classification：如前所述，秒级判断 PDF 类型并给出逐页 OCR 路由建议。
• 文本提取 Text extraction：带字体、坐标的位置感知提取，自动处理多列阅读顺序，旋转文本保留真实包围盒。
• Markdown 转换：标题（H1–H4，依据字号比例识别）、项目符号/编号/字母列表、代码块（等宽字体检测）、表格、粗体/斜体、URL 链接与分页符都能还原。
• 表格检测 Table detection：双模式——基于 PDF 绘图操作的矩形检测，以及基于文本对齐的启发式检测，可处理跨页金融表格、脚注等复杂情形。
• CID 字体支持：为 Type0/Identity-H 字体提供 ToUnicode CMap 解码，支持 UTF-16BE、UTF-8 与 Latin-1 编码。
• 多列与 RTL：自动检测报刊式多列与顺序阅读顺序，并支持从右到左（RTL）文本。
• 编码问题检测：自动标记损坏的字体编码，便于调用方回退到 OCR。
• 选择性 OCR Selective OCR：Rust / CLI / Python / Node 可仅对需要 OCR 的页面做本地渲染，运行 PP-OCRv6 Small，保留逐页来源与回退建议。
• 单次文档加载：文档只解析一次，在检测阶段与提取阶段共享，避免冗余 I/O。
• 浏览器 WebAssembly：在浏览器与 Web Worker 中运行同一套 Rust 解析器，内嵌 CMap，无服务器往返。

典型应用场景包括：报告、研究论文、财务文档、发票与法律 PDF 的本地清洗与转换；大规模 PDF 处理管道中在发送 OCR 前先做智能路由；以及任何需要在浏览器端离线解析 PDF 的 Web 应用。

三、如何安装与使用

PDF Inspector 提供 Rust、Python、Node.js / Bun、浏览器 WASM 与 CLI 五种使用形态，下面是各形态的最小可运行示例。

Python（基于 PyO3 绑定）：

pip install pdf-inspector

import pdf_inspector
result = pdf_inspector.process_pdf("document.pdf")
print(result.pdf_type)   # "text_based", "scanned", "image_based", "mixed"
print(result.markdown)

Node.js（基于 napi-rs 绑定）：

import { readFileSync } from 'fs';
import { processPdf } from '@firecrawl/pdf-inspector';
const pdf = readFileSync('document.pdf');
const result = processPdf(pdf);

浏览器 WebAssembly（基于 wasm-bindgen 编译）：

import init, { processPdf } from '@firecrawl/pdf-inspector-wasm';
await init();
const result = processPdf(pdfBytes);

Rust，在 Cargo.toml 中声明依赖：

[dependencies]
pdf-inspector = "1"

use pdf_inspector::process_pdf;
let result = process_pdf("document.pdf")?;

CLI 工具，安装后即可把 PDF 转 Markdown 或仅做类型检测：

cargo install pdf-inspector
pdf2md document.pdf          # 转 Markdown
pdf2md document.pdf --json   # JSON 输出
detect-pdf document.pdf      # 仅检测类型

需要 OCR 时，安装带 ocr 特性的 CLI 即可对扫描页做选择性渲染：

cargo install pdf-inspector --features ocr --bin pdf2md

四、官方地址与获取方式

• GitHub 仓库：https://github.com/firecrawl/pdf-inspector
• PyPI：pip install pdf-inspector
• npm：@firecrawl/pdf-inspector 与 @firecrawl/pdf-inspector-wasm
• crates.io：pdf-inspector（Rust 依赖）
• 协议：MIT，允许商用与二次分发

五、与同类方案对比

PDF Inspector 的差异点不在于「能不能抽文本」，而在于「是否先分类再做路由」。下面把它与全量 OCR 流水线、以及通用抽取库做一个横向比较。

简而言之，通用抽取库能解决「文本型 PDF 怎么抽」，但无法判断「这份 PDF 到底需不需要 OCR」；全量 OCR 能解决「扫描件怎么读」，但把 54% 本不需要 OCR 的文档也一刀切地送进昂贵服务。PDF Inspector 正好补齐了中间的「分类与路由」这一环。

六、核心机制深度解析

PDF Inspector 的整体数据流是一条「先分类、后提取」的单向管道。文档只加载一次，检测结果与提取过程共享同一份解析结果。

在 extractor 内部，fonts 负责字体宽度与编码，content_stream 遍历 PDF 操作符产出文本项与矩形，xobjects 处理 Form XObject 中的文本与图像占位，links 抽取超链接与 AcroForm 字段，layout 完成列检测、行分组与阅读顺序。最后由表格模块与 Markdown 模块分别产出结构化结果。

关键设计是「单次文档加载」：通过 load_document_from_path 或 load_document_from_mem 只解析一次文档，在检测与提取阶段之间共享，避免重复 I/O。这也是它能在 200ms 内完成文本型 PDF 处理的重要原因之一。

七、实用技巧

• 先做分类再路由：在批量管道里先用 detect-pdf 判断类型，只对 Scanned / Mixed 的页面走 OCR，文本型直接提取，能省下大量算力。
• 选择性 OCR 省资源：OCR 特性只在真正需要时渲染对应页面并运行 PP-OCRv6 Small，逐页保留来源与回退建议，避免整本文档全量识别。
• 浏览器端零往返：WASM 构建内嵌 CMap，可直接在 Web Worker 中解析 PDF，无需把文件传到服务器，适合隐私敏感场景。
• 编码异常即回退：当检测到损坏字体编码时，利用返回的标记把该页回退到 OCR，而不是硬抽一堆乱码。
• CLI 接管道：pdf2md document.pdf –json 输出结构化 JSON，方便在 shell 或服务端流水线里做二次处理。

八、最新更新动态

仓库一直保持活跃维护，最近一次提交时间为 2026-09-18。从 README 与提交记录可以看到，项目近期的演进重点集中在几个方向：补齐 MIT LICENSE 文件与协议徽章，完善 Rust / Python / Node / WASM 多语言绑定，引入浏览器 WebAssembly 形态让同一套解析器能跑在客户端，以及加入基于 PP-OCRv6 Small 的选择性 OCR 与逐页路由建议。

此外，CID 字体解码、表格双模式检测、多列与 RTL 阅读顺序、编码问题自动标记等能力，也都是围绕「更鲁棒地处理真实世界复杂 PDF」这一目标逐步加入的。对于关注长期稳定性的团队，可以持续跟踪其 crates.io 与 npm 包的版本发布。

九、常见问题 FAQ

十、总结

PDF Inspector 的价值不在于「又一个 PDF 文本抽取库」，而在于把「先判断类型、再决定是否调用 OCR」的路由逻辑做成了一个高速、本地、可嵌入的 Rust 库。它用约 200ms 的本地提取覆盖掉约 54% 不需要 OCR 的 PDF，并把扫描件智能导向 OCR，在延迟与成本上显著优于全量 OCR 方案。配合多语言绑定与浏览器 WASM，它既能嵌入服务端的大规模处理管道，也能直接在 Web 端离线运行。对于经常和大量 PDF 打交道的开发者与数据团队，这是一个值得加入工具箱的轻量组件。

在撰写本文的过程中，我主要参考了 PDF Inspector 的 GitHub 仓库（firecrawl/pdf-inspector）README.md 与公开 API 信息，仓库地址为 https://github.com/firecrawl/pdf-inspector。文中数据以官方公开信息为准，可能随版本更新而变化。