5 分钟上手 pdf-inspector：PDF 类型判断与 Markdown 提取完整指南
【免费下载链接】pdf-inspectorFast Rust library for PDF inspection, classification, and text extraction. Intelligently detects scanned vs text-based PDFs to enable smart routing decisions.项目地址: https://gitcode.com/GitHub_Trending/pdf/pdf-inspector
pdf-inspector 是一个纯 Rust 编写的开源 PDF 检查库：它在十几毫秒内判断一份 PDF 是文本型、扫描型还是混合型，再把文本型 PDF 在本地转成带标题、列表和表格的 Markdown，全程不调用 OCR 服务。本文带你在 5 分钟内完成安装，跑通"提取 Markdown、快速判断类型、选择性 OCR 路由"三个核心场景。
🎯 它解决什么问题：先判断，再决定要不要 OCR
很多 PDF 管线的成本都花在 OCR 上，但实际上不少 PDF 本身就带文本层，根本不需要 OCR。pdf-inspector 的设计思路就是"先分类，再路由"：
- 智能分类：约 10–50ms 判断文档属于 text_based、scanned、image_based 还是 mixed，返回 0–1 的置信度，并列出具体哪些页缺少文本层。
- 位置感知提取：每段文本携带 X/Y 坐标、字体大小与加粗/斜体等属性，自动处理多栏版式和 RTL（从右到左）文本的阅读顺序。
- Markdown 转换：按字号分级识别 H1–H4 标题，还原列表、代码块、加粗/斜体、表格，并把 URL 转成 Markdown 链接。
- 选择性 OCR：只有被原生提取拒绝的页面才路由到本地 OCR（PP-OCRv6 Small），干净的文本型 PDF 不会加载任何 OCR 运行时。
- 一次解析共享：文档只解析一次，检测结果和提取结果共用同一次 I/O，不重复读文件。
官方给出的典型路由是这样的：PDF 进来后先分类（约 20ms），如果判定为文本型且置信度高，就在本地约 150ms 内完成提取；否则才送去 OCR 服务（2–10s）。项目资料显示，约 54% 的 PDF 属于"不需要 OCR"的那一类——这部分成本被直接省掉。
📦 三步完成安装：Python、Node.js 与浏览器
Python：pip 一行命令
pip install pdf-inspector预编译 wheel 覆盖 CPython ≥3.8 的 Linux（x86_64、aarch64）、macOS（Intel、Apple Silicon）和 Windows（x64），无需 Rust 工具链。如果你是在仓库源码目录里做本地开发：
pip install maturin maturin develop --releaseNode.js：预编译二进制免编译
npm install @firecrawl/pdf-inspectornpm 会自动按平台安装对应的预编译二进制（Linux x64/ARM64、macOS ARM64、Windows x64），装完即可用。
浏览器：WebAssembly 版本
npm install @firecrawl/pdf-inspector-wasm同一个 Rust 核心编译成 WebAssembly，PDF 字节在浏览器本地解析、不会上传到任何服务器，适合 Web Worker 场景。
Rust 与命令行工具
cargo add pdf-inspector # 作为库依赖 cargo install pdf-inspector # 安装 pdf2md / detect-pdf 两个 CLI⚡ 首次实战：一行代码把 PDF 提取成 Markdown
Python 端最常用的是process_pdf，它一次完成"检测 + 提取 + 转 Markdown"：
import pdf_inspector result = pdf_inspector.process_pdf("document.pdf") print(result.pdf_type) # "text_based" / "scanned" / "image_based" / "mixed" print(result.confidence) # 0.0 - 1.0 的置信度 print(result.markdown) # 可直接使用的 Markdown 字符串返回结果里还有几个值得关注的字段：
- pages_needing_ocr：缺少文本层、需要 OCR 的页码列表（1 起始）。
- pages_with_tables / pages_with_columns：检测到表格和多栏版式的页面，可用来判断文档复杂度。
- has_encoding_issues：字体编码损坏时为 True，提示你回退到 OCR。
- processing_time_ms：本次处理耗时（毫秒）。
Node.js 端的对应写法同样直接：
import { readFileSync } from 'fs'; import { processPdf } from '@firecrawl/pdf-inspector'; const result = processPdf(readFileSync('document.pdf')); console.log(result.pdfType, result.markdown);不想写代码的话，CLI 一条命令就能出结果：
pdf2md document.pdf加--json可把结果变成 JSON 方便管道处理。浏览器端只需await init()后调用processPdf(uint8Array)，细节见 wasm/README.md。
🧭 快速判断 PDF 类型：10–50ms 决定路由
如果你的管线只需要"该不该走 OCR"这个答案，用detect_pdf就够了，它只做检测不做提取：
detection = pdf_inspector.detect_pdf("document.pdf") print(detection.pdf_type) # 类型 print(detection.confidence) # 置信度 print(detection.pages_needing_ocr) # 缺文本层的页分类原理是采样内容流，检查其中是否存在Tj/TJ文本操作符和Do图像操作符，因此即便 300 多页的大文档也能在毫秒级出结果。采样策略可按需选择：
- EarlyExit（默认）：逐页扫描，遇到第一个非文本页就提前退出，适合"文本型 PDF 直接走快速提取"的管线。
- Full：完整扫描不提前退出，用来精确区分 Mixed 和 Scanned。
- Sample(n)：均匀抽取 n 页（首、中、尾），适合速度优先的超大文档。
- Pages：只检查指定的 1 起始页码。
确认是扫描型之后，可以一步调用选择性 OCR：
ocr = pdf_inspector.process_pdf_with_ocr("document.pdf") print(ocr.pages_routed_to_ocr) # 实际走了 OCR 的页默认auto模式只对被原生提取拒绝的页面跑本地 PP-OCRv6 Small，并给每一页附带来源（native/ocr/fused）、模型标识和置信度等溯源信息；只有在真正路由到 OCR 时才会用到 PDFium 和 ONNX Runtime 外部库。离线部署、模型缓存等配置见 docs/ocr-runtime.md。
🔬 进阶用法：指定页面、位置信息与基准测试
常规之外的能力，每个都是一行调用，完整签名见 docs/python.md：
- 指定页面：
process_pdf("document.pdf", pages=[0, 2])只处理选中页。 - 字节输入：
process_pdf_bytes(data)直接处理内存中的 PDF，不落盘。 - 位置信息：
extract_text_with_positions返回每段文本的坐标、字号、字体与样式。 - 按页 Markdown：
extract_pages_markdown逐页输出 Markdown 及表格/多栏等布局元数据。 - 区域提取：
extract_text_in_regions只提取边界框内的文本，并给出needs_ocr质量标记。 - 标签 PDF：
extract_structure_elements读取带标签 PDF 的标题/段落等结构元素。
CLI 端同样够用：pdf2md支持--json、--raw（纯 Markdown 无头信息）、--compact（压缩点线等填充）、--pages（插入分页标记）、--select-pages 1,3,5-10（选页）；detect-pdf --analyze --json则额外输出表格与栏数分析。
性能方面，项目基准在 opendataloader-bench 语料（200 份 PDF，本地引擎、OCR 关闭）上刷新于 2026-07-31，Apple M4 Pro：
| 引擎 | 综合得分 | 阅读顺序 | 表格 (TEDS) | 200 份总耗时 |
|---|---|---|---|---|
| pdf-inspector | 0.875 | 0.915 | 0.814 | 0.470s |
| liteparse | 0.873 | 0.913 | 0.693 | 0.750s |
| opendataloader | 0.831 | 0.902 | 0.489 | 2.569s |
| pymupdf4llm | 0.735 | 0.886 | 0.401 | 17.117s |
| markitdown | 0.589 | 0.844 | 0.273 | 16.165s |
想在自己的语料上复现对比，仓库提供了配对基准工具，方法说明见 docs/benchmarking.md。
📚 延伸阅读：官方文档与示例
- docs/python.md：Python 完整 API 与结果类型说明。
- napi/README.md：Node.js / Bun 绑定，含区域提取与异步版本。
- wasm/README.md：浏览器 WebAssembly 使用细节。
- docs/rust-api.md：Rust 库 API 与 OCR 低层控制。
- docs/ocr-runtime.md：OCR 外部依赖安装、平台支持与离线模式。
- docs/debugging.md：用
RUST_LOG打开调试日志。 - examples/basic_usage.py：可运行的 Python 示例脚本，覆盖本文全部入口函数。
从本文的安装命令开始，先拿一份真实 PDF 跑一遍process_pdf看看输出质量；如果你的管线里混有扫描文档，再试一下detect_pdf的快速路由。更细的参数、OCR 运行时配置和基准复现方法，直接查阅上面链接的文档即可。
【免费下载链接】pdf-inspectorFast Rust library for PDF inspection, classification, and text extraction. Intelligently detects scanned vs text-based PDFs to enable smart routing decisions.项目地址: https://gitcode.com/GitHub_Trending/pdf/pdf-inspector
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
