"PDF structure, built for speed."——PDF 结构解析，为速度而生。

项目简介 What is pdf-inspector

pdf-inspector 是 Firecrawl 开发并开源的快速 Rust 库，专注于 PDF 的分类、文本提取与 Markdown 转换。

它的定位非常明确：为混合 OCR 管线当好「第一道关卡」。OCR 又慢又贵，但约 54% 的 PDF 其实是原生文本型，根本不需要 OCR。pdf-inspector 在约 10–50ms 内判断一份 PDF 是文本型还是扫描型，文本型的直接在本地 200ms 内完成提取与转换——只有真正需要的页面才送进 OCR。它是 Firecrawl 官方 PDF 处理链路的底层引擎。

它不是「套壳解析器」：默认构建纯 Rust 实现，没有 ML 模型、不调用外部服务，唯一的 PDF 解析依赖是 lopdf。整个提取就是一次纯粹的本地解析。

核心特性 Core Features

• 智能分类：TextBased / Scanned / ImageBased / Mixed 四种类型约 10–50ms 判定完成，返回 0–1 置信度分数和逐页 OCR 路由信号。
• 区域感知的文本提取：每个文本片段都带 X/Y 坐标、字体、字号；支持按包围盒（bounding box）提取指定区域的文字，并给出 needsOcr 质量标记。
• 版面感知：多栏、报纸式版面自动重建阅读顺序，RTL（从右向左）文本正确处理，跨页逻辑流保持连贯。
• 强大的文本解码：CID / Type0 字体经 ToUnicode CMap 正确解码，UTF-16BE / UTF-8 / Latin-1 编码全覆盖；编码损坏的页面会被自动标记，方便上层回退到 OCR。
• Markdown 转换：标题（按字号比例映射 H1–H4）、项目符号/编号/字母列表、代码块（等宽字体检测）、表格、粗斜体、URL 链接、分页标记一次成型。
• 双模式表格检测：基于矩形绘制操作的框线检测 + 基于文本对齐的启发式检测，财务表格和跨页续表都能还原。
• 单次文档加载：文档只解析一次，检测与提取阶段共享同一次解析结果。
• 选择性 OCR（可选）：原生版本可启用——只把被质量检查拒绝的页面送去 OCR，其余照常走快速路径，每页标注来源（native / ocr / fused）。
• 浏览器 WASM：CMap 内嵌，中日韩字体解码不依赖文件系统；单线程构建，无需跨域隔离。
• 测试完备：快照测试、变异测试、cargo-fuzz 模糊测试目标一应俱全。

技术架构 Architecture

pdf-inspector 的架构哲学可以用一句话概括：一次解析，全程复用。

PDF 文件 / 字节
        │
        ▼
  detector —— 类型判定（~10–50ms）
  TextBased / Scanned / ImageBased / Mixed + 置信度
        │
        ▼
  extractor —— 内容流文本拉取
  （位置、字体、字号，ToUnicode CMap 解码）
        │
        ▼
  layout —— 行/段落重组与阅读顺序
  （多栏归位、RTL、连字处理）
        │
        ▼
  tables —— 框线 + 对齐启发式双模式表格识别
        │
        ▼
  markdown —— 语义化 GFM 输出

关键组成：

组成	用途
Rust	核心语言，编译为原生库 / WebAssembly
lopdf	唯一的 PDF 解析依赖
detector.rs	快速类型判定（抽样渲染像素统计）
extractor/	区域感知的文本提取管线
tounicode.rs	ToUnicode CMap 解析
napi/ · wasm/	Node.js 与浏览器绑定

注意：原生包默认不内嵌任何 OCR 模型、PDFium 或 ONNX Runtime——干净的处理请求永远不会加载或下载这些外部组件；只有显式启用 OCR 且有页面被路由过去时才会用到它们。

四种 PDF 类型 Classification

类型	含义	推荐处理
TextBased	原生文本型，文字藏在内容流里	本地直接提取，又快又免费
Scanned	扫描型，整页都是图片	需要 OCR
ImageBased	图片型（如设计导出的 PDF）	需要 OCR
Mixed	混合型：部分页文本、部分页图片	逐页路由，只 OCR 需要的页

判定结果附置信度分数（0.0–1.0）和需要 OCR 的具体页码列表，你可以据此精确控制下游成本。

性能基准 Benchmark

官方在 opendataloader-bench 语料库（200 份真实 PDF）上做了横向对比（得分 0–1，越高越好；速度为完整跑完语料库的总耗时）：

工具	综合评分	阅读顺序	表格 (TEDS)	标题	速度
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

结论很清楚：综合最准、表格最强、速度最快（标题识别仅次于 liteparse）。详见性能基准页。

开源协议 License

pdf-inspector 使用 MIT License，完全开源，可自由使用、修改与商用。源码在 github.com/firecrawl/pdf-inspector，可通过 crates.io（Rust/CLI）、npm（Node/WASM）、PyPI（Python）安装。

快速体验 Try it now

• 不想装任何东西？直接在首页的在线 Demo 里拖一份 PDF 进去，浏览器本地完成解析。
• 想装进项目？到安装下载页选你的语言。
• 想系统上手？去快速上手专区。

一句话总结

pdf-inspector = 先分类后提取 + 五阶段流水线 + 一份干净的 Markdown，文本型 PDF 不花 OCR 的钱，纯本地、MIT、LLM 友好。