pdf-inspector

项目简介

pdf-inspector 是由 Firecrawl 团队开源的 Rust 库，专注于 PDF 文件的智能分类与文本提取。它能够快速判断一个 PDF 是扫描件还是原生文本文档，并据此决定是否需要调用 OCR 服务——据统计，约 54% 的 PDF 属于文本型，无需 OCR 即可完成提取，从而大幅节省计算成本。

核心功能

• 智能分类：10～50ms 内判断 PDF 类型（TextBased／Scanned／ImageBased／Mixed），返回置信度评分和逐页 OCR 路由建议
• 文本提取：支持位置感知提取，保留字体信息、X／Y 坐标，自动识别多栏排版和 RTL（从右到左）文本
• Markdown 转换：自动识别标题（H1～H4）、列表、代码块（等宽字体检测）、表格、链接等元素
• 表格检测：双轨策略——基于 PDF 绘图操作的矩形检测，加上基于文本对齐的启发式检测，覆盖财务报表、脚注、跨页表格
• 编码异常检测：自动标记字体编码问题，调用方可在此时回退到 OCR
• 选择性 OCR：仅对需要 OCR 的页面调用 PP-OCRv6 Small 模型，其余页面直接文本提取
• 跨平台多语言：Rust 原生库、Cargo 封装、Python 绑定（pip install）、Node.js 绑定（npm）和浏览器 WebAssembly 版本
• 单文档一次解析：检测与提取共享同一文档对象，避免重复 I/O

技术实现

pdf-inspector 使用 Rust 编写，利用 Rust 的内存安全特性和高性能优势，通过解析 PDF 内容流（Content Streams）来采样判断文档类型，而非依赖文件扩展名或文件头 magic bytes。在文本提取环节，库支持 ToUnicode CMap 解码，覆盖 Type0／Identity-H 字体、UTF-16BE、UTF-8 和 Latin-1 编码。表格检测采用双轨策略：基于 PDF 绘图操作的矩形检测，加上基于文本对齐的启发式检测，确保金融表格、跨页脚注等复杂场景的召回率。选择性 OCR 模式下，Rust 层负责判断页面是否需要 OCR，需要时才触发 PP-OCRv6 Small 模型，避免对所有页面无差别调用 OCR 服务。

快速上手

第一步：安装依赖。通过 pip install pdf-inspector（Python）或 npm install @firecrawl/pdf-inspector（Node.js）安装，或 cargo add pdf-inspector 加入 Rust 项目 第二步：获取分类结果。导入库后调用 inspect(pdf_path)，获取 type、confidence 和 per_page_ocr_recommendations 第三步：执行文本提取。根据分类结果调用 extract(pdf_path)，获得包含位置坐标的结构化 Markdown 第四步：集成生产管道。在文档处理流程中作为智能路由节点，自动分流到文本提取或 OCR 管线

适用人群

• 文档处理平台开发者：需要批量处理合同、发票、报告等 PDF 文档的工程师
• RAG（检索增强生成）系统构建者：需要从 PDF 中提取高质量文本以供大模型使用
• 数据科学与研究机构：需要从学术论文、专利文档中批量提取结构化信息
• OCR 服务商：希望降低 OCR 调用成本，先行过滤掉无需 OCR 的文本型 PDF