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 一律不兼容。Python 版本支持状态备注3.10 ~ 3.13✅推荐直接用3.9 及以下❌不支持需升级3.14 及以上❌超出requires-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 版 torchCUDA 加速没启用。修复用与显卡 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_SOURCEmodelscope mineru -p demo/pdfs/demo1.pdf -o output/验证下载进度条走 ModelScope 镜像完成后cat ~/mineru.json | grep model-source会写回modelscope。离线内网机器的本地模型用法现象服务器没有外网模型下载必然失败。根因模型首次使用时才从远端拉取离线机器必须走本地源。做法是在有网机器上执行mineru-models-download把模型目录和用户目录下的mineru.json一起拷到离线机器的相同相对位置然后export MINERU_MODEL_SOURCElocal 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 :langzh | head能看到 Noto Sans CJK 条目重跑解析后对比full.md的字数。OCR 乱码-l 语言参数选错现象英文被识别成乱码或中文段落夹杂大量错字。根因-l参数与文档实际语言不匹配pipeline 后端会用错 OCR 词表。文档场景推荐参数说明中英混合-l ch适配最好纯英文 / 日繁混合-l ch_server服务端模型准确率更高纯文本 PDF-m txt跳过 OCR 直接取内嵌文本最快修复mineru -p demo/pdfs/demo1.pdf -o output/ -b pipeline -l ch验证抽查output/下full.md中的中文段落无错字即参数选对。大文档渲染超时与内存溢出现象几百页的 PDF 跑到一半报渲染超时或进程被系统直接 kill。根因默认渲染超时 300 秒、处理窗口 64 页大文档内存峰值容易击穿。修复export MINERU_PDF_RENDER_TIMEOUT600 export MINERU_PROCESSING_WINDOW_SIZE16仍不够就分页跑mineru -p large.pdf -o output/ -s 0 -e 49 mineru -p large.pdf -o output/ -s 50 -e 99验证dmesg | tail没有 OOM kill 记录且第二段页码能完整跑完。后端选择与显存 OOMMinerU 的解析链路分为预处理、模型层、管线层、输出层与质检层后端不同各层的执行方式差异很大后端选型决策表先按机器配置对号入座现象不确定-b该填什么在纯 CPU 机器上硬跑vlm-engine慢到怀疑人生。根因各后端对算力和环境的要求完全不同选错直接性能崩塌。后端环境要求适用场景pipelineCPU / GPU文本为主的文档速度快vlm-engine/hybrid-engine本地装 vllm 或 lmdeploy复杂版式、大表格、公式vlm-http-clientCPU 网络边缘机连远端服务无需 torchhybrid-http-clientCPU/GPU 网络远端 VLM 本地小模型推荐本地显存 ≥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 倍率没有按机器显存调。对照表客户端显存MINERU_HYBRID_BATCH_RATIO≤ 6 GB8≤ 4 GB4≤ 3 GB2≤ 2 GB1修复export MINERU_HYBRID_BATCH_RATIO4 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_SECONDS600验证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_DEVICES0 mineru-openai-server --engine vllm --port 30000 CUDA_VISIBLE_DEVICES1 mineru-openai-server --engine vllm --port 30001验证nvidia-smi显示两个进程分别独占一张卡。收尾自检清单与排查决策树动手前先过一遍这个清单80% 的问题在第五步之前就能定位python --version落在 3.10 ~ 3.13python -c import cv2无 libGL 报错echo $MINERU_MODEL_SOURCE与当前网络环境匹配fc-list :langzh | head有 CJK 字体nvidia-smi显存与驱动版本符合后端要求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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MinerU 故障排查速查：15 个高频报错与修复命令
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 一律不兼容。Python 版本支持状态备注3.10 ~ 3.13✅推荐直接用3.9 及以下❌不支持需升级3.14 及以上❌超出requires-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 版 torchCUDA 加速没启用。修复用与显卡 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_SOURCEmodelscope mineru -p demo/pdfs/demo1.pdf -o output/验证下载进度条走 ModelScope 镜像完成后cat ~/mineru.json | grep model-source会写回modelscope。离线内网机器的本地模型用法现象服务器没有外网模型下载必然失败。根因模型首次使用时才从远端拉取离线机器必须走本地源。做法是在有网机器上执行mineru-models-download把模型目录和用户目录下的mineru.json一起拷到离线机器的相同相对位置然后export MINERU_MODEL_SOURCElocal 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 :langzh | head能看到 Noto Sans CJK 条目重跑解析后对比full.md的字数。OCR 乱码-l 语言参数选错现象英文被识别成乱码或中文段落夹杂大量错字。根因-l参数与文档实际语言不匹配pipeline 后端会用错 OCR 词表。文档场景推荐参数说明中英混合-l ch适配最好纯英文 / 日繁混合-l ch_server服务端模型准确率更高纯文本 PDF-m txt跳过 OCR 直接取内嵌文本最快修复mineru -p demo/pdfs/demo1.pdf -o output/ -b pipeline -l ch验证抽查output/下full.md中的中文段落无错字即参数选对。大文档渲染超时与内存溢出现象几百页的 PDF 跑到一半报渲染超时或进程被系统直接 kill。根因默认渲染超时 300 秒、处理窗口 64 页大文档内存峰值容易击穿。修复export MINERU_PDF_RENDER_TIMEOUT600 export MINERU_PROCESSING_WINDOW_SIZE16仍不够就分页跑mineru -p large.pdf -o output/ -s 0 -e 49 mineru -p large.pdf -o output/ -s 50 -e 99验证dmesg | tail没有 OOM kill 记录且第二段页码能完整跑完。后端选择与显存 OOMMinerU 的解析链路分为预处理、模型层、管线层、输出层与质检层后端不同各层的执行方式差异很大后端选型决策表先按机器配置对号入座现象不确定-b该填什么在纯 CPU 机器上硬跑vlm-engine慢到怀疑人生。根因各后端对算力和环境的要求完全不同选错直接性能崩塌。后端环境要求适用场景pipelineCPU / GPU文本为主的文档速度快vlm-engine/hybrid-engine本地装 vllm 或 lmdeploy复杂版式、大表格、公式vlm-http-clientCPU 网络边缘机连远端服务无需 torchhybrid-http-clientCPU/GPU 网络远端 VLM 本地小模型推荐本地显存 ≥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 倍率没有按机器显存调。对照表客户端显存MINERU_HYBRID_BATCH_RATIO≤ 6 GB8≤ 4 GB4≤ 3 GB2≤ 2 GB1修复export MINERU_HYBRID_BATCH_RATIO4 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_SECONDS600验证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_DEVICES0 mineru-openai-server --engine vllm --port 30000 CUDA_VISIBLE_DEVICES1 mineru-openai-server --engine vllm --port 30001验证nvidia-smi显示两个进程分别独占一张卡。收尾自检清单与排查决策树动手前先过一遍这个清单80% 的问题在第五步之前就能定位python --version落在 3.10 ~ 3.13python -c import cv2无 libGL 报错echo $MINERU_MODEL_SOURCE与当前网络环境匹配fc-list :langzh | head有 CJK 字体nvidia-smi显存与驱动版本符合后端要求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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考