企业官网建设流程全解析

MinerU 版本升级：4步完成1.x到2.x的完整升级，避开不兼容的坑

【免费下载链接】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 做版本升级时，被"找不到 magic_pdf 模块"之类的报错卡住过？MinerU 这个把 PDF、Office 文档转成 Markdown 的解析工具，老用户从 1.x 升上来时，最容易在包名和命令变更上翻车。其实这条升级路线并不复杂，真正的分叉只有一个：你还在不在 1.x 那个magic-pdf时代。这篇把升级主线、3个高频坑、验证和回退方法一次讲清，30分钟内就能完成切换，不用反复翻文档。

📍 定位你的版本

动手前先花30秒确认你在哪一档：如果你一直在用的命令还是magic-pdf，说明你在 1.x 时代；如果mineru已经装好，直接看版本号对号入座：

一句话说透：1.x 的用户要跨这次升级里最大的一道坎，包名、命令、配置文件全换了，得顺手改脚本；而 2.x 之间的升级就是"覆盖安装 + 补下模型"，跟升级任何 Python 包没区别。

对了，不管哪个版本，MinerU 干的事都一样：把杂乱 PDF 变成结构化 Markdown，整个解析流程长这样：

🚀 走通升级主线

备份配置和模型

先看整条主线，5步按顺序走，别跳步：

动任何手脚前，先备份用户目录下的配置文件和模型缓存。模型有好几个 G，重下很慢；配置里存着你自定义的公式分隔符、本地模型路径这些设置，丢了重写麻烦。

cp ~/.mineru.json ~/.mineru.json.backup cp -r ~/.cache/mineru ~/mineru_models_backup

干净卸载旧版本

这一步很多人会忘——1.x 和 2.x 是两个不同的包名，不卸干净的话新旧两份会共存，命令指向的可能是旧版，比不升级还乱。

uv pip uninstall magic-pdf mineru -y

安装新版本

其实很简单，新版开箱即用，一条命令装全所有可选后端；如果只跑核心解析功能，也可以把后缀换成mineru[core]省空间。

uv pip install -U "mineru[all]"

下载新模型

新版对应的是新一代模型文件，不会自己冒出来。跑一次内置下载命令，它会增量补齐缺失的模型，并自动生成新的mineru.json配置，后面首次解析才不会报错。

mineru-models-download

⚠️ 避开3个高频坑

依赖冲突导致安装失败

现象是安装中途报版本冲突，或者装完 mineru 一运行就报缺模块。多半是老环境历史依赖太多，新装的东西往上叠就打架了。最稳的办法是开一个干净的虚拟环境重装：

uv venv mineru-env && source mineru-env/bin/activate uv pip install "mineru[all]"

模型下载卡住或超时

现象是下载命令长时间没动静，或报连接失败。通常是当前网络访问不了默认模型源，切换 ModelScope 源一般就能通；如果是常驻服务机，把这个环境变量固定写进启动脚本。

export MINERU_MODEL_SOURCE=modelscope mineru-models-download

老脚本还在调用 magic-pdf

现象是新版装好了，原有脚本和定时任务却报"找不到命令"。这一步最容易漏：2.0.0 起包名改了，脚本里的magic-pdf命令和import magic_pdf都得换成mineru。先搜出所有调用位置，再全局替换：

grep -rn "magic-pdf\|magic_pdf" scripts/

升级前后对照

这5项里，模型管理和默认后端的变更对普通用户是完全透明的，你什么都不用做。必须手动处理的是调用方式：把脚本和定时任务里的magic-pdf找出来改名就行。显存从 6GB 提到 8GB，用老卡跑的朋友要留意一下。

✅ 验证、回退与后续关注

最后确认升级真的成功。最短的验证就是直接解析仓库里的示例文件，输出目录里出现 Markdown 和图片，就说明没问题：

mineru -p demo/pdfs/demo1.pdf -o output/

如果新版实在跑不动，别急，回退路线就是升级的逆操作：卸掉新包、装回旧包、恢复备份的配置，核心命令就一条：

uv pip install magic-pdf==1.3.12

后续关注3个渠道就够了：

• 官方 Release 页
• Discord 社区
• 官方文档更新日志

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU