pdf-inspector API 快速参考 - 五端用法对照

API 参考

pdf-inspector 的核心 API 就四件事，五端基本一致：

API	做什么	返回
`processPdf` / `process_pdf`	检测 + 提取 + 转 Markdown，一步到位	结果对象（含 `markdown`、`pdfType`、置信度）
`detectPdf` / `detect_pdf`	只判定类型，不提取内容	结果对象（`markdown` 为空）
`classifyPdf` / `classify_pdf`	轻量分类（类型 + 页数 + 需 OCR 页码 + 置信度）	分类结果对象
`extractText` / `extract_text`	提取纯文本	字符串

「先分类再决定怎么处理」是官方推荐的姿势：拿到 pagesNeedingOcr 列表后，只有真正需要的页面才送 OCR。

五端对照

Rust

use pdf_inspector::{process_pdf, detect_pdf, PdfType};

// 一步到位：检测 + 提取 + Markdown
let result = process_pdf("document.pdf")?;
println!("{:?} {:.0}%", result.pdf_type, result.confidence * 100.0);
if let Some(markdown) = &result.markdown {
    println!("{}", markdown);
}

// 只判定类型
let info = detect_pdf("document.pdf")?;
match info.pdf_type {
    PdfType::TextBased => { /* 本地直接提取 */ }
    _ => { /* info.pages_needing_ocr 告诉你哪些页要 OCR */ }
}

安装：cargo add pdf-inspector。更多选项见 PdfOptions builder（process_pdf_with_options）：指定页码、ProcessMode::Analyze 只分析版面、自定义抽样策略等；字节入口用 process_pdf_mem。

Node.js

import { classifyPdf, extractPagesMarkdownAsync } from '@firecrawl/pdf-inspector'

// 轻量分类（同步）
const classification = classifyPdf(pdf)
console.log(classification.pdfType)         // "TextBased" | "Scanned" | "Mixed" | "ImageBased"
console.log(classification.pagesNeedingOcr) // [5, 12]（0-indexed）
console.log(classification.confidence)      // 0.875

// 服务端推荐异步变体：libuv 线程池执行，不阻塞事件循环
if (classification.pdfType === 'TextBased') {
  const { pages } = await extractPagesMarkdownAsync(pdf)
}

安装：npm install @firecrawl/pdf-inspector。同步 API（processPdf/classifyPdf/extractPagesMarkdown）在事件循环上执行，一次性脚本没问题；服务端大文件请用对应的 *Async 版本。另有 processPdfWithOcr（选择性 OCR）与 extractTextInRegions（按包围盒区域提取，带 needsOcr 质量标记）。

Python

import pdf_inspector

# 一步到位
result = pdf_inspector.process_pdf("document.pdf")
print(result.pdf_type)       # "text_based"
print(result.page_count)
print(result.markdown)

# 只判定类型
info = pdf_inspector.detect_pdf("document.pdf")
if result.pdf_type == "text_based":
    print("可以本地提取！")
else:
    print(f"需要 OCR 的页：{result.pages_needing_ocr}")

# 带位置信息的文本项
items = pdf_inspector.extract_text_with_positions("document.pdf")
for item in items[:5]:
    print(f"'{item.text}' at ({item.x:.0f}, {item.y:.0f}) size={item.font_size}")

安装：pip install pdf-inspector。处理期间释放 GIL，适合与 asyncio / 多线程混用；包内附带类型存根（.pyi）。其他常用函数：process_pdf_bytes（字节入口）、extract_pages_markdown（逐页 Markdown + 版面元数据）、process_pdf_with_ocr（选择性 OCR）、extract_structure_elements（tagged PDF 结构树）。

WebAssembly（浏览器）

import init, { processPdf, detectPdf, classifyPdf, extractText } from '@firecrawl/pdf-inspector-wasm'

await init()          // 加载 wasm，一次即可
const result = processPdf(pdfBytes, { profile: 'compact', includePageMarkers: true })
console.log(result.pdfType)
console.log(result.markdown)

安装：npm install @firecrawl/pdf-inspector-wasm。解析完全在浏览器本地执行，文件不出设备——本站首页的在线 Demo 就是它。单线程构建无需跨域隔离；CMap 内嵌，中日韩字体开箱即用；解析是同步的，大文件建议放 Web Worker。

CLI

crate 自带两个二进制（cargo install pdf-inspector 即可拿到；npm 包也内置 CLI）：

pdf2md document.pdf                    # 转 Markdown 输出到 stdout
pdf2md document.pdf --pages 1-3        # 只处理部分页
pdf2md document.pdf --compact          # 省 token 的紧凑输出
pdf2md document.pdf --json             # 结构化 JSON
detect-pdf document.pdf --analyze --json   # 类型判定 + 分析信息

返回结构一览（以 Python 为例）

class PdfResult:                     # process_pdf / detect_pdf
    pdf_type: str                    # "text_based" | "scanned" | "image_based" | "mixed"
    markdown: str | None             # Markdown（detect_pdf 时为 None）
    page_count: int
    confidence: float                # 0.0 - 1.0
    pages_needing_ocr: list[int]     # 1-indexed 页码
    has_encoding_issues: bool        # 字体编码损坏 —— 建议 OCR 兜底
    pages_with_tables: list[int]
    pages_with_columns: list[int]

Node.js 的 PdfClassification 同构：pdfType / pageCount / pagesNeedingOcr（0-indexed）/ confidence。

需要注意的事

页码索引不统一是官方现状：Python 的 pages_needing_ocr 是 1-indexed，extract_pages_markdown 的 page 是 0-indexed，跨语言对照时留意
同步 vs 异步：Node 端同步版本会占住事件循环，服务器场景一律用 *Async
WASM 无 OCR：扫描件在浏览器端只会得到类型判定和明确提示
各端完整签名以官方文档为准：napi/README、docs/python.md、docs/rust-api.md

按语言深入请进：Node.js · Python · Rust · WebAssembly · CLI；遇到问题去错误处理与限制。