pdf-inspector：用于PDF分类和文本提取的快速Rust库
pdf-inspector是一个快速的Rust库，可用于PDF分类和文本提取。它能检测PDF是基于文本的、扫描版的，还能在感知位置的情况下提取文本，并将其转换为简洁的Markdown格式，且整个过程无需OCR。该库提供了Python、Node.js和浏览器WebAssembly的绑定。它由Firecrawl开发，旨在本地处理基于文本的PDF，处理时间不到200毫秒，对于约54%无需OCR服务的PDF，可跳过昂贵的OCR流程。
主要特性
智能分类：通过对内容流进行采样，在约10 - 50毫秒内检测出基于文本、扫描版、基于图像或混合类型的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 Workers中本地运行相同的Rust解析器，嵌入了CMaps，无需服务器往返。
轻量级：纯Rust实现，无机器学习模型，无需外部服务。仅依赖lopdf进行PDF解析。
基准测试
在opendataloader - bench语料库（200个PDF）上进行评估，仅展示无基于模型的PDF解析的本地引擎，且禁用了OCR。得分范围为0 - 1，分数越高越好。
| 引擎 | 总体得分 | 阅读顺序（NID） | 表格（TEDS） | 标题（MHS） | 速度（200个文档） |
|---|---|---|---|---|---|
| pdf - inspector | 0.875 | 0.915 | 0.814 | 0.788 | 0.470s |
| liteparse | 0.873 | 0.913 | 0.693 | 0.811 | 0.750s |
| opendataloader | 0.831 | 0.902 | 0.489 | 0.739 | 2.569s |
| pymupdf4llm | 0.735 | 0.886 | 0.401 | 0.424 | 17.117s |
| markitdown | 0.589 | 0.844 | 0.273 | 0.000 | 16.165s |
结果于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。速度是在排除一次预热运行后，五次交替或循环完整语料库运行的中位数，每个解析器在单个进程中按顺序处理文档。完整的解析器配置、每个文档的预测结果、评估器输出和生成的图表可在可复现结果分支中找到。
适用场景
pdf - inspector最适合处理对速度、阅读顺序和表格结构有要求的原生文本PDF。在此次比较中，pdf - inspector在总体得分、阅读顺序和表格得分方面表现出色，且完成运行速度最快。这使其成为报告、研究论文、财务文件、发票和法律PDF的强大本地默认选择，可在不增加OCR延迟或基础设施的情况下，生成干净、结构化的Markdown。可使用配对基准测试工具，针对相同的语料库和评估器版本比较两个本地构建版本。
快速开始
Python：
pip install maturin
maturin develop --release
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：
npm install @firecrawl/pdf - inspector
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：
npm install @firecrawl/pdf - inspector - wasm
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安装
cargo add pdf - inspector
// 或手动添加
[dependencies]
pdf - inspector = "0.1"
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：
# 安装CLI工具
cargo install pdf - inspector
# 将PDF转换为Markdown
pdf2md document.pdf
# JSON输出（用于管道传输）
pdf2md document.pdf --json
# 定位文本项JSON，包含是否下划线元数据
pdf2md document.pdf --items - json
# 仅输出原始Markdown（无标题）
pdf2md document.pdf --raw
# 高效令牌输出（合并长点线和类似的源填充）
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字节流输入后，会分别流向检测器和提取器。检测器可判断PDF类型（基于文本、扫描版、基于图像或混合类型）；提取器则负责解析字体、内容流、XObject、链接和布局等信息，进而进行表格检测和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` 枚举（仅检测、分析、完整处理）
- detector.rs：快速PDF类型检测，无需加载完整文档
- glyph_names.rs：Adobe字形列表到Unicode的映射
- tounicode.rs：用于CID编码文本的ToUnicode CMap解析
extractor/：文本提取管道
tables/：表格检测和格式化
markdown/：Markdown转换和结构检测
bin/：CLI工具（`pdf2md`、`detect_pdf`）
napi/：Node.js/Bun绑定（napi - rs）
wasm/：浏览器绑定（wasm - bindgen）
分类原理
解析交叉引用表和页面树（无需加载完整对象），根据扫描策略（默认扫描所有页面并提前退出）选择页面，在内容流中查找文本操作符 `Tj/TJ` 和图像操作符 `Do`，根据采样页面中文本操作符的存在情况进行分类。该方法可在毫秒内检测300多页的PDF。结果包含 `pages_needing_ocr`，即缺少文本的特定页面编号列表，支持按页进行OCR路由，而非全有或全无的处理方式。
扫描策略
| 策略 | 行为 | 适用场景 |
|---|---|---|
| EarlyExit（默认） | 扫描所有页面，遇到第一个非文本页面时停止 | 将基于文本的PDF路由到快速提取的管道 |
| Full | 扫描所有页面，不提前退出 | 准确区分混合类型和扫描版PDF |
| Sample(n) | 均匀采样n个页面（第一页、最后一页、中间页） | 对速度要求高于精度的超大PDF |
| Pages(vec) | 仅扫描指定的以1为索引的页面编号 | 调用者已知需要检查的页面时 |
Markdown输出转换规则
标题（H1 - H4）：根据相对于正文文本的字体大小层级检测，允许0.5pt的聚类范围。
粗体/斜体：通过字体名称模式（Bold、Italic、Oblique）检测。
项目符号列表：通过 `*`、`-`、`*`、`○`、`●`、`◦` 等前缀检测。
编号列表：通过 `1.`、`1)`、`(1)` 等模式检测。
字母列表：通过 `a.`、`a)`、`(a)` 等模式检测。
代码块：通过等宽字体（Courier、Consolas、Monaco、Menlo、Fira Code、JetBrains Mono）和关键字检测。
表格：结合基于PDF绘图操作的矩形检测和基于文本对齐的启发式检测。
财务表格：对合并的数值进行令牌拆分。
标题说明：通过 “Figure”、“Table”、“Source:” 等前缀检测。
上标/下标：根据相对于基线的字体大小和Y偏移检测。
URL：转换为Markdown链接。
连字符：重新连接跨线断开的单词。
页码：从输出中过滤掉。
大写首字母：将大的首字母与后续文本合并。
点线：将目录样式的点线合并为 “ ... ”。
用例：智能PDF路由
pdf - inspector专为大规模处理PDF的管道而设计。在处理PDF时，无需对每个PDF都进行OCR，而是先由pdf - inspector对其进行分类（约20毫秒），若为基于文本且置信度高，则在本地进行提取（约150毫秒）；否则，将其发送到OCR服务（2 - 10秒）。这种方式为大多数基于文本的PDF（如报告、论文、发票、法律文件）节省了成本和延迟。
调试
有关 `RUST_LOG` 环境变量的使用，请参阅docs/debugging.md。
许可证
本项目采用MIT许可证。那么，在实际应用中，pdf - inspector还会有怎样的表现呢？
