拓冰网站定制 
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还在为MinerU安装部署时的各种报错头疼吗模型下载卡住不动、解析结果缺字漏字、第一次请求慢得像卡死先别急。MinerU 是一款将 PDF、DOCX、PPTX、XLSX 等文档解析为 Markdown/JSON 的高精度文档解析引擎专为 LLM、RAG 与 Agent 场景设计。本文整理了 MinerU 使用中最常见的问题与报错解决方案读完通常能帮你在 3 分钟内定位问题并拿到一条可以直接执行的命令。读完本文你将获得✅ 按硬件条件判断该用哪个解析后端以及对应的性能参数怎么调✅ libGL 缺失CJK 文字丢失Windows 推理慢等安装环境报错的修复命令✅ ModelScope 镜像源、本地模型、mineru.json配置文件的完整配置方法✅ API 服务任务 404、首次请求慢、多卡部署等部署问题的处理方案✅ 一套结果验证与多后端对比的进阶调试方法一、排查总览先定位问题出在哪一环遇到问题别慌MinerU 的绝大多数问题都落在下面四个环节之一。先对照这张流程图确定你的问题类型再往下找对应章节能省掉大量试错时间二、安装与环境先排除跑不起来的问题Windows 直装后推理速度慢得离谱这是 Windows 用户反馈最多的问题原因基本只有一个装的是 CPU 版torchCUDA 加速没有生效。按显卡架构二选一Volta 及以后架构V100、20 系、T4、30 系、40 系到 PyTorch 官网选择与你 CUDA 版本匹配的 Windows 安装命令重装支持 CUDA 的torch和torchvision即可Blackwell 架构RTX 50xx 系列需要安装lmdeploy 0.11.1 cu128的 Windows wheel按你的 Python 版本替换版本号$env:PYTHON_VERSION 312 # 替换为你的Python版本如310/311/313 # 到lmdeploy官方releases页下载对应cu128 Windows wheel后执行 pip install $wheel --extra-index-url https://download.pytorch.org/whl/cu128WSL2/Ubuntu 报ImportError: libGL.so.1缺少系统图形库一条命令补上即可参考社区 issue #388sudo apt-get update sudo apt-get install libgl1-mesa-glxLinux 解析结果缺失中文等 CJK 文字MinerU 2.0 起改用pypdfium2渲染 PDF 页面部分 Linux 发行版因缺少 CJK 字体渲染成图片时会丢字参考 issue #2915。安装 Noto 字体包并刷新字体缓存sudo apt update sudo apt install fonts-noto-core fonts-noto-cjk fc-cache -fv嫌麻烦的话直接走 Docker 部署镜像里已内置完整字体参考 docs/zh/quick_start/docker_deployment.md。版本兼容速查与标准安装命令先确认你的环境在支持矩阵内再执行安装能避开一大半坑项目支持范围备注Python3.10 ~ 3.13Windows 因ray依赖限制最高只到 3.12Linux2019 年及以后发行版老系统如 CentOS 7兼容无保证macOS14.0 以上走原生安装不要用 DockerWindows全部版本Docker 部署需 WSL2pip install uv uv pip install -U mineru[all]需要源码安装时如国产加速卡适配git clone https://gitcode.com/GitHub_Trending/mi/MinerU cd MinerU uv pip install -e .[all]mineru[all]包含全部核心功能如果只跑 pipeline 后端或只做轻量 client可参考 docs/zh/quick_start/extension_modules.md 按需装扩展模块。三、模型下载与配置下载不动或想换地方放HuggingFace 连不上、下载卡在进度条国内网络访问 HuggingFace 受限时的标准解法是切换模型源到 ModelScope。该环境变量对 CLI 和 API 全量生效export MINERU_MODEL_SOURCEmodelscope mineru -p 输入路径 -o 输出路径注意MINERU_MODEL_SOURCE只接受huggingface、modelscope、local三个值不要设成auto——需要自动探测时直接不设置该变量即可默认策略会先探测 HuggingFace不通再回退 ModelScope并把结果写回配置文件。离线机器用本地模型内网、无外网的服务器可以先在有网机器下载、再整包搬运mineru-models-download # 交互式选择要下载的模型 # 搬运模型目录到目标机器后修改mineru.json中的models-dir export MINERU_MODEL_SOURCElocal模型目录移动后要同步更新mineru.json中的路径换机器部署时记得把mineru.json一起带到新设备的用户目录。mineru.json关键配置项配置文件默认在用户目录下首次运行mineru-models-download时自动生成也可把仓库里的 mineru.template.json 复制过去重命名。常用字段如下{ model-source: auto, models-dir: { pipeline: , vlm: }, latex-delimiter-config: { display: { left: $$, right: $$ }, inline: { left: $, right: $ } } }models-dir分别指定 pipeline / vlm 后端模型的本地目录配合MINERU_MODEL_SOURCElocal使用latex-delimiter-config公式分隔符不想要$时可改llm-aided-config配置 OpenAI 协议 LLM 辅助标题分级需自行填 API key 并把enable置为true想换配置文件位置设置环境变量MINERU_TOOLS_CONFIG_JSON指向新路径。更多字段说明见 docs/zh/usage/model_source.md。四、后端选择与性能调优精度、速度、显存的取舍到底该选哪个后端这是新手最容易问错的问题。对照官方支持矩阵选就行精度为 OmniDocBench v1.6 端到端 Overall 分数后端精度纯 CPU显存最低要求适用场景pipeline86.47✅4GB兼容性最好、无幻觉CPU 环境首选hybrid-engine95.39high/ 95.26medium❌8GB原生文本提取、低幻觉日常高精度vlm-engine95.30❌8GB端到端 VLM复杂版面*-http-client与对应引擎一致✅客户端2GB远程已有 OpenAI 兼容服务通用要求内存最低 16GB推荐 32GB磁盘 20GB建议 SSD。# CPU-only 机器显式指定 pipeline 后端 mineru -p 输入路径 -o 输出路径 -b pipelinehybrid 后端的解析强度怎么调3.3 版本起hybrid-engine/hybrid-http-client支持--effort参数默认mediummedium精度仅比 high 低约 0.13 分但解析速度可提升 35%~220%视平台与场景不支持图片/图表分析high追求极致精度或需要--image-analysis时再开。mineru -p 输入路径 -o 输出路径 -b hybrid-engine --effort high 显存与内存占用降不下来按症状调环境变量均已在 docs/zh/usage/cli_tools.md 中验证症状环境变量默认值调整思路hybrid-http-client 客户端显存紧张MINERU_HYBRID_BATCH_RATIO按显存分档≤6GB 设 8≤4GB 设 4≤3GB 设 2≤2GB 设 1大文档内存峰值高MINERU_PROCESSING_WINDOW_SIZE64改小正整数降低单次处理窗口PDF 渲染并发不合适MINERU_PDF_RENDER_THREADS4核数少就调小多卡机器指定用哪张卡CUDA_VISIBLE_DEVICES全部可见如CUDA_VISIBLE_DEVICES1 mineru ...长文档与分块解析上千页文档建议先按页码分段验证效果页码从 0 开始再全量跑mineru -p big_doc.pdf -o out/ -s 0 -e 9 mineru -p big_doc.pdf -o out/ -s 10 -e 19另外提醒3.4 版本 pipeline 后端 OCR 已升级到 PP-OCRv6且日语、繁体中文、英语、拉丁文等语言选项已移除统一路由到ch模型不要再沿用旧版本的语言参数。五、常见报错速查现象 → 原因 → 解法下表覆盖日常使用中出现频率最高的一类症状按报错信息/现象检索即可现象 / 报错常见原因解法ImportError: libGL.so.1缺系统图形库sudo apt-get install libgl1-mesa-glx结果缺 CJK 文字Linux 缺 CJK 字体装fonts-noto-cjkfc-cache -fvWindows 推理慢未装 CUDA 版 torch见二、Windows 直装后推理速度慢小节模型下载卡死HuggingFace 不通export MINERU_MODEL_SOURCEmodelscopeAPI 任务查询返回 404任务已超保留期被清理调大MINERU_API_TASK_RETENTION_SECONDS首次 VLM 请求特别慢VLM 模型首次才加载启动服务时加--enable-vlm-preload true解析慢但文档无公式/表格公式/表格解析默认开启-f false -t false关闭PDF 渲染超时渲染 worker 被大文档拖住调大MINERU_PDF_RENDER_TIMEOUT默认 300 秒不需要表格跨页合并合并功能默认开启MINERU_TABLE_MERGE_ENABLEfalse两个高频开关补充说明# 关闭公式与表格解析显著加快纯文本文档速度 mineru -p input.pdf -o out/ -f false -t false # OCR 语言指定仅 pipeline 后端有效中文文档推荐显式指定 mineru -p input.pdf -o out/ -b pipeline -l ch-l目前可选ch、ch_server、korean、ta、te、ka、th、el、arabic、east_slavic、cyrillic、devanagari指定文档语言可以提升 OCR 准确率。六、服务部署API、WebUI 与多卡编排 首次请求慢开启 VLM 预加载VLM/hybrid 引擎是懒加载的第一个请求要等模型初始化体验上像卡死。在 API 或 Gradio 启动时预加载即可mineru-api --host 0.0.0.0 --port 8000 --enable-vlm-preload trueGradio WebUI 同理mineru-gradio --server-name 0.0.0.0 --server-port 7860 --enable-vlm-preload true可加--max-convert-pages 50限制单次最大转换页数。任务查不到、输出目录找不着任务默认在完成或失败 24 小时后自动清理清理后再查/tasks/{task_id}就是 404属正常行为用MINERU_API_TASK_RETENTION_SECONDS调整保留时长API 输出默认写到工作目录下的./output可用MINERU_API_OUTPUT_ROOT改到磁盘空间更大的位置服务健康状态先看GET /health浏览器里访问http://127.0.0.1:8000/docs可查全部接口。多 GPU 与远程推理部署多卡统一入口mineru-router接口与mineru-api完全兼容支持自动负载均衡CUDA_VISIBLE_DEVICES0,1,2,3 mineru-router --host 0.0.0.0 --port 8002 --local-gpus auto远程 GPU 本地轻量 clientGPU 机器起 OpenAI 兼容服务本地无需装 torch 也能用vlm-http-clientmineru-openai-server --port 30000 mineru -p 输入路径 -o 输出路径 -b hybrid-http-client -u http://127.0.0.1:30000注意hybrid-http-client本地仍需mineru[pipeline]及 torch 等依赖vlm-http-client才是纯轻量端。七、进阶调试结果验证与瓶颈定位怎么确认解析效果没问题MinerU 支持 layout 可视化与 span 可视化输出方便肉眼比对模型看到了什么。同一份文档跑两个后端再对比差异是定位精度问题的最快方式mineru -p test.pdf -o out/pipeline/ -b pipeline mineru -p test.pdf -o out/hybrid/ -b hybrid-engine如上图所示可视化输出会标出标题、正文、图片、表格等区域出现文字丢失、顺序错乱类问题时应先看它再对照 Markdown 结果判断是版面检测问题还是 OCR 问题。精准开关与输出定位公式/表格/图片分析各有独立开关-f、-t、--image-analysis对应的环境变量MINERU_FORMULA_ENABLE、MINERU_TABLE_ENABLE优先级更高中间格式 JSONmiddle JSON信息最丰富排查输出结构问题建议直接读它输出文件说明见 docs/zh/reference/output_files.md解析慢时优先怀疑两个点PDF 渲染并发MINERU_PDF_RENDER_THREADS和 onnx 模型线程MINERU_INTRA_OP_NUM_THREADS、MINERU_INTER_OP_NUM_THREADS默认自动选择。排查收尾清单环境在支持矩阵内Python 版本、系统版本、字体、CUDA 依赖模型源可达或已切换 ModelScope / 本地模型后端与硬件匹配CPU-only 一定用pipeline或 http-client用可视化输出和双后端对比验证结果而不是只盯着 Markdown 猜。结语MinerU 的报错看着花样多归结起来就是环境、下载、参数、服务四件事。把上面的流程图当目录用先定位环节再照表取药绝大多数问题都能在半小时内解决。如果你的问题仍未解决建议先查项目 Issue本文未覆盖的问题大概率已有人踩过搜索报错关键字即可提交时附完整信息错误日志、MinerU 版本、操作系统/Python 版本以及能复现问题的样例文件这是加速定位的最关键材料加入社区交流通过 Discord 或官方微信群与其他用户和开发者沟通复杂场景可以在线讨论。祝你使用顺利解析愉快温馨提示本文内容基于 MinerU3.4.4版本整理其中参数、环境变量与精度数据均来自该版本官方文档。MinerU 迭代较快如 3.4 已更换 OCR 模型并调整语言选项请尽量升级到最新版本以获得最佳体验升级后可对照官方更新日志确认参数变化。【免费下载链接】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还在为MinerU安装部署时的各种报错头疼吗模型下载卡住不动、解析结果缺字漏字、第一次请求慢得像卡死先别急。MinerU 是一款将 PDF、DOCX、PPTX、XLSX 等文档解析为 Markdown/JSON 的高精度文档解析引擎专为 LLM、RAG 与 Agent 场景设计。本文整理了 MinerU 使用中最常见的问题与报错解决方案读完通常能帮你在 3 分钟内定位问题并拿到一条可以直接执行的命令。读完本文你将获得✅ 按硬件条件判断该用哪个解析后端以及对应的性能参数怎么调✅ libGL 缺失CJK 文字丢失Windows 推理慢等安装环境报错的修复命令✅ ModelScope 镜像源、本地模型、mineru.json配置文件的完整配置方法✅ API 服务任务 404、首次请求慢、多卡部署等部署问题的处理方案✅ 一套结果验证与多后端对比的进阶调试方法一、排查总览先定位问题出在哪一环遇到问题别慌MinerU 的绝大多数问题都落在下面四个环节之一。先对照这张流程图确定你的问题类型再往下找对应章节能省掉大量试错时间二、安装与环境先排除跑不起来的问题Windows 直装后推理速度慢得离谱这是 Windows 用户反馈最多的问题原因基本只有一个装的是 CPU 版torchCUDA 加速没有生效。按显卡架构二选一Volta 及以后架构V100、20 系、T4、30 系、40 系到 PyTorch 官网选择与你 CUDA 版本匹配的 Windows 安装命令重装支持 CUDA 的torch和torchvision即可Blackwell 架构RTX 50xx 系列需要安装lmdeploy 0.11.1 cu128的 Windows wheel按你的 Python 版本替换版本号$env:PYTHON_VERSION 312 # 替换为你的Python版本如310/311/313 # 到lmdeploy官方releases页下载对应cu128 Windows wheel后执行 pip install $wheel --extra-index-url https://download.pytorch.org/whl/cu128WSL2/Ubuntu 报ImportError: libGL.so.1缺少系统图形库一条命令补上即可参考社区 issue #388sudo apt-get update sudo apt-get install libgl1-mesa-glxLinux 解析结果缺失中文等 CJK 文字MinerU 2.0 起改用pypdfium2渲染 PDF 页面部分 Linux 发行版因缺少 CJK 字体渲染成图片时会丢字参考 issue #2915。安装 Noto 字体包并刷新字体缓存sudo apt update sudo apt install fonts-noto-core fonts-noto-cjk fc-cache -fv嫌麻烦的话直接走 Docker 部署镜像里已内置完整字体参考 docs/zh/quick_start/docker_deployment.md。版本兼容速查与标准安装命令先确认你的环境在支持矩阵内再执行安装能避开一大半坑项目支持范围备注Python3.10 ~ 3.13Windows 因ray依赖限制最高只到 3.12Linux2019 年及以后发行版老系统如 CentOS 7兼容无保证macOS14.0 以上走原生安装不要用 DockerWindows全部版本Docker 部署需 WSL2pip install uv uv pip install -U mineru[all]需要源码安装时如国产加速卡适配git clone https://gitcode.com/GitHub_Trending/mi/MinerU cd MinerU uv pip install -e .[all]mineru[all]包含全部核心功能如果只跑 pipeline 后端或只做轻量 client可参考 docs/zh/quick_start/extension_modules.md 按需装扩展模块。三、模型下载与配置下载不动或想换地方放HuggingFace 连不上、下载卡在进度条国内网络访问 HuggingFace 受限时的标准解法是切换模型源到 ModelScope。该环境变量对 CLI 和 API 全量生效export MINERU_MODEL_SOURCEmodelscope mineru -p 输入路径 -o 输出路径注意MINERU_MODEL_SOURCE只接受huggingface、modelscope、local三个值不要设成auto——需要自动探测时直接不设置该变量即可默认策略会先探测 HuggingFace不通再回退 ModelScope并把结果写回配置文件。离线机器用本地模型内网、无外网的服务器可以先在有网机器下载、再整包搬运mineru-models-download # 交互式选择要下载的模型 # 搬运模型目录到目标机器后修改mineru.json中的models-dir export MINERU_MODEL_SOURCElocal模型目录移动后要同步更新mineru.json中的路径换机器部署时记得把mineru.json一起带到新设备的用户目录。mineru.json关键配置项配置文件默认在用户目录下首次运行mineru-models-download时自动生成也可把仓库里的 mineru.template.json 复制过去重命名。常用字段如下{ model-source: auto, models-dir: { pipeline: , vlm: }, latex-delimiter-config: { display: { left: $$, right: $$ }, inline: { left: $, right: $ } } }models-dir分别指定 pipeline / vlm 后端模型的本地目录配合MINERU_MODEL_SOURCElocal使用latex-delimiter-config公式分隔符不想要$时可改llm-aided-config配置 OpenAI 协议 LLM 辅助标题分级需自行填 API key 并把enable置为true想换配置文件位置设置环境变量MINERU_TOOLS_CONFIG_JSON指向新路径。更多字段说明见 docs/zh/usage/model_source.md。四、后端选择与性能调优精度、速度、显存的取舍到底该选哪个后端这是新手最容易问错的问题。对照官方支持矩阵选就行精度为 OmniDocBench v1.6 端到端 Overall 分数后端精度纯 CPU显存最低要求适用场景pipeline86.47✅4GB兼容性最好、无幻觉CPU 环境首选hybrid-engine95.39high/ 95.26medium❌8GB原生文本提取、低幻觉日常高精度vlm-engine95.30❌8GB端到端 VLM复杂版面*-http-client与对应引擎一致✅客户端2GB远程已有 OpenAI 兼容服务通用要求内存最低 16GB推荐 32GB磁盘 20GB建议 SSD。# CPU-only 机器显式指定 pipeline 后端 mineru -p 输入路径 -o 输出路径 -b pipelinehybrid 后端的解析强度怎么调3.3 版本起hybrid-engine/hybrid-http-client支持--effort参数默认mediummedium精度仅比 high 低约 0.13 分但解析速度可提升 35%~220%视平台与场景不支持图片/图表分析high追求极致精度或需要--image-analysis时再开。mineru -p 输入路径 -o 输出路径 -b hybrid-engine --effort high 显存与内存占用降不下来按症状调环境变量均已在 docs/zh/usage/cli_tools.md 中验证症状环境变量默认值调整思路hybrid-http-client 客户端显存紧张MINERU_HYBRID_BATCH_RATIO按显存分档≤6GB 设 8≤4GB 设 4≤3GB 设 2≤2GB 设 1大文档内存峰值高MINERU_PROCESSING_WINDOW_SIZE64改小正整数降低单次处理窗口PDF 渲染并发不合适MINERU_PDF_RENDER_THREADS4核数少就调小多卡机器指定用哪张卡CUDA_VISIBLE_DEVICES全部可见如CUDA_VISIBLE_DEVICES1 mineru ...长文档与分块解析上千页文档建议先按页码分段验证效果页码从 0 开始再全量跑mineru -p big_doc.pdf -o out/ -s 0 -e 9 mineru -p big_doc.pdf -o out/ -s 10 -e 19另外提醒3.4 版本 pipeline 后端 OCR 已升级到 PP-OCRv6且日语、繁体中文、英语、拉丁文等语言选项已移除统一路由到ch模型不要再沿用旧版本的语言参数。五、常见报错速查现象 → 原因 → 解法下表覆盖日常使用中出现频率最高的一类症状按报错信息/现象检索即可现象 / 报错常见原因解法ImportError: libGL.so.1缺系统图形库sudo apt-get install libgl1-mesa-glx结果缺 CJK 文字Linux 缺 CJK 字体装fonts-noto-cjkfc-cache -fvWindows 推理慢未装 CUDA 版 torch见二、Windows 直装后推理速度慢小节模型下载卡死HuggingFace 不通export MINERU_MODEL_SOURCEmodelscopeAPI 任务查询返回 404任务已超保留期被清理调大MINERU_API_TASK_RETENTION_SECONDS首次 VLM 请求特别慢VLM 模型首次才加载启动服务时加--enable-vlm-preload true解析慢但文档无公式/表格公式/表格解析默认开启-f false -t false关闭PDF 渲染超时渲染 worker 被大文档拖住调大MINERU_PDF_RENDER_TIMEOUT默认 300 秒不需要表格跨页合并合并功能默认开启MINERU_TABLE_MERGE_ENABLEfalse两个高频开关补充说明# 关闭公式与表格解析显著加快纯文本文档速度 mineru -p input.pdf -o out/ -f false -t false # OCR 语言指定仅 pipeline 后端有效中文文档推荐显式指定 mineru -p input.pdf -o out/ -b pipeline -l ch-l目前可选ch、ch_server、korean、ta、te、ka、th、el、arabic、east_slavic、cyrillic、devanagari指定文档语言可以提升 OCR 准确率。六、服务部署API、WebUI 与多卡编排 首次请求慢开启 VLM 预加载VLM/hybrid 引擎是懒加载的第一个请求要等模型初始化体验上像卡死。在 API 或 Gradio 启动时预加载即可mineru-api --host 0.0.0.0 --port 8000 --enable-vlm-preload trueGradio WebUI 同理mineru-gradio --server-name 0.0.0.0 --server-port 7860 --enable-vlm-preload true可加--max-convert-pages 50限制单次最大转换页数。任务查不到、输出目录找不着任务默认在完成或失败 24 小时后自动清理清理后再查/tasks/{task_id}就是 404属正常行为用MINERU_API_TASK_RETENTION_SECONDS调整保留时长API 输出默认写到工作目录下的./output可用MINERU_API_OUTPUT_ROOT改到磁盘空间更大的位置服务健康状态先看GET /health浏览器里访问http://127.0.0.1:8000/docs可查全部接口。多 GPU 与远程推理部署多卡统一入口mineru-router接口与mineru-api完全兼容支持自动负载均衡CUDA_VISIBLE_DEVICES0,1,2,3 mineru-router --host 0.0.0.0 --port 8002 --local-gpus auto远程 GPU 本地轻量 clientGPU 机器起 OpenAI 兼容服务本地无需装 torch 也能用vlm-http-clientmineru-openai-server --port 30000 mineru -p 输入路径 -o 输出路径 -b hybrid-http-client -u http://127.0.0.1:30000注意hybrid-http-client本地仍需mineru[pipeline]及 torch 等依赖vlm-http-client才是纯轻量端。七、进阶调试结果验证与瓶颈定位怎么确认解析效果没问题MinerU 支持 layout 可视化与 span 可视化输出方便肉眼比对模型看到了什么。同一份文档跑两个后端再对比差异是定位精度问题的最快方式mineru -p test.pdf -o out/pipeline/ -b pipeline mineru -p test.pdf -o out/hybrid/ -b hybrid-engine如上图所示可视化输出会标出标题、正文、图片、表格等区域出现文字丢失、顺序错乱类问题时应先看它再对照 Markdown 结果判断是版面检测问题还是 OCR 问题。精准开关与输出定位公式/表格/图片分析各有独立开关-f、-t、--image-analysis对应的环境变量MINERU_FORMULA_ENABLE、MINERU_TABLE_ENABLE优先级更高中间格式 JSONmiddle JSON信息最丰富排查输出结构问题建议直接读它输出文件说明见 docs/zh/reference/output_files.md解析慢时优先怀疑两个点PDF 渲染并发MINERU_PDF_RENDER_THREADS和 onnx 模型线程MINERU_INTRA_OP_NUM_THREADS、MINERU_INTER_OP_NUM_THREADS默认自动选择。排查收尾清单环境在支持矩阵内Python 版本、系统版本、字体、CUDA 依赖模型源可达或已切换 ModelScope / 本地模型后端与硬件匹配CPU-only 一定用pipeline或 http-client用可视化输出和双后端对比验证结果而不是只盯着 Markdown 猜。结语MinerU 的报错看着花样多归结起来就是环境、下载、参数、服务四件事。把上面的流程图当目录用先定位环节再照表取药绝大多数问题都能在半小时内解决。如果你的问题仍未解决建议先查项目 Issue本文未覆盖的问题大概率已有人踩过搜索报错关键字即可提交时附完整信息错误日志、MinerU 版本、操作系统/Python 版本以及能复现问题的样例文件这是加速定位的最关键材料加入社区交流通过 Discord 或官方微信群与其他用户和开发者沟通复杂场景可以在线讨论。祝你使用顺利解析愉快温馨提示本文内容基于 MinerU3.4.4版本整理其中参数、环境变量与精度数据均来自该版本官方文档。MinerU 迭代较快如 3.4 已更换 OCR 模型并调整语言选项请尽量升级到最新版本以获得最佳体验升级后可对照官方更新日志确认参数变化。【免费下载链接】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），仅供参考