MinerU 故障排查速查从安装报错到解析质量的完整排障指南【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerUMinerU 把 PDF、DOCX、PPTX、XLSX 等文档解析为可直接喂给 LLM 的 Markdown/JSON。如果你部署时报依赖缺失、模型下载失败或解析结果缺字乱码按本文环境 → 模型 → 参数 → 结果的排查路线逐层定位基本都能自行修好。先定位问题在哪一层MinerU 排障的五层路线报错不可怕怕的是在错误的层上花时间。绝大多数 MinerU 报错可以归入五层之一先判断层再动手。图中顺序即排查顺序每一层修完都要回到最小复现验证不要跳过验证直接试下一层。环境层依赖缺失与版本不兼容的快速定位这一层的问题是装不上、起不来、出图缺字先看现象再执行对应命令。Python 版本不在 3.10–3.13 区间现象pip install mineru报Requires-Python 3.10,3.14或直接装不上依赖。原因MinerU 只支持 3.10 到 3.13Windows 因部分依赖限制仅到 3.12。动作新建 3.10–3.13 的虚拟环境重装例如uv venv --python 3.12后执行uv pip install -U mineru[all]。验证mineru --version能打印版本号当前仓库版本为 3.4.4。WSL2/Ubuntu 报libGL.so.1缺失现象启动即报ImportError: libGL.so.1: cannot open shared object file。原因镜像版发行版尤其 WSL2 的 Ubuntu 22.04缺少 OpenCV 依赖的图形共享库。动作sudo apt-get update sudo apt-get install -y libgl1-mesa-glx验证重新运行mineru -p input -o output不再出现该 ImportError。Linux 解析结果缺失 CJK 文字现象Markdown 里中文整段丢失但英文正常。原因MinerU 自 2.0 起用pypdfium2渲染 PDF系统缺少 CJK 字体时渲染成图片的过程会丢字。动作sudo apt install fonts-noto-core fonts-noto-cjk fc-cache -fv验证重新解析同一份 PDF抽查中文字符完整。不想折腾字体的直接用官方 Docker 部署镜像内置这些字体见 Docker 部署文档。Windows 装完能跑但推理极慢现象CPU 占用低、GPU 不吃、速度像纯 CPU。原因默认装的是无 CUDA 的torch。动作到 PyTorch 官网按显卡对应的 CUDA 版本重装torch和torchvisionRTX 50 系Blackwell需安装lmdeploy 0.11.1 cu128的 Windows wheel。验证解析时nvidia-smi能看到显存被占用。细节见 FAQ。老系统装不上如 CentOS 7、Ubuntu 18现象编译依赖如simsimdwheel 失败。原因官方仅测试 2019 年及以后的 Linux 发行版。动作优先换 Docker 部署没有条件就上 3.11 干净 conda 环境重试pip install -U mineru[all]。模型层下载失败、切换模型源与本地化模型问题集中在第一次解析时。默认策略是auto先探测 HuggingFace不通再回退 ModelScope并把实际来源写回mineru.json避免每次网络波动反复切换。首次运行卡在模型下载或直接超时现象长时间无输出、ConnectionError或 401/403。原因当前网络访问不了 HuggingFace。动作export MINERU_MODEL_SOURCEmodelscope mineru -p input_path -o output_path注意MINERU_MODEL_SOURCE只接受huggingface、modelscope、local三个值不要设成auto需要自动探测就删掉这个环境变量。想在离线/生产环境预先备好模型动作先跑mineru-models-download交互式选模型并落盘下载完成后路径会写进用户目录的mineru.json之后在离线机上设置export MINERU_MODEL_SOURCElocal即可。如果要自定义存放位置编辑mineru.json的models-dir分别为pipeline和vlm指定目录。⚠️ 移动模型文件夹到新服务器时记得把mineru.json一并带上并改好路径否则会报找不到模型。完整说明见 模型源文档。参数与硬件层后端选择、显存与并发调参这一层决定快不快、会不会 OOM。先选对后端再调显存和并发。按硬件和精度需求选后端后端-b取值适用场景显存最低纯 CPU精度OmniDocBenchpipeline简单文档、纯 CPU 机器4GB✅86.47hybrid-engine默认复杂版面、追求精度8GB❌95.26medium/ 95.39highvlm-engine端到端 VLM 场景8GB❌95.30hybrid-http-client/vlm-http-client连接 OpenAI 兼容推理服务2GBhybrid✅与 engine 对应值# 纯 CPU 机器固定走 pipeline mineru -p input_path -o output_path -b pipeline # 连接远端 OpenAI 兼容服务本地无需 torch 也可跑 vlm-http-client mineru -p input_path -o output_path -b hybrid-http-client -u http://127.0.0.1:30000hybrid后端还可加--effort high提升解析强度代价是更慢。参数全貌见 命令行工具说明。显存不够 OOM 或想压低客户端占用hybrid-*后端用环境变量控制小模型 batch 倍率显存越小倍率越低单卡/客户端显存MINERU_HYBRID_BATCH_RATIO≤ 6GB8≤ 4GB4≤ 3GB2≤ 2GB1并发与吞吐侧的旋钮MINERU_API_MAX_CONCURRENT_REQUESTS默认 3调小可降内存、MINERU_PROCESSING_WINDOW_SIZE默认 64大文档爆内存时调小、MINERU_PDF_RENDER_TIMEOUT渲染超时默认 300 秒。多卡场景在命令前加CUDA_VISIBLE_DEVICES1指定卡多卡统一入口用CUDA_VISIBLE_DEVICES0,1,2,3 mineru-router --host 0.0.0.0 --port 8002更多透传参数见 命令行参数进阶。结果质量层缺字、公式乱码与语言适配调优输出能跑但不准时按下面的开关逐项调每项只动一个变量以便归因。公式分隔符与下游渲染对不上动作编辑mineru.json的latex-delimiter-configinline/display分别设左右分隔符默认是$与$$Gradio WebUI 也可用--latex-delimiters-type a|b|all切换$或[]()风格。确认下游如 RAG 管道按同样分隔符解析。扫描件/混合语言识别不准动作给pipeline后端显式指定语言比自动判断稳mineru -p input_path -o output_path -b pipeline -l ch-l可选ch、ch_server、korean、arabic等ch_server面向中英混合与手写场景。若怀疑是文本层抽取而非 OCR 的问题可试-m ocr强制走识别路径。表格或公式解析异常想开关控制-t表格和-f公式默认开启确认问题出在表格结构识别时可用MINERU_TABLE_MERGE_ENABLEfalse关闭跨页表格合并观察差异或用--image-analysis false关掉 VLM/hybrid 的图片分析来排除图表分析引入的干扰。进阶调试最小复现、日志与多后端交叉验证定位疑难问题先把范围缩到一页再说话。最小复现用-s/-e指定页码从 0 开始只解析出错的那几页例如mineru -p big.pdf -o out/ -s 10 -e 11仓库自带demo/pdfs/demo1.pdf可作对照组。交叉验证同一页分别用-b pipeline和默认hybrid-engine各跑一次diff 两份full.md。两边一致说明是文档本身问题不一致再按差异定位模型层。服务化排障mineru-api --host 0.0.0.0 --port 8000起来后访问http://127.0.0.1:8000/docs看接口文档GET /health返回的max_concurrent_requests、processing_window_size可用于核对服务侧配置是否符合预期。排障与上线前检查清单修复完成或把 MinerU 纳入生产链路前过一遍这张清单Python 版本在 3.10–3.13mineru --version正常Linux 已装libgl1-mesa-glx与 Noto CJK 字体或改用 DockerMINERU_MODEL_SOURCE已按网络环境固定为huggingface/modelscope/localmineru.json中models-dir、model-source与实际模型位置一致后端与硬件匹配纯 CPU 用pipeline8GB 显存才上hybrid-engine显存/并发已按机器调过MINERU_HYBRID_BATCH_RATIO、MINERU_API_MAX_CONCURRENT_REQUESTS用-s/-e做过最小页级复现双后端交叉验证过关键页面如果清单全过仍无解提交 issue 时附上出错页码、完整命令、报错栈和一份可复现的 PDF 样例demo/pdfs/下的样例格式即可并说明系统、Python 与 MinerU 版本也可以先查 项目 FAQ或在项目社区渠道求助。排障的关键永远是先分层再动手。本文基于 MinerU 3.4.4 整理参数与默认值以最新仓库文档为准快速入门、命令行工具说明。【免费下载链接】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），仅供参考