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 的开源文档解析工具。不少用户在pip install阶段、首次运行阶段或拿到解析结果后卡住依赖编译失败、模型下载超时、Linux 上文字莫名丢失、显存爆了。本文按实际排障路径组织——从装不上、到跑不出正常结果、再到慢和 OOM每个条目都给出现象、一句话原因和可直接复制的修复命令最后一张报错速查表帮你按关键词秒查。安装阶段装不上、起不来的环境问题Python 版本与系统兼容性先对照这张表MinerU 对运行环境有明确边界超过边界的大多数报错依赖编译失败、wheel 缺失都源于此。检查项支持范围备注Python 版本✅ 3.10 – 3.133.10 或 3.14 均不支持Linux✅ 2019 年及以后的发行版过老系统会出现 wheel 编译失败Windows✅ Python 3.10 – 3.12关键依赖 ray 在 Windows 上未适配 3.13macOS✅ 14.0 及以上版本Apple Silicon 可启用 MPS 加速现象安装时反复出现ERROR: Failed building wheel for simsimd之类的编译报错最终安装失败。原因系统或 Python 版本不在支持矩阵内pip 被迫从源码编译依赖。修复重建一个 3.10–3.13 的 Python 环境再安装一条命令装齐全部功能conda create -n mineru python3.11 -y conda activate mineru uv pip install -U mineru[all]如需从源码安装可使用git clone https://gitcode.com/GitHub_Trending/mi/MinerU cd MinerU uv pip install -e .[all]WSL2 / 精简版 Linux 缺 libGL 的修复命令现象首次运行或 import 时报ImportError: libGL.so.1: cannot open shared object file: No such file or directory。原因WSL2 的 Ubuntu 和不少最小化安装的 Linux 发行版没有预装 OpenCV 依赖的 libGL 库。修复sudo apt-get update sudo apt-get install libgl1-mesa-glx装完重跑一次原命令即可无需重装 MinerU。结果异常跑出来了但文字、公式不对Linux 上解析结果缺失 CJK 文字的修复命令现象Linux 环境跑出来的 Markdown 里部分中文/日文等 CJK 文字缺失或整块空白。原因MinerU 2.0 起用pypdfium2渲染 PDF 页面系统缺少 CJK 字体时渲染成图片这一步就丢字了——问题出在操作系统字体不在 MinerU 配置。修复Ubuntu/Debiansudo apt update sudo apt install fonts-noto-core fonts-noto-cjk fc-cache -fv或者直接用官方 Docker 镜像部署仅 Linux 与 WSL2 可用镜像内置完整字体包可绕开这类系统级差异。公式分隔符不符合下游需求的配置方法现象输出的 Markdown 中 LaTeX 公式用了$...$/$$...$$但你的渲染器或 RAG 管线只认其他定界符。原因分隔符由用户目录下mineru.json的latex-delimiter-config控制默认是$系。修复编辑用户目录mineru.json可用仓库根目录的 mineru.template.json 作为模板{ latex-delimiter-config: { display: { left: $$, right: $$ }, inline: { left: $, right: $ } } }OCR 语言参数怎么选仅 pipeline 后端生效现象小语种或特殊文字体系识别率低。原因未给 pipeline 后端的 OCR 指定语言走了通用识别路径。修复通过-l指定文档语言支持值如下文档语言-l取值中英混合默认首选ch中英混合、服务端高负载场景ch_server韩文korean泰文 / 希腊文 / 阿拉伯文th/el/arabic东斯拉夫语系俄语等east_slavic西里尔字母cyrillic天城文印地语等devanagari泰卢固 / 泰米尔 / 卡纳达te/ta/kamineru -p input_path -o output_path -b pipeline -l ch正确解析后输出的版面结构应类似下图这样的分块定位效果后端怎么选先看硬件再看文档复杂度MinerU 当前提供五类后端pipeline、hybrid-engine、vlm-engine、hybrid-http-client、vlm-http-client。选错后端是显存爆、速度慢、结果差三类抱怨的最大来源按下面这张决策图走各后端硬件要求对照数值来自快速入门项目pipelinehybrid/vlm-engine*-http-client客户端纯 CPU 支持✅❌✅GPU 加速要求Volta 及以后架构或 Apple Silicon同左不需要显存最低4GB8GB2GB内存16GB 起推荐 32GB16GB 起推荐 32GB16GB磁盘20GB 起建议 SSD20GB 起建议 SSD2GB慢和 OOM能跑但资源不够用Windows 安装后推理特别慢的修复方法现象Windows 上装好直接跑一张 PDF 要等很久GPU 利用率接近 0。原因pip 默认装的是 CPU 版torchCUDA 加速没生效。修复按显卡架构分两种情况——V100 / 20 系 / T4 / 30 系 / 40 系Volta 到 Ada按你的 CUDA 版本到 PyTorch 官方安装页选 Windows 命令装带 CUDA 的torch和torchvisionRTX 50xxBlackwell安装lmdeploy 0.11.1 cu128的 Windows wheel把PYTHON_VERSION设为当前 Python 版本如 3.12 填312已装过 cu128 版 torch 时追加--no-dependencies避免重装低版本 torch。显存不够如何降配运行现象本地跑 engine 后端时CUDA out of memory。原因默认 batch 策略按较高显存规划小显存机器需要显式下调。修复按显存大小设置MINERU_HYBRID_BATCH_RATIO单端显存MINERU_HYBRID_BATCH_RATIO≤ 6GB8≤ 4GB4≤ 3GB2≤ 2GB1export MINERU_HYBRID_BATCH_RATIO2 mineru -p input_path -o output_path显存实在不够4GB时最优解不是硬降 batch而是把推理挪到服务端起一个 vLLM/lmdeploy 兼容服务客户端走hybrid-http-client本地只需 2GB 级显存或纯vlm-http-client本地不需要装 torch。大文档处理内存吃紧的调整项现象几百页文档处理到一半内存占满或被系统杀掉。原因单次处理窗口与渲染并发按默认值运行窗口 64 页、渲染线程 4。修复调小窗口 按页分段跑export MINERU_PROCESSING_WINDOW_SIZE16 export MINERU_PDF_RENDER_THREADS2 mineru -p large.pdf -o output/ -s 0 -e 99 mineru -p large.pdf -o output/ -s 100 -e 199多 API 并发场景再配合MINERU_API_MAX_CONCURRENT_REQUESTS默认 3下调并发避免多个任务同时吃显存。高频报错关键词速查表按报错信息里最显眼的那串词直接对号入座报错关键词 / 现象原因修复libGL.so.1: cannot open shared object file系统缺 libGLsudo apt-get install libgl1-mesa-glxFailed building wheel for simsimdPython/系统版本过老被迫源码编译换 Python 3.10–3.13 重装mineru[all]结果缺失 CJK 文字pypdfium2 渲染时缺 CJK 字体装fonts-noto-cjk后fc-cache -fv模型下载超时 / HuggingFace 连不上网络无法访问 HuggingFaceexport MINERU_MODEL_SOURCEmodelscopeCUDA out of memory本地 engine 显存规划过大降MINERU_HYBRID_BATCH_RATIO或改 http-client 架构Windows 能跑但极慢装到了 CPU 版 torch按显卡架构安装 CUDA 版 torch任务查询突然 404API 任务默认保留 24 小时后自动清理调大MINERU_API_TASK_RETENTION_SECONDSAddress already in use8000 端口mineru-api默认端口被占用mineru-api --port 8001排障方法与求助路径先定位再求助三步排查法确认版本与环境mineru -v记录版本python -V记录 Python 版本pip list | grep -E torch|transformers记录关键依赖版本。拿到完整日志当前版本中mineruCLI 会自动拉起本地临时mineru-api也可用--api-url直连已有服务先curl http://127.0.0.1:8000/health看服务是否正常启动再看终端输出的完整堆栈——报错栈的最内层那几行才是根因不要把进度条和下载日志当成错误。最小化复现用-s/-e把问题文档缩小到出问题的 1–2 页换pipeline与hybrid-engine两个后端各跑一次对比能快速区分是环境问题还是模型能力问题。如果确认是项目 bug 或解析效果问题去项目仓库提交 Issue附齐这五样维护者才能复现MinerU 版本、Python 版本、操作系统含 WSL2 说明、GPU 型号与显存完整复现命令含-b、-l等参数与完整报错日志出问题的文档样本或可脱敏的最小页面截图期望输出与实际输出的对照已尝试过的排查步骤。文档层面的补充资料常见问题解答、命令行工具说明、模型源说明 和 使用指南。文档没覆盖到的可加入官方 Discord 或微信社区向其他用户和开发者提问。本文基于 MinerU3.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），仅供参考
