PDF 转 Markdown 教程:pdf-inspector 本地解析,自动判断是否需要 OCR

01

PART

pdf-inspector 是什么

OVERVIEW · TOOL POSITIONING

判断 PDF 是文本型、扫描型、图片型还是混合型。

从文本型页面提取内容，并转换成结构化 Markdown。

02

PART

为什么先判断，再决定是否 OCR

ROUTING · COST CONTROL

PDF 类型；

判断置信度；

总页数；

需要 OCR 的页码；

字体编码是否异常；

文档是否包含表格或多栏布局。

03

PART

它能把哪些内容转成 Markdown

OUTPUT · DOCUMENT STRUCTURE

根据字号识别 H1 到 H4 标题；

识别项目符号、数字列表和字母列表；

保留粗体、斜体、链接与代码块；

处理多栏页面的阅读顺序；

识别带边框和按文字对齐形成的表格；

过滤页码，合并断行单词；

发现字体编码损坏时，提示改用 OCR。

04

PART

用 uv 安装 Python 版本

TUTORIAL · PYTHON SETUP

uv init pdf-reader

cd pdf-reader

uv add pdf-inspector

from pathlib import Path

import pdf_inspector

pdf_path = Path("document.pdf")

result = pdf_inspector.process_pdf(str(pdf_path))

print(f"PDF 类型：{result.pdf_type}")

print(f"总页数：{result.page_count}")

print(f"置信度：{result.confidence:.2f}")

print(f"需要 OCR 的页码：{result.pages_needing_ocr}")

print(f"存在编码问题：{result.has_encoding_issues}")

if result.markdown:

    output_path = pdf_path.with_suffix(".md")

    output_path.write_text(result.markdown, encoding="utf-8")

    print(f"Markdown 已保存到：{output_path}")

else:

    print("没有提取到可用文字，请对相应页面执行 OCR。")

uv run python inspect_pdf.py

05

PART

只检测 PDF，不提取全文

DETECTION · FAST CHECK

import pdf_inspector

result = pdf_inspector.detect_pdf("document.pdf")

print(result.pdf_type)

print(result.confidence)

print(result.pages_needing_ocr)

06

PART

混合 PDF 怎么处理

WORKFLOW · HYBRID PDF

import pdf_inspector

result = pdf_inspector.process_pdf("document.pdf")

if result.pdf_type == "text_based" and not result.has_encoding_issues:

    print("直接使用本地提取结果")

elif result.pdf_type == "mixed":

    print(f"仅对这些页面执行 OCR：{result.pages_needing_ocr}")

else:

    print("这份文件更适合走 OCR 流程")

07

PART

命令行用户可以直接用 pdf2md

CLI · AUTOMATION

cargo install pdf-inspector

pdf2md document.pdf

pdf2md document.pdf --raw

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

detect-pdf document.pdf --json

08

PART

Node.js 和浏览器也能接入

INTEGRATION · NODE AND WASM

npm install @firecrawl/pdf-inspector

import { readFileSync } from "node:fs";

import { processPdf } from "@firecrawl/pdf-inspector";

const pdf = readFileSync("document.pdf");

const result = processPdf(pdf);

console.log(result.pdfType);

console.log(result.pagesNeedingOcr);

console.log(result.markdown);

09

PART

官方基准怎么看

BENCHMARK · READ CAREFULLY

0.875

综合得分

0.470s

200 份文档

M4 Pro

项目方测试

普通文字报告；

双栏论文；

带合并单元格的财务表格；

扫描合同；

文字页和扫描附件混合的 PDF。

10

PART

哪些情况不要只靠它

LIMITS · OCR REQUIRED

数学公式很多的论文；

图表、流程图承担主要信息的报告；

字体映射损坏或加密受限的文件；

版面极不规则的宣传册；

需要像素级还原的发票和票据。

///

LAST

适合放进哪些工作流

PRACTICE · FINAL ADVICE

把论文和报告批量整理成 Markdown；

为 RAG 知识库清洗 PDF；

给 AI 助手准备可检索的本地资料；

从合同和财务文档中保留表格结构；

在上传 OCR 服务前筛掉不需要识别的页面；

在浏览器内完成隐私敏感文档的初步解析。