MinerU 排障实战从报错到跑通的完整路径【免费下载链接】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 input.pdf -o output/终端却弹出ImportError: libGL.so.1: cannot open shared object file或者解析出来的 Markdown 里中文缺了一大片。这篇文章是一份 MinerU 故障排查与问题解决指南先花两分钟排除最浅层的原因再按你亲眼看到的症状对号入座修最后只讲几个不改就踩坑的配置。两分钟自检动手排查前先过这 4 项每项都是一条命令的事排掉 80% 的低级问题再往下走版本与 Python运行mineru -v看版本MinerU 要求 Python 3.10–3.13版本旧先升级pip install -U mineru[all]。模型源变量运行echo $MINERU_MODEL_SOURCE。取值只允许huggingface/modelscope/local⚠️ 如果你手动设成了auto先unset掉。系统依赖Linux / WSL2 上运行ldconfig -p | grep libGL输出为空说明缺 libGL见下文启动即崩溃一节。磁盘空间df -h确认剩余空间模型加依赖约需 20GB。按症状分诊你看到什么就修什么下面按终端里实际出现的现象归类每个症状给出可能原因和可直接执行的修复命令。启动即崩溃ImportError: libGL.so.1 ...现象命令刚启动就崩日志停在 import opencv 附近。可能原因WSL2 的 Ubuntu 22.04 缺libgl系统库最常见精简版 Linux 镜像裁掉了图形库修复sudo apt-get update sudo apt-get install libgl1-mesa-glx解析结果缺字中文、日文凭空消失现象输出 Markdown 里部分 CJK 字符丢失版面看着对但内容不全。可能原因MinerU 2.0 起用pypdfium2做 PDF 渲染部分 Linux 发行版缺 CJK 字体渲染成图片时丢字你用的 PDF 本身字体未嵌入换用带完整文本层的 PDF 验证一次修复Ubuntu/Debiansudo apt update sudo apt install fonts-noto-core sudo apt install fonts-noto-cjk fc-cache -fv装完字体后重新解析同一份 PDF正常输出应能完整还原文字与版面结构效果类似这样首次运行模型下载卡住现象第一次运行长时间无进度或直接超时、连接失败。可能原因网络访问不到 HuggingFace未显式指定模型源自动探测反复重试修复# 切换到 ModelScope 源 export MINERU_MODEL_SOURCEmodelscope mineru -p input.pdf -o output/ # 或者一次性把模型下载到本地之后走本地加载 mineru-models-download export MINERU_MODEL_SOURCElocal 注意mineru-models-download执行时若已设置MINERU_MODEL_SOURCElocal它会自动临时忽略该值、改用远端源完成真实下载属于正常行为。显存溢出OOM / 进程被 kill现象解析中途进程被Killed或日志出现CUDA out of memory。可能原因vlm / hybrid-engine 后端显存最低要求 8GB你的卡不够大文档处理窗口过大内存峰值高多个进程同时抢同一张卡修复# 纯 CPU 场景切 pipeline 后端无需 GPU mineru -p input.pdf -o output/ -b pipeline # 或换一张显存更大的卡 CUDA_VISIBLE_DEVICES1 mineru -p input.pdf -o output/ # 降低内存峰值处理窗口默认 64可减半 export MINERU_PROCESSING_WINDOW_SIZE32Windows 上推理速度奇慢现象安装成功、能跑但速度接近纯 CPU。可能原因torch装的是 CPU 版CUDA 加速依赖缺失修复按你的显卡架构去 PyTorch 官网选择对应 CUDA 版本的 Windows 安装命令安装torchtorchvisionV100、20/30/40 系、T4 直接装带 CUDA 的版本即可RTX 50 系走lmdeploy 0.11.1 cu128的 wheel 方案。装完先验证python -c import torch; print(torch.__version__, torch.cuda.is_available())输出True才算成功。服务起不来mineru-api/ Gradio 无响应现象mineru-api报端口被占用或mineru命令自动拉起本地 API 时一直等到超时。可能原因8000 端口已被其他进程占用首次加载模型慢健康检查在默认 300 秒内没等到就绪修复# 换个端口再起 mineru-api --host 127.0.0.1 --port 8001 # Gradio WebUI 指定监听地址与端口 mineru-gradio --server-name 0.0.0.0 --server-port 7860 # 把本地 API 启动等待时间加长到 600 秒 export MINERU_LOCAL_API_STARTUP_TIMEOUT_SECONDS600配置精调改这几个变量多数环境问题就没了只讲三个真正影响日常体验的配置MINERU_MODEL_SOURCE模型从哪来、CUDA_VISIBLE_DEVICES用哪张卡、MINERU_HYBRID_BATCH_RATIO连远程推理服务时客户端占多少显存。MINERU_MODEL_SOURCE默认不设置时走自动探测先试 HuggingFace不通回落 ModelScope。内网服务器、离线环境一定要显式设成local否则每次启动都可能卡在网络探测上。CUDA_VISIBLE_DEVICES对mineru、mineru-api、mineru-gradio、mineru-router全部命令生效且对 pipeline 和 vlm 两种后端都适用是多卡环境下最直接的隔离手段。MINERU_HYBRID_BATCH_RATIO只影响hybrid-http-client客户端上的小模型 batch 倍率客户端显存越小设得越低。设备 / 场景推荐配置一句话说明国内网络、访问不了 HuggingFaceexport MINERU_MODEL_SOURCEmodelscope从 ModelScope 源下载并加载内网 / 离线服务器export MINERU_MODEL_SOURCElocal先用mineru-models-download下好模型多卡机器、指定用 1 号卡CUDA_VISIBLE_DEVICES1 mineru ...所有命令统一生效pipeline 和 vlm 都适用hybrid-http-client客户端显存 2–6GBMINERU_HYBRID_BATCH_RATIO取 1 / 2 / 4 / 8显存 ≤2GB 用 1≤6GB 最多用 8处理大文档、内存吃紧export MINERU_PROCESSING_WINDOW_SIZE32默认 64调小可降内存峰值性能与进阶后端怎么选、怎么加速默认hybrid-engine是精度与速度的平衡点追求最高精度用vlm-engine显存 8GB 起纯 CPU 只跑-b pipeline。生产环境推荐用 vLLM / SGLang / LMDeploy 起一个 OpenAI 兼容服务客户端用vlm-http-client加--url指向它多卡跑服务用mineru-router --local-gpus 0,1,2,3托管多个 worker。# 多卡路由托管 worker mineru-router --host 0.0.0.0 --port 8002 --local-gpus 0,1,2,3求助路径提 Issue 之前先准备好这些先查官方文档的 FAQ 页libGL、CJK 缺字、Windows CUDA 这三类高频问题都有现成答案。提交 Issue 时附三样东西mineru -v输出的版本号、完整报错日志、能复现问题的最小 PDF 样本。社区渠道项目官方 Discord 和微信群安装类问题先在群里问一轮通常更快。下一步动作挑一个最小 PDF 跑通mineru -p并保存全部日志然后直接按上面的清单提交 Issue。【免费下载链接】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），仅供参考