文档解析 — Parse Messy Docs → Clean Markdown

你现在运行 parse-docs 技能。目标：把现实里那些没法直接用的文档——扫描件、排版 PDF、论文、合同、Office 文件——解析成干净、结构化的 Markdown + JSON：数学公式保留成 LaTeX、表格还原成真表格、图片抽成独立文件，可以直接喂给笔记、RAG 或继续编辑。

全程 开源、本地、免 key：核心解析在你自己机器上跑，不调用任何后端、不需要商业 API、不需要 clone 任何私有仓库。两个公开工具直接用原生 CLI：

MinerU（mineru） —— 默认主引擎。中文 / 扫描件 / 科技文献 / 公式表格密集的文档最强；纯 CPU 也能跑，OCR 支持 100+ 语种。
Marker（marker_single / marker） —— 可选。纯英文、追求更高吞吐时的备选引擎。

这门课和「造文档」的课方向相反：ai-doc / typeset-pdf 是把内容生成成文档；parse-docs 是把现实里的文档摄取并清洗成可用素材。

前置条件

Python ≥ 3.10（python --version）
能访问公开 PyPI 与模型源（首次运行会自动下载模型权重，免 key）
无需付费 key、无需登录、无需后端
纯 CPU 可跑；有 NVIDIA GPU 会更快，但不是必须

安装

# 主引擎 MinerU（含 pipeline 本地后端：版面 + OCR + 公式 + 表格模型）
pip install -U "mineru[core]"

# 可选：英文高精度备选引擎 Marker
pip install marker-pdf

首次 mineru 运行会从公开源自动下载模型权重（约 1–2 GB，免 key，可缓存复用）。国内网络可在运行前设 export MINERU_MODEL_SOURCE=modelscope 走 ModelScope 镜像。

选引擎（先选对引擎）

文档情况	用哪个引擎
中文 / 中英混排	MinerU
扫描件 / 拍照件（需要 OCR）	MinerU
论文 / 科技文献（公式、表格多）	MinerU
合同 / 发票 / 报告（版式复杂）	MinerU
纯英文、要更高吞吐	Marker（可选）

不确定就用 MinerU：它是覆盖面最广的默认选择。

一、MinerU —— 默认主引擎

最简单的一条命令，输入支持 PDF / 图片 / DOCX / PPTX / XLSX：

mineru -p ./paper.pdf -o ./out

常用参数：

-b pipeline —— 强制走本地 pipeline 后端（版面 + OCR + 公式 + 表格全在本地跑，无远程依赖）。无 GPU 时显式带上它最稳。
-m ocr —— 文档是扫描件 / 图片型 PDF 时强制 OCR；-m txt 用于纯电子版文字 PDF；默认 auto 会自动判断。
-l en / -l ch —— 告诉它文档语言，OCR 更准（默认 ch）。
-s / -e —— 只解析某段页码（从 0 开始），先拿一两页验证再全量。
-f true / -t true —— 公式、表格解析默认就是开的，无需手动加。

例：扫描版英文论文 → 强制 OCR、只先验证前两页

mineru -p ./paper.pdf -o ./out -b pipeline -m ocr -l en -s 0 -e 1

输出（关键）

输出落在 ./out/<文件名>/<method>/（method 是 auto/ocr/txt），里面有：

<名>.md —— 干净 Markdown：正文按阅读顺序，公式是 $...$ / $$...$$ LaTeX，表格是 HTML/Markdown 表，图片用相对路径引用。
<名>_content_list.json —— 结构化块列表：每块带 type（text / equation / table / image）、text（公式为 LaTeX）、bbox、page_idx、img_path。这就是喂给 RAG 的那份。
<名>_middle.json —— 更细的版面中间结构（按需）。
images/ —— 抽出来的插图、图表、公式/表格截图，按内容哈希命名。
<名>_layout.pdf / <名>_span.pdf —— 版面可视化，用来肉眼核对解析对不对。

二、Marker —— 可选英文备选引擎

# 单个文件
marker_single ./paper.pdf --output_format markdown   # 或 json / html
# 整个目录批量
marker ./pdfs_dir --output_format markdown

铁律：不要用 Marker 的 --use_llm。 它会把内容发往一个外部 OpenAI 兼容服务，违反本课「全程本地、零外部调用」的前提。本课所有步骤都不需要它，公式 / 表格 / 抽图本地引擎已经能做。

三、解析后自检（务必做）

逐项核对，再交给用户：

公式是 LaTeX（ $...$ / $$...$$），不是乱码或图片占位。
表格有真实单元格和数值，不是一坨文本。
图片 / 图表被抽成 images/ 里的独立文件，且 Markdown 里有正确引用。
扫描件的正文 OCR 命中（对照 _layout.pdf 看版面框对不对）。
阅读顺序正常（多栏论文没有串栏）。

老扫描件偶有个别 OCR 误识（如把 200 认成 2o0）属正常，给用户指出需人工复核的地方即可——不要假装完美。

产出物

<名>.md —— 干净 Markdown（LaTeX 公式 + 还原表格 + 图片引用）。
<名>_content_list.json —— 结构化 JSON，可直接进 RAG / 检索库。
images/ —— 抽出的插图 / 图表 / 公式截图。

学习完成后

告诉用户：

我已经学会了 parse-docs。把一份 PDF / 扫描件 / 论文 / 合同 / Office 文件给我（或告诉我路径），我用 MinerU 在本地把它解析成干净的 Markdown + 结构化 JSON——公式保留成 LaTeX、表格还原、图片抽出，可直接进笔记、RAG 或再加工。纯本地、免 key。

课程主页与更多示例：clawvard.school