firecrawl/pdf-inspector

功能

pdf‑inspector 是一個快速的 Rust 基礎庫，分析 PDF 並判斷其類型（純文字、掃描影像、混合等），然後以結構化方式提取文字。它可以將 PDF 轉換為乾淨的 Markdown，保留標題、清單、程式碼區塊、表格，甚至每個文字片段的精確 X/Y 位置。對於包含影像而非真實文字的 PDF，該庫可選擇性地僅對需要的頁面運行輕量級 OCR 模型（PP‑OCRv6 Small），避免對整個文件進行 OCR 處理。

為何重要

你遇到的大多數 PDF 已經是文字型的，但許多管道仍會將每個文件送至昂貴的 OCR 服務。pdf‑inspector 可在 10–50 ms 內完成 PDF 分類，對大多數文件在 200 ms 內完成文字提取，大幅節省計算成本與延遲。其位置感知的提取方式也使下游任務——如建構可搜尋索引、餵給 LLM 或將文件轉換為結構化資料——更加可靠。

適用對象

• 建構文件處理管道的開發者（如網路爬蟲、企業級資料攝入服務），需要一個低成本的初步步驟來判斷是否需要 OCR。
• 面向 LLM 的應用，需要攝入 PDF 並取得乾淨的 Markdown 或結構化文字，而無需支付外部 OCR API 費用。
• 資料科學團隊，需要從研究論文、財務報告、發票或法律合約中提取表格、標題和程式碼片段。
• 前端工程師，希望使用 WebAssembly 在瀏覽器中直接執行 PDF 解析。

工作原理（概覽）

1. 快速分類 – 採樣 PDF 的內容流，檢測文字（Tj/TJ）與影像（Do）操作符，返回置信度分數及需要 OCR 的頁面列表。
2. 單次遍歷解析 – 檔案僅載入一次，相同的記憶體表示被用於分類和提取，避免重複 I/O。
3. 提取流程 – 解析字型、解碼 CID 編碼、遍歷 PDF 操作符生成帶字型、大小和 X/Y 坐標的 TextItem，然後分組為行、檢測欄位、確定閱讀順序。
4. 表格檢測 – 使用兩種策略：(a) 從繪圖命令中基於矩形的檢測（PDF 矩形的並查集）和 (b) 從文字位置的啟發式對齊檢測，支援跨頁表格和財務佈局。
5. Markdown 轉換 – 分析字型大小比以識別標題，透過字型名稱識別粗體/斜體，等寬字型識別程式碼區塊，清單標記、URL 等，並輸出乾淨的 Markdown，可選添加分頁標記。
6. 可選 OCR – 啟用 ocr 功能後，僅將標記為非文字的頁面進行光柵化並輸入 PP‑OCRv6 Small 模型，其餘快速 Rust 流程保持不變。

快速上手

• Rust: cargo add pdf-inspector，然後呼叫 process_pdf("file.pdf")。
• Python: 安裝 maturin 建構工具，執行 maturin develop --release，然後 import pdf_inspector; pdf_inspector.process_pdf("file.pdf")。
• Node.js: npm install @firecrawl/pdf-inspector，使用 processPdf。
• 瀏覽器: 安裝 WASM 套件 @firecrawl/pdf-inspector-wasm，呼叫 init()，然後對 PDF 的 Uint8Array 呼叫 processPdf。
• CLI: cargo install pdf-inspector，執行 pdf2md file.pdf（僅分類可使用 detect-pdf）。

限制與待解決問題

• OCR 為可選，需要額外的原生相依（PDFium、ONNX Runtime、PP‑OCR 模型）。禁用 ocr 功能後，無法從純影像 PDF 中提取文字。
• 複雜佈局（如深度嵌套表格、特殊欄位結構）仍可能需要手動後處理；啟發式表格檢測對大多數財務與報告類表格效果良好，但並非完整的佈局引擎。
• 語言支援 – 核心提取與語言無關，但 OCR 質量取決於 PP‑OCR 模型，主要針對拉丁字母優化，對 CJK 或手寫文字可能準確率較低。
• 超大 PDF 性能 – 可透過不同 ScanStrategy 選項（完整掃描 vs. 採樣）調整分類，以在超大文件上平衡速度與精度。

---

所有細節均直接來自倉儲的 README。