MinerU 版本升级指南从 1.x 到 2.7 的完整迁移路径【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU本文写给已安装 magic-pdf 1.x 或 mineru 2.x、准备升级到最新 2.7 系列的用户。内容覆盖版本路径选择、环境检查与备份、升级操作、破坏性变更核对与回滚全程按步骤执行即可。MinerU 是把 PDF、图片和 Office 文档转换成 Markdown 与 JSON 的文档解析工具。如果你的环境里装着旧版本、想换到新版本这篇文章带你完整走一遍版本升级流程。读完后你能独立完成升级、验证结果是否正确并在出问题时快速回退到旧版本。先查当前版本再选升级路径一条命令确认你装的是哪个版本mineru --version如果还在 1.x命令是magic-pdf --version。版本号查清后按下面的路径对号入座路径上有三个要点1.x 升上去变更最多。2.0.0 的包名、命令名两项破坏性变更必须先处理否则脚本会直接报错。2.0 到 2.4 升上去要留意 VLM 模型2.5 起 vlm 后端不再支持 MinerU2.0-2505-0.9B 模型最后一个支持它的版本是 2.2.2。业务依赖旧模型就先锁定 2.2.2再评估升级。2.5、2.6、2.7 属于同一大版本内的小升级直接更新包即可。注意 2.7.0 起默认解析后端从pipeline切换到hybrid-auto-engine输出细节可能有差异可用-b pipeline切回旧后端。动手前查四项备份一个文件先确认环境满足基线要求检查项要求查看方式Python 版本3.10 - 3.13python --version磁盘空间http-client 后端 ≥2GB本地模型 ≥20GBdf -hGPUvlm/hybrid 后端需 Volta 及以后架构、8GB 显存pipeline 支持纯 CPUnvidia-smi网络可访问 HuggingFace 或 ModelScope不通就先换国内源再解析备份只做一件事就拷一个文件cp ~/.mineru.json ~/.mineru.json.backupmineru.json记录了本地模型路径和相关配置回退时靠它恢复旧环境。如果你把模型放在自定义目录把路径抄一份下来。备份到此为止不多做。升级主流程四步走完第一步卸载旧版本目的清掉旧包让新包装进干净环境避免新旧依赖互相打架。uv pip uninstall magic-pdf -y uv pip uninstall mineru -y预期结果两条命令都无报错退出。提示未找到该包也没关系说明这个环境本来就没装过。第二步安装新版本目的装最新的 2.7。2.7.0 起一条命令装齐全部可选后端不用再逐个选模块。uv pip install -U mineru[all]预期结果安装结束、无报错。只想要核心功能省空间可改装uv pip install mineru[core]。第三步下载或更新模型目的2.x 有模型自动下载但跨大版本升级时建议显式跑一次内置下载命令保证模型与新版匹配。mineru-models-download预期结果模型落到本地缓存。命令按增量更新已有文件不会重下。如果模型目录被移动过会重新下到默认位置并更新mineru.json。第四步按需切换模型源目的环境访问不了 HuggingFace 时在解析或下载模型前切到国内镜像。设置环境变量export MINERU_MODEL_SOURCEmodelscope再重跑mineru-models-download。预期结果模型改从 ModelScope 拉取下载速度恢复正常。破坏性变更速查1.x 升上来要改什么从 1.x 升上去主要工作量在改代码和脚本对照下面这张表逐行核对即可变更项旧写法新写法影响面包导入import magic_pdfimport mineru所有引用旧包的 Python 代码命令行magic-pdf -p input.pdfmineru -p input.pdf所有 shell 脚本与定时任务配置文件magic-pdf.json1.x~/.mineru.json2.x 自动生成1.x 多数配置项已改为命令行参数不再手编 JSON默认后端pipelinehybrid-auto-engine2.7 起输出细节可能变化加-b pipeline可切回VLM 模型MinerU2.0-2505-0.9BMinerU2.52.5 起不再支持最后支持版本 2.2.2Office 文档内置 LibreOffice 先转 PDFDOCX/PPTX/XLSX 原生解析不再需要先转成 PDF已在 2.x 的用户只需关注默认后端切换这一条包名与配置文件不变。升级后怎么确认没问题查一版本号对。再跑一次mineru --version应打印出 2.7.x。查二冒烟通过。用一份业务里真实的 1 到 2 页文档做测试mineru --version mineru -p sample.pdf -o out/预期结果解析无报错out/目录下生成 Markdown 和图片。别一上来就批量跑先让单份文档通过。查三模型齐全。冒烟时报模型缺失重跑mineru-models-download做增量更新已有文件不会重复下载。卡住了对照四个高频问题现象ModuleNotFoundError: magic_pdf或提示命令不存在→ 可能原因脚本还在用旧包名、旧命令 → 解决import magic_pdf改为import mineru命令里的magic-pdf换成mineru。现象模型下载失败或超时→ 可能原因网络访问不了 HuggingFace → 解决export MINERU_MODEL_SOURCEmodelscope再重跑mineru-models-download。现象Linux 上解析输出缺字→ 可能原因2.0 起改用 pypdfium2 渲染 PDF系统缺 CJK 字体 → 解决Ubuntu/Debian 执行sudo apt install fonts-noto-cjk fc-cache -fv重跑解析。现象vlm 后端起不来或提示模型不对→ 可能原因2.5 起不再支持旧的 MinerU2.0-2505-0.9B 模型 → 解决下载 MinerU2.5 模型重跑或锁定最后支持旧模型的版本 2.2.2。实在不行回滚前提只有一个~/.mineru.json.backup还在旧模型文件没被删。满足的话回滚就三行uv pip uninstall mineru -y uv pip install magic-pdf1.3.12 cp ~/.mineru.json.backup ~/.mineru.json2.x 内部回退同理锁定版本即可例如uv pip install mineru2.6.7。先回滚恢复业务再慢慢查原因别在生产环境里硬改。收尾前过一遍清单版本路径以版本号为准先跑mineru --version再动手1.x 升级只改两样包名和命令行配置项自动迁移依赖旧 vlm 模型的业务先锁 2.2.2 再评估升级备份就一个文件~/.mineru.json升级期间留着别删已查清当前版本选定升级路径已备份~/.mineru.json已卸载旧包并装好mineru[all]已跑mineru-models-download样例 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考