MinerU

MinerU 快速入门

MinerU 是 OpenDataLab 开源的文档解析引擎：把 PDF、扫描件、Office 文档、EPUB、HTML 等复杂版式内容转成结构化 Markdown/JSON，是「文档喂给 RAG / Agent」链路上游最常用的开源工具之一。GitHub 81k+ 星标，2026-10-06 仍在活跃发版（v4.0.10）。2026-10-07 核验：官方文档站与 GitHub 仓库均可访问，版本与安装命令以官方 Quick Start 为准。

这是什么？适合谁？

LLM 读文档的真正难点不是「读文字」，而是读版式：双栏论文、跨页表格、公式脚注、扫描件的图片混排——直接塞给模型要么截断要么串行。MinerU 用专门的版面分析 + OCR + 公式识别模型把这件事工程化：输入一份 PDF，输出保留结构、公式转 LaTeX、表格转 HTML/Markdown 的干净文本，供下游 RAG、知识库、Agent 直接消费。

MinerU 4.0 把三件事合进一个工作流：文档转换、本地文档库（解析结果缓存 + 按页/按块续读 + 稳定引用定位）、以及面向 Agent 的阅读接口（mineru parse 默认只读前 10 页并返回续读定位符，避免一次把长文档灌爆上下文）。

适合人群：

• RAG / 知识库工程师：需要把企业 PDF、论文、报告可靠地转成可检索文本
• Agent 开发者：需要「按页续读 + 引用定位」的长文档阅读能力
• 数据团队：需要批量把扫描件/复杂表格结构化

不适合谁：只想「网页截图转文字」的轻度用户（OCR 在线工具更省事）；需要开箱即用云端 API 不愿本地部署的团队（官方明确「文档不会自动上传到官方服务」，远程解析需显式配置）。

准备工作

• 环境：Python ≥3.10 且 <3.15（官方推荐从 3.12 新建环境）；推荐用 uv 管理虚拟环境
• 预算：核心开源免费（仓库 License 为 AGPL-3.0 类自定义条款，商用集成前需核对仓库 LICENSE；官网明确 base 包含 WebUI、ONNX 小模型运行时与 llama.cpp VLM）
• 硬件：Flash 档（纯文本抽取）几乎无要求；Standard/Advanced 档需要下载模型权重，首次解析会自动拉取，建议预留数 GB 磁盘
• 时间预算：安装 5-10 分钟；首次模型解析含权重下载可能更久
• 替代方案：闭源商用可看 TextIn、Doc2X；开源同类可看 Marker、Docling；站内 RAGFlow 内置了自己的文档解析管线

快速上手

第一步：安装

uv venv --python 3.12 .venv
# Windows PowerShell: .venv\Scripts\Activate.ps1
source .venv/bin/activate
uv pip install -U "mineru>=4.0,<5"

base 包自带 WebUI、ONNX 小模型运行时与 llama.cpp VLM；Apple Silicon 自动带 Torch 依赖。不要装 3.x 的 extras（官方迁移指南明示）。

第二步：第一次转换

单文件转 Markdown，用模型解析档位：

mineru-kit parse document.pdf -o document.md --tier standard

首次运行会下载模型权重。如果只想要纯文本层抽取（不走模型），显式指定：

mineru-kit parse document.pdf -o document.md --tier flash --ocr-mode txt

第三步：批量与原生文档

Office/OpenDocument/EPUB/CSV 走本地 Flash 原生解析（无需模型）：

mineru-kit parse report.docx -o report.md --tier flash
mineru-kit parse ./documents -o ./output --format zip

多输入时 -o 必须是目录；单文件 Markdown 输出用文件路径。

预期结果

document.md 生成，双栏恢复为单栏阅读序、公式为 LaTeX、表格为 Markdown/HTML。用 --tier advanced 可处理更苛刻的版式（对应更高质量要求）。

初级用法

• 四档解析强度按需选：Flash（快速预览/索引，纯文本抽取）→ Basic（OCR + 模型）→ Standard → Advanced（苛刻版式）。PDF 与图片支持全部四档；Office/EPUB/HTML/CSV 走本地 Flash 原生解析；纯文本直接读取不解析。
• 九种输出目标：一套文档模型支持 Markdown、HTML、LaTeX、DOCX、EPUB、PDF、Structured Content、Content List V1/V2 渲染，各 CLI/API 暴露的子集不同（见官方 Output Formats）。
• 文档库模式：mineru parse 走本地文档库与缓存，配合 mineru search "keyword" --json 做库内检索；与 mineru-kit parse（直写完整输出）是两条不同入口。
• 独立模型配置：小模型可用 ONNX 或 Torch；VLM 后端可选 llama.cpp、vLLM、LMDeploy——显存紧张用 llama.cpp，吞吐优先用 vLLM/LMDeploy。

高级玩法

1. Agent 长文档阅读管道：mineru parse document.pdf --json 默认只解析前 10 页，输出长度到达预算时返回 continuation request（定位符 + next_request）——Agent 按需续读下一块，引用定位符保持稳定，适合做「先读目录再跳读」的问答 Agent。
2. API 服务化：mineru-kit api-server --host 127.0.0.1 --port 8000 --tier standard 起本地 V1 HTTP 服务，带 OpenAPI 文档；上游应用统一走 API，避免每台机器重复配环境。
3. WebUI 快速验证：mineru-kit webui --server-name 127.0.0.1 --server-port 7860（或 mineru-webui），不带 --api-url 时自动管理本地 V1 API 服务，适合转换质量的人工抽检。
4. Docker 部署：官方提供 Docker 部署指南，适合服务器端统一解析服务、避免本机驱动差异（Torch/vLLM 等引擎对 wheel/OS/驱动有额外约束）。

常见踩坑

踩坑 1：装了 3.x 的 extras 导致依赖冲突

• 症状：升级到 4.0 后报依赖错误或命令行为异常。
• 原因：3.x 平台的 extras 与 4.0 包结构不兼容，官方迁移指南明示「Do not use 3.x extras」。
• 解决：干净环境重装 mineru>=4.0,<5；从 3.x 迁移先读官方 Migration to 4.0 文档。
• 来源：官方 Quick Start

踩坑 2：扫描版 PDF 用 flash+txt 模式输出空白

• 症状：--tier flash --ocr-mode txt 对扫描件产出几乎为空。
• 原因：txt 模式只读 PDF 文本层、不加 OCR 回退——扫描件没有文本层。
• 解决：扫描件用 --ocr-mode ocr 并确保相应模型已就绪，或直接用 Basic/Standard 档。
• 来源：官方 Quick Start

踩坑 3：mineru parse 只解析了前 10 页

• 症状：库模式解析长文档，输出明显不全。
• 原因：mineru parse 默认只读前 10 页、到长度预算会返回续读请求——这是面向 Agent 的设计行为，不是 bug。
• 解决：要完整输出用 mineru-kit parse（默认全部页）；库模式按返回的 locator/next_request 续读。
• 来源：官方 Quick Start

踩坑 4：多文件批量时 -o 传了文件路径

• 症状：目录/多输入解析报错。
• 原因：目录或多输入时 -o 必须是目录；单文件 Markdown 输出才用文件路径。
• 解决：批量场景 -o ./output --format zip。
• 来源：官方 Quick Start

踩坑 5：担心文档被上传到官方服务

• 症状：企业数据合规审查卡住。
• 原因/事实：官方文档明确「Documents are not automatically uploaded to the official service; remote parsing requires explicit configuration」——默认全本地。
• 解决：保持默认即本地解析；如需官方云端解析再显式配置。
• 来源：官方首页

踩坑 6：AMD/加速卡用户升级 4.0 后不支持

• 症状：4.0 环境里找不到对应加速适配。
• 原因：AMD 与厂商加速卡适配仍留在 <4 的 legacy 平台。
• 解决：参照官方 Legacy Platforms 指南使用旧版。
• 来源：官方首页

小技巧

1. 新环境永远从 Python 3.12 开始（官方明示 practical starting point），避开解释器边界问题。
2. 质量抽检先跑 mineru-kit webui，人工对比三五个样本再决定上 Standard 还是 Advanced。
3. --format zip 打包批量输出，方便整体搬运到 RAG 入料目录。
4. vLLM/LMDeploy 引擎约束多（wheel/OS/驱动），生产部署优先考虑 Docker 或 llama.cpp。
5. 引用定位符（citation locators）保持稳定——做「答案带页码引用」的问答系统时直接复用，不要自己重新切块编号。

FAQ

Q1: MinerU 与 RAGFlow 是什么关系？选哪个？

A: 定位不同。MinerU 是解析引擎（文档→结构化文本），RAGFlow 是完整 RAG 引擎（解析→分块→检索→生成）。RAGFlow 自带文档理解管线；如果你已有检索/生成栈、只缺高质量解析这一环，用 MinerU。站内两者都有收录，可对比评分。

Q2: 免费吗？商用有什么限制？

A: 开源免费。仓库 License 为自定义/AGPL 类条款（GitHub API 显示 NOASSERTION），商用集成前请直接核对仓库 LICENSE 文件，避免想当然按 MIT 处理。

Q3: 和 Marker、Docling 比怎么样？

A: 同为开源文档解析。MinerU 的差异点是四档强度分级、本地文档库与 Agent 续读接口、九种输出目标；Marker/Docling 更聚焦单文件转换质量。没有逐项实测对比，选型建议拿自己的样本各跑一遍。

Q4: 支持中文吗？

A: 官方文档站提供中文版（导航有「中文」切换）；解析中文 PDF/扫描件是主要场景之一（OpenDataLab 为上海AI实验室系团队）。

Q5: 最低需要什么显卡？

A: Flash 档（纯文本抽取）无模型依赖；模型档用 ONNX 小模型 + llama.cpp VLM 可在 CPU/低显存跑，速度换兼容；追求吞吐再上 vLLM/LMDeploy。官方未给统一硬件基线，按档位与引擎组合实测为准。

参考链接

• 官方文档站
• GitHub 仓库 opendatalab/MinerU
• PyPI mineru

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。