MinerU 4.2 装完仍报错：五步排查与三档速度实测

一句话结论：MinerU 4.2.1 在 M4 16GB 的 Mac 上能完整跑通，装完约 3 分 40 秒、占 3.2GB 磁盘，33 页纯文字 PDF 转 Markdown 只要 1.6 秒。但装完直接敲 mineru parse 一定会失败，卡点全在配置层，跟模型有没有下完关系不大。

三条命令各管什么，先分清再动手

4.0 之后这个项目从一个命令拆成了三层，中文教程里常见的 mineru -p input.pdf -o output 在 4.2.1 上会直接报错。装完之后先跑 mineru --help，能看到 15 个子命令，其中真正做转换的只有两个入口。

mineru-kit parse 是无状态的一次性转换，读完文件直接吐 Markdown，不建库、不缓存，适合批处理和脚本调用。mineru parse 走的是文档库那套，会建 SQLite、算 sha256、留缓存，还支持后续 mineru search 全文检索。想省事就用前者，想反复读同一批文件就用后者。

还有第三个进程 mineru server，它是文档库的后台服务，跑在 Unix socket 上。第一次敲 mineru parse 之前必须先把它拉起来，否则连文件都读不进去。这层依赖在官方快速上手页里只用一句话带过，是新手最容易卡住的地方。

安装本身不慢，34 秒结束

我用 uv 建 3.12 的虚拟环境，包从清华源拉，实测 34 秒装完，虚拟环境 1.2GB。基础包已经把 torch 2.15.0 拉进来了，MPS 加速可用，不需要额外装 mineru[torch]。如果你还没配 uv 的国内镜像，可以照 uv 国内加速的配法 先把源换掉，装包环节能从十几秒压到两秒内。

uv venv --python 3.12 .venv
source .venv/bin/activate
UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple uv pip install mineru
mineru version --json

最后一条命令返回 {"mineru_version": "4.2.1", "python_version": "3.12.12"}，版本号记住，后面所有结论都基于这一版。装完不要急着解析，先做一件事：查模型状态。

模型 2.0GB，下完还要校验

4.x 把模型按档位管起来了，basic 只用小模型，standard 在小模型之外再加一个 1.2B 的视觉语言模型。mineru-kit models download --tier standard 实测 184 秒拉完 2.0GB，分两块落在 ~/.mineru/models 下。

mineru-kit models download --tier standard
mineru-kit models verify
mineru-kit models show

目录明细是 MinerU-4_models_torch 858MB、MinerU2.5-Pro-2605-1.2B-GGUF 1.2GB。前者装版面检测、OCR、公式、表格四个小模型，后者是那个量化过的 1.2B 模型。加上虚拟环境，整套占 3.2GB，比 safetensors 转 GGUF 那类纯格式工具重得多（转换侧的体积账可以参考 safetensors 转 GGUF 的实测）。

models verify 会逐仓库报正常或缺失，两个仓库都显示正常才算真的到位。models show 额外告诉你生效的后端：我这台机器上是 torch 加 llama-cpp，也就是小模型走 PyTorch 的 MPS，大模型走 llama.cpp 的 Metal。这个组合决定了后面的速度量级。

报错五级阶梯，每一级都长得一样

这是整篇文章最值钱的部分。从装完到真正跑通，我踩了五层，其中三层返回的是同一个错误码。

第一级，用旧语法。mineru -p input.pdf -o output 退出码 2，界面报 No such option: -p。注意退出码是 2 而不是 1，写批处理脚本时按 1 判断会漏掉。

第二级，服务没起。mineru parse input.pdf 退出码 1，返回 server_not_running，提示里写得很清楚，让你先跑 mineru server start。按提示做，3.1 秒就起来了。

第三级，服务起了但没引擎。同一个命令返回 quality_tier_unavailable，英文提示给了三条出路：起本地解析服务、走 --remote、或者显式加 --tier flash 只做文本预览。到这里很多人会以为模型没装。

第四级，模型装完仍然报同一个码。我把 2.0GB 全部下完、models verify 两个仓库都正常，mineru parse 依然返回 quality_tier_unavailable。真因在配置里：parse_server.local.mode 的默认值是 disabled，模型在本地不等于引擎被启用。

mineru config show
mineru config set parse_server.local.mode managed

第五级，改完配置还是报错。设置返回 [override] 成功，再敲解析，仍然是那个码。原因是已经在跑的文档库服务不会重读配置文件。得 mineru server stop 再 mineru server start。

第六级其实是等待。重启之后服务会拉起一个子进程 python -m mineru.parser.api_server --tier standard --port 16580 --preload-models，它要先把 1.2B 模型读进显存。我按每 4 秒探测一次，0 到 18 秒之间每次都是 quality_tier_unavailable，第 22 秒才第一次成功。这段等待期没有任何进度提示，只有日志里那一行启动命令能证明它在干活。

把这条链画成一句话：报同一个码可能是四种完全不同的病，从服务没起、模型没下、开关没开、到服务没重启、再到模型还在加载。排错顺序只能是重启服务，然后等 25 秒，最后才怀疑文件。想跳过整套文档库的话，直接用 mineru-kit parse，它不需要服务、不需要改配置，装完模型就能跑。

三档实测：速度差 7 倍，内存差 15 倍

四个档位里 advanced 没有独立的模型包，实测只跑了前三档。测试机是 M4 芯片 16GB 统一内存，输入三份：一页自制中文数字版 PDF（含一张五列表格）、一页同内容的纯图片扫描件、一份 33 页英文设计手册。

单页那三行的耗时几乎全是固定开销。standard 跑一页要 17 秒，跑 33 页只要 36 秒，多出来的 32 页只花了 19 秒，说明 1.2B 模型的加载占了 14 秒左右。批量处理时这个固定成本会被摊薄，处理单页反而最不划算。

flash 档在纯文字 PDF 上是碾压级的速度：33 页 1.6 秒，每页 0.05 秒，因为它只读 PDF 里的原生文本层，连版面模型都不加载，峰值内存 269MB。代价是它不做版面理解，表格直接按坐标转成 HTML 表，段落顺序出错概率高一些。

真正反直觉的是 basic 和 standard 的关系。我拿那份一页中文 PDF 分别跑两档，两次输出 diff 结果为空，一个字节都不差。也就是说对干净的电子版文档，多花 7 秒和 1.5GB 内存，standard 没有任何增量。

差异出现在有代码块的页面上。33 页那份手册里，basic 和 standard 有 28 行不同，其中大部分是代码围栏错配。basic 会出现 ```txt 开头却没闭合、下一行直接跟 `bash 的情况，标准档能把围栏配对正确。所以判断标准不是文件大小，是文档里有没有需要推理的块结构。

输出格式的两个硬差异

第一个是表格。flash 档给的是 <table> 加 rowspan 和 colspan 的 HTML 表，basic 及以上的档位给的是 Markdown 管道表。如果你的下游是 Markdown 渲染器或向量库的固定切片规则，管道表直接可用，HTML 表要先转一道。这一条在官方文档里没写成对照表，实测差别很大。

第二个是图片。三档默认都把图片编成 base64 内联进 Markdown，那份 33 页手册出来 454KB，正文只有 43KB，剩下全是图片数据。直接喂给知识库会撑爆切片长度。

mineru-kit parse samples/doc_c.pdf -o out.zip --tier basic -f zip
unzip -l out.zip

加 -f zip 之后压缩包里是 images/page_0_table_3.jpg、markdown.md、middle_json.json、structured_content.json 四样东西，图片单独成文件，正文里的引用变成相对路径。要接 Cherry Studio 那种本地知识库，用 zip 输出比用裸 Markdown 省事得多，切块长度也更可控。同理，把解析好的 md 丢进 Open WebUI 的知识库 之前，先把 base64 图片剥掉，能减少一大半无效 token。

踩坑清单：四个会让人白折腾半小时的点

默认页数两套逻辑。 mineru parse 对 PDF 默认只解析前 10 页，返回的 page_range 字段写的是 1-10。mineru-kit parse 默认全篇，33 页就是 33 页。同一份文件换个命令，结果差 23 页。要全篇必须显式加 --pages all。

状态查询永远返回成功。 服务没在跑的时候，mineru server status 打印一行 服务未在运行。，退出码却是 0。脚本里用 if mineru server status; then 判断会恒为真，只能去 grep 输出文字或者查 socket 文件。

非 PDF 只认 flash。 拿 HTML 文件跑 --tier basic 会退出 1，报 Tier 'basic' is only supported for PDF and image files; 'html' files use tier 'flash'. 这句话写得比多数工具的报错都清楚。Office、EPUB、OFD、CSV 同理，全部归到 flash 档，而且是整篇解析，不接受 --pages。反过来 flash 解析 HTML 只要 0.019 秒。

遥测默认是开的。 装完没做任何选择，mineru telemetry status 就显示 enabled、来源 default，队列里已经积了 1 个周期 28 项指标。我用 telemetry preview 把待发请求体打出来看过，里面只有档位、耗时、成功与否、操作系统和 Python 版本，grep 文件名和路径都是空。介意的话跑 mineru telemetry disable，队列立刻清零，状态变 disabled。

什么时候用它，什么时候别用

本地方案的价值在批量与私密。一百份合同要转 Markdown，走本地 basic 档，每页 0.94 秒，一千页不到十六分钟，全程不联网。advanced 档只在版面极复杂时才值得开，它会加大推理计算量，官方也没给单独的模型包，需要自己准备算力。

反过来说，只处理三五份文件、又不介意上传的话，官网的 --remote 通道更省事，配置里 parse_server.remote.url 默认就指向官方接口，加个 key 就能用。本地这套 3.2GB 的体积和五级报错，在低频率场景下并不划算。

还有一类情况不适合它：需要精确坐标、要还原原版 PDF 版式的场景。MinerU 输出的是语义化的 Markdown 和 middle JSON，坐标信息在 JSON 里有，但 Markdown 里没有版式。要拿版式数据得读 middle_json.json，那是另一个话题。

常见问题

装完之后第一条命令就报 quality_tier_unavailable，怎么办？
先确认服务在跑，再确认 parse_server.local.mode 是 managed，然后重启服务并等 22 秒。这三步做完还报同样的码，才去看 models verify 的输出。也可以直接换 mineru-kit parse，它绕开文档库，不吃这套配置。

只想把电子版 PDF 转成 Markdown，需要下 2GB 模型吗？
不需要。mineru-kit parse --tier flash 在纯文字 PDF 上零模型依赖，33 页 1.6 秒，峰值内存 269MB。只有当文档是扫描件、或者表格需要结构还原时，才值得装 858MB 的小模型走 basic 档。

扫描件用 flash 档能不能凑合？
文字能看，结构不行。实测扫描件在 flash 档下会把表格压成一段用空格对齐的等宽代码块，行列关系全丢，数字倒是全对（12800、21500、38999 三个报价都对上了）。要给 RAG 用就必须上 basic，同样一页从 10.54 秒变成 11.38 秒，只多 0.84 秒。