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如果你还在用 magic-pdf1.x或停在 2.0 系列这篇文章就是写给你的。先看「变更全景」判断要不要动再照对应路径执行。全程约 30 分钟迁移 MinerU 不需要重新搭环境。 变更全景30 秒判断要不要动维度1.x旧2.x新包名magic-pdfmineruCLI 入口magic-pdfmineru核心 APImagic_pdf 模块mineru 包输出统一为 middle_json模型/依赖手动下载 layout、OCR 模型新增 MinerU-VL 模型自动下载管理最低环境Python 3.10Python 3.10–3.13改动最大的一处是包名和 CLI 从 magic-pdf 换成了 mineru所有脚本、定时任务、代码里的import都要跟着改。第二大处是模型体系2.0 引入小参数量的 VLM视觉语言模型能看图直接输出文档内容旧的手动模型目录配置不再使用。 前置检查跑 4 条命令跑一下python --version3.10 以下或 3.14 以上先处理 Python 环境跑一下pip show magic-pdf mineru确认装的是旧包、新包还是两个都没有备份配置cp ~/magic-pdf.json ~/magic-pdf.json.bak2.x 对应的是mineru.json跑一下df -h .确认有 10GB 以上空闲模型文件有数 GB️ 迁移路径三条路对号入座路径一跨大版本1.x → 2.x4 步第一步卸载旧版uv pip uninstall magic-pdf第二步装新版uv pip install mineru[all]⚠️ 旧代码里的import magic_pdf全部改为import mineru命令行的magic-pdf改为mineru第三步改配置。2.0 起绝大多数参数直接走命令行旧magic-pdf.json不再读取新配置默认在用户目录mineru.jsonexport MINERU_MODEL_SOURCEmodelscope第四步拉取模型mineru-models-download⚠️ 2.0 移除了内置 LibreOffice 模块Office 文档需先转 PDFlibreoffice --headless --convert-to pdf doc.docx路径二同大版本小版本2.0.x → 2.12 步2.1 起内置了 FastAPI 服务和 Gradio WebUIOCR 支持 37 种语言模型支持增量更新。配置基本兼容直接更新uv pip install -U mineru[all] mineru-models-download路径三仅补丁版本1 条命令比如 2.1.9 升到 2.1.10 这类纯修复版本无配置和模型变更uv pip install -U mineru[all]✅ 验证与回滚验证跑 3 条命令跑通即过mineru -v mineru -p input.pdf -o output/ ls output/回滚到旧版的 3 条命令uv pip uninstall mineru uv pip install magic-pdf1.3.12 cp ~/magic-pdf.json.bak ~/magic-pdf.json出现以下现象立即回滚解析输出缺少你业务依赖的字段或脚本启动直接报ModuleNotFoundError且与模型无关。 高频故障速查现象mineru: command not found根因命令缓存或虚拟环境指向旧路径 解法hash -r后重试不行就uv pip install -U mineru[all]现象模型下载反复超时失败 根因当前网络访问不了默认模型源 解法export MINERU_MODEL_SOURCEmodelscope再执行mineru-models-download现象安装时 torch、transformers 依赖冲突 根因旧虚拟环境残留依赖与新版本不兼容 解法uv venv .venv source .venv/bin/activate再uv pip install mineru[all]现象升级后 docx、pptx 解析入口报错 根因2.0 移除内置 LibreOffice 转换模块 解法libreoffice --headless --convert-to pdf doc.docx再喂给 mineru升级后扫一眼 Release Notes 里的不兼容变更标记提前改掉还在引用旧模块名的脚本。生产机器上保留一份magic-pdf.json备份回滚才只用 3 条命令。新模型下载成功后确认mineru.json里的路径写对了再放开批量任务。跑完上面那 3 条验证命令迁移就算收工了。【免费下载链接】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），仅供参考