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.13；Windows 因依赖 ray，最高到 3.12。

处理：

conda create -n mineru python=3.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 directory，WSL2 的 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_SOURCE=modelscope mineru -p demo/pdfs/demo1.pdf -o output/ # 方式二：预先下载模型到本地 mineru-models-download # 交互式选择，路径自动写入用户目录 mineru.json export MINERU_MODEL_SOURCE=local # 方式三：在用户目录 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

hybrid 与 vlm 后端由 VLM 自行判断语言，不需要-l。

2.4 表格或公式用不上：-t / -f 关闭省时

现象：文档里没有公式和表格，却仍要等 MFR、表格结构识别跑完。

处理：

mineru -p plain.pdf -o output/ -f false -t false # 关闭公式与表格解析 # 等价环境变量：MINERU_FORMULA_ENABLE=false、MINERU_TABLE_ENABLE=false

验证：解析日志中不再出现公式与表格识别阶段，整体耗时明显下降。

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 端到端分数）：

mineru -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 倍率：

export MINERU_HYBRID_BATCH_RATIO=4 # 4GB 显存按上表降档

验证：同一文档重跑不 OOM；nvidia-smi中显存峰值低于卡上限。

3.3 大文档慢且吃内存：降并发 + 分页解析

处理：

export MINERU_PROCESSING_WINDOW_SIZE=32 # 默认 64，大文档内存吃紧时下调 export MINERU_API_MAX_CONCURRENT_REQUESTS=1 # 默认 3，API 侧并发 # 按 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_DEVICES=0/1给不同服务绑卡，或直接用第 4 章的 router。

验证：client 端日志显示请求已转发，单页解析耗时显著低于本地 engine。

3.5 Windows 上推理慢：确认 torch 不是 CPU 版

现象：装了 NVIDIA 显卡，但速度接近纯 CPU。

原因：pip 默认装的 torch 是 CPU 版，CUDA 依赖没配对。

处理：到 PyTorch 官网选择与本机 CUDA 版本匹配的安装命令重装torch与torchvision；RTX 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-router

4.1 mineru-api：FastAPI 服务与两个必知行为

现象：客户端直连服务后，GET /tasks/{task_id}/result突然返回404。

原因：任务完成后默认只保留 24 小时（MINERU_API_TASK_RETENTION_SECONDS=86400），过期自动清理；服务重启后历史任务状态也不保证可查。

处理：

# 生产启动：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_SECONDS=259200 # 保留 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-gradio：WebUI 与页数上限

处理：

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_DEVICES=0,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:8000

router 对外接口与mineru-api完全一致（/health、/tasks、/file_parse等），客户端无需改代码。

验证：curl http://127.0.0.1:8002/health返回聚合后的并发窗口信息。

5. 报错速查：12 个高频报错定位表

6. 提问题前的自查清单与排查流程

6.1 四组自检项

📌环境

• Python 在 3.10–3.13 区间（Windows ≤ 3.12）
• python -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