MinerU如何整理文档进RAG流程

ENGINEERING NOTES

技术专栏目录

01 MinerU如何整理文档进RAG流程

NO.01

MinerU如何整理文档进RAG流程

2026-06-30

TECH NOTE

先给结论：MinerU 适合放在 RAG 的入口层

MinerU 是 opendatalab/MinerU 仓库里的文档解析工具，目标是把 PDF、图片、DOCX、PPTX、XLSX 转成 Markdown 和 JSON。

它解决的不是问答模型能力，而是文档进入模型前的结构损耗：标题、段落、表格、页码和图片说明如果先乱了，后面的 RAG 很难救回来。

最小试用条件是 Python 3.10 到 3.13、少量脱敏样本文档、可单独保存 Markdown/JSON 的输出目录，以及一次人工抽查。

今天先不要全量导入知识库，先跑 5 到 20 份代表性样本，看结构保真、来源追溯和人工修正成本。

MinerU 值得看的点，不是“又一个文档解析项目”，而是它把文档进入 RAG 前最容易被忽略的一层单独拎出来了。很多团队做知识库时，第一反应是把 PDF 直接丢进向量库，然后调 embedding、调 chunk、调 prompt。问题是，如果解析阶段已经把表格拆坏、标题层级丢掉、页码和正文关系打散，后面检索再努力也只是从错误材料里找答案。

所以这篇更适合按工具上手来读：先让它跑通一条小样本链路，再决定要不要放进日常文档管线。别一开始就把它包装成完整 Agent 工程，也别把所有 PDF 批量扔进去。

TECH NOTE

前置条件：先把环境、样本和输出目录收住

第一步不是安装，而是收口测试范围。你需要准备一组能代表真实难点的样本文档，例如中文 PDF、扫描页、带表格的报告、PPT、Office 文档和一两份质量一般的图片。样本必须脱敏，输出目录必须单独建，不要和正式知识库混在一起。

Python 版本也要先确认。项目配置里要求 Python 版本在 3.10 到 3.13 之间，试用时不要用系统 Python 硬装一堆依赖，建议单独开虚拟环境。这样一旦模型下载、推理后端或 Gradio 界面出问题，可以直接删掉环境重来，不影响别的项目。

TECH NOTE

上手路径：先跑通一个最小闭环

创建隔离环境并确认 Python 版本。动作是准备 Python 3.10 到 3.13 的环境，对象是 MinerU 的核心依赖；检查点是 `python --version` 在支持范围内，样本文档已经放到单独目录。

获取仓库并进入项目目录。动作是 clone opendatalab/MinerU，对象是 README、pyproject.toml 和脚本入口；检查点是能看到 `mineru`、`mineru-models-download`、`mineru-gradio`、`mineru-api` 等入口信息。

安装核心依赖。动作是安装 `mineru[core]`，对象是最小解析能力；检查点是安装过程没有 Python 版本冲突，也没有缺少基础依赖。

下载模型资源。动作是执行 `mineru-models-download`，对象是解析所需模型；检查点是下载结束后没有网络、磁盘、代理或权限错误。

先启动人工试用入口。动作是执行 `mineru-gradio`，对象是本地 Gradio 界面；输入是一份代表性 PDF 或 Office 文件；检查点是能产生 Markdown/JSON 输出，并能肉眼对照原文。

再启动服务化入口。动作是执行 `mineru-api`，对象是后续批处理或 RAG 导入脚本；检查点是服务能在本机启动，不要第一天就暴露公网。

最后做三份对照。动作是保留原始文件、Markdown 和 JSON；检查点是标题层级、段落顺序、表格、图片说明和来源路径能互相对得上。

BASH

git clone https://github.com/opendatalab/MinerU.git cd MinerU python -m venv .venv source .venv/bin/activate python -m pip install "mineru[core]" mineru-models-download mineru-gradio mineru-api mineru --help

这组命令的目的不是把 MinerU 所有能力一次性跑满，而是完成“获取项目、安装核心依赖、准备模型资源、打开人工界面、启动服务入口、确认 CLI 可用”这条最小闭环。真正处理文件时，具体参数要以仓库 README 和官方文档为准；素材没有给出完整输入参数时，不应该编造一个看似能跑的解析命令。

TECH NOTE

命令与配置：把脚本入口和依赖选择写清楚

MinerU 的配置重点不是 API key，而是 Python 版本、依赖组、脚本入口和数据边界。团队试用时最容易出问题的地方，是每个人装的依赖不一样：有人只装 core，有人装 vllm，有人用 Gradio，有人直接起 API。先把这些写成一份本地记录，后面比较结果才有意义。

ENV

PROJECT_NAME=mineru REQUIRES_PYTHON=">=3.10,<3.14" OPTIONAL_DEP_CORE="mineru[core]" OPTIONAL_DEP_VLM="mineru[vlm]" OPTIONAL_DEP_VLLM="mineru[vllm]" OPTIONAL_DEP_LMDEPLOY="mineru[lmdeploy]" OPTIONAL_DEP_MLX="mineru[mlx]" SCRIPT_CLI=mineru SCRIPT_MODELS=mineru-models-download SCRIPT_GRADIO=mineru-gradio SCRIPT_API=mineru-api INPUT_DIR=./samples OUTPUT_DIR=./runs/mineru

依赖可以分三档走。第一档只装 core，用来验证基本解析和 Gradio 试用路径；第二档再按机器选择推理后端，比如 Linux 看 vllm，Windows 看 lmdeploy，macOS 看 mlx；第三档再考虑 S3、API 服务或接入批处理。不要第一天全装，否则失败时你很难判断问题来自文档、模型、推理后端、网络下载还是服务启动。

输出也要分层保存。原始文件用于最终复核，Markdown 用于人读和编辑，JSON 用于程序化 chunk、索引和引用。只把文本扔进向量库，是最不利于排查的方式，因为后面答案错了，你很难知道错误发生在解析、切分、召回还是生成。

TECH NOTE

工作流拆解：Markdown 给人看，JSON 给程序用

一个稳一点的 RAG 入口流程可以拆成四段：原始文档进入 MinerU；MinerU 输出 Markdown 和 JSON；脚本根据标题、页码、段落和表格做 chunk；问答或 Agent 在回答时引用 chunk，并且能回链到原始文件。

Markdown 和 JSON 的职责不要混在一起。Markdown 适合人快速判断解析是否对了，尤其是标题、段落、列表和表格是否还能读。JSON 适合程序处理，保留层级、页码、区域、路径和后续索引所需的字段。出了问题时，人看 Markdown，程序查 JSON，再回到原始文件复核。

如果你在做 Agent 文档读取，MinerU 的价值不是让 Agent 多一个工具名，而是减少 Agent 读错资料的概率。Agent 最怕拿到半截上下文后自信执行下一步，例如把表格列读成行、把脚注当正文、把目录页当内容、把图注和正文分离。解析层越可控，后面的摘要、检索、报告生成和工具调用越少靠模型猜。

TECH NOTE

输出检查：别只看是否生成了文件

验收先看结构保真。至少检查标题层级、段落顺序、表格可读性、图片说明、页码或来源路径，不能只看输出字符数。

再看后续可用性。Markdown 是否适合人工阅读，JSON 是否能稳定进入 chunk 脚本，字段是否每次都存在。

权限边界要提前收紧。试用时只放脱敏样本，Gradio 和 API 都先限制在本机或受控网络，输出目录按内部资料管理。

失败条件要记录清楚。如果 20 份代表性样本里频繁出现表格错位、标题丢失、扫描页无法识别、中文段落顺序混乱，就不要进入全量导入。

性能也要留日志。记录单文件耗时、模型下载耗时、磁盘占用、失败文件类型和人工修正时间。

第一轮验收可以做得很小：挑 5 到 20 份真实样本，给每份文档记录“是否成功输出、标题是否正确、表格是否可读、页码是否可追溯、是否需要人工修正、是否可进入 RAG”。样本量不必大，但必须覆盖真实难点。

失败时也不要直接否定工具。安装失败先看 Python 版本和依赖组；模型下载失败看网络、代理、磁盘和权限；界面启动失败看 Gradio 相关依赖；服务入口失败看 API 启动日志；输出质量差再回到样本文档类型和解析链路。只有当代表性样本持续在结构上失败，才说明它暂时不适合主流程。

TECH NOTE

是否值得放进日常

MinerU 短期更适合三类人先试：正在搭 RAG 知识库的开发者，手里有大量 PDF/Office 文档的内容或研究团队，以及想给 Agent 增加文档读取能力但经常遇到引用不准的人。它不适合只处理干净 Markdown、网页文本或短资料的人，也不适合没有人力做输出验收、只想一键导入全量资料库的团队。

最合适的落点是“入口层替换”：原来直接把 PDF 上传到问答系统，现在先用 MinerU 转成 Markdown/JSON，再进入 chunk、embedding、检索和回答链路。这个替换的工程量相对可控，也最容易看出收益。你只需要比较同一批文档在两条路径下的召回质量、引用准确率和人工排错时间。

DECISION

今天可以试的是正在做 RAG、文档问答、批量摘要或 Agent 文档读取流程的开发者；应该先观望的是只处理干净 Markdown/网页文本、没有脱敏样本、或没有人力检查 Markdown/JSON 输出质量的团队；试用时看 3 个指标：结构保真度是否足够进入 chunk，来源追溯是否能回到原文件，失败样本的人工修正成本是否低于原有导入方式。