pdf-inspector 开源：Firecrawl 的 PDF 交通警察，200 份文档 0.47 秒分类提取

刚刚发现，Firecrawl 也开源了一款 PDF 智能分类与文本提取库：pdf-inspector，已经收获了超 1.4 万人标星。

简单说，pdf-inspector就是 PDF 世界的"交通警察"——先看清楚来的是什么车，再指挥它走对应的车道。
Firecrawl 把目光投向 PDF 处理场景，思路非常务实：别一股脑全丢 OCR，先判断 PDF 是什么类型，再决定怎么处理。
具体来说，pdf-inspector 能做四件事：
1.智能分类：判断 PDF 是文本型、扫描件、图片型还是混合型
2.位置感知提取：不仅提取文字，还保留坐标和字体信息
3.Markdown 转换：输出干净的 Markdown，标题、列表、表格统统搞定
4.按需路由：精确到具体哪几页需要 OCR，而不是全量处理
最炸裂的是性能数据——分类只要 10-50ms，文本型 PDF 本地处理 200ms 以内，200 份 PDF 的基准测试居然只用了 0.47 秒。
没错，不到半秒，两百个文件。

核心亮点

亮点一：智能 PDF 分类

pdf-inspector 最核心的能力就是智能分类。
它的做法很聪明——不是把 PDF 从头到尾读一遍，而是采样内容流里的关键操作符：看看有没有文字绘制指令（Tj/TJ），有没有图片插入指令（Do），快速判断文档类型。
支持四种分类结果：
•TextBased：文本型 PDF，直接提取就完事了
•Scanned：扫描件，老老实实送去 OCR
•ImageBased：纯图片型文档
•Mixed：混合型，麻烦就在这儿，但 pdf-inspector 有办法
重点来了：它不会只给你一个模糊的结论，而是给出置信度分数（0.0-1.0）和按页的 OCR 路由信息。

亮点二：极致性能

说到性能，这就是 pdf-inspector 最恐怖的地方了。
Firecrawl 拿它跟几个主流工具做了对比，用的是 200 份真实 PDF 的测试集，结果把我看傻了：

亮点三：位置感知提取

用过其他 PDF 提取工具的人都知道那个痛点：提取出来的文字顺序是乱的。
尤其是双栏排版的技术论文、多栏的财经报告，左栏第一行和右栏第一行混在一起，读起来全乱套。
pdf-inspector 不一样。它提取的不只是文字本身，还带上了位置信息：
•X/Y 坐标：每个文本片段在页面上的精确位置
•字体信息：字体名称、字号、样式
•自动多列检测：识别报纸式多栏布局，还原正确的阅读顺序
这个功能对于 RAG 系统来说太重要了——你肯定不想让 AI 读到乱序的文本，然后生成一堆乱七八糟的总结。

亮点四：表格检测

表格是 PDF 处理的终极难题。我之前用过很多工具，要么把表格转成纯文本（格式全毁），要么直接跳过。
pdf-inspector 用了双模式检测来解决这个问题：
1.矩形检测模式：通过 PDF 里的绘图指令，识别有边框的表格
2.启发式检测模式：通过文本对齐方式，识别没有边框的表格
它能处理的表格类型相当丰富：
• 财务报表（数字对齐特别准）
• 跨页连续表格（比如年报里的合并报表）
• 脚注表格
• 各种边框样式的表格
基准测试里，pdf-inspector 的表格检测得分是 0.814，比第二名高了 0.12，比 MarkItDown 高了整整 0.54。这个差距不是一星半点。

快速上手

说了这么多，你肯定想试试了。下面是各平台的安装和使用方法。

Python 用户

pip install pdf-inspector

import pdf_inspector

# 一行代码搞定：分类 + 提取 + 转 Markdown
result = pdf_inspector.process_pdf("document.pdf")

print(result.pdf_type)   # "text_based", "scanned", "image_based", "mixed"
print(result.markdown)   # Markdown 内容
print(result.confidence)  # 置信度 0.0-1.0

Node.js 用户

npm install @firecrawl/pdf-inspector

import { readFileSync } from 'fs';
import { processPdf } from '@firecrawl/pdf-inspector';

const result = processPdf(readFileSync('document.pdf'));
console.log(result.pdfType);   // "TextBased" 等
console.log(result.markdown);  // Markdown 内容

浏览器端（WASM）

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);

Rust 用户

cargo add pdf-inspector

use pdf_inspector::process_pdf;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let result = process_pdf("document.pdf")?;
    println!("类型: {:?}", result.pdf_type);
    if let Some(markdown) = &result.markdown {
        println!("{}", markdown);
    }
    Ok(())
}

CLI 工具

如果你只是想快速测试，pdf-inspector 还提供了两个命令行工具：

# 安装
cargo install pdf-inspector

# 检测 PDF 类型（0.05 秒出结果）
detect-pdf document.pdf
detect-pdf document.pdf --json  # JSON 格式输出

# 转 Markdown
pdf2md document.pdf
pdf2md document.pdf --json              # 带元数据的 JSON
pdf2md document.pdf --select-pages 1,3,5-10  # 只处理指定页

# 智能管道示例
pdf_type=$(detect-pdf document.pdf --json | jq -r '.pdf_type')
if [ "$pdf_type" = "text_based" ]; then
    pdf2md document.pdf > output.md
else
    echo "需要送去 OCR"
fi

写在最后

pdf-inspector 是 Firecrawl 团队在 PDF 处理领域的一次漂亮出击。
它没有试图做一个"万能 PDF 魔法盒"，而是非常务实地解决了一个核心问题：不该做 OCR 的，就别做 OCR。
它的核心价值可以总结为五点：
1.智能路由：精确判断哪些 PDF（或哪些页面）需要 OCR，不浪费资源
2.极致性能：200 份文档 0.47 秒，比竞品快 30 倍
3.结构化输出：保留标题、表格、列表等 Markdown 结构，即插即用
4.多平台覆盖：Python、Node.js、Rust、浏览器全支持
5.轻量无依赖：纯 Rust 实现，单依赖，无云服务，保护隐私
如果你正在构建 PDF 处理管道、RAG 系统或文档自动化工具，pdf-inspector 是值得纳入的技术选型。
项目地址：https://github.com/firecrawl/pdf-inspector