Knowledge/Clippings/为什么越来越多人用 MinerU？.md at main

Cheney/Knowledge

Fork 0

Files

T

cheney 7015312702 vault backup: 2026-11-07 16:33:44

2026-11-07 16:33:55 +08:00

9.1 KiB

Raw Permalink Blame History

title, source, author, published, created, description, tags

title

source

author

published

created

description

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

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

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 天不掉订阅，掉订阅，按天退差价

9.1 KiB Raw Permalink Blame History Unescape Escape