firecrawl/pdf-inspector

Kết luận: partial · Công nghệ: pdf-processing · ocr-routing · text-extraction · rust · document-ingestion

firecrawl/pdf-inspector là thư viện/utility tập trung vào kiểm tra PDF, phân loại scanned vs text-based, và trích xuất văn bản để quyết định pipeline xử lý phù hợp. Với ~9.7k sao và phạm vi rõ ràng cho OCR routing/document ingestion, đây là lựa chọn đáng thử khi hệ thống cần đọc PDF nhanh trước khi đẩy sang OCR hay indexing.

📖 Giới thiệu chi tiết

🧩 Nó là gì?

firecrawl/pdf-inspector là một thư viện Rust rất nhanh để kiểm tra file PDF, nhận biết PDF có sẵn chữ hay chỉ là ảnh scan, rồi trích xuất nội dung thành text hoặc Markdown sạch.

Nói đơn giản: nó giúp bạn “soi” một file PDF trước khi quyết định nên đọc trực tiếp hay phải đưa qua OCR.

🎯 Giải quyết vấn đề gì? Dành cho ai?

Nhiều hệ thống xử lý tài liệu thường gặp câu hỏi: “PDF này có chữ thật để trích xuất không, hay chỉ là ảnh scan cần OCR?”

firecrawl/pdf-inspector giải quyết đúng bài toán đó:

• Nhận diện PDF thuộc loại TextBased, Scanned, ImageBased, hoặc Mixed.
• Trích xuất text có hiểu vị trí, thứ tự đọc, cột, bảng, heading, link.
• Chuyển PDF text-based thành Markdown để dễ đưa vào search, AI, indexing, hoặc lưu trữ.
• Giúp tránh gửi mọi PDF sang OCR, vốn thường chậm và tốn chi phí.

Dự án này phù hợp với:

• Developer xây hệ thống document ingestion, tức pipeline nạp và xử lý tài liệu.
• Team làm search, RAG, AI chatbot, indexing tài liệu.
• Hệ thống cần xử lý nhiều PDF như báo cáo, hóa đơn, tài liệu pháp lý, nghiên cứu.
• Người cần công cụ CLI để nhanh chóng chuyển PDF sang Markdown.

⚙️ Hoạt động ra sao?

• Nhận đầu vào là PDF từ file, bytes, Node.js, Python, Rust, CLI hoặc browser WebAssembly.
• Đọc cấu trúc PDF và kiểm tra các trang có toán tử text như Tj / TJ hay chỉ có ảnh như Do.
• Phân loại PDF thành TextBased, Scanned, ImageBased, hoặc Mixed.
• Trả về độ tin cậy qua confidence score từ 0.0 đến 1.0.
• Nếu có trang không có text, trả về pages_needing_ocr để bạn chỉ OCR đúng các trang cần thiết.
• Nếu PDF có text thật, extractor sẽ lấy chữ cùng thông tin vị trí như font, tọa độ X/Y, dòng, cột.
• Layout engine sắp xếp lại thứ tự đọc, xử lý nhiều cột, bảng, heading, list, code block, link.
• Markdown converter biến nội dung đã trích xuất thành Markdown sạch.
• Tài liệu chỉ được load một lần rồi dùng chung cho cả bước detect và extract, tránh đọc lặp không cần thiết.

Luồng xử lý dễ hình dung:

PDF arrives
  → pdf-inspector classifies it (~20ms)
  → TextBased + high confidence?
      YES → extract locally (~150ms), done
      NO  → send to OCR service (2-10s)

🆚 Khi nào nên dùng / không nên

Nên dùng firecrawl/pdf-inspector khi:

• Bạn cần phân loại nhanh PDF trước khi quyết định có OCR hay không.
• PDF chủ yếu là text-based, ví dụ báo cáo, research papers, invoices, legal PDFs.
• Bạn cần Markdown sạch, có heading, list, bảng, link, thứ tự đọc tương đối tốt.
• Bạn muốn xử lý local, không phụ thuộc dịch vụ bên ngoài.
• Bạn cần chạy trong Rust, Python, Node.js, CLI hoặc browser WebAssembly.

Không nên dùng khi:

• Bạn cần OCR cho ảnh scan hoàn toàn. pdf-inspector không làm OCR.
• PDF là ảnh chụp mờ, scan kém chất lượng, hoặc chữ nằm trong ảnh.
• Bạn cần hiểu ngữ nghĩa sâu như “đọc hiểu” nội dung, tóm tắt, phân loại theo chủ đề. Nó chỉ trích xuất và cấu trúc hóa nội dung.
• Bạn cần độ chính xác tuyệt đối với mọi layout PDF phức tạp. PDF là định dạng khó, nên vẫn có trường hợp cần fallback sang OCR hoặc parser khác.

So với lựa chọn khác:

• So với OCR: nhanh và rẻ hơn rất nhiều nếu PDF đã có text, nhưng không đọc được chữ nằm trong ảnh.
• So với parser PDF tổng quát: tập trung mạnh vào routing OCR, text extraction và Markdown sạch.
• So với dịch vụ cloud: chạy local, nhẹ, không cần gửi tài liệu ra ngoài.

🚀 Bắt đầu nhanh

Python

Cài đặt:

pip install maturin
maturin develop --release

Ví dụ tối thiểu:

import pdf_inspector

result = pdf_inspector.process_pdf("document.pdf")
print(result.pdf_type)   # "text_based", "scanned", "image_based", "mixed"
print(result.markdown)   # Markdown string or None

Node.js

Cài đặt:

npm install @firecrawl/pdf-inspector

Ví dụ tối thiểu:

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

const result = processPdf(readFileSync('document.pdf'));
console.log(result.pdfType);   // "TextBased", "Scanned", "ImageBased", "Mixed"
console.log(result.markdown);  // Markdown string or null

Browser WebAssembly

Cài đặt:

npm install @firecrawl/pdf-inspector-wasm

Ví dụ tối thiểu:

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

Cài đặt:

cargo add pdf-inspector

Hoặc thêm thủ công:

[dependencies]
pdf-inspector = "0.1"

Ví dụ tối thiểu:

use pdf_inspector::process_pdf;

let result = process_pdf("document.pdf")?;
println!("Type: {:?}", result.pdf_type);
if let Some(markdown) = &result.markdown {
    println!("{}", markdown);
}

CLI

Cài đặt:

cargo install pdf-inspector

Chuyển PDF sang Markdown:

pdf2md document.pdf

Xuất JSON để dùng trong pipeline:

pdf2md document.pdf --json

Chỉ detect, không extract:

detect-pdf document.pdf
detect-pdf document.pdf --json

Detect kèm phân tích layout như bảng và cột:

detect-pdf document.pdf --analyze --json

Chỉ xử lý một số trang:

pdf2md document.pdf --select-pages 1,3,5-10

✅ Điểm mạnh & ⚠️ Hạn chế

Điểm mạnh:

• Rất nhanh: phân loại PDF thường chỉ khoảng 10-50ms, xử lý text-based PDF local có thể dưới 200ms.
• Không cần OCR, không cần ML model, không cần dịch vụ ngoài.
• Hỗ trợ nhiều môi trường: Rust, Python, Node.js, CLI, browser WebAssembly.
• Trích xuất text có vị trí, font, tọa độ, hỗ trợ nhiều cột và thứ tự đọc.
• Chuyển Markdown khá giàu cấu trúc: heading, list, table, code block, bold/italic, URL, page break.
• Có khả năng chỉ ra trang nào cần OCR qua pages_needing_ocr, giúp tiết kiệm chi phí.
• Hỗ trợ bảng bằng hai cách: dựa trên rectangle trong PDF và dựa trên căn chỉnh text.
• Có phát hiện lỗi encoding để caller biết khi nào nên fallback sang OCR.

Hạn chế:

• Không phải OCR engine, nên không đọc được chữ nằm trong ảnh scan.
• PDF quá phức tạp hoặc layout lạ vẫn có thể cho Markdown chưa hoàn hảo.
• Kết quả bảng phụ thuộc vào cách PDF được tạo; không phải bảng nào cũng giữ cấu trúc tốt.
• Với PDF Mixed, bạn vẫn cần pipeline OCR bổ sung cho các trang không có text.
• Nếu font encoding trong PDF bị hỏng nặng, text trích xuất có thể không đáng tin và cần fallback.
• Benchmark có thể khác tùy máy, corpus tài liệu và phiên bản engine.