firecrawl/pdf-inspector

Fast Rust library for PDF inspection, classification, and text extraction. Intelligently detects scanned vs text-based PDFs to enable smart routing decisions.

功能

pdf‑inspector 是一个快速的 Rust 基础库，分析 PDF 并判断其类型（纯文本、扫描图像、混合等），然后以结构化方式提取文本。它可以将 PDF 转换为干净的 Markdown，保留标题、列表、代码块、表格，甚至每个文本片段的精确 X/Y 位置。对于包含图像而非真实文本的 PDF，该库可选择性地仅对需要的页面运行轻量级 OCR 模型（PP‑OCRv6 Small），避免对整个文档进行 OCR 处理。

为何重要

你遇到的大多数 PDF 已经是文本型的，但许多管道仍会将每个文件发送到昂贵的 OCR 服务。pdf‑inspector 可在 10–50 ms 内完成 PDF 分类，对大多数文件在 200 ms 内完成文本提取，显著节省计算成本和延迟。其位置感知的提取方式也使下游任务——如构建可搜索索引、喂给 LLM 或将文档转换为结构化数据——更加可靠。

适用人群

构建文档处理管道的开发者（如网络爬虫、企业级数据摄入服务），需要一个低成本的初步步骤来判断是否需要 OCR。
面向 LLM 的应用，需要摄入 PDF 并获取干净的 Markdown 或结构化文本，而无需支付外部 OCR API 费用。
数据科学团队，需要从研究论文、财务报告、发票或法律合同中提取表格、标题和代码片段。
前端工程师，希望使用 WebAssembly 在浏览器中直接运行 PDF 解析。

工作原理（概览）

快速分类 – 采样 PDF 的内容流，检测文本（Tj/TJ）与图像（Do）操作符，返回置信度分数及需要 OCR 的页面列表。
单次遍历解析 – 文件仅加载一次，相同的内存表示被用于分类和提取，避免重复 I/O。
提取流水线 – 解析字体、解码 CID 编码、遍历 PDF 操作符生成带字体、大小和 X/Y 坐标的 TextItem，然后分组为行、检测列、确定阅读顺序。
表格检测 – 使用两种策略：(a) 从绘图命令中基于矩形的检测（PDF 矩形的并查集）和 (b) 从文本位置的启发式对齐检测，支持跨页表格和财务布局。
Markdown 转换 – 分析字体大小比以识别标题，通过字体名称识别粗体/斜体，等宽字体识别代码块，列表标记、URL 等，并输出干净的 Markdown，可选添加分页标记。
可选 OCR – 启用 ocr 功能后，仅将标记为非文本的页面进行光栅化并输入 PP‑OCRv6 Small 模型，其余快速 Rust 流水线保持不变。

快速上手

Rust: cargo add pdf-inspector，然后调用 process_pdf("file.pdf")。
Python: 安装 maturin 构建工具，运行 maturin develop --release，然后 import pdf_inspector; pdf_inspector.process_pdf("file.pdf")。
Node.js: npm install @firecrawl/pdf-inspector，使用 processPdf。
浏览器: 安装 WASM 包 @firecrawl/pdf-inspector-wasm，调用 init()，然后对 PDF 的 Uint8Array 调用 processPdf。
CLI: cargo install pdf-inspector，运行 pdf2md file.pdf（仅分类可使用 detect-pdf）。

限制与待解决问题

OCR 为可选，需要额外的原生依赖（PDFium、ONNX Runtime、PP‑OCR 模型）。禁用 ocr 功能后，无法从纯图像 PDF 中提取文本。
复杂布局（如深度嵌套表格、特殊列结构）仍可能需要手动后处理；启发式表格检测对大多数财务和报告类表格效果良好，但并非完整的布局引擎。
语言支持 – 核心提取与语言无关，但 OCR 质量取决于 PP‑OCR 模型，主要针对拉丁字母优化，对 CJK 或手写文本可能准确率较低。
超大 PDF 性能 – 可通过不同 ScanStrategy 选项（完整扫描 vs. 采样）调整分类，以在超大文档上平衡速度与精度。

所有细节均直接来自仓库的 README。