前言
大家好，我是苏三。
不知道你做RAG知识库的时候，有没有遇到过下面这种场景：
用户问“这份财报里Q3的净利润是多少”，系统检索出来的片段里，表格是散的，数字和指标名对不上。
问“这篇论文的核心公式是什么”，检索出来的内容里公式全变成了问号或者一串乱码。
你换了更好的Embedding模型，调了切片大小，甚至上了重排序，效果还是不行。
根本原因往往不在检索层，而在更前面的文档解析层：解析工具把一份双栏排版的PDF，左栏的最后一行和右栏的第一行拼在了一起；把表格拆成了散落的文字；把公式识别成了占位符。
RAG的上限，很多时候卡在文档解析这一层。
你喂给RAG的原料是碎的，它检索出来的东西就是碎的，大模型基于碎料生成的回答，自然也是碎的。
RAG的上限，不在向量库，不在大模型，在文档解析这一层。
MinerU解决的正是这个问题。
它在GitHub上有8万以上Star，定位是AI-Ready数据生产的基础设施。
今天这篇文章，我把它的核心优势、底层逻辑、代码用法讲清楚。
希望对你会有所帮助。
更多项目实战在Java突击队网：susan.net.cn/project
一、传统PDF解析到底“碎”在哪？
有些小伙伴可能会说：“我用PyMuPDF不也能把文字提出来吗？”
能。
但PyMuPDF做的事情，本质上是逐行逐块地“抠字”。
它不知道哪一行是标题、哪一块是表格、哪一段是公式。
它只是把PDF里的文本对象按坐标顺序吐出来。
你让一个只会“抠字”的工具去解析一篇学术论文，它会遇到几个致命问题：
第一，多栏排版。
双栏论文的阅读顺序是“左栏从上到下，然后右栏从上到下”。但抠字工具按坐标排序，经常把左栏底部和右栏顶部拼在一起，上下文直接断裂。
第二，表格。
表格里的内容在PDF里是一堆独立的文本块，抠出来就是散落的数字和文字，行列关系全丢了。RAG检索到这样的片段，大模型根本不知道哪个数字对应哪个指标。
第三，公式。
公式在PDF里要么是图片，要么是特殊字体渲染的符号。抠字工具要么提取不出来，要么提取出一串乱码。
对于技术文档和学术论文来说，公式就是核心内容，丢了公式等于丢了半篇文章。
MinerU做的事情，不是“抠字”，是“理解结构再重组”。
它先判断每一页上有什么——标题、段落、表格、公式、图片——然后按照人类阅读的逻辑，把这些元素重新组织成结构化的Markdown或JSON。
二、一张图看懂MinerU的处理链路
MinerU的解析策略是分场景处理的，不是“一招打天下”。
第一步，判断文档类型。
如果PDF本身带有可提取的文本和矢量信息（比如arXiv上的论文），直接用PyMuPDF解析原生对象，避免不必要的图像转换。如果是扫描件或纯图片页，才启用OCR。
第二步，布局分析。
用视觉模型识别文本块、表格、插图和公式的位置。这一步决定了后续“怎么切分”和“按什么顺序读”。
第三步，分元素处理。
公式交给自研模型转成LaTeX，表格转成HTML或OTSL结构，图片提取出来并保留位置信息。
第四步，结构化重组。
按照人类阅读顺序重新组织内容，剔除页眉页脚页码，保留标题层级和段落结构。
三、从“工具”到“Agent的基础设施”
2026年9月，MinerU发布了4.0版本，这是一次面向Agent时代的重大升级。
最核心的变化是“定位器”（Locator）能力。
以前的文档解析，输出的是“一段文本”。Agent拿到这段文本之后，如果想知道“这句话来自第几页、哪个位置”，只能靠猜。
MinerU 4.0的输出里带上了稳定的定位器：doc:{id}/tier:{tier}/page:{page}/block:{block}。
这意味着Agent可以先读文档的整体结构，找到相关段落，然后精确地回到原文对应位置去复查、引用、继续阅读。
另一个重要的变化是四种解析档位。
MinerU 4.0用flash、basic、standard、advanced四个档位替代了原来的pipeline/vlm/hybrid选择：
| 档位 | 适用场景 | 特点 |
|---|---|---|
| flash | 快速预览、索引 | 不跑推理模型，直接解析原生文本 |
| basic | 轻量处理 | 小模型跑OCR/公式/表格，CPU可跑 |
| standard | 日常高质量解析（默认） | 小模型 + VLM，平衡质量与速度 |
| advanced | 复杂/困难文档 | 投入更多推理算力，追求最高质量 |
这个设计的好处是：你不需要为了一份简单的合同去跑最重的模型，也不需要为了一篇复杂的学术论文去忍受flash档的粗糙。
按需选择，成本和质量的平衡权交给你。
四、代码实战
4.1 安装
MinerU 4.0的基础包支持ONNX CPU小模型 + llama.cpp VLM，开箱即用：
pip install uv
uv pip install -U "mineru"
如果你有GPU想跑更快的VLM，装完整版：
uv pip install -U "mineru[full]"
4.2 命令行解析
最简单的用法：
# 解析单个PDF，默认只读前10页，返回续读命令
mineru parse input.pdf --json
# 一次读完，输出Markdown
mineru parse input.pdf --pages all -o output.md
注意：4.0的默认行为是只读前10页，并返回一个next_request续读命令。这是为了支持Agent的渐进式读取——先看个大概，需要深入再继续。
4.3 Java项目怎么用？
MinerU是Python工具，但Java项目可以通过HTTP服务的方式集成。
MinerU 4.0的HTTP服务围绕V1 API重建：
mineru server start
Java侧调用逻辑（上传→创建任务→轮询）：
@Service
public class MinerUClient {
public String parseDocument(MultipartFile file, String tier) throws Exception {
// 1. 上传文件，拿到 file_id
String uploadResp = upload(file);
String fileId = JsonPath.read(uploadResp, "$.id");
// 2. 创建解析任务
String jobResp = createJob(fileId, tier); // tier: flash/basic/standard/advanced
String jobId = JsonPath.read(jobResp, "$.job_id");
// 3. 轮询状态直到完成
while (true) {
String status = getJobStatus(jobId);
if ("completed".equals(status)) {
return getJobResult(jobId); // 返回 Markdown 或 JSON
}
if ("failed".equals(status)) {
throw new RuntimeException("解析失败");
}
Thread.sleep(2000);
}
}
}
关键理解：MinerU的解析是异步的。
长文档可能需要几分钟，Java侧必须用轮询或者回调的方式处理，不能同步阻塞等待。
五、四档解析怎么选
四档的价值在于“不用为简单任务跑最重的模型”。
合同预览用flash，学术论文用standard，高难度扫描件用advanced。
六、Agent为什么需要定位器
定位器的核心价值：Agent可以先读结构，发现相关段落，再精确回到原文核验。
不需要“把几百页一次性喂给大模型”，也不需要“重新解析整份文档”。
七、优缺点
优点
1. 结构化输出，RAG友好
不是“一堆文字”，而是带标题层级、表格HTML、公式LaTeX的Markdown/JSON。切片质量和检索准确率跟“抠字”完全不是一个量级。
2. 原生多格式支持
PDF、图片、DOCX、PPTX、XLSX、EPUB、OFD、HTML等格式都可以直接解析，不需要先转PDF。
3. 四档解析，按需选成本
flash适合预览和索引，standard适合日常高质量解析，advanced应对复杂文档。不需要为简单任务跑最重的模型。
4. Agent定位器
4.0的定位符让Agent可以精确引用原文、渐进式读取，不需要一次性把整份文档塞进上下文。
5. 完全本地，隐私可控
默认全程本地解析，只有显式使用--remote才会上传文档。匿名遥测可以关闭。
6. 8万+ Star，社区验证
从2024年开源至今，已经被大量RAG项目和企业文档处理链路验证。
缺点
1. 对非学术文档优化不足
MinerU的基因是“解决科学文献的符号转换问题”。合同、发票这类文档虽然能用，但针对性优化不如学术场景。
2. 不支持手写中文/古籍竖排
这是明确的限制。手写体和竖排古籍需要另找方案。
3. Python工具，Java集成需要走HTTP
MinerU本身是Python CLI和SDK。Java项目需要通过HTTP服务集成，增加了网络层和异步轮询的复杂度。
4. 部分依赖有独立许可证
PyMuPDF等依赖可能有自己的许可证（AGPL等），企业使用前需要确认合规性。
八、适用场景
| 场景 | 推荐程度 | 理由 |
|---|---|---|
| RAG知识库文档预处理 | ✅✅✅ 强烈推荐 | 结构化输出直接喂给向量库 |
| 学术论文解析 | ✅✅✅ 强烈推荐 | 公式LaTeX、表格HTML、双栏顺序还原 |
| 企业文档数字化 | ✅✅✅ 强烈推荐 | 多格式支持，定位器可溯源 |
| Agent工作流文档读取 | ✅✅✅ 强烈推荐 | 4.0定位器+渐进式读取 |
| 扫描件OCR | ✅✅ 推荐 | 内置多语言OCR，手写体不擅长 |
| 合同/发票等业务文档 | ⚠️ 需评估 | 能用，但优化不如学术场景 |
| 手写中文/古籍竖排 | ❌ 不推荐 | 明确不支持 |
更多项目实战在Java突击队网：susan.net.cn/project
写在最后
回到最初的问题：为什么越来越多人用MinerU？
因为它把“文档解析”这件事，从“能读出来”升级到了“能直接用”。
RAG的上限在文档解析这一层。
你喂给大模型的原料如果是乱序的文字、散落的表格、乱码的公式，它吐出来的答案也只能是垃圾。
MinerU做的事情，是理解文档的结构，然后按照人类阅读的逻辑重新组织内容，输出结构化、可溯源、Agent友好的Markdown/JSON。
4.0版本的定位器能力，更是把文档解析从“一次性转换”变成了“Agent可以反复查阅的知识库”。
Agent可以先读结构，再深入细节，最后回到原文核验——这个过程，才是真正的“Agent工作流”。
当然，MinerU不是万能的。
它对非学术文档的优化还在路上，不支持手写中文和古籍竖排，Java集成需要走HTTP服务。
但对于RAG知识库、学术论文解析、企业文档数字化这些场景来说，它已经是一个经过8万开发者验证、持续迭代、开源的选择。
开源项目推荐：gitee.com/dvsusan/kno…
