pdf-inspector 新手入门 - 第一个 PDF 转 Markdown

新手教程

第一次用 pdf-inspector，很多人最担心的是"会不会装不上、解析不了"。其实真正影响体验的，往往是没想清楚三个问题：这份 PDF 是什么类型、在哪里跑最快、以及输出会不会丢东西。把这三件事先弄明白，第一次解析五分钟内就能完成。

先把预期放对

pdf-inspector 是一个解析库，不是一个 PDF 阅读器。它的任务是：先判断 PDF 能不能直接提取文字，能提就转成干净、带位置信息的 Markdown。开始前先接受三件事：

解析是本地完成的，不联网、不上传，文本型 PDF 全流程 200ms 以内
输出的是纯文本 Markdown，不会保留视觉样式（字体颜色、装饰图形会有取舍）
纯扫描件/图片型 PDF 提不出文字——它不会假装成功，而是明确告诉你哪些页需要 OCR

开始前需要知道的事

核心能力：分类（TextBased / Scanned / ImageBased / Mixed）+ 提取（位置感知 + Markdown）
许可证：MIT，免费、可商用
原生绑定：Rust / Node.js / Python / 浏览器（WebAssembly）/ CLI
已知限制：网页 WASM 版不含 OCR；扫描页需要 OCR 运行时
官方仓库：github.com/firecrawl/pdf-inspector

第一次解析：CLI 三连

CLI 是上手最快的路径，不需要任何项目环境。Rust 用户一条命令安装：cargo install pdf-inspector，随后就有两个工具可用：

# 1. 判定类型：这 PDF 能不能直接提文字？
detect-pdf annual-report.pdf --analyze --json

# 2. 转 Markdown，输出到终端
pdf2md annual-report.pdf

# 3. 只处理部分页，输出到文件
pdf2md annual-report.pdf --pages 1-3 -o report.md

先判定再提取

detect-pdf 只花 10–50ms 就告诉你文档类型和需要 OCR 的页码。拿到 TextBased 再跑 pdf2md，是官方推荐的路由姿势。

转完打开输出的 Markdown 看一眼：标题有没有变成 # 层级？多栏是不是按正确顺序排的？表格规不规整？这些就是 pdf-inspector 给你打的样。

常用选项速记

用法	说明
`pdf2md <file>`	解析文件，Markdown 输出到 stdout
`pdf2md <file> -o out.md`	输出到指定文件
`pdf2md <file> --pages 1-3`	只处理指定页
`pdf2md <file> --compact`	紧凑模式，省 token 的精简输出
`pdf2md <file> --json`	输出结构化 JSON
`detect-pdf <file> --analyze --json`	类型判定 + 分析信息

各语言的第一行代码

CLI 之外，其他语言同样几行起步：

// Node.js
import { classifyPdf } from '@firecrawl/pdf-inspector'
const result = classifyPdf(pdfBuffer)
console.log(result.pdfType)   // "TextBased"

# Python
import pdf_inspector
result = pdf_inspector.process_pdf("document.pdf")
print(result.pdf_type)        # "text_based"
print(result.markdown)

// Rust
use pdf_inspector::process_pdf;
let result = process_pdf("document.pdf")?;
println!("{}", result.markdown.unwrap_or_default());

// 浏览器（WASM）
import init, { processPdf } from '@firecrawl/pdf-inspector-wasm'
await init()
const { pdfType, markdown } = processPdf(pdfBytes)

想深入某一端？看API 快速参考，或者直接进对应语言的完整页（Node.js / Python / Rust / WebAssembly / CLI）。

三个常见误区

误区一：以为所有 PDF 都能直接转

不能。约 54% 的 PDF 是原生文本型，可以直接转；剩下的扫描件和图片型必须 OCR。pdf-inspector 的价值恰恰在于先花几十毫秒搞清楚你手里的是哪种，别把文本型也送去烧钱。

误区二：以为能无损还原排版

做不到，也不需要。pdf-inspector 的目标是信息完整且结构正确（标题层级、阅读顺序、表格都在），不是视觉一致。追求像素级还原请用 PDF 阅读器，追求给 LLM 干净输入请用 pdf-inspector。

误区三：遇到乱码以为库坏了

更可能是源文件的字体编码就是坏的（GID 编码、缺失 ToUnicode CMap）。pdf-inspector 会把这些页面标记出来（Python 里看 has_encoding_issues，区域提取里看 needsOcr），正确的做法是让这些页走 OCR，而不是反复重试。

新手要点清单

用 cargo install pdf-inspector 装好 CLI，先跑 detect-pdf 看类型
Node 服务端用异步变体（processPdfAsync 等），别阻塞事件循环
大文档只需要部分内容时用 pages 参数，省时间也省内存
喂 LLM 用 --compact / profile: "compact" 省 token
扫描件提示需要 OCR 不是 bug，那是它在替你省钱

如果只记一句话：pdf-inspector 是"PDF → 结构化 Markdown"这条管道的入口，先判定类型，再决定怎么提取。 下一步可以去看API 快速参考，或者直接跳到你的语言那一篇。