MinerU 排障指南从部署报错到生产批量跑10 分钟定位问题【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU凌晨两点解析任务卡在模型下载整整 20 分钟终端还甩出一句ImportError: libGL.so.1分不清是网络、系统库还是模型的事。MinerU 是把 PDF 和 Office 文档解析成 Markdown/JSON 的工具但部署报错分散在系统依赖、模型源和推理引擎三处。这篇文章按安装、首跑、调参、上生产的顺序把高频坑一次排清你可以按现象直接跳读。快速诊断表先在这里对号入座你看到的现象最可能的原因第一动作import 时报libGL.so.1WSL2 缺 libglsudo apt-get install libgl1-mesa-glxFailed building wheel for simsimdglibc 太老无预编译 wheel改用 Docker 镜像部署模型下载卡在 huggingface网络不可达export MINERU_MODEL_SOURCEmodelscope输出缺中文、只丢部分文字系统缺 CJK 字体装fonts-noto-cjk并刷新字体缓存CUDA out of memory显存不足或并发过高MINERU_API_MAX_CONCURRENT_REQUESTS降到 1首个请求极慢、第二个正常VLM 冷启动服务端加--enable-vlm-preload trueWindows 上推理很慢torch 是 CPU 版安装对应 CUDA 版本的 torch wheel安装阶段libGL 缺失这类部署报错怎么修导入报 libGL.so.1WSL2 一条命令装上这个错几乎都出在 WSL2 的 Ubuntu 22.04 上。先执行sudo apt-get install libgl1-mesa-glx为什么这么做OpenCV 依赖 libGL 完成图形相关调用而 WSL2 的无头镜像默认不带这个库装完包即可通过 import。较新的 Ubuntu 仓库里包名是libgl1装不上时换成它重试。老 Linux 编不过 simsimd 的 wheelCentOS 7、Ubuntu 18 这一代系统的 glibc 太旧pip 找不到预编译 wheel只能回退到源码编译然后失败。别在老系统上硬扛编译直接用项目 Docker 部署仓库里现成的是docker/compose.yaml。为什么这么做镜像里 C 扩展依赖已经编译好还预装了完整字体一次绕开 glibc、依赖、字体三类问题。版本检查Python 不在 3.10 到 3.13 之间先跑python -V确认版本。低于 3.10 或高于 3.13 都会直接被依赖链卡住。低于 3.10 时新建环境conda create -n mineru python3.11 -y为什么这么做pyproject.toml声明的范围是3.10,3.143.13 需要最新版本的 MinerU 与配套 wheel3.9 及以下没有可用轮子。第一次跑通模型下载卡住与出结果缺字HuggingFace 模型下载卡死一行切到 ModelScope默认模型源是 huggingface国内网络经常连不上表现为下载进度条长时间不动。先执行export MINERU_MODEL_SOURCEmodelscope为什么这么做环境变量优先级最高对所有命令行工具和 API 调用生效首次探测完成后来源会写回用户目录的mineru.json后面不用反复切。取值支持huggingface、modelscope、local详见 docs/zh/usage/model_source.md。首次输出缺中文装上 Noto CJK 字体注意区分这种情况解析流程本身没报错只是渲染 PDF 成图片时丢了部分文字。先执行sudo apt install fonts-noto-core fonts-noto-cjk fc-cache -fv为什么这么做2.0 起 MinerU 用 pypdfium2 渲染页面系统缺 CJK 字体时中文会整段消失重装字体并刷新缓存即可恢复。跑完对一下版式效果正常应长这样首个请求比第二个慢一个量级开启 VLM 预加载如果你走mineru-api或服务端模式第一个请求要等 VLM 模型初始化观感像卡死。先执行mineru-api --enable-vlm-preload true --port 8000为什么这么做预加载把模型初始化挪到服务启动阶段首个真实请求就不用再等。注意该参数只作用于本地拉起的服务连远端--api-url时不生效。结果不对或速度不达标解析参数怎么调报错和结果差是两类问题先按下图判断你在哪个分支显存不够时该调哪三个参数OOM 时先降并发再降窗口最后动解析强度export MINERU_API_MAX_CONCURRENT_REQUESTS1 export MINERU_PROCESSING_WINDOW_SIZE16为什么这么做前者决定同时处理的任务数直接决定显存峰值后者决定大文档一次在内存里持有多少页默认 64减半即可明显降压。第三个旋钮是--efforthybrid 的 medium 强度会自动关闭图片分析比 high 省不少显存。✅ 三个都调完仍 OOM说明文档复杂度超出该卡承载换 vlm 服务端模式更合适。表格公式解析不对语言与后端怎么选文字级结果不对时先看 span 层面的中间结果确认是识别错了还是排版错了pipeline 后端手动指定语言能显著提升准确率mineru -p input.pdf -o out/ -b pipeline -l ch为什么这么做-l告诉 OCR 识别模型使用哪个字符集中英混合、手写、日繁混排用ch_server更稳⚠️ 该参数只对 pipeline 后端生效。超大财务表格和复杂公式VLM 类后端的效果通常明显好于传统 OCR 流程。后端怎么选pipeline、hybrid、vlm 各适用什么默认后端是 hybrid-engine各后端的取舍如下后端特点适用场景pipeline稳定、显存需求低文本为主、批量跑hybrid默认质量与成本平衡大多数场景vlm-engine复杂版面最强财报、手写、多栏*-http-client客户端无需 torch纯前端节点直连服务引擎的自动选择逻辑在 mineru/utils/engine_utils.py 里Linux 优先 vllmWindows 优先 lmdeploymacOS 优先 mlx。多卡机器用CUDA_VISIBLE_DEVICES前缀即可指定用哪张卡对全部命令生效。上生产前mineru-api 并发与多卡扩容并发排队严重调大 mineru-api 并发上限服务默认最多 3 个并发请求批量任务进来就排队。确认显存余量后export MINERU_API_MAX_CONCURRENT_REQUESTS4为什么这么做并发是吞吐的第一杠杆每次加 1 观察显存曲线稳定后再加。客户端侧的等待上限由MINERU_TASK_RESULT_TIMEOUT_SECONDS控制默认 3600 秒长任务场景别把默认值设太小。一张卡不够mineru-router 多卡并行单卡打满后再横向扩router 会按本地 GPU 自动拉起多个 worker并对外提供与 mineru-api 完全一致的接口CUDA_VISIBLE_DEVICES0,1,2,3 mineru-router --host 0.0.0.0 --port 8002 --local-gpus auto为什么这么做你只维护一个入口地址扩容只是多传几张卡也可以--upstream-url接入已存在的远端 mineru-api 服务。大文档处理超时用页码切片跑500 页以上的文档整份跑客户端容易先于任务超时。切片执行mineru -p big.pdf -o out/ -s 0 -e 99为什么这么做-s/-e按页切片从 0 计失败只需重跑失败的分片单片也更容易落在超时窗口内。常用的配套环境变量如下环境变量默认值控制什么MINERU_PROCESSING_WINDOW_SIZE64大文档单次处理页数影响内存MINERU_API_MAX_CONCURRENT_REQUESTS3服务最大并发请求数MINERU_LOCAL_API_STARTUP_TIMEOUT_SECONDS300等待本地 api 健康的最长时间MINERU_TASK_RESULT_TIMEOUT_SECONDS3600客户端等待任务终态的上限MINERU_API_TASK_RETENTION_SECONDS86400任务结果保留时长MINERU_PDF_RENDER_THREADS4PDF 渲染并发数反复踩坑的边界情况换机器后本地模型失效mineru.json 要跟着走用local源时模型路径写在用户目录的mineru.json里。换机或移动模型文件夹后必须同步更新该文件里的路径并保留MINERU_MODEL_SOURCElocal这一行环境变量。配置结构可以照着仓库根目录的 mineru.template.json 来建。为什么这么做local 源不探测远端路径错了只会静默找不到模型不会给出醒目的报错。Windows 推理慢torch 装的是 CPU 版Windows 直接 pip 装到的 torch 默认不带 CUDA推理会慢一个数量级。去 PyTorch 官方页面按显卡架构选 wheelV100、20 系、T4、30 系、40 系选对应 cu12x 版本RTX 50xx 这类 Blackwell 卡要走 cu128 加 lmdeploy 0.11.1 的组合。为什么这么做加速能力取决于 torch 二进制是否编译了对应 CUDA 架构装错版本时程序能跑、只是慢没有任何报错提示。任务查询突然 40424 小时保留窗口任务完成或失败后默认只保留 24 小时之后状态与输出目录都会被清理再查就是 404。需要留更久时调大MINERU_API_TASK_RETENTION_SECONDS它和清理轮询间隔MINERU_API_TASK_CLEANUP_INTERVAL_SECONDS配套使用。为什么这么做这是防磁盘堆积的默认策略不是服务挂了批量流程里若客户端轮询慢于清理周期把保留时长调到大于任务总时长即可。如果以上都没解决做两件事用完整原始报错文本去项目 issue 里检索别用翻译后的关键词提 issue 时附上最小可复现的 PDF 样本、完整 traceback 和mineru -v的版本输出。本文验证于 v3.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），仅供参考 MinerU 排障指南：从部署报错到生产批量跑，10 分钟定位问题
MinerU 排障指南从部署报错到生产批量跑10 分钟定位问题【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU凌晨两点解析任务卡在模型下载整整 20 分钟终端还甩出一句ImportError: libGL.so.1分不清是网络、系统库还是模型的事。MinerU 是把 PDF 和 Office 文档解析成 Markdown/JSON 的工具但部署报错分散在系统依赖、模型源和推理引擎三处。这篇文章按安装、首跑、调参、上生产的顺序把高频坑一次排清你可以按现象直接跳读。快速诊断表先在这里对号入座你看到的现象最可能的原因第一动作import 时报libGL.so.1WSL2 缺 libglsudo apt-get install libgl1-mesa-glxFailed building wheel for simsimdglibc 太老无预编译 wheel改用 Docker 镜像部署模型下载卡在 huggingface网络不可达export MINERU_MODEL_SOURCEmodelscope输出缺中文、只丢部分文字系统缺 CJK 字体装fonts-noto-cjk并刷新字体缓存CUDA out of memory显存不足或并发过高MINERU_API_MAX_CONCURRENT_REQUESTS降到 1首个请求极慢、第二个正常VLM 冷启动服务端加--enable-vlm-preload trueWindows 上推理很慢torch 是 CPU 版安装对应 CUDA 版本的 torch wheel安装阶段libGL 缺失这类部署报错怎么修导入报 libGL.so.1WSL2 一条命令装上这个错几乎都出在 WSL2 的 Ubuntu 22.04 上。先执行sudo apt-get install libgl1-mesa-glx为什么这么做OpenCV 依赖 libGL 完成图形相关调用而 WSL2 的无头镜像默认不带这个库装完包即可通过 import。较新的 Ubuntu 仓库里包名是libgl1装不上时换成它重试。老 Linux 编不过 simsimd 的 wheelCentOS 7、Ubuntu 18 这一代系统的 glibc 太旧pip 找不到预编译 wheel只能回退到源码编译然后失败。别在老系统上硬扛编译直接用项目 Docker 部署仓库里现成的是docker/compose.yaml。为什么这么做镜像里 C 扩展依赖已经编译好还预装了完整字体一次绕开 glibc、依赖、字体三类问题。版本检查Python 不在 3.10 到 3.13 之间先跑python -V确认版本。低于 3.10 或高于 3.13 都会直接被依赖链卡住。低于 3.10 时新建环境conda create -n mineru python3.11 -y为什么这么做pyproject.toml声明的范围是3.10,3.143.13 需要最新版本的 MinerU 与配套 wheel3.9 及以下没有可用轮子。第一次跑通模型下载卡住与出结果缺字HuggingFace 模型下载卡死一行切到 ModelScope默认模型源是 huggingface国内网络经常连不上表现为下载进度条长时间不动。先执行export MINERU_MODEL_SOURCEmodelscope为什么这么做环境变量优先级最高对所有命令行工具和 API 调用生效首次探测完成后来源会写回用户目录的mineru.json后面不用反复切。取值支持huggingface、modelscope、local详见 docs/zh/usage/model_source.md。首次输出缺中文装上 Noto CJK 字体注意区分这种情况解析流程本身没报错只是渲染 PDF 成图片时丢了部分文字。先执行sudo apt install fonts-noto-core fonts-noto-cjk fc-cache -fv为什么这么做2.0 起 MinerU 用 pypdfium2 渲染页面系统缺 CJK 字体时中文会整段消失重装字体并刷新缓存即可恢复。跑完对一下版式效果正常应长这样首个请求比第二个慢一个量级开启 VLM 预加载如果你走mineru-api或服务端模式第一个请求要等 VLM 模型初始化观感像卡死。先执行mineru-api --enable-vlm-preload true --port 8000为什么这么做预加载把模型初始化挪到服务启动阶段首个真实请求就不用再等。注意该参数只作用于本地拉起的服务连远端--api-url时不生效。结果不对或速度不达标解析参数怎么调报错和结果差是两类问题先按下图判断你在哪个分支显存不够时该调哪三个参数OOM 时先降并发再降窗口最后动解析强度export MINERU_API_MAX_CONCURRENT_REQUESTS1 export MINERU_PROCESSING_WINDOW_SIZE16为什么这么做前者决定同时处理的任务数直接决定显存峰值后者决定大文档一次在内存里持有多少页默认 64减半即可明显降压。第三个旋钮是--efforthybrid 的 medium 强度会自动关闭图片分析比 high 省不少显存。✅ 三个都调完仍 OOM说明文档复杂度超出该卡承载换 vlm 服务端模式更合适。表格公式解析不对语言与后端怎么选文字级结果不对时先看 span 层面的中间结果确认是识别错了还是排版错了pipeline 后端手动指定语言能显著提升准确率mineru -p input.pdf -o out/ -b pipeline -l ch为什么这么做-l告诉 OCR 识别模型使用哪个字符集中英混合、手写、日繁混排用ch_server更稳⚠️ 该参数只对 pipeline 后端生效。超大财务表格和复杂公式VLM 类后端的效果通常明显好于传统 OCR 流程。后端怎么选pipeline、hybrid、vlm 各适用什么默认后端是 hybrid-engine各后端的取舍如下后端特点适用场景pipeline稳定、显存需求低文本为主、批量跑hybrid默认质量与成本平衡大多数场景vlm-engine复杂版面最强财报、手写、多栏*-http-client客户端无需 torch纯前端节点直连服务引擎的自动选择逻辑在 mineru/utils/engine_utils.py 里Linux 优先 vllmWindows 优先 lmdeploymacOS 优先 mlx。多卡机器用CUDA_VISIBLE_DEVICES前缀即可指定用哪张卡对全部命令生效。上生产前mineru-api 并发与多卡扩容并发排队严重调大 mineru-api 并发上限服务默认最多 3 个并发请求批量任务进来就排队。确认显存余量后export MINERU_API_MAX_CONCURRENT_REQUESTS4为什么这么做并发是吞吐的第一杠杆每次加 1 观察显存曲线稳定后再加。客户端侧的等待上限由MINERU_TASK_RESULT_TIMEOUT_SECONDS控制默认 3600 秒长任务场景别把默认值设太小。一张卡不够mineru-router 多卡并行单卡打满后再横向扩router 会按本地 GPU 自动拉起多个 worker并对外提供与 mineru-api 完全一致的接口CUDA_VISIBLE_DEVICES0,1,2,3 mineru-router --host 0.0.0.0 --port 8002 --local-gpus auto为什么这么做你只维护一个入口地址扩容只是多传几张卡也可以--upstream-url接入已存在的远端 mineru-api 服务。大文档处理超时用页码切片跑500 页以上的文档整份跑客户端容易先于任务超时。切片执行mineru -p big.pdf -o out/ -s 0 -e 99为什么这么做-s/-e按页切片从 0 计失败只需重跑失败的分片单片也更容易落在超时窗口内。常用的配套环境变量如下环境变量默认值控制什么MINERU_PROCESSING_WINDOW_SIZE64大文档单次处理页数影响内存MINERU_API_MAX_CONCURRENT_REQUESTS3服务最大并发请求数MINERU_LOCAL_API_STARTUP_TIMEOUT_SECONDS300等待本地 api 健康的最长时间MINERU_TASK_RESULT_TIMEOUT_SECONDS3600客户端等待任务终态的上限MINERU_API_TASK_RETENTION_SECONDS86400任务结果保留时长MINERU_PDF_RENDER_THREADS4PDF 渲染并发数反复踩坑的边界情况换机器后本地模型失效mineru.json 要跟着走用local源时模型路径写在用户目录的mineru.json里。换机或移动模型文件夹后必须同步更新该文件里的路径并保留MINERU_MODEL_SOURCElocal这一行环境变量。配置结构可以照着仓库根目录的 mineru.template.json 来建。为什么这么做local 源不探测远端路径错了只会静默找不到模型不会给出醒目的报错。Windows 推理慢torch 装的是 CPU 版Windows 直接 pip 装到的 torch 默认不带 CUDA推理会慢一个数量级。去 PyTorch 官方页面按显卡架构选 wheelV100、20 系、T4、30 系、40 系选对应 cu12x 版本RTX 50xx 这类 Blackwell 卡要走 cu128 加 lmdeploy 0.11.1 的组合。为什么这么做加速能力取决于 torch 二进制是否编译了对应 CUDA 架构装错版本时程序能跑、只是慢没有任何报错提示。任务查询突然 40424 小时保留窗口任务完成或失败后默认只保留 24 小时之后状态与输出目录都会被清理再查就是 404。需要留更久时调大MINERU_API_TASK_RETENTION_SECONDS它和清理轮询间隔MINERU_API_TASK_CLEANUP_INTERVAL_SECONDS配套使用。为什么这么做这是防磁盘堆积的默认策略不是服务挂了批量流程里若客户端轮询慢于清理周期把保留时长调到大于任务总时长即可。如果以上都没解决做两件事用完整原始报错文本去项目 issue 里检索别用翻译后的关键词提 issue 时附上最小可复现的 PDF 样本、完整 traceback 和mineru -v的版本输出。本文验证于 v3.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），仅供参考