企业官网建设流程全解析

MinerU 故障排查速查：15 个高频报错与修复命令

【免费下载链接】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 时遇到的报错，绝大多数集中在四件事：import 就挂、模型下载卡死、解析结果缺字乱码、显存 OOM。这是一份 MinerU 故障排查速查表，按"装不上 → 跑不通 → 效果差 → 服务起不来"的链路组织，每个问题都按"现象 → 根因 → 修复命令 → 验证方式"展开，命令可直接复制执行。

安装与导入阶段：import 报错与装不上

WSL2 Ubuntu 下 libGL.so.1 缺失的一条修复命令

现象：执行mineru --version或python -c "import mineru"时抛出ImportError: libGL.so.1: cannot open shared object file。根因：opencv 依赖系统级 OpenGL 库，WSL2 的 Ubuntu 默认不带。修复：

sudo apt-get update sudo apt-get install -y libgl1-mesa-glx

验证：python -c "import cv2; print(cv2.__version__)"能打印版本号即修复成功。

Python 版本不在支持区间导致安装失败

现象：安装报requires-python相关错误，或装完运行报奇怪的语法/依赖异常。根因：MinerU 的requires-python区间是>=3.10,<3.14，超出区间的 Python 一律不兼容。

推荐用uv建一个干净环境：

uv venv --python 3.11 .venv source .venv/bin/activate uv pip install "mineru[core]"

验证：python --version && mineru --version两条命令都能正常输出。

Windows 直接安装后推理速度慢一个数量级

现象：同一份 PDF 在 Windows 上跑得明显比 Linux 慢，进度条几乎不动。根因：pip 默认装的是 CPU 版 torch，CUDA 加速没启用。修复：用与显卡 CUDA 版本匹配的 index 重装 torch（以 cu124 为例）：

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124

验证：python -c "import torch; print(torch.cuda.is_available())"输出True说明 GPU 已接管。

模型下载与源切换失败

HuggingFace 下载超时，一条环境变量切到 ModelScope

现象：首次运行卡在模型下载，报连接超时或huggingface_hub相关网络错误。根因：默认模型源是 HuggingFace，国内网络环境无法直连。修复：

export MINERU_MODEL_SOURCE=modelscope mineru -p demo/pdfs/demo1.pdf -o output/

验证：下载进度条走 ModelScope 镜像；完成后cat ~/mineru.json | grep model-source会写回modelscope。

离线内网机器的本地模型用法

现象：服务器没有外网，模型下载必然失败。根因：模型首次使用时才从远端拉取，离线机器必须走本地源。做法是在有网机器上执行mineru-models-download，把模型目录和用户目录下的mineru.json一起拷到离线机器的相同相对位置，然后：

export MINERU_MODEL_SOURCE=local mineru -p input.pdf -o output/

验证：启动日志里不再出现下载进度条；ls -lh确认模型目录文件齐全。

磁盘空间不足时改模型存储路径

现象：系统盘写满，模型下载中断。根因：模型默认落在用户目录。修复：在~/mineru.json中指定models-dir：

{ "models-dir": { "pipeline": "/data/models/pipeline", "vlm": "/data/models/vlm" } }

验证：重新下载后du -sh /data/models/*显示新目录下有实际文件。

解析结果缺字、乱码的修复

Linux 解析结果缺失 CJK 文字

现象：PDF 里一部分中文在 Markdown 输出里变成空白。根因：2.0 起 MinerU 用pypdfium2渲染 PDF 页面，某些 Linux 发行版缺 CJK 字体，渲染阶段直接丢字。修复：

sudo apt update sudo apt install -y fonts-noto-core fonts-noto-cjk fc-cache -fv

验证：fc-list :lang=zh | head能看到 Noto Sans CJK 条目；重跑解析后对比full.md的字数。

OCR 乱码：-l 语言参数选错

现象：英文被识别成乱码，或中文段落夹杂大量错字。根因：-l参数与文档实际语言不匹配，pipeline 后端会用错 OCR 词表。

修复：

mineru -p demo/pdfs/demo1.pdf -o output/ -b pipeline -l ch

验证：抽查output/下full.md中的中文段落，无错字即参数选对。

大文档渲染超时与内存溢出

现象：几百页的 PDF 跑到一半报渲染超时，或进程被系统直接 kill。根因：默认渲染超时 300 秒、处理窗口 64 页，大文档内存峰值容易击穿。修复：

export MINERU_PDF_RENDER_TIMEOUT=600 export MINERU_PROCESSING_WINDOW_SIZE=16

仍不够就分页跑：

mineru -p large.pdf -o output/ -s 0 -e 49 mineru -p large.pdf -o output/ -s 50 -e 99

验证：dmesg | tail没有 OOM kill 记录，且第二段页码能完整跑完。

后端选择与显存 OOM

MinerU 的解析链路分为预处理、模型层、管线层、输出层与质检层，后端不同，各层的执行方式差异很大：

后端选型决策表：先按机器配置对号入座

现象：不确定-b该填什么，在纯 CPU 机器上硬跑vlm-engine慢到怀疑人生。根因：各后端对算力和环境的要求完全不同，选错直接性能崩塌。

推荐：本地显存 ≥8G 直接用vlm-engine；纯 CPU 机器用pipeline；边缘设备一律vlm-http-client。验证：mineru --help | grep backend查看当前环境可选后端。

8G 显存跑 vllm 就 OOM 的参数压法

现象：vlm-engine或mineru-openai-server启动即torch.cuda.OutOfMemoryError。根因：vllm 默认按较高比例预分配显存。所有 vllm / lmdeploy 官方参数都可透传，直接压低预分配比例：

mineru-openai-server --engine vllm --gpu-memory-utilization 0.75 --port 30000

验证：nvidia-smi观察 vllm 初始显存占用，留有余量后重跑不再 OOM。

hybrid-http-client 的客户端显存档位

现象：hybrid-http-client模式下本地小模型吃满客户端显存。根因：本地 batch 倍率没有按机器显存调。对照表：

修复：

export MINERU_HYBRID_BATCH_RATIO=4 mineru -p input.pdf -o output/ -b hybrid-http-client -u http://127.0.0.1:30000

验证：解析过程中nvidia-smi显存峰值落在预算内。

mineru-api 与 Gradio 服务起不来

API 服务健康检查失败

现象：mineru-api启动后，客户端连接超时，GET /health无响应。根因：端口被占，或首次启动加载模型超过默认 300 秒的本地健康等待。修复：

mineru-api --host 0.0.0.0 --port 8000

若首启模型加载慢，调大等待上限：

export MINERU_LOCAL_API_STARTUP_TIMEOUT_SECONDS=600

验证：

curl http://127.0.0.1:8000/health

返回包含protocol_version、processing_window_size字段的 JSON 即服务正常。

Gradio WebUI 大文件上传后无响应

现象：WebUI 上传成功但长时间不出结果，大文件直接报错。根因：默认--max-convert-pages限制了可转换页数。修复：

mineru-gradio --server-name 0.0.0.0 --server-port 7860 --max-convert-pages 100

验证：浏览器打开http://127.0.0.1:7860，上传demo/pdfs/demo1.pdf能产出 Markdown。

同一台机器起多个 vllm 服务互相挤爆显存

现象：第二实例 vllm 服务起不来，日志显示显存不足。根因：vllm 预分配特性导致同一张卡上的多个服务互相抢显存。修复：按卡隔离，每卡一个服务：

CUDA_VISIBLE_DEVICES=0 mineru-openai-server --engine vllm --port 30000 CUDA_VISIBLE_DEVICES=1 mineru-openai-server --engine vllm --port 30001

验证：nvidia-smi显示两个进程分别独占一张卡。

收尾：自检清单与排查决策树

动手前先过一遍这个清单，80% 的问题在第五步之前就能定位：

1. python --version落在 3.10 ~ 3.13
2. python -c "import cv2"无 libGL 报错
3. echo $MINERU_MODEL_SOURCE与当前网络环境匹配
4. fc-list :lang=zh | head有 CJK 字体
5. nvidia-smi显存与驱动版本符合后端要求
6. curl http://127.0.0.1:8000/health服务健康

遇到新报错时，沿这张 MinerU 常见问题排查决策树走，先查哪一层不通再查下一层：

更多参数细节可查仓库内docs/zh/faq/index.md与docs/zh/usage/cli_tools.md，里面列全了每个环境变量和 CLI 参数的默认值。

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU