MinerU 问题排查指南：从安装报错到解析调优的完整自救清单

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 / macOS3.10 - 3.13macOS 需 14.0 及以上Windows3.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 50xxBlackwell 架构显卡需安装lmdeploy 0.11.1 cu128的 Windows wheel参考仓库 FAQ 中的 Windows CUDA 加速章节。模型下载卡住或失败怎么解决本章解决首次运行卡在下载模型这一步或国内网络下 HuggingFace 连不通。MinerU 首次使用会自动下载所需模型之后走本地缓存。所以下载问题基本只出现一次但卡住时确实很吓人。现象进度条停在 HuggingFace反复超时重试原因默认模型源是 HuggingFace网络不通时下载必然失败。解决切换到 ModelScope 源对国内网络最稳export MINERU_MODEL_SOURCEmodelscope注意两点环境变量不能设为auto。默认行为本身就是auto——先探测 HuggingFace 是否可达不可达自动回退 ModelScope探测成功后会把结果写回用户目录的mineru.json避免下次因网络波动反复切换来源。想恢复自动选择删掉这个环境变量即可。MINERU_MODEL_SOURCE的优先级高于mineru.json里的model-source字段调试完记得清掉免得以后排查配置时打架。现象不想依赖远端源想彻底离线原因服务器 / 内网环境连不上任何模型仓库。解决先在一台能上网的机器上跑mineru-models-download把模型拉到本地支持交互选择下载哪些后端模型把模型目录和mineru.json一起拷到目标机器的用户目录然后export MINERU_MODEL_SOURCElocal模型目录移动后记得同步修改mineru.json里的models-dir路径pipeline和vlm后端是分开指定的。下载时命令会优先复用本地缓存文件命中缓存就不会重复下载。显存不够、OOM 或想指定用哪张卡本章解决解析时报 CUDA OOM、显存不够或多 GPU 机器上想用指定显卡。先确认你的硬件落在哪个档位不同后端对硬件的要求差得很多选错后端是显存问题的第一来源精度指标为 OmniDocBench v1.6 的 End-to-End Overall 分数后端纯 CPU 可用显存最低要求精度指标pipeline✅4GB86.47hybrid-engine/vlm-engine❌8GB95.39high/ 95.26medium*-http-client远程推理✅2GB本地小模型与对应 engine 一致内存要求本地推理后端最低 16GB、推荐 32GB 以上磁盘建议 20GB 以上 SSD。现象torch.OutOfMemoryError或解析到一半进程被 kill原因模型权重 推理 batch 同时占用显存文档页面复杂时峰值会更高。解决按顺序试换更省的后端-b pipeline4GB 显存即可跑CPU 也行hybrid 后端调低解析强度--effort medium默认值速度更快且精度损失很小hybrid-http-client场景下显存占用主要由本地小模型决定可用环境变量MINERU_HYBRID_BATCH_RATIO控制 batch 倍率单客户端显存MINERU_HYBRID_BATCH_RATIO≤ 6 GB8≤ 4 GB4≤ 3 GB2≤ 2 GB1临时关闭图片/图表分析--image-analysis falsemedium 强度本身也会自动关闭它。想固定用某张卡在命令前加CUDA_VISIBLE_DEVICES对所有命令行工具mineru、mineru-api、mineru-openai-server等和 pipeline / vlm 后端都生效CUDA_VISIBLE_DEVICES1 mineru -p input.pdf -o output/多卡起两个服务时分别指定不同卡号、监听不同端口即可。解析结果不对缺字、公式乱、表格碎本章解决命令跑通了但输出的 Markdown 质量不符合预期。先做个预期管理复杂版面、扫描件、手写体本来就是解析难点官方也建议先在线体验评估效果再决定本地怎么用。下面几个是最常见、也最容易被忽略的原因。Linux 上解析结果缺失部分文字尤其 CJK 字符现象输出的 Markdown 里整段中文/日文丢失但原 PDF 里明明有。原因2.0 版本起 MinerU 用pypdfium2替换了pymupdf作为 PDF 渲染引擎解决许可证问题。某些 Linux 发行版缺少 CJK 字体PDF 渲染成图片这一步就会丢字——丢的不是 OCR 环节是渲染环节。解决Ubuntu/Debiansudo 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-enginehybrid 后端需要图片/图表分析时把--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 truemineru-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），仅供参考