MinerU PDF Parser 是一个将复杂 PDF 文档转换为机器可读的 Markdown/JSON 格式的工具，适用于 LLM 和 RAG 应用。
用途 该技能主要用于：(1) PDF 转 Markdown/JSON；(2) 提取 PDF 中的文本、表格、公式、图像；(3) 解析学术论文、技术文档、商业报告；(4) 为 RAG 应用准备文档数据。
安装 推荐使用 uv 安装：
推荐使用uv安装
pip install uv uv pip install -U "mineru[all]"
下载模型（首次使用）
mineru-models-download
主要能力 工具支持三种解析模式：
- pipeline：快速、资源少，适用于简单文档、纯文本 PDF。
- vlm：高精度、复杂布局，适用于学术论文、公式表格文档。
- hybrid：平衡速度精度，适用于通用场景。
输出文件包括：
- {filename}.md：Markdown 正文
- {filename}_content_list.json：结构化 JSON
- images/：提取的图像
- {filename}_middle.json：中间结果（调试）
使用方式 命令行：
解析单个PDF
mineru -p input.pdf -o output_dir
批量解析
mineru -p pdf_folder/ -o output_dir
指定解析模式
mineru -p input.pdf -o output_dir --backend vlm # VLM模式（高精度） mineru -p input.pdf -o output_dir --backend pipeline # Pipeline模式（快速） mineru -p input.pdf -o output_dir --backend hybrid # 混合模式（平衡）
Python API：
from mineru import MinerU
mineru = MinerU() result = mineru.parse("document.pdf")
获取输出
markdown = result.to_markdown() json_data = result.to_json()
详细 API 见 references/api_reference.md。
适用场景
- 学术论文解析：mineru -p paper.pdf -o output --backend vlm
- 批量处理：使用 Python API 遍历目录中的 PDF 文件并保存结果。
- RAG 数据准备：通过 result.get_sections() 获取章节，并将标题与内容加入向量数据库。
- 启用 GPU 加速：修改 ~/.mineru.json 中 device-mode 为 cuda。
更多最佳实践见 references/best_practices.md。
验收标准（解析任务完成前自查）
- 输出目录里 .md 与 _content_list.json 都存在，把实际路径回报用户。
- 抽查 1-2 页对照原 PDF：表格/公式没有明显丢失或错乱；有问题主动告知而不是静默交付。
- backend 选择有依据（简单文本→pipeline；公式表格密集→vlm；拿不准→hybrid）。
- 批量任务报告成功/失败清单，失败的给原因。
已知陷阱
- 首次运行缺模型：未执行 mineru-models-download 直接解析报错。应对：安装后先跑模型下载；下载体积大，提前告知用户耗时。
- 无 GPU 硬跑 vlm：CPU 上 vlm 模式极慢，像卡死。应对：无 GPU 时用 pipeline/hybrid；有 GPU 改 ~/.mineru.json 的 device-mode 为 cuda。
- 扫描件预期过高：低清晰度扫描 PDF 解析质量差。应对：提前告知扫描件效果取决于清晰度；结果差时换 backend 重试一次，仍差则如实报告。
- 大文件内存压力：数百页 PDF 单次解析内存暴涨。应对：大文件分批解析或按章节拆分。
脚本 使用 scripts/mineru_parse.py 进行解析，支持错误处理和日志记录。