MinerU 文档解析故障排查手册：12 个高频常见问题一次讲清

MinerU 文档解析故障排查手册12 个高频常见问题一次讲清【免费下载链接】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、扫描件与 Office 文档解析为大模型可直接消费的 Markdown/JSON。本文收集了安装失败、解析丢字、显存 OOM、API 返回 404 等高频问题按「装不上 → 结果不对 → 慢且费 → 部署」的路径组织每个问题都给出现象、原因、处理与验证命令可直接复制执行。1. 还没跑起来安装与模型下载的阻断问题1.1 pip 安装直接失败Python 版本不达标现象执行pip install mineru[all]报Requires-Python 3.10,3.14或安装后mineru命令不存在。原因MinerU 3.4.4 支持 Python 3.10–3.13Windows 因依赖 ray最高到 3.12。处理conda create -n mineru python3.11 -y conda activate mineru pip install --upgrade pip pip install -U mineru[all] # 全功能Linux 上额外包含 vllm验证mineru -v输出3.4.4。1.2 报 ImportError: libGL.so.1现象首次运行即报ImportError: libGL.so.1: cannot open shared object file: No such file or directoryWSL2 的 Ubuntu 22.04 上最常见。原因OpenCV 依赖的图形库在精简版系统里缺失。处理sudo apt-get update sudo apt-get install libgl1-mesa-glx # 旧版 Ubuntu新版可用 libgl1验证python -c import cv2; print(cv2.__version__)能打印版本号。1.3 模型下载卡住三种模型源切换方式现象首次解析长时间无进度或日志中出现 huggingface 请求超时、ConnectionError。处理按场景三选一# 方式一环境变量切换到 modelscope 源当前终端生效 export MINERU_MODEL_SOURCEmodelscope mineru -p demo/pdfs/demo1.pdf -o output/ # 方式二预先下载模型到本地 mineru-models-download # 交互式选择路径自动写入用户目录 mineru.json export MINERU_MODEL_SOURCElocal # 方式三在用户目录 mineru.json 中固定来源模板见仓库根目录 mineru.template.json{ model-source: auto, models-dir: { pipeline: /data/models/pipeline, vlm: /data/models/vlm } }验证重新运行解析日志直接进入版面解析阶段不再出现下载进度。详细说明见 docs/zh/usage/model_source.md。2. 跑起来了但结果不对解析质量四类主因2.1 渲染图里中文丢字安装 CJK 字体现象Linux 系统下输出的 Markdown 或部分页面图像缺中文、日文、韩文字符英文正常。原因2.0 版本起 MinerU 用 pypdfium2 渲染 PDF 页面缺少 CJK 字体时渲染过程会丢字。处理sudo apt update sudo apt install fonts-noto-core fonts-noto-cjk # Noto 字体包 fc-cache -fv # 刷新字体缓存验证重新解析同一份文档打开输出目录中的页面图片中文完整显示。2.2 公式分隔符与下游不匹配修改 latex-delimiter-config现象解析出的 Markdown 里公式用了$...$但你下游的渲染器只认\(\)公式原样显示。处理编辑用户目录下的mineru.json可用 mineru.template.json 复制后改名{ latex-delimiter-config: { display: { left: $$, right: $$ }, inline: { left: $, right: $ } } }若用 Gradio WebUI也可用--latex-delimiters-type a$型、b()[]型或all两种都输出。验证重新解析后Markdown 中公式分隔符与配置一致。2.3 识别不准-l 与 -m 参数选对现象扫描件识别错字多或对纯英文文档走了中英混合流程速度偏慢。处理# -l 仅对 pipeline 后端生效-m 可选 auto(默认)/txt/ocr也仅 pipeline 与 hybrid 系后端可用 mineru -p scan.pdf -o output/ -b pipeline -l ch文档语言推荐-l取值说明中英混合ch中文场景首选纯英文、日繁、手写ch_server服务端大模型识别韩/泰/阿拉伯/西里尔等korean、th、arabic、cyrillic等见mineru --help完整列表hybrid 与 vlm 后端由 VLM 自行判断语言不需要-l。2.4 表格或公式用不上-t / -f 关闭省时现象文档里没有公式和表格却仍要等 MFR、表格结构识别跑完。处理mineru -p plain.pdf -o output/ -f false -t false # 关闭公式与表格解析 # 等价环境变量MINERU_FORMULA_ENABLEfalse、MINERU_TABLE_ENABLEfalse验证解析日志中不再出现公式与表格识别阶段整体耗时明显下降。2.5 输出文件在哪看对目录现象-o指定的目录里找不到.md文件。原因输出按output/文件名/后端名/三级组织后端目录名是pipeline、vlm、hybrid等。处理ls output/demo1/hybrid/查看该后端的 markdown、content list 与 middle json各文件的含义见 docs/zh/reference/output_files.md。走 API 部署时客户端可加--client-side-output-generation true由客户端基于服务端返回的 middle JSON 本地生成 Markdown。验证能直接定位到目标.md文件。3. 能用但慢 / 费后端选型与显存降档3.1 先选对后端五个后端对比现象无 GPU 的机器上默认跑 hybrid-engine卡在模型加载或直接 OOM。处理按设备选后端精度为 OmniDocBench v1.6 端到端分数后端-b显存要求纯 CPU精度pipeline4GB✅86.47hybrid-engine默认8GB❌95.26(medium) / 95.39(high)vlm-engine8GB❌95.30hybrid-http-client2GB本地小模型需 pipeline 依赖✅95.26 / 95.39vlm-http-client2GB本地无需 torch✅95.30mineru -p doc.pdf -o output/ -b hybrid-engine --effort high # 精度优先 mineru -p doc.pdf -o output/ -b pipeline # 纯 CPU 兜底3.2 显存不够MINERU_HYBRID_BATCH_RATIO 降档现象hybrid 后端在小显存机器上报CUDA out of memory。处理按单机显存设小模型 batch 倍率单 client 显存MINERU_HYBRID_BATCH_RATIO≤ 6 GB8≤ 4 GB4≤ 3 GB2≤ 2 GB1export MINERU_HYBRID_BATCH_RATIO4 # 4GB 显存按上表降档验证同一文档重跑不 OOMnvidia-smi中显存峰值低于卡上限。3.3 大文档慢且吃内存降并发 分页解析处理export MINERU_PROCESSING_WINDOW_SIZE32 # 默认 64大文档内存吃紧时下调 export MINERU_API_MAX_CONCURRENT_REQUESTS1 # 默认 3API 侧并发 # 按 50 页一段拆开跑页码从 0 开始闭区间 mineru -p large.pdf -o out/ -s 0 -e 49 mineru -p large.pdf -o out/ -s 50 -e 99验证进程内存峰值下降分段任务全部产出对应页面结果。3.4 长期提速vllm / lmdeploy 服务端 http-client现象engine 后端单文档耗时长想要推理框架级加速。处理# 终端 1启动 OpenAI 兼容服务需先安装 vllm 或 lmdeploy mineru-openai-server --engine vllm --port 30000 # 引擎报错 Neither vLLM nor LMDeploy is installed 时pip install -U mineru[vllm] # 终端 2轻量 client 直连本地不需要 torch mineru -p doc.pdf -o out/ -b vlm-http-client -u http://127.0.0.1:30000多卡场景用CUDA_VISIBLE_DEVICES0/1给不同服务绑卡或直接用第 4 章的 router。验证client 端日志显示请求已转发单页解析耗时显著低于本地 engine。3.5 Windows 上推理慢确认 torch 不是 CPU 版现象装了 NVIDIA 显卡但速度接近纯 CPU。原因pip 默认装的 torch 是 CPU 版CUDA 依赖没配对。处理到 PyTorch 官网选择与本机 CUDA 版本匹配的安装命令重装torch与torchvisionRTX 50 系Blackwell建议装 lmdeploy 0.11.1 cu128 的 Windows wheel。验证python -c import torch; print(torch.cuda.is_available())输出True。4. 部署出去mineru-api、mineru-gradio、mineru-router4.1 mineru-apiFastAPI 服务与两个必知行为现象客户端直连服务后GET /tasks/{task_id}/result突然返回404。原因任务完成后默认只保留 24 小时MINERU_API_TASK_RETENTION_SECONDS86400过期自动清理服务重启后历史任务状态也不保证可查。处理# 生产启动VLM 预热避免首个 vlm/hybrid 请求卡在模型初始化 mineru-api --host 0.0.0.0 --port 8000 --enable-vlm-preload true # 调整输出根目录与任务保留时长 export MINERU_API_OUTPUT_ROOT/data/mineru/output export MINERU_API_TASK_RETENTION_SECONDS259200 # 保留 3 天常用接口GET /health健康检查、POST /tasks异步、POST /file_parse同步、GET /tasks/{id}/result结果。验证curl http://127.0.0.1:8000/health返回protocol_version与max_concurrent_requests字段。服务入口源码在 mineru/cli/fast_api.py。4.2 mineru-gradioWebUI 与页数上限处理mineru-gradio --server-name 0.0.0.0 --server-port 7860 \ --max-convert-pages 50 \ # 限制单文件最大解析页数 --enable-api true # 对外开放 Gradio API坑位未传--api-url时 Gradio 会自动拉起本地mineru-api首次启动含模型加载若等待超过 300 秒MINERU_LOCAL_API_STARTUP_TIMEOUT_SECONDS默认值会判定启动失败模型大时先把该值调大。验证浏览器访问http://127.0.0.1:7860上传 demo/pdfs/demo1.pdf 能出结果。4.3 mineru-router多 GPU 与多服务统一入口现象多张卡或多台服务机希望一个入口调度全部。处理# 自动拉起本地全部 GPU 的 worker CUDA_VISIBLE_DEVICES0,1,2,3 mineru-router --host 0.0.0.0 --port 8002 --local-gpus auto # 聚合已有服务--upstream-url 可重复传入多个地址 mineru-router --host 0.0.0.0 --port 8002 \ --upstream-url http://127.0.0.1:8000 --upstream-url http://10.0.0.2:8000router 对外接口与mineru-api完全一致/health、/tasks、/file_parse等客户端无需改代码。验证curl http://127.0.0.1:8002/health返回聚合后的并发窗口信息。5. 报错速查12 个高频报错定位表报错原文 / 表现定位方向处理版本 / 参数 / 配置三选一Requires-Python 3.10,3.14版本换 Python 3.10–3.13Windows 最高 3.12ImportError: libGL.so.1环境sudo apt-get install libgl1-mesa-glx渲染结果缺中文字环境sudo apt install fonts-noto-cjk后fc-cache -fvhuggingface 下载超时网络export MINERU_MODEL_SOURCEmodelscopeNeither vLLM nor LMDeploy is installed依赖pip install -U mineru[vllm]torch.cuda.is_available()为False依赖重装 CUDA 版 torch 与 torchvisionCUDA out of memory显存export MINERU_HYBRID_BATCH_RATIO4起降档Address already in use参数mineru-api --port 8001、gradio--server-port 7861查任务结果返回404配置任务已过 24h 保留期重提或调大MINERU_API_TASK_RETENTION_SECONDS首个 VLM 请求异常缓慢配置--enable-vlm-preload true预热CLI 拉起本地服务阶段超时配置调大MINERU_LOCAL_API_STARTUP_TIMEOUT_SECONDS默认 300 秒Windows Python 3.13 装不上版本降级 Python 3.126. 提问题前的自查清单与排查流程6.1 四组自检项环境Python 在 3.10–3.13 区间Windows ≤ 3.12python -c import cv2无报错libGL 已解决fc-list | grep -i noto能看到 CJK 字体Linux 为 2019 年及以后发行版macOS 14.0 以上参数-b与设备匹配纯 CPU 用pipeline或*-http-client显存档位与MINERU_HYBRID_BATCH_RATIO对应大文档已用-s/-e分页未对 vlm-engine 后端误传-l该参数仅 pipeline 与 hybrid 系生效网络MINERU_MODEL_SOURCE已设置且能访问对应源走本地模型时mineru.json的models-dir路径真实存在版本mineru -v为最新稳定版当前 3.4.4用 Docker 的用户确认拉的是新镜像而非本地旧缓存6.2 排查决策流程收尾仍未解决时走三条路径在项目 Issues 搜同类问题无结果就带最小复现样本提 Bug附完整报错与mineru -v版本号也可以先用mineru -p demo/pdfs/demo1.pdf -o output/确认本机基线是否可用把结论写进 Issue或者加入官方社区Discord / 微信群直接和开发者对。【免费下载链接】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），仅供参考