MinerU 版本升级指南四步完成从 magic-pdf 到 mineru 的迁移附回滚方案【免费下载链接】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-pdf1.x时代还是已经用了 2.x 想跟上最新版当前稳定版为 3.4.4本文都会告诉你要不要升、走哪条路线、动手怎么执行、失败了怎么退回。读完之后你可以独立在测试环境完成一次完整升级并做验收不需要额外翻别的资料。一、如何判断是否需要升级 MinerU 版本升级不是例行公事先看下面这些信号命中任意一条就值得排期升级。触发信号不升级的代价你的脚本仍调用magic-pdf命令或import magic_pdf旧包停止维护bug 和依赖漏洞如 pdfminer.six 的 CVE 已在 2.7.1 修复不会在你手上修需要跨页表合并、hybrid 后端、109 种语言 OCR 等新能力解析精度和能力停留在旧版本扫描版/多语言文档效果明显吃亏环境是旧版 LinuxCentOS 7 等或 torch/sglang 老版本2.2.0 起已移除对老系统的安装支持升级后无法安装新依赖想跑 MinerU2.5 模型或 vllm 加速2.2.2 是最后一个支持旧 VLM 模型的版本之后模型与引擎都已更换如果你的业务长期只解析简单的文本型 PDF且没有任何报错可以先把升级排在下一个维护窗口。二、按版本区间选择 MinerU 升级路线先执行mineru --version旧版为magic-pdf --version确认你所在区间再对号入座。四条路线互斥风险与耗时差异很大。当前版本区间升级路线风险与耗时magic-pdf 1.x迁移到 mineru 2.x 以上最新版包名、命令、import 全部变更脚本需逐项改约半天2.0.x - 2.1.x升级到 2.7 / 3.xVLM 加速引擎由 sglang 切换为 vllm模型需重新下载含模型下载约一天2.2.x - 2.5.x升级到最新版VLM 模型更换为 MinerU2.5旧模型缓存不再兼容数小时2.7.x - 3.x 小版本直接升级安装包风险最低分钟级完成仅跑一次冒烟验证Python 环境统一要求 3.10-3.13python --version检查四条路线通用。三、MinerU 升级执行四步备份、换包、补模型、冒烟以下命令假设你使用 uv 管理依赖全程在一个干净的虚拟环境里做。第 1 拍留退路。目的把升级前状态固化下来回滚时可直接还原。cp ~/.mineru.json ~/.mineru.json.bak cp -r ~/.cache/mineru ~/.cache/mineru_backup第 2 拍换版本。目的彻底清除旧包残留避免新旧依赖混装。uv pip uninstall magic-pdf -y # 1.x 用户执行2.x 用户跳过 uv pip uninstall mineru -y uv pip install -U mineru[all]第 3 拍补依赖与模型。目的新版本自带模型自动管理机制用内置命令拉齐模型文件并写入配置。mineru-models-download -m all只跑单一后端时可改为-m pipeline或-m vlm下载量更小。第 4 拍冒烟验证。目的用最小输入确认整条链路可用。mineru --version mineru -p demo/pdfs/demo1.pdf -o out/输出目录下应生成 markdown 与 JSON 结果文件-b参数可指定后端默认hybrid-auto-engine-l指定 OCR 语言可提升识别精度。四、MinerU 不兼容变更新旧对照跨大版本升级时按这张表逐项替换脚本和调用即可。旧1.x / 旧 2.x新2.0 / 最新版包名magic-pdfmineruimport magic_pdfimport minerumagic-pdf -p input.pdf -o output/mineru -p input.pdf -o output/内置 LibreOffice 转换 Office 文档先自行转 PDFlibreoffice --headless --convert-to pdf 文件.docx默认后端pipeline默认后端hybrid-auto-engine2.7.0 起vlm 加速引擎sglangvllm2.5 起手动编辑 JSON 配置管理模型命令行参数 mineru-models-download自动管理五、升级验收清单与回滚命令验收按勾选进行全部通过再宣布升级完成。mineru --version输出为目标版本号示例 PDF 解析后输出目录生成 markdown 和 JSON 结果抽查一处表格与一处公式结构无缺失所有脚本、CI 中的magic-pdf已替换为mineru二次运行不再提示下载模型缓存完整任一环节失败且短时间无法定位直接执行回滚uv pip uninstall mineru -y uv pip install mineru升级前版本号 # 2.x 回 2.x1.x 用户改装 magic-pdf1.3.12 cp ~/.mineru.json.bak ~/.mineru.json六、MinerU 升级后常见报错急救magic-pdf: command not found或No module named magic_pdf报错怎么办原因2.0 起包名与命令已改为mineru旧命令永久失效。解决把脚本里的命令和 import 全部替换为mineru并执行uv pip uninstall magic-pdf -y清掉旧包。模型下载失败或超时报错怎么办原因默认源在部分网络下不可达。解决切换到 ModelScope 源后重试。export MINERU_MODEL_SOURCEmodelscope mineru-models-download -m all升级后依赖冲突、import 即崩溃怎么办原因旧版本包残留在当前环境与新依赖互相覆盖。解决放弃修复旧环境重建干净环境。uv venv source .venv/bin/activate uv pip install -U mineru[all]升级本身并不复杂真正的成本在路线判断与旧脚本清理先确认版本区间再动手备份做到位回滚才有底。各版本的详细变更记录见 docs/zh/reference/changelog.md遇到本文未覆盖的问题建议到项目 Issues 与 Discussions 区搜索相同报错多数场景已有现成结论。【免费下载链接】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 版本升级指南：四步完成从 magic-pdf 到 mineru 的迁移（附回滚方案）
MinerU 版本升级指南四步完成从 magic-pdf 到 mineru 的迁移附回滚方案【免费下载链接】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-pdf1.x时代还是已经用了 2.x 想跟上最新版当前稳定版为 3.4.4本文都会告诉你要不要升、走哪条路线、动手怎么执行、失败了怎么退回。读完之后你可以独立在测试环境完成一次完整升级并做验收不需要额外翻别的资料。一、如何判断是否需要升级 MinerU 版本升级不是例行公事先看下面这些信号命中任意一条就值得排期升级。触发信号不升级的代价你的脚本仍调用magic-pdf命令或import magic_pdf旧包停止维护bug 和依赖漏洞如 pdfminer.six 的 CVE 已在 2.7.1 修复不会在你手上修需要跨页表合并、hybrid 后端、109 种语言 OCR 等新能力解析精度和能力停留在旧版本扫描版/多语言文档效果明显吃亏环境是旧版 LinuxCentOS 7 等或 torch/sglang 老版本2.2.0 起已移除对老系统的安装支持升级后无法安装新依赖想跑 MinerU2.5 模型或 vllm 加速2.2.2 是最后一个支持旧 VLM 模型的版本之后模型与引擎都已更换如果你的业务长期只解析简单的文本型 PDF且没有任何报错可以先把升级排在下一个维护窗口。二、按版本区间选择 MinerU 升级路线先执行mineru --version旧版为magic-pdf --version确认你所在区间再对号入座。四条路线互斥风险与耗时差异很大。当前版本区间升级路线风险与耗时magic-pdf 1.x迁移到 mineru 2.x 以上最新版包名、命令、import 全部变更脚本需逐项改约半天2.0.x - 2.1.x升级到 2.7 / 3.xVLM 加速引擎由 sglang 切换为 vllm模型需重新下载含模型下载约一天2.2.x - 2.5.x升级到最新版VLM 模型更换为 MinerU2.5旧模型缓存不再兼容数小时2.7.x - 3.x 小版本直接升级安装包风险最低分钟级完成仅跑一次冒烟验证Python 环境统一要求 3.10-3.13python --version检查四条路线通用。三、MinerU 升级执行四步备份、换包、补模型、冒烟以下命令假设你使用 uv 管理依赖全程在一个干净的虚拟环境里做。第 1 拍留退路。目的把升级前状态固化下来回滚时可直接还原。cp ~/.mineru.json ~/.mineru.json.bak cp -r ~/.cache/mineru ~/.cache/mineru_backup第 2 拍换版本。目的彻底清除旧包残留避免新旧依赖混装。uv pip uninstall magic-pdf -y # 1.x 用户执行2.x 用户跳过 uv pip uninstall mineru -y uv pip install -U mineru[all]第 3 拍补依赖与模型。目的新版本自带模型自动管理机制用内置命令拉齐模型文件并写入配置。mineru-models-download -m all只跑单一后端时可改为-m pipeline或-m vlm下载量更小。第 4 拍冒烟验证。目的用最小输入确认整条链路可用。mineru --version mineru -p demo/pdfs/demo1.pdf -o out/输出目录下应生成 markdown 与 JSON 结果文件-b参数可指定后端默认hybrid-auto-engine-l指定 OCR 语言可提升识别精度。四、MinerU 不兼容变更新旧对照跨大版本升级时按这张表逐项替换脚本和调用即可。旧1.x / 旧 2.x新2.0 / 最新版包名magic-pdfmineruimport magic_pdfimport minerumagic-pdf -p input.pdf -o output/mineru -p input.pdf -o output/内置 LibreOffice 转换 Office 文档先自行转 PDFlibreoffice --headless --convert-to pdf 文件.docx默认后端pipeline默认后端hybrid-auto-engine2.7.0 起vlm 加速引擎sglangvllm2.5 起手动编辑 JSON 配置管理模型命令行参数 mineru-models-download自动管理五、升级验收清单与回滚命令验收按勾选进行全部通过再宣布升级完成。mineru --version输出为目标版本号示例 PDF 解析后输出目录生成 markdown 和 JSON 结果抽查一处表格与一处公式结构无缺失所有脚本、CI 中的magic-pdf已替换为mineru二次运行不再提示下载模型缓存完整任一环节失败且短时间无法定位直接执行回滚uv pip uninstall mineru -y uv pip install mineru升级前版本号 # 2.x 回 2.x1.x 用户改装 magic-pdf1.3.12 cp ~/.mineru.json.bak ~/.mineru.json六、MinerU 升级后常见报错急救magic-pdf: command not found或No module named magic_pdf报错怎么办原因2.0 起包名与命令已改为mineru旧命令永久失效。解决把脚本里的命令和 import 全部替换为mineru并执行uv pip uninstall magic-pdf -y清掉旧包。模型下载失败或超时报错怎么办原因默认源在部分网络下不可达。解决切换到 ModelScope 源后重试。export MINERU_MODEL_SOURCEmodelscope mineru-models-download -m all升级后依赖冲突、import 即崩溃怎么办原因旧版本包残留在当前环境与新依赖互相覆盖。解决放弃修复旧环境重建干净环境。uv venv source .venv/bin/activate uv pip install -U mineru[all]升级本身并不复杂真正的成本在路线判断与旧脚本清理先确认版本区间再动手备份做到位回滚才有底。各版本的详细变更记录见 docs/zh/reference/changelog.md遇到本文未覆盖的问题建议到项目 Issues 与 Discussions 区搜索相同报错多数场景已有现成结论。【免费下载链接】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），仅供参考