MinerU 问题排查指南：从安装报错到解析调优的完整自救清单
【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU
本文是一份面向 MinerU 的问题排查指南。MinerU 可以把 PDF、DOCX、PPTX、XLSX 和图片解析成 LLM 可直接使用的 Markdown / JSON，但很多人卡在三个地方：安装报错、模型下载失败、解析效果不达预期。下面按"装不上 → 下不动 → 显存吃紧 → 结果不对 → 彻底卡住"的排查顺序组织，每章都可独立阅读：找到你当前的报错，跳到对应章节即可。
第一次启动就报错？先看是哪一层的问题
本章解决：
mineru -p命令刚跑起来就失败，或 pip 安装阶段就报错。
排查时先分清错误发生在哪一层：Python 环境层、系统依赖层、还是 MinerU 自身。不同层的修复方式完全不同。
Python 版本不对导致的安装报错
- 现象：
pip install mineru装不上，或装完运行直接报PythonX.Y required之类的错误。 - 原因：MinerU 要求
requires-python >=3.10,<3.14，低于 3.10 的旧环境没有任何可用 wheel。 - 解决：用 conda 或 pyenv 建一个 3.10~3.13 的干净环境，不要装在系统 Python 里。
各平台支持的 Python 版本有细微差别，安装前先对号入座：
| 平台 | 支持的 Python 版本 | 说明 |
|---|---|---|
| Linux / macOS | 3.10 - 3.13 | macOS 需 14.0 及以上 |
| Windows | 3.10 - 3.12 | 关键依赖ray不支持 Windows 上的 3.13 |
| 全部 | Linux 需 2019 年及以后的发行版 | 更老的系统不在主线测试范围内 |
WSL2 里报libGL.so.1: cannot open shared object file
- 现象：WSL2 的 Ubuntu 22.04 中运行报
ImportError: libGL.so.1: cannot open shared object file: No such file or directory。这个报错不常见，但原因很明确。 - 原因：MinerU 依赖
opencv-python，它运行时要加载系统的 OpenGL 库libGL.so.1；精简版 Ubuntu 镜像默认不带。 - 解决：
sudo apt-get install libgl1-mesa-glx依赖编译失败（simd、opencv 之类的 C 扩展）
- 现象：安装时报
Failed building wheel，常见于老系统。 - 原因：系统 glibc / 编译器太旧，第三方包没有现成 wheel，只能源码编译然后失败。这不是 MinerU 的 bug，是底座太老。
- 解决：优先升级系统或换 conda 环境；再不行直接用 Docker 部署（仓库内
docker/compose.yaml有现成编排），Docker 镜像已包含完整字体和系统依赖，能绕过绝大多数环境兼容问题。
Windows 装好了但推理速度很慢
- 现象：命令能跑，但一页要等很久，GPU 利用率近乎为 0。
- 原因：CUDA 加速依赖没装对。Linux 和 macOS 会自动尝试 cuda/mps 加速，Windows 需要你自己装支持 CUDA 的
torch和torchvision。 - 解决：去 PyTorch 官网按你的 CUDA 版本选对应的 Windows 安装命令。如果是 RTX 50xx（Blackwell 架构）显卡，需安装
lmdeploy 0.11.1 + cu128的 Windows wheel，参考仓库 FAQ 中的 Windows CUDA 加速章节。
模型下载卡住或失败怎么解决
本章解决：首次运行卡在"下载模型"这一步，或国内网络下 HuggingFace 连不通。
MinerU 首次使用会自动下载所需模型，之后走本地缓存。所以下载问题基本只出现一次，但卡住时确实很吓人。
现象：进度条停在 HuggingFace，反复超时重试
- 原因：默认模型源是 HuggingFace，网络不通时下载必然失败。
- 解决：切换到 ModelScope 源，对国内网络最稳：
export MINERU_MODEL_SOURCE=modelscope注意两点：
- 环境变量不能设为
auto。默认行为本身就是auto——先探测 HuggingFace 是否可达，不可达自动回退 ModelScope；探测成功后会把结果写回用户目录的mineru.json，避免下次因网络波动反复切换来源。想恢复自动选择，删掉这个环境变量即可。 MINERU_MODEL_SOURCE的优先级高于mineru.json里的model-source字段，调试完记得清掉，免得以后排查配置时打架。
现象：不想依赖远端源，想彻底离线
- 原因：服务器 / 内网环境连不上任何模型仓库。
- 解决：先在一台能上网的机器上跑
mineru-models-download把模型拉到本地（支持交互选择下载哪些后端模型），把模型目录和mineru.json一起拷到目标机器的用户目录，然后：
export MINERU_MODEL_SOURCE=local模型目录移动后，记得同步修改mineru.json里的models-dir路径（pipeline和vlm后端是分开指定的）。下载时命令会优先复用本地缓存文件，命中缓存就不会重复下载。
显存不够、OOM 或想指定用哪张卡
本章解决：解析时报 CUDA OOM、显存不够，或多 GPU 机器上想用指定显卡。
先确认你的硬件落在哪个档位
不同后端对硬件的要求差得很多，选错后端是显存问题的第一来源（精度指标为 OmniDocBench v1.6 的 End-to-End Overall 分数）：
| 后端 | 纯 CPU 可用 | 显存最低要求 | 精度指标 |
|---|---|---|---|
pipeline | ✅ | 4GB | 86.47 |
hybrid-engine/vlm-engine | ❌ | 8GB | 95.39（high）/ 95.26（medium） |
*-http-client（远程推理） | ✅ | 2GB（本地小模型） | 与对应 engine 一致 |
内存要求：本地推理后端最低 16GB、推荐 32GB 以上；磁盘建议 20GB 以上 SSD。
现象：torch.OutOfMemoryError或解析到一半进程被 kill
- 原因：模型权重 + 推理 batch 同时占用显存，文档页面复杂时峰值会更高。
- 解决，按顺序试：
- 换更省的后端：
-b pipeline（4GB 显存即可跑，CPU 也行）； - hybrid 后端调低解析强度：
--effort medium（默认值，速度更快且精度损失很小）； hybrid-http-client场景下，显存占用主要由本地小模型决定，可用环境变量MINERU_HYBRID_BATCH_RATIO控制 batch 倍率：
- 换更省的后端：
| 单客户端显存 | MINERU_HYBRID_BATCH_RATIO |
|---|---|
| ≤ 6 GB | 8 |
| ≤ 4 GB | 4 |
| ≤ 3 GB | 2 |
| ≤ 2 GB | 1 |
- 临时关闭图片/图表分析：
--image-analysis false（medium 强度本身也会自动关闭它）。
想固定用某张卡？
在命令前加CUDA_VISIBLE_DEVICES，对所有命令行工具（mineru、mineru-api、mineru-openai-server等）和 pipeline / vlm 后端都生效：
CUDA_VISIBLE_DEVICES=1 mineru -p input.pdf -o output/多卡起两个服务时分别指定不同卡号、监听不同端口即可。
解析结果不对：缺字、公式乱、表格碎
本章解决：命令跑通了，但输出的 Markdown 质量不符合预期。
先做个预期管理：复杂版面、扫描件、手写体本来就是解析难点，官方也建议先在线体验评估效果，再决定本地怎么用。下面几个是最常见、也最容易被忽略的原因。
Linux 上解析结果缺失部分文字（尤其 CJK 字符）
- 现象：输出的 Markdown 里整段中文/日文丢失，但原 PDF 里明明有。
- 原因：2.0 版本起 MinerU 用
pypdfium2替换了pymupdf作为 PDF 渲染引擎（解决许可证问题）。某些 Linux 发行版缺少 CJK 字体，PDF 渲染成图片这一步就会丢字——丢的不是 OCR 环节，是渲染环节。 - 解决（Ubuntu/Debian）：
sudo apt update sudo apt install fonts-noto-core fonts-noto-cjk fc-cache -fv或者直接改用 Docker 部署，官方镜像已内置这些字体包。
公式、表格解析不符合预期
- 现象：公式 LaTeX 错乱、表格结构解析不准。
- 原因：公式/表格解析默认是开启的（
-f/-t），但它们各自依赖专门的模型，在低精度后端或低强度模式下效果有限。 - 解决，按代价从低到高：
- 确认你的文档场景确实用得到它们——不需要就关掉省资源：
-f false或-t false； - 换更高精度后端：
-b vlm-engine或-b hybrid-engine； - hybrid 后端需要图片/图表分析时，把
--effort切到high（默认medium会自动关闭图片分析，追求最高精度时再开 high，代价是速度下降）； - LaTeX 分隔符不合你的下游渲染习惯时，改
mineru.json里的latex-delimiter-config（默认$包裹）。
- 确认你的文档场景确实用得到它们——不需要就关掉省资源：
语言参数（--lang）到底怎么选
- 该参数只对 pipeline 后端生效，用于指定文档语言以提升 OCR 准确率。
- 中英混排、日文、繁体、英文、西文等场景统一选
ch即可：3.4 版本已把日文、繁体、英文、西文选项移除，这些场景全部路由到ch模型，不用纠结。 - 其他可选值：
ch_server（服务器版模型，对手写更友好）、korean、ta、te、ka、th、el、arabic、east_slavic、cyrillic、devanagari。 - 不想选语言就保持默认 auto 自动检测，但自动检测在非常见语种上属于实验性能力。
不确定是解析问题还是我传参问题
用同一份文档对比两个后端的输出，差异一眼可见：
mineru -p test.pdf -o out/pipeline/ -b pipeline mineru -p test.pdf -o out/hybrid/ -b hybrid-engine输出目录里同时有 Markdown、中间 JSON 和可视化图，对着看比空猜快得多。
大文档、API 服务启动慢或任务超时
本章解决：几百页文档处理到一半出问题，或
mineru-api/ Gradio 起服务时等待异常。
大文档处理到一半内存紧张或特别慢
- 原因：页面渲染和批量处理都占内存，文档越大峰值越高。
- 解决：
- 用
-s/-e指定页码范围（从 0 开始），先分段跑通再放大； MINERU_PROCESSING_WINDOW_SIZE（默认 64）控制单次处理窗口大小，直接影响大文档的内存占用和吞吐，内存吃紧就调小；- PDF 渲染环节的并发与超时也可调：
MINERU_PDF_RENDER_THREADS（默认 4）和MINERU_PDF_RENDER_TIMEOUT（默认 300 秒）。渲染卡死时先怀疑这里； - Gradio WebUI 场景可直接
--max-convert-pages 50限制单次最大页数。
- 用
API 服务 / CLI 一直转圈，迟迟不出结果
- 现象：
mineru命令执行后长时间无输出，或 Gradio 启动卡在等待阶段。 - 原因：从当前版本起
mineru是基于mineru-api的编排客户端——不传--api-url时会自动拉起一个本地临时mineru-api。首次启动要加载模型，默认只等 300 秒（MINERU_LOCAL_API_STARTUP_TIMEOUT_SECONDS），超了就失败。 - 解决：
- 模型首次加载确实慢，耐心等待或调大
MINERU_LOCAL_API_STARTUP_TIMEOUT_SECONDS； - 已知要用 VLM/hybrid 后端时，加
--enable-vlm-preload true（mineru-api/mineru-gradio/mineru-router都支持），让模型在服务启动阶段就预热，避免首个请求时才初始化； - 确认网络能连通模型源（见第二章），模型没下完服务永远不会进入健康状态。
- 模型首次加载确实慢，耐心等待或调大
客户端轮询超时（MINERU_TASK_RESULT_TIMEOUT_SECONDS相关报错）
- 原因：默认任务结果等待上限 3600 秒，大文档 + 低配机器确实可能超过。
- 解决：调大
MINERU_TASK_RESULT_TIMEOUT_SECONDS；如果卡在下载结果阶段，则调大MINERU_TASK_RESULT_DOWNLOAD_TIMEOUT_SECONDS（默认 600 秒）。
查任务状态返回 404
- 现象：服务重启前明明存在的
task_id，现在查询返回 404。 - 原因：任务默认完成/失败后保留 24 小时（
MINERU_API_TASK_RETENTION_SECONDS）就被清理，连输出目录一起删；且任务状态是进程内实现，服务重启后历史状态不可查。 - 解决：这不是 bug。需要长期留存就调大保留时长，或在客户端侧及时把结果落盘。
彻底卡住时：自查流程与求助清单
本章解决：以上都没命中时的排查动线，以及怎么提交一个"能被快速解决"的 Issue。
问题自查流程
按这个顺序走，能覆盖绝大多数问题：
两条通用建议：
- 排查时永远先跑最小复现：一份能稳定复现问题的文档 + 一条最短命令，比大文档随机出错好定位得多。
- 用
mineru -v记下你的版本号。仓库docs目录下的 FAQ 和 changelog 是官方维护的第一手资料，很多报错在那里有编号可查。
向社区求助前，先备齐这些信息
- ✅ 提交 issue 前请附上 PDF / 文档样例（官方明确欢迎效果不佳的样例文档）
- ✅ MinerU 版本（
mineru -v）、操作系统、Python 版本 - ✅ 使用的后端（
-b参数值）与模型源（MINERU_MODEL_SOURCE是否设置过） - ✅ 完整报错日志（从命令开始到报错结束的原始输出，不要只截最后一行）
- ✅ 最小复现命令与文档页数、页码范围（
-s/-e） - ✅ 相关环境变量的设置情况（如
CUDA_VISIBLE_DEVICES、MINERU_PDF_RENDER_*） - ✅ 已经尝试过的解法（哪怕没用，也能帮维护者跳过弯路）
FAQ 里没覆盖的问题，可以在仓库的 FAQ 开头提到的 AI 助手（DeepWiki）里先问一轮，大部分常见问题能直接得到解答；仍无法解决时，带着上面的清单去提 Issue 或加入社区交流，信息越完整，得到的帮助越快、越准。
【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
