Firecrawl PDF Inspector：先判断 PDF 是否需要 OCR，再转 Markdown

Firecrawl PDF Inspector（仓库名 pdf-inspector）是 Firecrawl 开源的一套本地 PDF 分类与文本提取工具。它可以判断 PDF 中的文字是否能够直接提取，读取文本和版面信息并转换为 Markdown，同时返回需要进一步 OCR 的页面。

在私有知识库、RAG 或批量文档处理流程中，PDF 通常要先经过文本提取，再进入切分、Embedding 或后续模型处理。如果不区分文档类型就把所有 PDF 都送进云端 OCR 或视觉模型，本身已经包含可提取文字的文件也会重复走一次识别流程，增加接口调用、处理时间和费用。

RAG 文档处理为什么要先判断 PDF 是否需要 OCR？

企业研报、电子合同、发票和学术论文里，有不少文件本身就是由 Word、LaTeX 或排版软件直接导出的原生文本 PDF。这类 PDF 通常已经包含可提取的文字和位置信息，不需要先把页面转成图片再做 OCR。

Firecrawl 自己的 PDF 数据里，大约有 54% 的文件不需要 OCR 就能直接提取文本。不同业务里的文档来源差别很大，这个比例不一定能直接套用，但也说明了一个问题：并不是每份 PDF 都值得先跑一遍 OCR。

Firecrawl PDF Inspector 做的就是把这一步判断放到 OCR 前面。能够可靠提取文字的 TextBased 页面直接在本地解析并转换为 Markdown；对于 Mixed、Scanned、ImageBased 文档中缺少可靠文本层或提取结果不理想的页面，再交给 OCR 处理。

Firecrawl PDF Inspector 怎么判断 PDF 是否需要 OCR

pdf-inspector 不需要先渲染整份 PDF 再做识别。它会读取 PDF 本身的页面结构和内容流，先判断文件里有没有可以直接提取的文本。

四种 PDF 类型与置信度

检测时，pdf-inspector 会解析 xref 表和页面树，并检查页面内容流中的文本操作符（Tj/TJ）和图像操作符（Do）。通常在 10~50 毫秒内就能返回结果，将 PDF 分为 TextBased、Scanned、ImageBased 或 Mixed，同时给出 0~1 的置信度分数。

可以按页面和区域决定是否需要 OCR

分类结果还会返回需要 OCR 的具体页码。比如一份 50 页的财报，前 2 页是扫描封面，后面 48 页都能正常提取原生文本，就可以只处理前 2 页，不需要把整份 PDF 再跑一遍 OCR。

Node.js 版本还提供 extractTextInRegions() 接口。调用方指定页面区域后，pdf-inspector 会尝试从 PDF 结构中提取该区域的文本，并通过 needsOcr 标记文本为空、乱码或字体编码异常等提取结果不可靠的区域。后续 OCR 只需要处理这些区域，不必默认重新识别整页。

Firecrawl PDF Inspector 解析效果怎么样？基准测试与同类工具对比

pdf-inspector 不只是判断 PDF 类型，也会处理文本的阅读顺序和版面结构。当前版本支持多栏排版、CID/Type0 字体、标题和列表识别，以及基于矩形边框和文本对齐的两种表格检测方式，提取结果可以直接转换为 Markdown。

项目 README 还给出了一组 opendataloader-bench 测试结果，共包含 200 份 PDF，比较对象都是未启用 OCR 和模型解析的本地 PDF 引擎。下面的数据更新于 2026 年 7 月 31 日，测试设备为 Apple M4 Pro，成绩取 5 次完整运行的中位数，另有一次 warm-up 不计入结果。

Firecrawl PDF Inspector 怎么接入？CLI、Python、Node.js 与本地 OCR

pdf-inspector 的核心用 Rust 编写，可以直接通过命令行使用，也提供 Python、Node.js 和浏览器 WASM 版本。只是想检测 PDF 类型或转 Markdown，不需要另外配置 OCR 服务。

# 安装
cargo install pdf-inspector

# 检测 PDF 类型并输出 JSON
detect-pdf document.pdf --json

# 转为 Markdown
pdf2md document.pdf

npm install @firecrawl/pdf-inspector

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

const pdf = readFileSync('document.pdf');
const result = classifyPdf(pdf);

console.log(result.pdfType);
console.log(result.pagesNeedingOcr);
console.log(result.confidence);

pip install pdf-inspector

import pdf_inspector

result = pdf_inspector.process_pdf("document.pdf")

print(result.pdf_type)
print(result.pages_needing_ocr)
print(result.markdown)

默认安装主要使用 PDF 自带的文本和结构信息完成分类、文本提取和 Markdown 转换，不会加载 OCR 模型。需要直接处理扫描页面时，Rust / CLI 版本可以额外启用 ocr feature：

cargo install pdf-inspector --features ocr --bin pdf2md

启用后，pdf-inspector 会使用 PP-OCRv6 Small 处理被分流到 OCR 的页面，而不是默认把整份 PDF 都重新识别。OCR 版本还需要 PDFium、ONNX Runtime 和对应模型文件等运行依赖，因此部署方式会比默认解析版本复杂一些。

Firecrawl PDF Inspector 适合哪些场景？有哪些限制？

pdf-inspector 更适合原生文本 PDF 和扫描页混在一起的文档库，尤其是需要批量处理合同、研报、论文、发票或知识库资料的场景。如果文件来源比较单一，也可以先用自己的文档样本测试一下，再决定有没有必要加这一层判断。

使用前可以留意这几点：

• 复杂扫描件仍可能需要更强的 OCR：对于字迹模糊、页面倾斜、纸张老化或版面非常复杂的扫描文件，即使启用了 pdf-inspector 的可选本地 OCR，实际识别效果仍要看文档质量；必要时可以继续接其他 OCR 服务或视觉模型。
• 网页版 Demo 主要用于体验解析：官方 WebAssembly 演示主要面向原生文本 PDF，目前单文件限制为 25MB。大文件或完整 OCR 流程更适合使用本地库或 CLI。
• 是否上传第三方取决于后续 OCR 怎么接：PDF 分类和原生文本提取可以在本地完成。如果后面接的是本地 OCR，文件可以继续留在自己的环境里；如果调用云端 OCR API，对应页面或数据就会进入第三方服务。
• 特殊部署环境需要检查兼容性：Python 和 Node.js 已提供常见 Linux、macOS 和 Windows 平台的预编译包。未覆盖的平台或部分受限 Serverless 环境，可能还需要处理原生依赖或自行编译。

如果每天要处理很多来源不同的 PDF，尤其是原生文本和扫描件混在一起的情况，pdf-inspector 可以先把能够直接解析的页面筛出来，减少后面的 OCR 请求。如果资料基本都是纯扫描档案，这层分类带来的节省就不会那么明显。

Firecrawl PDF Inspector 源码、文档与在线演示入口