从报错到跑通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/MinerU如果你用 MinerU 把 PDF 解析成 Markdown 和 JSON 时卡住了——装不上、跑起来报ImportError、模型下载超时、解析结果缺字漏表、显存爆掉或是mineru-api部署后连不上——这篇 PDF解析问题排查指南就是为你准备的。核心思路只有一条先判断你卡在哪一步再对症处理最后学会把问题问清楚。第零步排查前自检版本与先查这三项先做版本核对能排掉一半伪故障。本文基于 MinerU 3.4.4 整理旧文章里那些 2.x 时代的参数如--vram、mineru-sglang-server、vlm-transformers后端在当前版本大多已不存在照抄只会越查越乱。mineru -v # 确认当前版本建议 pip install -U mineru 升级到最新 python --version # 要求 3.10 ~ 3.133.9 及以下无法安装 pip show torch # GPU 机器确认 torch 是否为 CUDA 版对照 docs/zh/ 里的官方文档核对以下清单全部打勾再往下走自检项合格标准不达标怎么办Python 版本3.10 ~ 3.13用 conda 新建 3.11 环境重装后端依赖解析 PDF 建议mineru[core]或按需装pipeline组件pip install -U mineru[core]模型源可达默认auto自动探测 HuggingFace不通则回退 ModelScopeexport MINERU_MODEL_SOURCEmodelscopeGPU 驱动nvidia-smi可见显卡且驱动匹配 CUDA装对应版本的 torch / 换 Docker 镜像第一步装不上、跑不起来安装与启动阶段故障MinerU 安装失败先查这三项现象pip install中途编译报错老系统上常见Failed building wheel或装完导入就崩。原因一是 Python 版本不在 3.10~3.13 区间二是老系统CentOS 7 等的编译器太旧装不上新版依赖。命令/配置干净环境里按顺序执行conda create -n mineru python3.11 -y conda activate mineru pip install -U mineru[core] python -c import mineru; print(ok)WSL2 报ImportError: libGL.so.1怎么办现象启动即崩报错libGL.so.1: cannot open shared object file。原因WSL2 的 Ubuntu 精简镜像缺 OpenCV 依赖的系统图形库不是 MinerU 本身的问题。命令/配置sudo apt-get update sudo apt-get install -y libgl1-mesa-glx模型下载超时、卡在 HuggingFace 怎么办现象首次解析或跑mineru-models-download时长时间无响应或直接连接失败。原因当前网络访问不了 HuggingFace。auto策略虽会自动探测并回退 ModelScope但探测过程本身可能很慢。命令/配置手动指定国内源一步到位export MINERU_MODEL_SOURCEmodelscope mineru-models-download下完模型后想离线使用比如部署到内网服务器把模型目录和~/.mineru.json一起拷过去再export MINERU_MODEL_SOURCElocal。Windows 能跑但慢得像在跑 CPU现象Linux 上几秒的文档Windows 上要几分钟GPU 利用率几乎为零。原因默认装的 torch 是 CPU 版CUDA 加速没生效。命令/配置去 PyTorch 官网按你的 CUDA 版本装 Windows 对应命令重装torchtorchvisionRTX 50 系Blackwell显卡则装lmdeploy 0.11.1 cu128的 Windows wheel详细步骤见 docs/zh/faq/。验证方式很简单解析一个短 PDF观察nvidia-smi里显存是否被占用。第二步能跑但结果不对解析质量与参数调优Linux 解析结果缺字先查 CJK 字体现象Linux 上中文 PDF 解析出来整段缺字Windows 上正常。原因MinerU 2.0 用pypdfium2渲染 PDF 页面而不少 Linux 发行版没装 CJK 字体渲染成图片时文字直接丢失。命令/配置sudo apt update sudo apt install fonts-noto-core fonts-noto-cjk fc-cache -fv图省事的话直接用官方 Docker 部署见 docs/zh/quick_start/镜像里已内置这些字体。MinerU 表格解析不准怎么调现象跨页表格被切成两段、复杂合并单元格识别错乱。原因默认后端对复杂版面的还原能力有限而表格开关与合并开关没按文档特点配置。命令/配置先确认两个默认开启的开关没被关掉——-t true表格解析与环境变量MINERU_TABLE_MERGE_ENABLE跨页表格合并默认true别误设成false。复杂表格建议换更强的后端再解析一遍对比mineru -p 财报.pdf -o out/ -b hybrid-engine -t true公式没转成 LaTeX只剩图片现象文档里的公式在 Markdown 里变成图片链接不是$...$代码。原因公式解析模块MFR默认开启但可能通过环境变量被禁用或扫描件模糊导致识别失败。命令/配置确认没被关掉export MINERU_FORMULA_ENABLEtrue # 默认 true排查时被设过 false 的话恢复它 mineru -p input.pdf -o out/ -f true多语言文档识别差怎么选后端现象日文、阿拉伯文等文档 OCR 错字率高。原因pipeline后端的--lang参数虽支持korean、thai、arabic等 12 种取值但 3.4 起 OCR 已统一收敛到ch模型PP-OCRv6其他语种的原生多语言识别在 hybrid / vlm 后端能力更强。命令/配置非中英文文档优先用mineru -p input.pdf -o out/ -b hybrid-engine后端怎么选一句话总结追求稳定无幻觉、CPU 也能跑用pipeline追求精度复杂表格、扫描件、多语言用hybrid-engine默认或vlm-engine。更多说明见 docs/zh/usage/。第三步太慢、爆显存性能与资源优化MinerU 显存不足OOM怎么调现象跑 hybrid / vlm 后端时直接 OOMvllm 起不来。原因vllm 系引擎要求 Volta 及以上架构显卡且显存 ≥8Ghybrid-http-client 客户端本地小模型占显存不受控。命令/配置# hybrid-http-client 按单卡显存降 batch 倍率默认 8 export MINERU_HYBRID_BATCH_RATIO4 # ≤6G 用 4≤3G 用 2≤2G 用 1 # 指定用哪张卡 CUDA_VISIBLE_DEVICES1 mineru -p input.pdf -o out/ -b hybrid-http-client -u http://127.0.0.1:30000大文档处理到一半内存爆了怎么办现象几百页 PDF 跑到一半进程被系统杀掉OOM Killer。原因处理窗口默认 64 页窗口越大吞吐越高、内存占用也越大。命令/配置两步走——先调小窗口再分批按页码切export MINERU_PROCESSING_WINDOW_SIZE32 mineru -p big.pdf -o out/ -s 0 -e 99 mineru -p big.pdf -o out/ -s 100 -e 199API 侧同理用MINERU_API_MAX_CONCURRENT_REQUESTS默认 3压低并发。MinerU 解析速度怎么优化现象同样的文档速度只有预期的零头。原因常见就三个——GPU 加速没生效、没走 vllm 加速、重复冷启动模型。命令/配置# vlm 后端走 vllm 引擎GPU 显存 ≥8G首次预热模型 CUDA_VISIBLE_DEVICES0 mineru-openai-server --engine vllm --port 30000 mineru -p input.pdf -o out/ -b vlm-http-client -u http://127.0.0.1:30000 # hybrid 后端精度换速度medium 档在多数平台提速 35%~220%默认即 medium mineru -p input.pdf -o out/ -b hybrid-engine --effort mediumAPI 常驻服务再加--enable-vlm-preload true把 VLM 模型在服务启动阶段就加载好避免第一个请求卡几分钟。第四步部署成服务后出问题API / WebUI / 加速服务mineru-api 起不来或接口 404现象服务显示启动成功浏览器却打不开文档页或任务查着查着 404。原因文档页被环境变量关了或者任务状态是进程内存态的服务一重启就丢且任务默认完成 24 小时后被自动清理。命令/配置mineru-api --host 0.0.0.0 --port 8000 --enable-vlm-preload true # 打开/关闭 API 文档页默认 true export MINERU_API_ENABLE_FASTAPI_DOCStrue # 任务需要更久才能查到调保留时长秒 export MINERU_API_TASK_RETENTION_SECONDS172800先访问http://127.0.0.1:8000/health它能返回protocol_version等信息说明服务本身是活的。Gradio WebUI 打不开、上传被拒怎么办现象http://127.0.0.1:7860打不开或上传大 PDF 被拦下。原因默认只监听本机远程机器访问不到上传页数超过默认上限。命令/配置mineru-gradio --server-name 0.0.0.0 --server-port 7860 \ --enable-http-client true --max-convert-pages 50其中--enable-http-client true是当你想连远端 OpenAI 兼容模型服务时才需要的。多卡多服务怎么统一入口现象单台机器多张卡想并行跑多个解析服务或已有多个mineru-api想合并成一个入口。原因mineru-api是单服务设计编排是mineru-router的职责。命令/配置# 自动识别本机 GPU 拉起 worker mineru-router --host 0.0.0.0 --port 8002 --local-gpus auto # 或聚合多个已存在的 api 服务 mineru-router --port 8002 --upstream-url http://127.0.0.1:8000 --upstream-url http://127.0.0.1:8001注意 vllm 会预占显存同一台机器上避免多个 vllm 服务互相抢卡。还不好排查把日志开细现象报错信息只有一行看不出根因。原因默认日志级别是INFO中间步骤都被吞了。命令/配置export MINERU_LOG_LEVELDEBUG这个变量对mineru、mineru-api、mineru-gradio等全部命令行工具生效排查完记得改回INFO。附录MinerU 常见报错速查对照表按报错关键词检索先对照这里再回上面对应章节看细节报错 / 现象大概率原因快速处理ImportError: libGL.so.1WSL2 缺图形库sudo apt-get install libgl1-mesa-glx解析结果缺中文文字Linux 缺 CJK 字体装fonts-noto-corefonts-noto-cjk后fc-cache -fv模型下载卡死 / 连接超时HuggingFace 不通export MINERU_MODEL_SOURCEmodelscopeOOM / 显存不足引擎显存需求超显卡MINERU_HYBRID_BATCH_RATIO降档vllm 需 ≥8G 显存Windows 上极慢torch 是 CPU 版按 CUDA 版本重装 Windows 版 torch公式只剩图片公式解析被关MINERU_FORMULA_ENABLEtrue、-f true表格跨页断裂合并开关被关确认MINERU_TABLE_MERGE_ENABLE为trueAPI 文档页 404docs 被关闭export MINERU_API_ENABLE_FASTAPI_DOCStrue任务状态查不到服务重启或超 24h 被清理调MINERU_API_TASK_RETENTION_SECONDS重启会丢历史任务老系统 pip 编译报错系统太旧conda 建 Python 3.11 环境后重装求助指南如何把问题问清楚再找人自己查不动要去社区提问Discord / 微信群入口见 docs/zh/时先自查一遍日志MINERU_LOG_LEVELDEBUG跑一遍把关键报错段留下来。一份合格的提问包含六要素版本mineru -v输出 Python 版本python --version命令原样贴出你执行的完整命令API Key 打码报错完整 traceback不要只截最后一行环境系统、显卡型号、显存大小、nvidia-smi驱动版本最小复现能复现的最短 PDF / 文档脱敏以及输入输出目录已尝试试过哪些方案分别得到什么结果信息越全别人帮你定位越快只贴一行报错的提问基本只能得到先升级最新版试试的回答。写在最后别慌MinerU 的问题九成是环境问题或参数没配对按先定位阶段 → 对症处理 → 留好日志求助这条路径走绝大多数报错都能自己解掉。本文基于 MinerU 3.4.4 整理旧版本的参数与后端名可能已变更动手前先pip install -U mineru升到最新版再看 docs/zh/ 官方文档核对。【免费下载链接】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 PDF解析常见问题排查完全指南
从报错到跑通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/MinerU如果你用 MinerU 把 PDF 解析成 Markdown 和 JSON 时卡住了——装不上、跑起来报ImportError、模型下载超时、解析结果缺字漏表、显存爆掉或是mineru-api部署后连不上——这篇 PDF解析问题排查指南就是为你准备的。核心思路只有一条先判断你卡在哪一步再对症处理最后学会把问题问清楚。第零步排查前自检版本与先查这三项先做版本核对能排掉一半伪故障。本文基于 MinerU 3.4.4 整理旧文章里那些 2.x 时代的参数如--vram、mineru-sglang-server、vlm-transformers后端在当前版本大多已不存在照抄只会越查越乱。mineru -v # 确认当前版本建议 pip install -U mineru 升级到最新 python --version # 要求 3.10 ~ 3.133.9 及以下无法安装 pip show torch # GPU 机器确认 torch 是否为 CUDA 版对照 docs/zh/ 里的官方文档核对以下清单全部打勾再往下走自检项合格标准不达标怎么办Python 版本3.10 ~ 3.13用 conda 新建 3.11 环境重装后端依赖解析 PDF 建议mineru[core]或按需装pipeline组件pip install -U mineru[core]模型源可达默认auto自动探测 HuggingFace不通则回退 ModelScopeexport MINERU_MODEL_SOURCEmodelscopeGPU 驱动nvidia-smi可见显卡且驱动匹配 CUDA装对应版本的 torch / 换 Docker 镜像第一步装不上、跑不起来安装与启动阶段故障MinerU 安装失败先查这三项现象pip install中途编译报错老系统上常见Failed building wheel或装完导入就崩。原因一是 Python 版本不在 3.10~3.13 区间二是老系统CentOS 7 等的编译器太旧装不上新版依赖。命令/配置干净环境里按顺序执行conda create -n mineru python3.11 -y conda activate mineru pip install -U mineru[core] python -c import mineru; print(ok)WSL2 报ImportError: libGL.so.1怎么办现象启动即崩报错libGL.so.1: cannot open shared object file。原因WSL2 的 Ubuntu 精简镜像缺 OpenCV 依赖的系统图形库不是 MinerU 本身的问题。命令/配置sudo apt-get update sudo apt-get install -y libgl1-mesa-glx模型下载超时、卡在 HuggingFace 怎么办现象首次解析或跑mineru-models-download时长时间无响应或直接连接失败。原因当前网络访问不了 HuggingFace。auto策略虽会自动探测并回退 ModelScope但探测过程本身可能很慢。命令/配置手动指定国内源一步到位export MINERU_MODEL_SOURCEmodelscope mineru-models-download下完模型后想离线使用比如部署到内网服务器把模型目录和~/.mineru.json一起拷过去再export MINERU_MODEL_SOURCElocal。Windows 能跑但慢得像在跑 CPU现象Linux 上几秒的文档Windows 上要几分钟GPU 利用率几乎为零。原因默认装的 torch 是 CPU 版CUDA 加速没生效。命令/配置去 PyTorch 官网按你的 CUDA 版本装 Windows 对应命令重装torchtorchvisionRTX 50 系Blackwell显卡则装lmdeploy 0.11.1 cu128的 Windows wheel详细步骤见 docs/zh/faq/。验证方式很简单解析一个短 PDF观察nvidia-smi里显存是否被占用。第二步能跑但结果不对解析质量与参数调优Linux 解析结果缺字先查 CJK 字体现象Linux 上中文 PDF 解析出来整段缺字Windows 上正常。原因MinerU 2.0 用pypdfium2渲染 PDF 页面而不少 Linux 发行版没装 CJK 字体渲染成图片时文字直接丢失。命令/配置sudo apt update sudo apt install fonts-noto-core fonts-noto-cjk fc-cache -fv图省事的话直接用官方 Docker 部署见 docs/zh/quick_start/镜像里已内置这些字体。MinerU 表格解析不准怎么调现象跨页表格被切成两段、复杂合并单元格识别错乱。原因默认后端对复杂版面的还原能力有限而表格开关与合并开关没按文档特点配置。命令/配置先确认两个默认开启的开关没被关掉——-t true表格解析与环境变量MINERU_TABLE_MERGE_ENABLE跨页表格合并默认true别误设成false。复杂表格建议换更强的后端再解析一遍对比mineru -p 财报.pdf -o out/ -b hybrid-engine -t true公式没转成 LaTeX只剩图片现象文档里的公式在 Markdown 里变成图片链接不是$...$代码。原因公式解析模块MFR默认开启但可能通过环境变量被禁用或扫描件模糊导致识别失败。命令/配置确认没被关掉export MINERU_FORMULA_ENABLEtrue # 默认 true排查时被设过 false 的话恢复它 mineru -p input.pdf -o out/ -f true多语言文档识别差怎么选后端现象日文、阿拉伯文等文档 OCR 错字率高。原因pipeline后端的--lang参数虽支持korean、thai、arabic等 12 种取值但 3.4 起 OCR 已统一收敛到ch模型PP-OCRv6其他语种的原生多语言识别在 hybrid / vlm 后端能力更强。命令/配置非中英文文档优先用mineru -p input.pdf -o out/ -b hybrid-engine后端怎么选一句话总结追求稳定无幻觉、CPU 也能跑用pipeline追求精度复杂表格、扫描件、多语言用hybrid-engine默认或vlm-engine。更多说明见 docs/zh/usage/。第三步太慢、爆显存性能与资源优化MinerU 显存不足OOM怎么调现象跑 hybrid / vlm 后端时直接 OOMvllm 起不来。原因vllm 系引擎要求 Volta 及以上架构显卡且显存 ≥8Ghybrid-http-client 客户端本地小模型占显存不受控。命令/配置# hybrid-http-client 按单卡显存降 batch 倍率默认 8 export MINERU_HYBRID_BATCH_RATIO4 # ≤6G 用 4≤3G 用 2≤2G 用 1 # 指定用哪张卡 CUDA_VISIBLE_DEVICES1 mineru -p input.pdf -o out/ -b hybrid-http-client -u http://127.0.0.1:30000大文档处理到一半内存爆了怎么办现象几百页 PDF 跑到一半进程被系统杀掉OOM Killer。原因处理窗口默认 64 页窗口越大吞吐越高、内存占用也越大。命令/配置两步走——先调小窗口再分批按页码切export MINERU_PROCESSING_WINDOW_SIZE32 mineru -p big.pdf -o out/ -s 0 -e 99 mineru -p big.pdf -o out/ -s 100 -e 199API 侧同理用MINERU_API_MAX_CONCURRENT_REQUESTS默认 3压低并发。MinerU 解析速度怎么优化现象同样的文档速度只有预期的零头。原因常见就三个——GPU 加速没生效、没走 vllm 加速、重复冷启动模型。命令/配置# vlm 后端走 vllm 引擎GPU 显存 ≥8G首次预热模型 CUDA_VISIBLE_DEVICES0 mineru-openai-server --engine vllm --port 30000 mineru -p input.pdf -o out/ -b vlm-http-client -u http://127.0.0.1:30000 # hybrid 后端精度换速度medium 档在多数平台提速 35%~220%默认即 medium mineru -p input.pdf -o out/ -b hybrid-engine --effort mediumAPI 常驻服务再加--enable-vlm-preload true把 VLM 模型在服务启动阶段就加载好避免第一个请求卡几分钟。第四步部署成服务后出问题API / WebUI / 加速服务mineru-api 起不来或接口 404现象服务显示启动成功浏览器却打不开文档页或任务查着查着 404。原因文档页被环境变量关了或者任务状态是进程内存态的服务一重启就丢且任务默认完成 24 小时后被自动清理。命令/配置mineru-api --host 0.0.0.0 --port 8000 --enable-vlm-preload true # 打开/关闭 API 文档页默认 true export MINERU_API_ENABLE_FASTAPI_DOCStrue # 任务需要更久才能查到调保留时长秒 export MINERU_API_TASK_RETENTION_SECONDS172800先访问http://127.0.0.1:8000/health它能返回protocol_version等信息说明服务本身是活的。Gradio WebUI 打不开、上传被拒怎么办现象http://127.0.0.1:7860打不开或上传大 PDF 被拦下。原因默认只监听本机远程机器访问不到上传页数超过默认上限。命令/配置mineru-gradio --server-name 0.0.0.0 --server-port 7860 \ --enable-http-client true --max-convert-pages 50其中--enable-http-client true是当你想连远端 OpenAI 兼容模型服务时才需要的。多卡多服务怎么统一入口现象单台机器多张卡想并行跑多个解析服务或已有多个mineru-api想合并成一个入口。原因mineru-api是单服务设计编排是mineru-router的职责。命令/配置# 自动识别本机 GPU 拉起 worker mineru-router --host 0.0.0.0 --port 8002 --local-gpus auto # 或聚合多个已存在的 api 服务 mineru-router --port 8002 --upstream-url http://127.0.0.1:8000 --upstream-url http://127.0.0.1:8001注意 vllm 会预占显存同一台机器上避免多个 vllm 服务互相抢卡。还不好排查把日志开细现象报错信息只有一行看不出根因。原因默认日志级别是INFO中间步骤都被吞了。命令/配置export MINERU_LOG_LEVELDEBUG这个变量对mineru、mineru-api、mineru-gradio等全部命令行工具生效排查完记得改回INFO。附录MinerU 常见报错速查对照表按报错关键词检索先对照这里再回上面对应章节看细节报错 / 现象大概率原因快速处理ImportError: libGL.so.1WSL2 缺图形库sudo apt-get install libgl1-mesa-glx解析结果缺中文文字Linux 缺 CJK 字体装fonts-noto-corefonts-noto-cjk后fc-cache -fv模型下载卡死 / 连接超时HuggingFace 不通export MINERU_MODEL_SOURCEmodelscopeOOM / 显存不足引擎显存需求超显卡MINERU_HYBRID_BATCH_RATIO降档vllm 需 ≥8G 显存Windows 上极慢torch 是 CPU 版按 CUDA 版本重装 Windows 版 torch公式只剩图片公式解析被关MINERU_FORMULA_ENABLEtrue、-f true表格跨页断裂合并开关被关确认MINERU_TABLE_MERGE_ENABLE为trueAPI 文档页 404docs 被关闭export MINERU_API_ENABLE_FASTAPI_DOCStrue任务状态查不到服务重启或超 24h 被清理调MINERU_API_TASK_RETENTION_SECONDS重启会丢历史任务老系统 pip 编译报错系统太旧conda 建 Python 3.11 环境后重装求助指南如何把问题问清楚再找人自己查不动要去社区提问Discord / 微信群入口见 docs/zh/时先自查一遍日志MINERU_LOG_LEVELDEBUG跑一遍把关键报错段留下来。一份合格的提问包含六要素版本mineru -v输出 Python 版本python --version命令原样贴出你执行的完整命令API Key 打码报错完整 traceback不要只截最后一行环境系统、显卡型号、显存大小、nvidia-smi驱动版本最小复现能复现的最短 PDF / 文档脱敏以及输入输出目录已尝试试过哪些方案分别得到什么结果信息越全别人帮你定位越快只贴一行报错的提问基本只能得到先升级最新版试试的回答。写在最后别慌MinerU 的问题九成是环境问题或参数没配对按先定位阶段 → 对症处理 → 留好日志求助这条路径走绝大多数报错都能自己解掉。本文基于 MinerU 3.4.4 整理旧版本的参数与后端名可能已变更动手前先pip install -U mineru升到最新版再看 docs/zh/ 官方文档核对。【免费下载链接】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），仅供参考