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/MinerUMinerU 从 1.x 到 2.x 的升级涉及包名、命令行、模型管理三处变化本文按你的当前版本把 1.x 到 2.x 升级拆成三条独立路径覆盖卸载、重装、模型重新下载与回滚到旧版本的完整操作。升级决策该不该升、升到哪个版本先跑mineru --version1.x 为magic-pdf --version确认当前版本再对照下三条路径走当前版本目标版本升级性质说明1.x最新 2.x重大升级需卸载旧包、改名import、重新下载模型2.0.x ~ 2.0.62.1.x 及以上常规升级直接安装新版包注意 2.5 后模型与引擎变更2.1.x 及以上最新小版本热更新升级包即可模型自动管理值得升级的判断标准很简单你要用vlm/hybrid后端、多语言 OCR37 种语言起、更强的表格解析或者需要内置 FastAPI/Gradio 服务那就该升。三条升级路径路径一1.x 到 2.xmagic-pdf 迁移到 mineru备份配置与模型目录cp ~/.magic-pdf.json ~/.magic-pdf.json.bak cp -r ~/.cache/modelscope ~/.cache/modelscope.bak 2/dev/null卸载旧包uninstall只移除 Python 包不动你的文档与模型缓存如果环境里依赖较多更稳妥的做法是直接新建一个干净虚拟环境uv pip uninstall magic-pdf -y uv pip install -U mineru[all]触发模型重新下载跑一次解析即可首次运行会按新版本自动拉取所需模型。国内网络可先执行export MINERU_MODEL_SOURCEmodelscope。全局搜索并替换代码里的import magic_pdf为import mineru。这里有个坑2.0 起包名改了老代码不改会直接抛 ImportError。路径二2.0.x 升到 2.1.x 及以上同样先备份配置文件位置见破坏性变更对照再执行uv pip install -U mineru[all]2.7.0 起默认解析后端从pipeline切到hybrid-auto-engine如果你此前显式指定过后端参数升级后核对一次解析结果是否符合预期。注意 2.5.x 的 vlm 后端只兼容 MinerU2.5 模型不再兼容 2.0-2505-0.9B 模型最后一个支持旧模型的版本是 mineru-2.2.2。加速引擎从sglang切到了vllm脚本里如有vlm-sglang-engine之类的旧参数改成对应的*-auto-engine或 vllm 写法。路径三小版本热更新直接升级包命令与路径二第 1 步相同uv pip install -U mineru[all]。模型由新版本自动管理一般无需手动操作仅当升级日志提示模型缺失时跑一次解析触发自动下载。破坏性变更对照旧1.x / 2.0 之前新2.x包名magic-pdf代码里import magic_pdf包名mineruimport mineru命令magic-pdf -p in.pdf -o out/命令mineru -p in.pdf -o out/配置文件~/.magic-pdf.json配置文件~/.mineru.json内置 LibreOffice 直接转 Office 文档移除该模块需独立 LibreOffice 先转 PDFvlm 加速用 sglangvlm 加速切换至 vllm模型手动下载管理模型自动下载与更新验证三步法版本确认mineru --version输出应为你的目标版本号。功能冒烟mineru -p demo/pdfs/demo1.pdf -o ./output能生成 Markdown 即通过。性能基线用time包住同一条解析命令和升级前的耗时记录对比偏差超过 30% 再排查。回滚预案以下操作会移除当前版本并恢复旧配置执行前确认已保存本次升级产生的输出文件uv pip uninstall mineru -y uv pip install magic-pdf1.3.12 # 或升级前记录的版本号 cp ~/.mineru.json.bak ~/.magic-pdf.json出现以下信号就该回滚别硬扛升级后连续两次解析失败或中断核心功能输出与升级前明显不一致乱码、丢表格显存占用或耗时异常暴涨。回滚前先记录旧版本号和新版本报错方便定位。故障速查报错现象原因修复ImportError: No module named magic_pdf包名已改为mineru旧代码没同步代码中import magic_pdf改为import mineru安装后依赖冲突、import 报版本不匹配旧版残留依赖与新包冲突新建干净虚拟环境uv venv uv pip install mineru[all]模型下载超时或失败默认源 huggingface 不可达export MINERU_MODEL_SOURCEmodelscope后重跑解析CUDA error或 torch 加载失败torch 与驱动 CUDA 版本不匹配nvcc --version核对后按 PyTorch 官网选匹配 wheel 重装 torch版本能力对比能力1.x2.0.x2.1.x 及以上包名与命令magic-pdfminerumineru模型管理手动下载自动下载自动管理 离线下载命令多语言 OCR有限基础37 种语言起hybrid 支持 109 种加速引擎无sglangvllm / lmdeploy8G 显存Turing可跑内置服务无无FastAPI Gradio router生产环境建议先在测试环境完整走一遍验证三步法通过后再动生产分批灰度升级升级前记录旧版本号、备份~/.mineru.json与模型缓存保留旧环境至少一个迭代周期依赖 2.x 新结构middle_json、content_list.json 字段有调整的下游二次开发先做一轮回归再放量。已备份配置文件与模型缓存已记录旧版本号并测好性能基线已卸载旧包并安装目标版本模型已按新源重新下载冒烟解析通过输出正常下游代码中的旧包名/命令已替换回滚命令已备好并验证可执行记住升级出问题先回滚再排查。【免费下载链接】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/MinerUMinerU 从 1.x 到 2.x 的升级涉及包名、命令行、模型管理三处变化本文按你的当前版本把 1.x 到 2.x 升级拆成三条独立路径覆盖卸载、重装、模型重新下载与回滚到旧版本的完整操作。升级决策该不该升、升到哪个版本先跑mineru --version1.x 为magic-pdf --version确认当前版本再对照下三条路径走当前版本目标版本升级性质说明1.x最新 2.x重大升级需卸载旧包、改名import、重新下载模型2.0.x ~ 2.0.62.1.x 及以上常规升级直接安装新版包注意 2.5 后模型与引擎变更2.1.x 及以上最新小版本热更新升级包即可模型自动管理值得升级的判断标准很简单你要用vlm/hybrid后端、多语言 OCR37 种语言起、更强的表格解析或者需要内置 FastAPI/Gradio 服务那就该升。三条升级路径路径一1.x 到 2.xmagic-pdf 迁移到 mineru备份配置与模型目录cp ~/.magic-pdf.json ~/.magic-pdf.json.bak cp -r ~/.cache/modelscope ~/.cache/modelscope.bak 2/dev/null卸载旧包uninstall只移除 Python 包不动你的文档与模型缓存如果环境里依赖较多更稳妥的做法是直接新建一个干净虚拟环境uv pip uninstall magic-pdf -y uv pip install -U mineru[all]触发模型重新下载跑一次解析即可首次运行会按新版本自动拉取所需模型。国内网络可先执行export MINERU_MODEL_SOURCEmodelscope。全局搜索并替换代码里的import magic_pdf为import mineru。这里有个坑2.0 起包名改了老代码不改会直接抛 ImportError。路径二2.0.x 升到 2.1.x 及以上同样先备份配置文件位置见破坏性变更对照再执行uv pip install -U mineru[all]2.7.0 起默认解析后端从pipeline切到hybrid-auto-engine如果你此前显式指定过后端参数升级后核对一次解析结果是否符合预期。注意 2.5.x 的 vlm 后端只兼容 MinerU2.5 模型不再兼容 2.0-2505-0.9B 模型最后一个支持旧模型的版本是 mineru-2.2.2。加速引擎从sglang切到了vllm脚本里如有vlm-sglang-engine之类的旧参数改成对应的*-auto-engine或 vllm 写法。路径三小版本热更新直接升级包命令与路径二第 1 步相同uv pip install -U mineru[all]。模型由新版本自动管理一般无需手动操作仅当升级日志提示模型缺失时跑一次解析触发自动下载。破坏性变更对照旧1.x / 2.0 之前新2.x包名magic-pdf代码里import magic_pdf包名mineruimport mineru命令magic-pdf -p in.pdf -o out/命令mineru -p in.pdf -o out/配置文件~/.magic-pdf.json配置文件~/.mineru.json内置 LibreOffice 直接转 Office 文档移除该模块需独立 LibreOffice 先转 PDFvlm 加速用 sglangvlm 加速切换至 vllm模型手动下载管理模型自动下载与更新验证三步法版本确认mineru --version输出应为你的目标版本号。功能冒烟mineru -p demo/pdfs/demo1.pdf -o ./output能生成 Markdown 即通过。性能基线用time包住同一条解析命令和升级前的耗时记录对比偏差超过 30% 再排查。回滚预案以下操作会移除当前版本并恢复旧配置执行前确认已保存本次升级产生的输出文件uv pip uninstall mineru -y uv pip install magic-pdf1.3.12 # 或升级前记录的版本号 cp ~/.mineru.json.bak ~/.magic-pdf.json出现以下信号就该回滚别硬扛升级后连续两次解析失败或中断核心功能输出与升级前明显不一致乱码、丢表格显存占用或耗时异常暴涨。回滚前先记录旧版本号和新版本报错方便定位。故障速查报错现象原因修复ImportError: No module named magic_pdf包名已改为mineru旧代码没同步代码中import magic_pdf改为import mineru安装后依赖冲突、import 报版本不匹配旧版残留依赖与新包冲突新建干净虚拟环境uv venv uv pip install mineru[all]模型下载超时或失败默认源 huggingface 不可达export MINERU_MODEL_SOURCEmodelscope后重跑解析CUDA error或 torch 加载失败torch 与驱动 CUDA 版本不匹配nvcc --version核对后按 PyTorch 官网选匹配 wheel 重装 torch版本能力对比能力1.x2.0.x2.1.x 及以上包名与命令magic-pdfminerumineru模型管理手动下载自动下载自动管理 离线下载命令多语言 OCR有限基础37 种语言起hybrid 支持 109 种加速引擎无sglangvllm / lmdeploy8G 显存Turing可跑内置服务无无FastAPI Gradio router生产环境建议先在测试环境完整走一遍验证三步法通过后再动生产分批灰度升级升级前记录旧版本号、备份~/.mineru.json与模型缓存保留旧环境至少一个迭代周期依赖 2.x 新结构middle_json、content_list.json 字段有调整的下游二次开发先做一轮回归再放量。已备份配置文件与模型缓存已记录旧版本号并测好性能基线已卸载旧包并安装目标版本模型已按新源重新下载冒烟解析通过输出正常下游代码中的旧包名/命令已替换回滚命令已备好并验证可执行记住升级出问题先回滚再排查。【免费下载链接】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），仅供参考