MinerU 版本升级指南：从 1.x 到 2.7 的完整迁移路径
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.13 | python --version |
| 磁盘空间 | http-client 后端 ≥2GB，本地模型 ≥20GB | df -h |
| GPU | vlm/hybrid 后端需 Volta 及以后架构、8GB 显存；pipeline 支持纯 CPU | nvidia-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_SOURCE=modelscope，再重跑mineru-models-download。
预期结果：模型改从 ModelScope 拉取，下载速度恢复正常。
破坏性变更速查：1.x 升上来要改什么
从 1.x 升上去，主要工作量在改代码和脚本，对照下面这张表逐行核对即可：
| 变更项 | 旧写法 | 新写法 | 影响面 |
|---|---|---|---|
| 包导入 | import magic_pdf | import mineru | 所有引用旧包的 Python 代码 |
| 命令行 | magic-pdf -p input.pdf | mineru -p input.pdf | 所有 shell 脚本与定时任务 |
| 配置文件 | magic-pdf.json（1.x） | ~/.mineru.json（2.x 自动生成） | 1.x 多数配置项已改为命令行参数，不再手编 JSON |
| 默认后端 | pipeline | hybrid-auto-engine（2.7 起） | 输出细节可能变化，加-b pipeline可切回 |
| VLM 模型 | MinerU2.0-2505-0.9B | MinerU2.5 | 2.5 起不再支持，最后支持版本 2.2.2 |
| Office 文档 | 内置 LibreOffice 先转 PDF | DOCX/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_SOURCE=modelscope，再重跑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-pdf==1.3.12" cp ~/.mineru.json.backup ~/.mineru.json2.x 内部回退同理，锁定版本即可，例如uv pip install "mineru==2.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），仅供参考