MinerU 常见问题与报错排查从装不上到爆显存一次搞定 PDF 解析所有坑【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerUMinerU 是把 PDF、DOCX、PPTX、XLSX 解析成 Markdown/JSON 的开源文档解析工具喂给大模型之前用它做数据准备的人很多。装不上、模型下不动、解析丢字、显存不够用……遇到别慌这篇按你卡在哪一步组织照下面这条排查线对号入座就行。先定位你卡在哪一步你看到的现象跳到libGL.so.1: cannot open shared object file缺 libGL 怎么补旧 Linux 上Failed building wheel老系统装不上怎么办pip install成功但第一次跑就卡住不动模型下载卡住怎么办解析出来的 Markdown 里中文/特殊字符缺失解析结果丢中文怎么办公式变乱码、表格错位公式表格解析不准怎么办CUDA out of memory/ 显存不足8G 显存怎么设速度太慢又慢怎么提速想给别的系统调接口mineru-api 怎么起装不上 / 跑不起来缺 libGL.so.1 怎么补启动就报ImportError: libGL.so.1: cannot open shared object file多半是系统少了图形库依赖WSL2 里的 Ubuntu 尤其常见跟 MinerU 本身没关系。装一下就好sudo apt-get update sudo apt-get install libgl1-mesa-glx装完重新跑一遍一般就过了。如果还报libglib、libgthread之类的缺库同样思路sudo apt-get install libglib2.0-0逐个补。老 Linux 系统装不上怎么办CentOS 7、Ubuntu 18 这类老系统上pip install mineru容易卡在编译第三方依赖比如Failed building wheel。原因是发行版太老、GCC 和 glibc 跟不上。可以试试换 conda 建个 3.10 的新环境再装conda create -n mineru python3.11 -y或者直接上 Docker 部署镜像里依赖都是配好的最省事仓库里带了现成的 compose 文件可参考 Docker 部署说明。正常的安装只需要两行uv pip install -U mineru[all] mineru -p demo.pdf -o output/mineru[all]包含全部后端Windows / Linux / macOS 通用Python 需要 3.10–3.13。如果是想自己改源码可以克隆仓库后本地安装git clone https://gitcode.com/GitHub_Trending/mi/MinerU cd MinerU uv pip install -e .[all]另外 Windows 上装完如果推理慢得离谱多半是 CUDA 没生效、在拿 CPU 硬跑。按显卡架构装对应 CUDA 版本的 torch 即可具体见 官方 FAQ。模型下载卡住或很慢怎么办第一次运行会联网拉模型卡在这里是最常见的假死。两个方向换国内源。默认从 HuggingFace 下载访问不了就切到 ModelScopeexport MINERU_MODEL_SOURCEmodelscope换个磁盘位置或直接用本地模型。如果默认缓存盘空间不够或模型已经准备好了可以指定 models-dir{ models-dir: { pipeline: /data/models/pipeline, vlm: /data/models/vlm } }已有本地权重时设export MINERU_MODEL_SOURCElocal跳过下载。也可以提前用mineru-models-download命令把模型拉下来避免跑任务时卡在下载上。能跑但结果不对解析结果丢了中文怎么办Linux 上解析出来的 Markdown 里 CJK 字符整段缺失、页面上明明有字一般是渲染引擎缺中文字体——MinerU 用 pypdfium2 把 PDF 渲染成图片系统里没有对应字体就画不出来。Ubuntu/Debian 装 Noto 字体包再刷新缓存sudo apt update sudo apt install fonts-noto-core fonts-noto-cjk fc-cache -fvDocker 镜像里已含完整字体走容器部署可以绕开这个问题。公式表格解析不准怎么办先看两点确认公式和表格解析没被关掉CLI 里默认是开的如果你手动加过参数去掉-f false/-t false复杂表格财报那种跨页大表、手写文档传统流程后端吃力换成 VLM 系后端效果会明显更好mineru -p test.pdf -o output/ -b hybrid-engine --effort high--effort high会带上图表分析准确率更高但更慢日常文档用默认的medium就够了。多语言扫描件可以显式指定语言提升 OCR 准确率仅 pipeline 后端生效中英混合默认-l ch基本够用纯英文等场景按文档提示调整。又慢又爆显存显存不够怎么设报CUDA out of memory时先量一下自己的显存档位再给后端喂--vram参数数值代表预留的显存预算单位 GB设备建议说明纯 CPU-b pipelinepipeline 后端 CPU 可跑VLM 后端不行8G 显存--vram 6适合简单文档16G 显存--vram 12大多数文档24G 显存--vram 20复杂文档mineru -p input.pdf -o output/ --vram 8选后端的取舍一句话版图省事、没显卡 → pipeline要精度、有 8G 显卡 → vlm/hybrid 系已有推理服务器 → http-client 系客户端本地几乎不吃显存。又慢怎么提速按顺序试大文档分段跑-s/-e指定起止页从 0 开始单段挂了也能续mineru -p large.pdf -o output/ -s 0 -e 9 mineru -p large.pdf -o output/ -s 10 -e 19内存吃紧进程被 OOM kill就降低并发少开并行任务有推理服务器的话上 vllm/SGLang 部署服务端客户端走 http 后端吞吐差距很大mineru-vllm-server --port 30000 mineru -p input.pdf -o output/ -b vlm-http-client -u http://127.0.0.1:30000确认 CUDA 真的在跑nvidia-smi能看到显存占用别用 pipeline 后端硬扛大模型。想接进自己的系统mineru-api 怎么起MinerU 自带 FastAPI 服务起完就能被其他程序调用mineru-api --host 0.0.0.0 --port 8000浏览器打开http://127.0.0.1:8000/docs能看到交互式接口文档。CLI 侧可以直接指向这个服务不用本地再起解析环境mineru -p input.pdf -o output/ --api-url http://127.0.0.1:8000想给团队开个网页界面用 Gradio 版 WebUImineru-gradio默认起在本机 7860 端口。接入 Dify、Cherry Studio、n8n 这类工具做 RAG 时走 mineru-api 或 http-client 后端最顺服务器端常驻解析服务客户端只传文件本地无 GPU 也能跑完整精度显存要求约 2G。具体插件配置可看 使用指南 里的插件章节。通用排查心法遇到没列出来的问题按这个顺序走一遍基本能定位看日志export MINERU_LOG_LEVELDEBUG后重跑真正的报错多半藏在 INFO 看不到的层级里降并发、分段跑先证明单文件、单页能跑通再放大规模切模型源下载类问题先怀疑网络换MINERU_MODEL_SOURCEmodelscope排除升版本很多解析异常块覆盖、可视化漂移之类新版已修pip show mineru确认版本再决定多后端对比同一份 PDF 分别用-b pipeline和-b hybrid-engine各跑一次对比产出能分清是模型能力问题还是环境配置问题。还没解决怎么办先翻 官方 FAQ常见问题都沉淀在那里再到项目 Issue 区搜报错原文把版本号、完整 traceback、最小可复现的 PDF 样例都附上能复现的样例解决速度最快社区渠道Discord / 微信群也常有人踩过同款坑直接问通常比自己抠半天快。本文基于 MinerU 3.4.4 整理解析能力更新很快建议保持使用最新版以获得最佳效果。【免费下载链接】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），仅供参考