MinerU 升级指南如何从 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 升级指南按“备份 → 升级 → 验证 → 回滚”的顺序带你把 MinerU 从 1.xmagic-pdf一路升到 2.x 最新系列。读完你会清楚三件事该升到哪个版本、命令行和代码要改哪里、升级失败如何退回原状。适用范围覆盖 1.x → 2.0.x 与 2.0.x → 2.7 两条路径。️ 版本全景你该升到哪先对照下表定位自己版本区间包名 / 命令关键变化硬件门槛1.xmagic-pdf/magic-pdf模型需手动放置内置 LibreOffice 转换 Office 文档无强制显存要求2.0.xmineru/mineru包名与命令改名去掉 pymupdf 依赖模型自动下载更新输出统一为 middle_jsonPython 3.10-3.132.7mineru/mineru新增hybrid后端并成为默认hybrid-auto-engineOCR 支持 109 种语言适配多款国产算力卡vlm/hybrid 引擎后端需 8GB 显存Volta 及以上怎么选你在 1.x直接升到最新 2.7中间版本不用停你在 2.0-2.6只需更新包并重新下载模型。纯 CPU 机器不用纠结后端全程用pipeline即可最低 4GB 显存或纯 CPU 可跑。️ 升级主线三步走完准备阶段升级前检查清单先确认环境达标。2.x 只支持 Python 3.10-3.13模型加依赖至少占 20GB 磁盘python --version mineru --version # 或 magic-pdf -v确认你现在处于哪个区间 df -h输出版本落在 3.10-3.13、磁盘余量大于 20GB这一步就算通过。如果你有自定义配置文件通常是~/.mineru.json先备份——升级可能覆盖它。备份只是复制一份没有风险cp ~/.mineru.json ~/.mineru.json.bak旧模型的缓存目录不要删。留它在原地是后面回滚的退路。执行阶段卸载旧版并安装新版卸载会移除现有命令和依赖装新版本前没有回头余地确认备份完成再执行uv pip uninstall magic-pdf -y uv pip uninstall mineru -y uv pip install -U mineru[all]mineru[all]从 2.7.0 起已包含全部可选后端依赖不用再单独装 VLM 引擎。执行后pip show mineru能看到新版本号说明安装成功。验证阶段下载模型并跑通首次解析export MINERU_MODEL_SOURCEmodelscope # 国内网络用这一行 mineru-models-download --type all mineru -p demo/pdfs/demo1.pdf -o output/下载命令跑完会打印下载完成的日志解析命令结束后在output/下能找到与输入同名的子目录里面有.md、切出的图片和 middle JSON首次解析就算通过。⚠️ 不兼容变更迁移表三处必改旧用法1.x新用法2.x影响范围import magic_pdfimport mineru所有 Python 脚本与二次开发magic-pdf -p x.pdf -o out/mineru -p x.pdf -o out/shell 脚本、定时任务、CI依赖内置 LibreOffice 转 Officedocx/pptx/xlsx 可直接输入由 office 后端解析必须走 LibreOffice 时先libreoffice --headless --convert-to pdf再解析Office 文档工作流全局搜一遍仓库里的magic-pdf和magic_pdf替换完才算迁移完成。❓ 常见问题Q1升级后mineru: command not found或报No module named magic_pdf现象旧命令和旧 import 全失效。原因2.0.0 起包名和 CLI 都从 magic-pdf 改成了 mineru。解法命令改用mineru代码改用import mineru两处都改。Q2模型下载反复超时现象mineru-models-download卡在连接阶段。原因默认源在境外网络不通。解法设置export MINERU_MODEL_SOURCEmodelscope后重跑下载命令换源即可。Q3pip 报依赖冲突或 CUDA 不匹配现象安装阶段报错或装完 torch 跑不起来。原因旧版本残留依赖与新版本打架或 torch 的 CUDA 版本与本机不符。解法新建干净环境再装uv venv source .venv/bin/activate uv pip install -U mineru[all]CUDA 侧用nvcc --version对照安装匹配版本的 torch。Q4vlm 后端启动即 OOM现象显存爆掉或进程被杀。原因vlm/hybrid 引擎后端最低要 8GB 显存且需 Volta 及以上架构纯 CPU 机器不适用。解法加-b pipeline走 CPU 流水线或把模型服务放到远端 GPU 机器本地用 http-client 后端通过-u指向服务地址。 生产环境与回滚生产机器建议分批走测试环境装完并验证通过再上小流量观察一天无异常才全量。任一步异常就回滚回滚前提是旧版模型缓存和配置备份还在uv pip uninstall mineru -y uv pip install magic-pdf1.3.12 cp ~/.mineru.json.bak ~/.mineru.json具体每个小版本改了什么查官方更新日志docs/zh/reference/changelog.md安装细节看 docs/zh/quick_start/index.md。✅ 行动清单升级本质就是一次换包加一次模型重下风险只藏在被忽略的变更里。逐项打勾再动手python --version在 3.10-3.13磁盘余量大于 20GB配置已备份为~/.mineru.json.bak旧模型缓存保留旧包已卸载uv pip install -U mineru[all]装完新版mineru-models-download --type all正常结束样例 PDF 首次解析通过md 与图片输出齐全脚本里所有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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MinerU 升级指南：如何从 1.x 平滑升到 2.x（附回滚命令）
MinerU 升级指南如何从 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 升级指南按“备份 → 升级 → 验证 → 回滚”的顺序带你把 MinerU 从 1.xmagic-pdf一路升到 2.x 最新系列。读完你会清楚三件事该升到哪个版本、命令行和代码要改哪里、升级失败如何退回原状。适用范围覆盖 1.x → 2.0.x 与 2.0.x → 2.7 两条路径。️ 版本全景你该升到哪先对照下表定位自己版本区间包名 / 命令关键变化硬件门槛1.xmagic-pdf/magic-pdf模型需手动放置内置 LibreOffice 转换 Office 文档无强制显存要求2.0.xmineru/mineru包名与命令改名去掉 pymupdf 依赖模型自动下载更新输出统一为 middle_jsonPython 3.10-3.132.7mineru/mineru新增hybrid后端并成为默认hybrid-auto-engineOCR 支持 109 种语言适配多款国产算力卡vlm/hybrid 引擎后端需 8GB 显存Volta 及以上怎么选你在 1.x直接升到最新 2.7中间版本不用停你在 2.0-2.6只需更新包并重新下载模型。纯 CPU 机器不用纠结后端全程用pipeline即可最低 4GB 显存或纯 CPU 可跑。️ 升级主线三步走完准备阶段升级前检查清单先确认环境达标。2.x 只支持 Python 3.10-3.13模型加依赖至少占 20GB 磁盘python --version mineru --version # 或 magic-pdf -v确认你现在处于哪个区间 df -h输出版本落在 3.10-3.13、磁盘余量大于 20GB这一步就算通过。如果你有自定义配置文件通常是~/.mineru.json先备份——升级可能覆盖它。备份只是复制一份没有风险cp ~/.mineru.json ~/.mineru.json.bak旧模型的缓存目录不要删。留它在原地是后面回滚的退路。执行阶段卸载旧版并安装新版卸载会移除现有命令和依赖装新版本前没有回头余地确认备份完成再执行uv pip uninstall magic-pdf -y uv pip uninstall mineru -y uv pip install -U mineru[all]mineru[all]从 2.7.0 起已包含全部可选后端依赖不用再单独装 VLM 引擎。执行后pip show mineru能看到新版本号说明安装成功。验证阶段下载模型并跑通首次解析export MINERU_MODEL_SOURCEmodelscope # 国内网络用这一行 mineru-models-download --type all mineru -p demo/pdfs/demo1.pdf -o output/下载命令跑完会打印下载完成的日志解析命令结束后在output/下能找到与输入同名的子目录里面有.md、切出的图片和 middle JSON首次解析就算通过。⚠️ 不兼容变更迁移表三处必改旧用法1.x新用法2.x影响范围import magic_pdfimport mineru所有 Python 脚本与二次开发magic-pdf -p x.pdf -o out/mineru -p x.pdf -o out/shell 脚本、定时任务、CI依赖内置 LibreOffice 转 Officedocx/pptx/xlsx 可直接输入由 office 后端解析必须走 LibreOffice 时先libreoffice --headless --convert-to pdf再解析Office 文档工作流全局搜一遍仓库里的magic-pdf和magic_pdf替换完才算迁移完成。❓ 常见问题Q1升级后mineru: command not found或报No module named magic_pdf现象旧命令和旧 import 全失效。原因2.0.0 起包名和 CLI 都从 magic-pdf 改成了 mineru。解法命令改用mineru代码改用import mineru两处都改。Q2模型下载反复超时现象mineru-models-download卡在连接阶段。原因默认源在境外网络不通。解法设置export MINERU_MODEL_SOURCEmodelscope后重跑下载命令换源即可。Q3pip 报依赖冲突或 CUDA 不匹配现象安装阶段报错或装完 torch 跑不起来。原因旧版本残留依赖与新版本打架或 torch 的 CUDA 版本与本机不符。解法新建干净环境再装uv venv source .venv/bin/activate uv pip install -U mineru[all]CUDA 侧用nvcc --version对照安装匹配版本的 torch。Q4vlm 后端启动即 OOM现象显存爆掉或进程被杀。原因vlm/hybrid 引擎后端最低要 8GB 显存且需 Volta 及以上架构纯 CPU 机器不适用。解法加-b pipeline走 CPU 流水线或把模型服务放到远端 GPU 机器本地用 http-client 后端通过-u指向服务地址。 生产环境与回滚生产机器建议分批走测试环境装完并验证通过再上小流量观察一天无异常才全量。任一步异常就回滚回滚前提是旧版模型缓存和配置备份还在uv pip uninstall mineru -y uv pip install magic-pdf1.3.12 cp ~/.mineru.json.bak ~/.mineru.json具体每个小版本改了什么查官方更新日志docs/zh/reference/changelog.md安装细节看 docs/zh/quick_start/index.md。✅ 行动清单升级本质就是一次换包加一次模型重下风险只藏在被忽略的变更里。逐项打勾再动手python --version在 3.10-3.13磁盘余量大于 20GB配置已备份为~/.mineru.json.bak旧模型缓存保留旧包已卸载uv pip install -U mineru[all]装完新版mineru-models-download --type all正常结束样例 PDF 首次解析通过md 与图片输出齐全脚本里所有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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考