12k Star 的 pdf-inspector：让 AI 文档处理系统学会”先判断再动手”

做 RAG 或者文档处理应用，绕不开一个问题：用户上传的 PDF，到底是文本型还是扫描件？

很多系统一股脑走 OCR 路线——扫描件 OCR 没毛病，但文本型 PDF 也走 OCR，延迟高、费用贵、还容易出错。Firecrawl 团队开源的 pdf-inspector 就是来解决这个问题的：快速判断 PDF 类型，智能路由，精准提取文本，全在本地跑，不用任何外部服务。

不是又一个 PDF 解析库

市面上 PDF 工具很多，但 pdf-inspector 的定位很清晰——它不追求覆盖所有 PDF 场景，而是专注做好一件事：文本型 PDF 的高质量提取，同时给出可操作的分类决策。

核心思路是：先用 detector 在 10-50ms 内判断 PDF 类型（TextBased / Scanned / ImageBased / Mixed），返回置信度分数和逐页 OCR 路由建议。如果判断为文本型，直接提取；如果判断为扫描件，系统就知道该走 OCR 流程。这个路由决策才是它的核心价值。

技术细节上，纯 Rust 实现，不依赖任何 ML 模型，也不需要外部服务。解析只跑一次，检测和提取共享同一个文档对象，避免重复 I/O。CMap 支持也很完整，UTF-16BE、UTF-8、Latin-1 都能处理。

实打实的数据

Firecrawl 团队在 opendataloader-bench 基准测试（200 份真实 PDF）上跑了对比，只测本地引擎、关闭 OCR，结果很有说服力：

200 份 PDF 全程 0.47 秒，pdf-inspector 速度是 pymupdf4llm 的 36 倍，同时综合分和表格检测分数都是最高的。这背后靠的是 Rust 的性能和对 PDF 内容流的直接解析，没有中间层绕路。

多语言支持：Python、Node.js、WASM、Rust

你不用换技术栈就能用上它。

Python（需要 maturin 构建 Rust 扩展）：

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

Node.js（npm 直接安装）：

import { processPdf, classifyPdf } from '@firecrawl/pdf-inspector';
const result = processPdf(readFileSync('document.pdf'));
console.log(result.pdfType);   // "TextBased" | "Scanned" | "ImageBased" | "Mixed"

浏览器 WASM（零服务器往返）：

import init, { processPdf } from '@firecrawl/pdf-inspector-wasm';
await init();
const pdf = new Uint8Array(await fetch('/doc.pdf').then(r => r.arrayBuffer()));
const result = processPdf(pdf);

Rust / CLI 也有完整支持，还有 pdf2md 和 detect-pdf 两个开箱即用的命令行工具：

# PDF 转 Markdown
pdf2md document.pdf

# 检测类型（不提取）
detect-pdf document.pdf --json

# 带布局分析
detect-pdf document.pdf --analyze --json

适合谁 / 不适合谁

适合：

• RAG 流水线里需要对 PDF 做文本提取的开发团队
• 文档处理系统，需要区分扫描件和原生 PDF 做智能路由
• 大量科研论文、财务报表、合同等文本密集型文档的批量处理
• 对延迟敏感的场景（200ms 内处理文本型 PDF）
• 本地优先，不想依赖云端 OCR 服务

不适合：

• 需要处理重度图像内容（海报、手绘图）为主的用户——这类 PDF 本质上就是图片，pdf-inspector 会标记为 ImageBased，OCR 路由决定权在你
• 非技术用户（CLI 和 API 对开发者友好，但需要一定技术基础）
• 超大型文档库批量处理——单文档处理很快，但并发和分布式场景需要自己搭架构

真实使用门槛

几个务实的注意事项：

1. Python 绑定的构建门槛。 Python 版需要先装 maturin 再编译 Rust 扩展，不能 pip install 直接用预编译 wheel——这对不会 Rust 环境的团队是个坑。当然，Node.js 和 WASM 版本是纯 npm 安装，没有这个问题。

2. 表格检测有局限。 基准测试里 pdf-inspector 表格得分 0.814，是对比中最强的，但对复杂跨页表格、嵌套表格的处理仍有误判。金融报表、学术论文里的大表格，建议输出后人工复核或搭配 markitdown 做二次处理。

3. 不支持加密 PDF。 加密/密码保护文档会直接报错，需要先解密再处理。

4. 版本相对新（v0.2.x）。 88 个 open issues 说明还在快速迭代中，生产环境使用建议锁定版本号，别追 latest。

下一步建议

如果你的 RAG 管道或者其他文档处理场景还在用 pymupdf 或 markitdown 处理所有 PDF，建议花 30 分钟把 pdf-inspector 集成进去对比效果：

第一步：Node.js 项目直接 npm install @firecrawl/pdf-inspector，Python 项目参照 docs/python.md 搭好 maturin 环境。

第二步：跑一下你自己场景里的 PDF 样本，对比提取质量（尤其是表格和多栏布局）。

第三步：加一层智能路由——判断为 TextBased 直接走 pdf-inspector，Scanned/ImageBased 再走 OCR 流程。

第四步：有性能要求的场景，把 200ms latency 目标跑个基准，记录节省的 OCR 调用量和延迟改善，给团队算笔账。

项目地址：https://github.com/firecrawl/pdf-inspector
官网文档：https://firecrawl.github.io/pdf-inspector/