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 问题排查中最典型的两类报错。本文按装、跑、提速、兜底四个阶段组织照着往下执行可以覆盖绝大多数常见故障。症状所在小节预计耗时ImportError: libGL.so.1第一幕 · libGL 缺失2 分钟Failed building wheel for simsimd第一幕 · 老 Linux 编译失败10 分钟解析结果缺中文第一幕 · CJK 字体缺失5 分钟Python 版本不被接受第一幕 · 版本矩阵5 分钟模型下载卡住或失败第一幕 · 模型源切换5 分钟首次解析不知用哪个后端第二幕 · 后端选择10 分钟显存不足、CUDA OOM第二幕 · 显存档位5 分钟公式分隔符/表格碎片化第二幕 · 公式与表格5 分钟非中文文档识别差第二幕 · 语言参数5 分钟批量解析太慢第三幕 · 加速服务10 分钟API / WebUI 起不来第三幕 · 服务部署10 分钟大文档内存溢出第三幕 · 分批处理5 分钟报错编号看不懂第四幕 · 错误速查10 分钟第一幕 装得起来先把环境做干净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 libgl1Ubuntu 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 :langzh能列出 Noto CJK 条目重跑同一份 PDF中文段落恢复。Python 版本支持矩阵Python 版本支持状态备注3.10 ~ 3.12✅ 完全支持requires-python 3.10,3.14推荐 3.113.13✅ 支持需配合最新 3.4.x 3.10❌ 不支持安装阶段直接拒绝现象pip install mineru报requires a different Python: 3.9.x。原因解释器版本低于包声明的下界。处理conda create -n mineru python3.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_SOURCEmodelscope取值只有huggingface、modelscope、local三种环境变量优先于配置文件。想用已下好的模型目录时编辑用户目录下mineru.json{ models-dir: { pipeline: /data/models/pipeline, vlm: /data/models/vlm }, model-source: modelscope }再配合export MINERU_MODEL_SOURCElocal指向本地目录。验证mineru-models-download正常跑完并落盘模型文件第二次启动不再触发下载。第二幕 跑得通首次解析与参数调优首次解析该用哪个后端后端-b取值适用场景状态pipelineCPU 可用、通用文档、最省资源✅ 首选起步vlm-engine本地 GPU、追求高精度的端到端 VLM⚠️ 显存要求高hybrid-engine默认后端大小模型混合兼顾速度与精度✅ 默认vlm-http-client/hybrid-http-client算力在远端连 OpenAI 兼容服务✅ 生产推荐处理第一次跑用最轻的 pipeline先确认链路通mineru -p input.pdf -o output/ -b pipeline验证output/input/pipeline/下生成同名.md文件与 middle json 文件images/目录有切图。产出结构可对照仓库docs目录里的 output_files 说明。显存不足怎么调参数单客户端显存MINERU_HYBRID_BATCH_RATIO建议值≤ 6 GB8≤ 4 GB4≤ 3 GB2≤ 2 GB1现象日志出现 CUDA out of memory任务中途被杀。原因hybrid/vlm 后端的小模型 batch 倍率默认偏大占用显存。处理CUDA_VISIBLE_DEVICES0 MINERU_HYBRID_BATCH_RATIO4 mineru -p input.pdf -o output/ -b hybrid-engineCUDA_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 中定界符与配置一致跨页表格合并为一块。多语言文档参数怎么选文档语言-l取值状态中英混合ch默认✅日文 / 繁中ch_server✅韩文korean✅泰文th✅希腊文el✅阿拉伯文arabic✅俄文 / 东斯拉夫cyrillic/east_slavic✅印地文天城文devanagari✅现象非中文文档识别率低、乱码多。原因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_DEVICES1选卡。远端需要鉴权时用环境变量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_SECONDS600WebUI 侧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_SIZE16 export MINERU_API_MAX_CONCURRENT_REQUESTS1验证任务按批全部到达终态内存曲线不再持续爬升。第四幕 还报错速查、日志与求助错误编号速查表Issue 编号现象修复方式#3232区块覆盖导致解析异常升级到最新版当前 3.4.4#3175旋转文档可视化漂移升级到最新版#2771公式识别步骤显存消耗过大升级到最新版#3005文本块内容丢失升级到最新版#2968加速服务客户端依赖报错升级并重装依赖验证升级后确认版本mineru --version输出应为 3.4.4。老版本上的临时绕过手段不要带进生产直接升级。如何开启调试日志现象报错只有一行无法定位阶段。原因默认日志级别是 INFO细节被吞掉。处理export MINERU_LOG_LEVELDEBUG重跑失败命令保留完整日志文件。级别取值与标准 logging 一致DEBUG最详细。验证日志中出现逐阶段的处理记录渲染、检测、OCR 分步输出能指出具体卡在哪一步。提交 Issue 前需要准备哪些信息现象问题复现不了来回追问浪费时间。原因缺最小上下文维护者无法复现。处理按清单备齐再提交——mineru --version输出、操作系统与 GPU 型号完整命令行含环境变量与完整 DEBUG 日志最小可复现 PDF或注明页码区间期望输出与diff后的实际输出片段首次出现该问题的版本号如可查验证维护者拿到信息后能一次性复现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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考