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 -p xxx.pdf -o output/，终端先吐出一行ImportError: libGL.so.1: cannot open shared object file；或者模型下载卡在进度条上，半小时纹丝不动。这是 MinerU 问题排查中最典型的两类报错。本文按"装、跑、提速、兜底"四个阶段组织，照着往下执行，可以覆盖绝大多数常见故障。

第一幕 装得起来：先把环境做干净

libGL 缺失如何修复

现象：任何入口命令都在导入阶段直接退出。

ImportError: libGL.so.1: cannot open shared object file: No such file or directory

原因：依赖链里的 OpenCV 需要系统 OpenGL 动态库，WSL2 和精简版 Ubuntu 默认不装。

处理：

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

Ubuntu 20.04 换用libgl1-mesa-glx包名。装的是运行库，不是源码重编译，所以 2 分钟内完成。

验证：重新执行原命令，不再抛ImportError，能正常进入模型加载阶段。

老 Linux 上 wheel 编译失败怎么办

现象：pip install mineru阶段报错：

ERROR: Failed building wheel for simsimd

原因：老 GCC/glibc 编不过新版 C 扩展。当前 3.4.x 版本已移除pipeline_old_linux兜底安装项，不再为 CentOS 7 这类系统提供降级编译路径。

处理：不要在编译上耗时间，直接走 Docker 部署，仓库已内置编排文件：

docker compose -f docker/compose.yaml up

验证：容器状态为 Up，端口监听正常，容器内字体与依赖完整。

解析结果缺 CJK 字符怎么办

现象：同一份 PDF，在 Windows 上中文完整，在 Linux 服务器输出的 Markdown 里整段中文丢失，且终端不报任何错误。

原因：PDF 文本渲染依赖系统字体，无桌面环境的服务器默认没有 CJK 字体包。

处理：

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

验证：fc-list :lang=zh能列出 Noto CJK 条目；重跑同一份 PDF，中文段落恢复。

Python 版本支持矩阵

现象：pip install mineru报requires a different Python: 3.9.x。

原因：解释器版本低于包声明的下界。

处理：

conda create -n mineru python=3.11 -y conda activate mineru pip install -U "mineru[core]"

core汇总了 vlm、pipeline、gradio 三组依赖，装一次即可。

验证：新环境内import mineru无报错，版本号为 3.4.4。

模型下载失败如何切换模型源

现象：启动后模型下载长时间停滞，或出现huggingface-hub网络超时类报错。

原因：默认源是 HuggingFace，国内网络不稳定。

处理：

export MINERU_MODEL_SOURCE=modelscope

取值只有huggingface、modelscope、local三种，环境变量优先于配置文件。想用已下好的模型目录时，编辑用户目录下mineru.json：

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

再配合export MINERU_MODEL_SOURCE=local指向本地目录。

验证：mineru-models-download正常跑完并落盘模型文件，第二次启动不再触发下载。

第二幕 跑得通：首次解析与参数调优

首次解析该用哪个后端

处理：第一次跑用最轻的 pipeline，先确认链路通：

mineru -p input.pdf -o output/ -b pipeline

验证：output/input/pipeline/下生成同名.md文件与 middle json 文件，images/目录有切图。产出结构可对照仓库docs目录里的 output_files 说明。

显存不足怎么调参数

现象：日志出现 CUDA out of memory，任务中途被杀。

原因：hybrid/vlm 后端的小模型 batch 倍率默认偏大，占用显存。

处理：

CUDA_VISIBLE_DEVICES=0 MINERU_HYBRID_BATCH_RATIO=4 mineru -p input.pdf -o output/ -b hybrid-engine

CUDA_VISIBLE_DEVICES指定可见卡，对 pipeline 与 vlm 后端都生效。仍紧张就加--image-analysis false关掉图表分析。

验证：日志无 OOM，任务跑完且产物齐全。

公式与表格输出不准怎么调

现象：Markdown 里公式定界符不符合渲染器要求；跨页大表被切成多个碎片。

原因：分隔符走的是配置默认值；表格合并由独立开关控制，关掉就会碎。

处理：-f false、-t false可整体关公式/表格（默认都是开）。改分隔符就编辑配置文件的latex-delimiter-config，结构为display与inline两组：

{ "latex-delimiter-config": { "display": {"left": "$$", "right": "$$"}, "inline": {"left": "$", "right": "$"} } }

跨页合并受环境变量MINERU_TABLE_MERGE_ENABLE控制，默认true，别误关。

验证：重新生成后 md 中定界符与配置一致，跨页表格合并为一块。

多语言文档参数怎么选

现象：非中文文档识别率低、乱码多。

原因：pipeline 后端按语言选 OCR 模型，默认按中文优化。

处理：已知语种就显式传参，例如mineru -p doc.pdf -o output/ -b pipeline -l korean。注意-l只对 pipeline 后端生效，vlm 后端不需要。

验证：对比前后两版 md，目标语种段落完整率明显提升。

第三幕 跑得快、管得住：加速与服务化

如何部署加速推理服务

现象：单条命令串行解析，吞吐量上不去。

原因：默认本地引擎逐任务加载，没有常驻服务复用显存。

处理：先起一个常驻的 OpenAI 兼容服务：

mineru-openai-server --engine vllm --port 30000

客户端切换为 http-client 后端连过去：

mineru -p input.pdf -o output/ -b vlm-http-client -u http://127.0.0.1:30000

多卡时在每条命令前加CUDA_VISIBLE_DEVICES=1选卡。远端需要鉴权时用环境变量MINERU_VL_API_KEY，同服务挂多个模型时用MINERU_VL_MODEL_NAME指定。

验证：客户端日志无 401/404，任务在服务端可查询到终态。

mineru-api 与 mineru-gradio 起不来怎么办

现象：mineru-api启动后从别的机器连不上；CLI 报"等待本地临时 API 进入健康状态超时"；Gradio 页面打不开。

原因：三个高频坑——默认--host是127.0.0.1，外部访问不了；端口被占用；模型预载慢导致启动健康检查超时（默认 300 秒）。

处理：

mineru-api --host 0.0.0.0 --port 8000

预载慢就拉长超时：

export MINERU_LOCAL_API_STARTUP_TIMEOUT_SECONDS=600

WebUI 侧：

mineru-gradio --server-name 0.0.0.0 --server-port 7860 --enable-api true --max-convert-pages 50

验证：浏览器打开http://127.0.0.1:8000/docs出现 Swagger 页面；7860 端口出现 Gradio 界面并能提交任务。

大文档内存溢出如何分批处理

现象：几百页 PDF 跑到中途进程被 kill，或 API 侧内存飙升。

原因：中间结果驻留内存，窗口大小默认 64 页、API 默认并发 3，大文档容易顶穿。

处理：按页码分批，页码从 0 开始：

mineru -p large_doc.pdf -o output/ -s 0 -e 9 mineru -p large_doc.pdf -o output/ -s 10 -e 19

服务侧压低占用：

export MINERU_PROCESSING_WINDOW_SIZE=16 export MINERU_API_MAX_CONCURRENT_REQUESTS=1

验证：任务按批全部到达终态，内存曲线不再持续爬升。

第四幕 还报错：速查、日志与求助

错误编号速查表

验证：升级后确认版本：

mineru --version

输出应为 3.4.4。老版本上的临时绕过手段不要带进生产，直接升级。

如何开启调试日志

现象：报错只有一行，无法定位阶段。

原因：默认日志级别是 INFO，细节被吞掉。

处理：

export MINERU_LOG_LEVEL=DEBUG

重跑失败命令，保留完整日志文件。级别取值与标准 logging 一致，DEBUG最详细。

验证：日志中出现逐阶段的处理记录（渲染、检测、OCR 分步输出），能指出具体卡在哪一步。

提交 Issue 前需要准备哪些信息

现象：问题复现不了，来回追问浪费时间。

原因：缺最小上下文，维护者无法复现。

处理：按清单备齐再提交——

1. mineru --version输出、操作系统与 GPU 型号
2. 完整命令行（含环境变量）与完整 DEBUG 日志
3. 最小可复现 PDF，或注明页码区间
4. 期望输出与diff后的实际输出片段
5. 首次出现该问题的版本号（如可查）

验证：维护者拿到信息后能一次性复现，Issue 不被退回补充材料。

问题仍未解决时，先拿libGL、OOM、modelscope这类关键词去项目 Issue 库搜同类记录，九成情况已有定论；搜不到再按上面的清单提交新 Issue。环境类报错拿不准时，对照docker/compose.yaml里官方镜像的完整依赖组合做基准，比逐包排查更快。以最新版本的官方文档为准。

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