---
title: "为什么越来越多人用 MinerU？"
source: "https://mp.weixin.qq.com/s/dDW3KUNFkBf-o8yy-yjQYg"
author:
  - "[[鹏磊]]"
published:
created: 2026-10-21
description:
tags:
  - "clippings"
---
鹏磊 架构师专栏 *2026年10月21日 11:13*

![图片](https://mmbiz.qpic.cn/sz_mmbiz_png/v5ssib16QE9pUFOBcqwGRvp1vGLRwVMBx2lKA1jv5y6rmYDBjo4OwAqbgjf4KxNWgJicfHqt2Sic0f1sWPOeJMAkMrAWfqU0zzicic5a3dibkXnicU/640?wx_fmt=png&from=appmsg&wxfrom=5&wx_lazy=1&tp=webp#imgIndex=1)

质保 30 天不掉订阅，掉订阅，按天退差价

MinerU 是上海 AI 实验室 OpenDataLab 团队开源的一款文档解析软件，做的事儿很简单：就是把 PDF、扫描件、图片、Office 文档等转换为 Markdown 和结构化的 JSON，并且直接输入到 RAG、知识库或者自己设计的清洗流程中去。目前 GitHub 上已经有 8.2 万个 star，这样的数量级，在文档解析项目中是很少见的

和 pdfplumber 那样只提取文本内容不是一回事。公式输出为 LaTeX 格式，表格输出为 HTML 格式，标题、图片、页脚都有相应的类型和坐标信息，该模型可以全部下载到本地运行，在不离开内网的情况下也可以进行数据处理

上个月为一家做 RAG 的公司清理标书，有 2000 多个 PDF 文件，双栏、跨页表格以及 LaTeX 公式一应俱全。第一版使用了 pdfplumber 来提取文本内容，但是由于读取顺序被打乱，所以表格变成了一个只有一列数字的表格。换作使用 MinerU 运行一晚上的时候，在第二天 structured\_content.json 文件中就会看到表格已经变成了 HTML、公式也变成了 LaTeX，并且标题层次依然存在。那会儿我就明白了它为什么会传播得那么快

## 它所要解决的问题并不是抽离出文字来，而是要把版面还原出来

传统库只能根据字符坐标的大小来判断数据之间的关系，并不能够理解到语义。双栏论文按照行来阅读就会出现串栏的情况，页眉、页脚混入到正文中去，表格没有行列之间的关系，在进行扫描之后也无法得到任何信息

MinerU 的做法是把每一页的 PDF 渲染成图片，然后进行版面检测，把标题、正文、表格、图片、公式、页眉页脚等都分离开来，并按照阅读顺序重新排列。表格走结构识别输出 HTML，公式走识别模型输出 LaTeX，扫描件再叠一层 OCR

该链条在 4.0 的时候被分成四个等级，并且质量、价格都可以自己选择

| 档位 | 实际跑什么 | 典型用途 |
| --- | --- | --- |
| flash | 原生文本解析 + Flash OCR | 建索引、预览、Office 文档 |
| basic | ONNX 或 Torch 小模型 | 纯 CPU、扫描件、公式表格 |
| standard | 小模型 + 1.2B VLM | 复杂版面，默认档 |
| advanced | 同模型，更多推理计算 | 高价值文档 |

标准档背后是 MinerU2.5-Pro-2605-1.2B。模型不大，但是它被用来对文档进行解析的任务上训练过的，并不是用一般的多模态通用模型来套用的。我认为最核心的是专用的小模型，在版面中更加稳定，而且显存可以节省很多

## 命令行三分钟跑通

4.0 安装包和 2.x 完全不相干，请不要再按照老教程来安装 core、pipeline 等 extra，已经全部失效

```
# 基础包：ONNX + llama.cpp，CPU 和 Apple Silicon 够用
uv pip install -U "mineru>=4.0,<5"

# 有 NVIDIA 卡、要高吞吐再上 full，Linux 会自动装 vLLM
uv pip install -U "mineru[full]>=4.0,<5"

# 国内网络先把模型源切到 ModelScope，否则首次下载模型能卡到怀疑人生
export MINERU_MODEL_SOURCE=modelscope
```

安装完毕之后使用 `mineru-kit models show` 来查看一下实际生效后的后端情况，否则你会认为自己是在运行 GPU，实际上却一直在消耗 CPU。解析命令有两处入口，行为不同。 `mineru-kit parse` 是无状态的，默认情况下会把整个文档解析出来； `mineru parse` 是一个文档库客户端，PDF 默认只读前 10 页

```
# 单文件转Markdown，standard档：小模型+VLM
mineru-kit parse paper.pdf -o paper.md --tier standard

# 批量目录出 zip；显式 --pages all，绕开两个入口的默认值差异
mineru-kit parse ./docs -o ./out --format zip --pages all

# 只是入库检索，flash 档不跑 VLM，速度快一个量级
mineru-kit parse manual.pdf -o manual.md --tier flash
```

## 代码中如何连接

从 Python 语言的角度来看，4.0 版本把无状态入口收进了 mineru.parser 里面，并且 parse、parse\_async 都是对外开放的

```
from pathlib import Path
from mineru.parser import parse

# tier 决定了成本：flash 走原生文本，standard 才拉小模型加 VLM
result = parse(
    "paper.pdf",
    tier="standard",
    ocr_mode="txt",      # 文本型 PDF 不做 OCR，扫描件换成 ocr
    page_range="1-20",   # 页码从 1 开始，闭区间
)

# markdown() 给人看，to_json() 给程序用，来自同一次解析
Path("paper.md").write_text(result.markdown(), encoding="utf-8")
Path("paper.json").write_text(result.to_json(), encoding="utf-8")
```

批量任务使用异步入口，注意一个坏文件不会把整批都拖垮

```
import asyncio
from pathlib import Path
from mineru.parser import parse_async

asyncdefmain():
for pdf insorted(Path("./docs").glob("*.pdf")):
try:
# 已经处在事件循环里就直接 await，不要外面再套一层
result = await parse_async(str(pdf), tier="standard")
Path(f"./out/{pdf.stem}.md").write_text(result.markdown(), encoding="utf-8")
except Exception as exc:
print(f"{pdf.name} 解析失败: {exc}")

asyncio.run(main())
```

## 有三种部署方式可以选用，根据团队大小来选择

一个人使用的话，就直接命令行模式，不要设置为服务，模型下载一次之后就结束

两个或者几个业务需要共享同一个模型，并且起 V1 API，模型只加载一次，比每个进程各自使用一份显存要划算得多

```
# V1 API，接口都在 /v1/*，旧的 /file_parse 和 /tasks 在 4.0 已经删了
mineru-kit api-server --host 0.0.0.0 --port 8000 --tier standard

# 多卡或多机，router 统一入口，按 --local-gpus 自动拉 worker
mineru-kit router --host 0.0.0.0 --port 8002 --local-gpus auto
```

客户端可以复用同一个解析器实例，能力发现、上传、轮询、下载都包含在内，每次调用都会自己打开和关闭会话，并且不需要手动释放

```
from mineru.parser import MinerUApiParser

# api_url 填 /v1 之前的根地址，密钥走 MINERU_API_KEY，别写死在代码里
parser = MinerUApiParser(api_url="http://127.0.0.1:8000", tier="standard")
print(parser.parse("contract.pdf").markdown())
```

第三种是使用 Gradio 做前端界面， `mineru-kit webui` 起一个，给不会用代码的同事来做人工校验。不要把生产当作接口来使用，它只是一个可视化的外壳

## 真正能够留住人的就是那些中间产物

很多解析服务只会给你一份 Markdown，看上去很美，但是下游无法使用。除了 Markdown 之外，MinerU 还保留了 middle.json 和 structured\_content.json 两个文件，其中每个块都有 type、page\_idx、bbox 等字段

这就意味着你能够自己编写切片逻辑：表格块整体进入向量库，公式块单独抽取出来进行检索，页眉和页脚按照坐标进行过滤。RAG 中最让人头疼的“表格被分割了”的问题，在这层就可以解决了

```
# structured_content 按页给块、按块切比按字符切靠谱得多
for page in result.structured_content()["pages"]:
for block in page["blocks"]:
if block["type"] == "table":
store_table(block["content"])     # 表格 HTML，行和列的关系仍然存在
elif block["type"] == "equation":
store_formula(block["content"])   # LaTeX
```

## 在什么样的情况下不要使用它

纯文本 PDF，只要文字不要结构，使用 pypdf 后几十毫秒就可以完成任务，上 MinerU 是拿高射炮打蚊子

对于延迟非常敏感的在线接口也不适合，standard 档一次解析是秒级到十几秒级，老老实实做异步任务队列

另外还有一个坑要提一下，在 3.1 版本之后，许可证就变成了基于 Apache 2.0 的 MinerU 开源许可证，相比之前的 AGPL 时代更加舒适一些。但是使用之前还是要看一下 LICENSE.md 文件，不要相信别人的一句“随便用”。

## 我的判断

MinerU 热门并不是因为它的榜单第一，而是在于它可以做到以下三点：可以进行私有化部署、可以批量运行、可以产出结构化的中间结果。做 RAG 的团队里最缺乏的东西并不是再去调用一个云上的 API，而是在于对数据入口的控制

我使用的办法是先用 flash 全量跑一遍来做索引，命中率高的文档再走 standard 重解析，可以降低成本一半以上。这套组合拳要比无脑全量 standard 务实性强一些

至于它是“最好的”解析器吗？我不会得出这样的结论。但是在我所接触过的项目中，它是我目前少数能够掌握住整个数据链条的工具

我是鹏磊，持续分享 AI 编程干货，今天就到这里，我们下期见

质保 30 天不掉订阅，掉订阅，按天退差价