MinerU 从 1.x 迁移到 2.x/3.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 从 1.x 到 2.x 再到 3.x 的版本迁移如何判断自己处于哪个版本区间、哪些变更会破坏现有脚本、以及升级失败后如何回退。读完后可直接按下面的定位表选择执行路径在测试机上独立完成一次升级验证。 版本迁移快速定位表先确认当前状态pip show magic-pdf或pip show mineru看版本which mineru看入口命令。你的当前状态目标版本入口章节magic-pdf 1.x含 magic-pdf.json 配置2.x / 3.x场景一mineru 2.0–2.4sglang 时代0.9B vlm 模型2.5场景二mineru 2.5–2.6vllm 已引入2.7 / 3.x场景三mineru 2.7hybrid 默认后端3.x 最新场景三Docker / compose 部署最新镜像场景三 影响面扫描按对现有流程的影响半径排序从大到小依次是包名/入口命令 Office 处理链路 模型加载机制 默认后端 中间文件格式 配置文件。对照下表逐项确认任何一项需要做的事为空才可以跳过。变更项按影响半径旧行为新行为需要做什么包名与入口命令magic-pdf、import magic_pdf2.0 起统一为mineru、import mineru全局替换 import、CI 脚本、定时任务命令Office 文档链路内置 LibreOffice 转换2.0 移除该模块3.x 原生解析 docx/pptx/xlsx低版本先独立部署 LibreOffice 转 PDF升到 3.x 可直接投喂 Office 文件模型加载机制1.x 手动下载模型mineru-models-download自动下载更新2.5 的 vlm 不再支持 0.9B 模型升级后执行模型下载被锁在 0.9B 模型的版本上限是 2.2.2默认后端pipeline 为主2.7 默认 hybrid-auto-engine需复现旧结果时用-b pipeline固定后端中间文件格式middle.json 类型较少2.5 结构调整、布局类型更多2.2 增加 bbox 字段解析 middle.json / content_list.json 的二次开发代码需适配字段配置文件magic-pdf.json 手工维护多数参数支持 CLI/API 直接设置配置文件更名 mineru.json迁移自定义项路径模板见 mineru.template.json️ 分场景迁移执行手册场景一从 magic-pdf 1.x 迁移包名切换后如何修改 import 与脚本备份旧配置防止自定义参数丢失。cp ~/.magic-pdf.json ~/magic-pdf.json.bak # 仅当自定义过配置干净安装。旧包与 mineru 共存会抢占入口命令必须先在目标 venv 中卸载旧包。pip uninstall magic-pdf -y pip install mineru[all] # 需要 pipelinevlm 全部后端只用 API 客户端可装裸 mineru拉取新模型。1.x 的手动模型与 2.0 结构不通用必须重新下载。MINERU_MODEL_SOURCEmodelscope mineru-models-download --type all # 国内网络走 modelscope 源替换代码中的 import 与命令import magic_pdf改为import minerumagic-pdf -p ... -o ...改为mineru -p ... -o ...。核心参数-p/-o/-m/-b/-l语义保持一致脚本改动量主要在包名。场景二升级 2.0–2.4vLLM 引擎与 1.2B 模型的替换这一段的本质是 vlm 推理框架从 sglang 切换到 vllm且模型换成了 MinerU2.5-2509-1.2B两者都不向后兼容旧模型。确认显卡架构。Turing 及以后架构可直接用 vllm 加速更老的卡建议只用 pipeline 后端。python -c import torch; print(torch.cuda.get_device_capability()) # 主版本号 7 即 Turing升级包并补装 vllm 依赖vllm 对 torch 版本有下限装前先记录pip show torch。pip install -U mineru[vllm] # 需要 vllm0.10.1.1下载新 vlm 模型旧 0.9B 模型不会再被引用。mineru-models-download --type vlm # 拉取 MinerU2.5-1.2B如果你的业务依赖 0.9B 模型的行为不要强升——最后一个支持该模型的主包版本是 2.2.2保持现状或走场景三评估 1.2B 的结果差异。场景三升级 2.5默认后端切换的处理直接升级到最新即可2.7 的安装方式已简化为一条命令。pip install -U mineru[all]升级后先用旧后端复跑一份样本确认与旧版本输出一致再放开默认后端。mineru -p demo/pdfs/demo1.pdf -o output/ -b pipeline # 固定旧后端做回归对比对比通过后再走默认路径并按需指定 effort。mineru -p demo/pdfs/demo1.pdf -o output/ # 默认 hybrid-auto-engine # 需要图表分析时加 --effort highDocker 部署的用户拉取仓库内 docker/compose.yaml 对应的新镜像重建服务即可注意 mineru-api、mineru-gradio 两个服务入口命令名已统一带 mineru 前缀。 升级验证与回退一体化验证和回退必须成对做升级后跑通验证项之前不要通知下游切换流量。验证三步版本号、样例解析、产物结构。mineru --version # 确认目标版本已生效 mineru -p demo/pdfs/demo1.pdf -o output/ ls output/*/ # 应包含 markdown、content_list.json、middle.json 等产物再用旧版本曾解析过的文档抽 1–2 份人工比对标题层级、表格和公式是否仍符合预期。回退方案pip uninstall mineru -y pip install magic-pdf1.3.12 # 回 1.x或 pip install mineru2.2.2 回 2.x 末版 cp ~/magic-pdf.json.bak ~/.magic-pdf.json # 恢复旧配置如当初备份过回退后如何确认恢复正常magic-pdf --version显示旧版本用同一份样例文档重新解析产物目录结构和内容抽查与升级前一致即视为回退成功。注意模型缓存是共享目录回退后首次运行会自动按旧版本清单重新拉取模型属正常现象。❓ 常见边界情况速查Q升级后 import mineru 报模块冲突或入口行为怪异大概率是 magic-pdf 残留未卸干净两个包声明了部分同名资源。不要在旧环境里打补丁新建 venv 重装最省事。Q模型下载失败或环境无法访问 HuggingFace设置环境变量 MINERU_MODEL_SOURCEmodelscope 后再执行下载命令。完全断网的机器在线上机下载后整包拷贝模型缓存目录再部署。Q升级后解析结果与旧版本明显不一致优先怀疑默认后端变了2.7 是 hybrid-auto-engine先用 -b pipeline 复跑对比若一致则是模型升级带来的精度变化属预期行为而非事故。Qtorch/CUDA 依赖解析失败不要在老环境上叠加安装。干净 venv 中按显卡对应的 CUDA 先装 torch再装 mineru 的 extrasvllm 后端对 torch 版本有硬性下限。Q旧的 magic-pdf.json 配置还能用吗不能直接沿用。2.0 多数参数已支持命令行或 API 直传确需配置时改用 mineru.json字段以仓库内 mineru.template.json 为准可用 MINERU_TOOLS_CONFIG_JSON 指定配置路径。版本迁移的核心原则只有一条先固定后端、再换包、最后对齐模型三者错一个输出必漂移。更细的字段级变更与历史版本说明以仓库内 docs/zh/reference/changelog.md 更新日志和官方 issue 跟踪为准。【免费下载链接】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/3.x：版本迁移操作手册与回退方案
MinerU 从 1.x 迁移到 2.x/3.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 从 1.x 到 2.x 再到 3.x 的版本迁移如何判断自己处于哪个版本区间、哪些变更会破坏现有脚本、以及升级失败后如何回退。读完后可直接按下面的定位表选择执行路径在测试机上独立完成一次升级验证。 版本迁移快速定位表先确认当前状态pip show magic-pdf或pip show mineru看版本which mineru看入口命令。你的当前状态目标版本入口章节magic-pdf 1.x含 magic-pdf.json 配置2.x / 3.x场景一mineru 2.0–2.4sglang 时代0.9B vlm 模型2.5场景二mineru 2.5–2.6vllm 已引入2.7 / 3.x场景三mineru 2.7hybrid 默认后端3.x 最新场景三Docker / compose 部署最新镜像场景三 影响面扫描按对现有流程的影响半径排序从大到小依次是包名/入口命令 Office 处理链路 模型加载机制 默认后端 中间文件格式 配置文件。对照下表逐项确认任何一项需要做的事为空才可以跳过。变更项按影响半径旧行为新行为需要做什么包名与入口命令magic-pdf、import magic_pdf2.0 起统一为mineru、import mineru全局替换 import、CI 脚本、定时任务命令Office 文档链路内置 LibreOffice 转换2.0 移除该模块3.x 原生解析 docx/pptx/xlsx低版本先独立部署 LibreOffice 转 PDF升到 3.x 可直接投喂 Office 文件模型加载机制1.x 手动下载模型mineru-models-download自动下载更新2.5 的 vlm 不再支持 0.9B 模型升级后执行模型下载被锁在 0.9B 模型的版本上限是 2.2.2默认后端pipeline 为主2.7 默认 hybrid-auto-engine需复现旧结果时用-b pipeline固定后端中间文件格式middle.json 类型较少2.5 结构调整、布局类型更多2.2 增加 bbox 字段解析 middle.json / content_list.json 的二次开发代码需适配字段配置文件magic-pdf.json 手工维护多数参数支持 CLI/API 直接设置配置文件更名 mineru.json迁移自定义项路径模板见 mineru.template.json️ 分场景迁移执行手册场景一从 magic-pdf 1.x 迁移包名切换后如何修改 import 与脚本备份旧配置防止自定义参数丢失。cp ~/.magic-pdf.json ~/magic-pdf.json.bak # 仅当自定义过配置干净安装。旧包与 mineru 共存会抢占入口命令必须先在目标 venv 中卸载旧包。pip uninstall magic-pdf -y pip install mineru[all] # 需要 pipelinevlm 全部后端只用 API 客户端可装裸 mineru拉取新模型。1.x 的手动模型与 2.0 结构不通用必须重新下载。MINERU_MODEL_SOURCEmodelscope mineru-models-download --type all # 国内网络走 modelscope 源替换代码中的 import 与命令import magic_pdf改为import minerumagic-pdf -p ... -o ...改为mineru -p ... -o ...。核心参数-p/-o/-m/-b/-l语义保持一致脚本改动量主要在包名。场景二升级 2.0–2.4vLLM 引擎与 1.2B 模型的替换这一段的本质是 vlm 推理框架从 sglang 切换到 vllm且模型换成了 MinerU2.5-2509-1.2B两者都不向后兼容旧模型。确认显卡架构。Turing 及以后架构可直接用 vllm 加速更老的卡建议只用 pipeline 后端。python -c import torch; print(torch.cuda.get_device_capability()) # 主版本号 7 即 Turing升级包并补装 vllm 依赖vllm 对 torch 版本有下限装前先记录pip show torch。pip install -U mineru[vllm] # 需要 vllm0.10.1.1下载新 vlm 模型旧 0.9B 模型不会再被引用。mineru-models-download --type vlm # 拉取 MinerU2.5-1.2B如果你的业务依赖 0.9B 模型的行为不要强升——最后一个支持该模型的主包版本是 2.2.2保持现状或走场景三评估 1.2B 的结果差异。场景三升级 2.5默认后端切换的处理直接升级到最新即可2.7 的安装方式已简化为一条命令。pip install -U mineru[all]升级后先用旧后端复跑一份样本确认与旧版本输出一致再放开默认后端。mineru -p demo/pdfs/demo1.pdf -o output/ -b pipeline # 固定旧后端做回归对比对比通过后再走默认路径并按需指定 effort。mineru -p demo/pdfs/demo1.pdf -o output/ # 默认 hybrid-auto-engine # 需要图表分析时加 --effort highDocker 部署的用户拉取仓库内 docker/compose.yaml 对应的新镜像重建服务即可注意 mineru-api、mineru-gradio 两个服务入口命令名已统一带 mineru 前缀。 升级验证与回退一体化验证和回退必须成对做升级后跑通验证项之前不要通知下游切换流量。验证三步版本号、样例解析、产物结构。mineru --version # 确认目标版本已生效 mineru -p demo/pdfs/demo1.pdf -o output/ ls output/*/ # 应包含 markdown、content_list.json、middle.json 等产物再用旧版本曾解析过的文档抽 1–2 份人工比对标题层级、表格和公式是否仍符合预期。回退方案pip uninstall mineru -y pip install magic-pdf1.3.12 # 回 1.x或 pip install mineru2.2.2 回 2.x 末版 cp ~/magic-pdf.json.bak ~/.magic-pdf.json # 恢复旧配置如当初备份过回退后如何确认恢复正常magic-pdf --version显示旧版本用同一份样例文档重新解析产物目录结构和内容抽查与升级前一致即视为回退成功。注意模型缓存是共享目录回退后首次运行会自动按旧版本清单重新拉取模型属正常现象。❓ 常见边界情况速查Q升级后 import mineru 报模块冲突或入口行为怪异大概率是 magic-pdf 残留未卸干净两个包声明了部分同名资源。不要在旧环境里打补丁新建 venv 重装最省事。Q模型下载失败或环境无法访问 HuggingFace设置环境变量 MINERU_MODEL_SOURCEmodelscope 后再执行下载命令。完全断网的机器在线上机下载后整包拷贝模型缓存目录再部署。Q升级后解析结果与旧版本明显不一致优先怀疑默认后端变了2.7 是 hybrid-auto-engine先用 -b pipeline 复跑对比若一致则是模型升级带来的精度变化属预期行为而非事故。Qtorch/CUDA 依赖解析失败不要在老环境上叠加安装。干净 venv 中按显卡对应的 CUDA 先装 torch再装 mineru 的 extrasvllm 后端对 torch 版本有硬性下限。Q旧的 magic-pdf.json 配置还能用吗不能直接沿用。2.0 多数参数已支持命令行或 API 直传确需配置时改用 mineru.json字段以仓库内 mineru.template.json 为准可用 MINERU_TOOLS_CONFIG_JSON 指定配置路径。版本迁移的核心原则只有一条先固定后端、再换包、最后对齐模型三者错一个输出必漂移。更细的字段级变更与历史版本说明以仓库内 docs/zh/reference/changelog.md 更新日志和官方 issue 跟踪为准。【免费下载链接】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），仅供参考