pdf-converter

name	pdf-converter
description	本地 MinerU 将 PDF/Office/图片转为 Markdown（含 images/ 图文、表格与公式识别）。复杂版式、扫描件、长书须先确认页范围与后端。用户要转 PDF、提取表格、OCR、或问「这篇 PDF 讲了什么」时使用。

Document to Markdown (Local MinerU)

使用本机 MinerU CLI 将 PDF、图片、Office 转为 Markdown。全程离线（首次会下载数 GB 模型），无需 API Key。

语言规则

用与用户相同语言回复（本技能正文为中文时，对用户仍用中文）。

执行前确认（长文档 / 高成本）

收到转换任务后，若 PDF 超过约 50 页或体积 >10MB，先用简短列表确认再执行：

1. 输入路径与输出目录（默认：与 PDF 同级的 mineru-output/，或用户指定）
2. 是否全量转换，或仅指定页（-s/-e，0 起算）
3. 后端：pipeline（默认，稳定）或 vlm-auto-engine（需完整 VLM 权重）
4. 是否需要 bundle（.md + images/ 打平目录，便于搬运）

未确认前不要对数百页 PDF 默认全量跑满。

核心流程

1. Extract — mineru 或 python3 scripts/convert.py 转为 Markdown
2. Read & Process — 按需摘要、抽表、整理；MinerU 只负责 OCR/版面，理解由代理完成

图文：.md 与 images/ 必须一起保留；禁止只拷贝 .md。

推荐命令（复杂 PDF / 中文书）

# 技能目录下（安装后路径因工具而异）；Python 3.10+，仅标准库
python3 scripts/convert.py -p "/path/to/book.pdf" -o "./output" -b pipeline -l ch -m auto

# 试跑前 10 页（页码 0–9）
python3 scripts/convert.py -p book.pdf -o ./output --start 0 --end 9

# 全量（确认后）
mineru -p book.pdf -o ./output -b pipeline --lang ch -m auto -t True -f True

打平为便于分享的 bundle：

python3 scripts/bundle_markdown.py ./output/书名
# → ./output/书名-bundle/书名.md + images/

脚本通过 subprocess 调用已安装的 mineru CLI（与 uv tool install mineru 一致），本身无第三方 Python 依赖。

安装

uv tool install mineru
uv tool update-shell    # 按提示把 uv tools 加入 PATH
mineru --version        # 首次会拉取模型

Apple Silicon / 仅需稳定本地转换：默认使用 -b pipeline，不要假设 hybrid-auto-engine 一定可用。

若使用 VLM 后端（vlm-auto-engine / hybrid-auto-engine），在 mineru 的 uv 环境中安装 accelerate，并确保 HuggingFace 权重完整：

MINERU_PY="$(dirname "$(which mineru)")/../share/uv/tools/mineru/bin/python"
uv pip install --python "$MINERU_PY" accelerate
# 若报缺 model.safetensors：
mineru-models-download

常用参数

场景	命令要点
中文 PDF、图文混排	-l ch -m auto -b pipeline
扫描件	-m ocr
仅文字层、无图	-m txt（会弱化图片）
表格/公式	-t True -f True（默认开启）
大书分段	-s 0 -e 99 多次输出后合并
复用已启动的 API	mineru-api --port 8000 另开终端；mineru ... --api-url http://127.0.0.1:8000

完整参数：mineru --help。

输出结构（MinerU 3.x）

<output_dir>/
└── <文档名>/
    └── auto/
        ├── <文档名>.md
        ├── <文档名>_middle.json
        ├── <文档名>_content_list.json
        └── images/

读取路径：<文档名>/auto/<文档名>.md。表格/图表行为见 references/mineru-output-and-tables.md。

表格与图片

• 图片：![](images/<hash>.jpg)，文件在 auto/images/。
• 表格：简单表可能为 Markdown | 表；复杂表、行情图、截图表格常为图片块——需在回答中说明，或结合 _content_list.json / 读图补全。
• 分享或入库：使用 python3 scripts/bundle_markdown.py 或打包整个 auto/ 目录。

模式速查

情况	建议
一般中文 PDF	pipeline + auto + ch
扫描版	--method ocr
保留插图/版式	避免 --method txt
内存不足	pipeline，或分页 -s/-e
最佳精度（环境完备）	hybrid-auto-engine 或 vlm-auto-engine

不负责

• 不代装 uv/Python（仅给出命令）
• 不默认把数百页 PDF 全量转换（须确认）
• 不把云端 MinerU Open API 当作本技能默认路径（本技能以本地 CLI 为准）

故障排除

问题	处理
command not found: mineru	uv tool update-shell，重开终端
VLM：requires accelerate	见上文 uv pip install accelerate
VLM：缺 model.safetensors	mineru-models-download 或改用 pipeline
首次极慢	模型初始化，同机再次运行会快很多
加密 PDF	多数仍可解析；若失败提示用户解除复制限制或另存
乱码	显式 --lang ch 或 en

调试：MINERU_LOG_LEVEL=DEBUG mineru ...

参考

• 输出/表格详解：references/mineru-output-and-tables.md
• 上游：https://github.com/opendatalab/MinerU