MinerU 版本演进全解读：从 0.x 首次开源到 2.7 系列的后端路线图与环境变量速查

MinerU 版本演进全解读：从 0.x 首次开源到 2.7 系列的后端路线图与环境变量速查

【免费下载链接】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 从 2024/07/05 首次开源到 2.7 系列的能力演进主线：pipeline / vlm / hybrid 三类后端的兴衰更替、推理引擎从 sglang 到 vllm/lmdeploy/MLX 的迁移、国产算力平台的适配进程，以及贯穿各版本的环境变量配置项。读完后，你可以按版本对照源码定位每一项能力的实现落点，并在升级、回退或选型时快速判断兼容边界。

一、先看清版本坐标：文档覆盖范围与当前仓库状态

更新日志文档记录了项目自 0.x 系列（首次开源 2024/07/05）至 2.7.6（2026/02/06）的完整更新历史。需要注意一点版本事实：当前仓库 版本声明 中的__version__已为3.4.4，即仓库代码已经演进到更新日志最后一个条目之后的阶段，因此文中涉及“当前行为”的描述一律以当前源码为准，而版本条目本身忠实保留更新日志的原始表述。

从 pyproject.toml 可以还原出各版本提到的命令与依赖在今天的实际形态：

• 包名为mineru（关键词中仍保留magic-pdf，呼应 2.0 的改名历史），Python 要求>=3.10,<3.14；
• 注册的命令行入口包括mineru（主解析入口，mineru.cli.client:main）、mineru-api（FastAPI 服务）、mineru-router（多 worker 路由服务）、mineru-gradio（WebUI）、mineru-models-download（离线模型下载）、mineru-vllm-server/mineru-lmdeploy-server/mineru-openai-server（VLM 推理服务端）。更新日志中 2.1.1 提到的“compose.yaml 便于启动 sglang-server、mineru-api、mineru-gradio”等服务，在当前仓库对应为 docker/compose.yaml 及上述入口脚本；
• 可选依赖组：core = vlm + pipeline + gradio，而all = core + s3 + 平台相关加速项（macOS 下装mlx、Linux 下装vllm、Windows 下装lmdeploy），这正是 2.7.0 “uv pip install mineru[all]一条命令装齐所有可选后端依赖”的落地方式。

二、2.7 系列：hybrid 后端成为默认，国产算力版图补全

2.7.6 / 2.7.4 / 2.7.2：国产算力平台适配持续推进

• 2.7.6（2026/02/06）：新增昆仑芯、太初元碁的适配支持。至此官方和厂商适配并支持的国产算力平台共 11 家：昇腾、平头哥、沐曦、海光、燧原、摩尔线程、天数智芯、寒武纪、昆仑芯、太初元碁、壁仞；
• 2.7.4（2026/01/30）：新增天数智芯、寒武纪的适配支持；
• 2.7.2（2026/01/23）：新增海光、燧原、摩尔线程的适配支持，同时优化跨页表合并，提升合并成功率与合并效果。

当前仓库在 docs/zh/usage/acceleration_cards 目录下按平台放置了各加速卡的适配文档（含 AMD、Ascend、Biren、Cambricon、Enflame、Hygon、IluvatarCorex、Kunlunxin、METAX、MooreThreads、THead、Tecorigin、VastAI 等文件），是排查国产平台安装与运行问题的第一手资料。

2.7.1：安全依赖升级与 EXIF 方向校正

• 修复缺陷（issue #4300）；
• 更新pdfminer.six依赖版本，解决 CVE-2025-64512；
• 支持输入图像的 EXIF 方向自动校正，提升 OCR 识别效果（issue #4283）。

源码印证：当前 pdf_image_tools.py 在读取图像时执行ImageOps.exif_transpose(image)，依据 EXIF 的 Orientation 标记自动转正手机拍摄的倾斜照片，避免 OCR 识别到旋转 90°/180° 的文字导致乱码。

2.7.0：hybrid 后端登场并取代 pipeline 成为默认

这是更新日志中信息密度最高的一个版本：

• 简化安装流程，uv pip install mineru[all]即可安装所有可选后端依赖；
• 增加全新后端hybrid，结合pipeline与vlm的优势：
  • 从文本 PDF 中直接抽取文本，在文本 PDF 场景原生支持多语言识别，并大幅减少解析幻觉；
  • 通过指定 OCR 语言，在扫描 PDF 场景支持 109 种语言的文本识别；
  • 支持独立的行内公式识别开关，在不需要时可单独关闭以改善结果视觉效果；
• 简化vlm/hybrid后端的引擎选择逻辑，用户只需指定*-auto-engine即可自动选择合适的推理引擎；
• 默认解析后端从pipeline切换至hybrid-auto-engine，提升新用户开箱即用时的结果一致性；
• Gradio 应用增加 i18n 适配，支持中英文切换。

源码印证：

• hybrid 后端的独立实现位于 mineru/backend/hybrid 目录（hybrid_analyze.py、hybrid_magic_model.py、hybrid_model_output_to_middle_json.py），与pipeline、vlm、office并列，佐证了“混合抽取”是一条独立管线而非简单拼接；
• backend_options.py 中DEFAULT_BACKEND = BACKEND_HYBRID_ENGINE，公开后端为pipeline、vlm-engine、hybrid-engine以及对应的*-http-client远程模式，并保留LEGACY_BACKEND_ALIASES将旧名vlm-auto-engine、hybrid-auto-engine规范映射为新名——即 2.7.0 时期的*-auto-engine命名在后续版本中已演进出更简洁的*-engine名称，旧写法仍向后兼容。

三、2.6 系列：引擎生态扩展与运行时参数系统化

2.6.7（2025/12/12）：bug 修复

• 修复缺陷（issue #4168）。

2.6.6（2025/12/02）：Ascend 适配优化与 mineru-api 工具优化

Ascend 适配优化

• 优化命令行工具初始化流程，使 Ascend 适配方案中vlm-vllm-engine后端在命令行工具中可用；
• 为 Atlas 300I Duo（310p）设备更新适配文档。

mineru-api 工具优化

• 为mineru-api接口参数增加描述性文本，优化接口文档可读性；
• 可通过环境变量MINERU_API_ENABLE_FASTAPI_DOCS控制是否启用自动生成的接口文档页面，默认为启用；
• 为vlm-vllm-async-engine、vlm-lmdeploy-engine、vlm-http-client后端增加并发数配置选项，可通过环境变量MINERU_API_MAX_CONCURRENT_REQUESTS控制 api 接口的最大并发请求数，默认为不限制数量。

源码印证：fast_api.py 与 router.py 中create_app()均以env_flag_enabled("MINERU_API_ENABLE_FASTAPI_DOCS", default=True)决定是否挂载/docs、/openapi.json端点；并发数的读取与校验在 config_reader.py 中实现（要求正整数）。演进提示：当前仓库中该变量在 API worker 侧的默认值已调整为 3（见 cli_tools 文档 与 api_client.py），而非 2.6.6 时期的“不限制”。

2.6.5（2025/11/26）：lmdeploy 引擎与三张国产卡

• 增加新后端vlm-lmdeploy-engine支持，使用方式与vlm-vllm-(async)engine类似，但以lmdeploy作为推理引擎，与vllm相比额外支持 Windows 平台原生推理加速；
• 新增国产算力平台昇腾/npu、平头哥/ppu、沐曦/maca的适配支持，用户可在对应平台上使用pipeline与vlm模型，并使用vllm/lmdeploy引擎加速 vlm 模型推理；
• 更新日志同时提醒：国产平台适配不易，官方已尽量确保完整性和稳定性，但仍可能存在稳定性/兼容问题与精度对齐问题，建议按各适配文档页面内的红绿灯情况选择环境；遇到文档未提及的问题请在官方 discussions 指定帖子中反馈。

源码印证：pyproject.toml 中的lmdeploy可选依赖组（lmdeploy>=0.10.2,<0.12+qwen-vl-utils）以及all组中mineru[lmdeploy] ; sys_platform == 'win32'的平台标记，与“Windows 原生推理加速”的定位一致；服务端入口mineru-lmdeploy-server即为此后端的配套工具。

2.6.4（2025/11/04）：两个关键的运行时保护参数

• 为 pdf 渲染图片增加超时配置，默认为 300 秒，可通过环境变量MINERU_PDF_RENDER_TIMEOUT配置，防止部分异常 pdf 文件导致渲染过程长时间阻塞；
• 为 onnx 模型增加 cpu 线程数配置选项，默认为系统 cpu 核心数，可通过环境变量MINERU_INTRA_OP_NUM_THREADS和MINERU_INTER_OP_NUM_THREADS配置，减少高并发场景下对 cpu 资源的抢占冲突。

源码印证：os_env_config.py 中get_load_images_timeout()默认 300 秒，该值被 pdf_image_tools.py 在渲染 pdf 页面为图片时消费；get_op_num_threads()读取两个 ONNX 线程变量，未设置或非法值时回退为-1（即交由 onnxruntime 使用系统核心数）。此外当前源码还带有MINERU_PDF_RENDER_THREADS（渲染并发线程数，默认 3），属于日志未单列但实际存在的配套参数。

2.6.3（2025/10/31）：MLX 引擎登陆 Apple Silicon

• 增加新后端vlm-mlx-engine支持，在 Apple Silicon 设备上使用MLX加速MinerU2.5模型推理，相比vlm-transformers后端速度提升 100%~200%；
• 缺陷修复（issue #3849、#3859）。

源码印证：mlx可选依赖组（mlx-vlm+mlx）只被all组在sys_platform == 'darwin'时装载，与“仅 Apple Silicon”的适用边界吻合。

2.6.2（2025/10/24）：OCR 大提速、表格合并开关与公式中文化

pipeline 后端优化

• 增加对中文公式的实验性支持，配置环境变量export MINERU_FORMULA_CH_SUPPORT=1开启。该功能可能导致 MFR 速率略微下降、部分长公式识别失败等问题，建议仅在需要解析中文公式的场景下开启；设置为0可关闭；
• OCR 速度大幅提升 200%~300%（致谢社区贡献者提供的优化方案）；
• OCR 模型优化拉丁文识别的准度和广度，并将西里尔文、阿拉伯文、天城文、泰卢固语、泰米尔文语系更新至ppocr-v5版本，精度相比上代模型提升 40% 以上。

vlm 后端优化

• table_caption、table_footnote匹配逻辑优化，提升页内多张连续表场景下表格标题和脚注的匹配准确率与阅读顺序合理性；
• 优化使用vllm后端时高并发下的 cpu 资源占用，降低服务端压力；
• 适配vllm0.11.0 版本。

通用优化

• 跨页表格合并效果优化，新增跨页续表合并支持，提升多列合并场景下的表格合并效果；
• 为表格合并功能增加环境变量MINERU_TABLE_MERGE_ENABLE，功能默认开启，可设置为0关闭。

源码印证：

• 公式开关在 model_init.py 中直接决定 MFR 模型选择——MINERU_FORMULA_CH_SUPPORT为真值时选用pp_formulanet_plus_m（面向中文公式训练），为假值时使用默认的unimernet_small，非法值会打印警告并回退默认；
• 表格合并在 runtime_utils.py 中实现：读取MINERU_TABLE_MERGE_ENABLE（默认true），取值为true/1/yes时执行merge_table(pdf_info)，false/0/no时跳过，未知值仅告警，与“默认开启”的描述一致。

四、2.5 系列：MinerU2.5 发布与仓库结构性调整

2.5.4（2025/09/26）

• MinerU2.5 技术报告发布（可阅读其模型架构、训练策略、数据工程和评测结果）；
• 修复部分 pdf 文件被误识别成ai文件导致无法解析的问题。这一文件类型识别问题，与当前 pyproject.toml 依赖列表中的文件类型识别库magika的引入方向一致（从依赖结构看，可推断当前版本通过专门的文件指纹识别替代了单纯的后缀判断）。

2.5.3（2025/09/20）

• 依赖版本范围调整，使 Turing 及更早架构显卡可以使用 vLLM 加速推理 MinerU2.5 模型；
• pipeline后端对 torch 2.8.0 的若干兼容性修复；
• 降低 vLLM 异步后端默认并发数，降低服务端压力，避免高压导致的链接关闭问题；
• 更多兼容性内容详见官方公告（原链接指向外部 discussions，此处不再附外链）。

2.5.2（2025/09/19）：MinerU2.5 正式发布

官方口径：MinerU2.5 仅凭 1.2B 参数，在 OmniDocBench 文档解析评测中精度全面超越 Gemini2.5-Pro、GPT-4o、Qwen2.5-VL-72B 等顶级多模态大模型，并显著领先于主流文档解析专用模型（如 dots.ocr、MonkeyOCR、PP-StructureV3 等）。模型发布于 HuggingFace 与 ModelScope 平台。

核心亮点

• 极致能效：以 1.2B 的轻量化规模实现超越百亿乃至千亿级模型的 SOTA 性能，重新定义文档解析的能效比；
• 先进架构：“两阶段推理”（解耦布局分析与内容识别）与原生高分辨率架构结合，在布局分析、文本识别、公式识别、表格识别及阅读顺序五大方面均达到 SOTA 水平。

关键能力提升

• 布局检测：结果更完整，精准覆盖页眉、页脚、页码等非正文内容，并提供更精准的元素定位与更自然的格式还原（如列表、参考文献）；
• 表格解析：大幅优化对旋转表格、无线/少线表、长难表格的解析能力；
• 公式识别：显著提升中英混合公式及复杂长公式的识别准确率，大幅改善数学类文档解析能力。

仓库调整（伴随 vlm 2.5 发布）

• vlm 后端升级至 2.5 版本，支持 MinerU2.5 模型，不再兼容 MinerU2.0-2505-0.9B 模型，最后一个支持 2.0 模型的版本为 mineru-2.2.2；
• vlm 推理相关代码移至独立的mineru-vl-utils包，降低与 mineru 主仓库的耦合度，便于独立迭代。当前 pyproject.toml 的硬依赖中确有mineru-vl-utils>=1.0.5,<2，印证了这次拆分；
• vlm 加速推理框架从sglang切换至vllm，实现对 vllm 生态的完全兼容，使用户可以在任何支持 vllm 框架的平台上使用 MinerU2.5 模型并加速推理；
• 由于 vlm 模型重大升级、支持更多 layout type，解析中间文件middle.json和结果文件content_list.json的结构做出调整，详见 输出文件说明；各后端生成中间文件的代码分别位于 pipeline、vlm、hybrid 目录中。

其他仓库优化

• 移除对输入文件的后缀名白名单校验，当输入文件为 PDF 文档或图片时，对文件的后缀名不再有要求，提升易用性。

五、2.2–2.4 系列：表格解析精度升级

2.2.2（2025/09/10）

• 修复新的表格识别模型在部分表格解析失败时影响整体解析任务的问题。

2.2.1（2025/09/08）

• 修复使用模型下载命令时，部分新增模型未下载的问题（对应mineru-models-download入口）。

2.2.0（2025/09/05）

主要更新

• 重点提升表格解析精度：引入新的有线表识别模型（RapidTable 方向的 TableStructureRec）和全新的混合表格结构解析算法，显著提升pipeline后端的表格识别能力；当前仓库中 mineru/model/table/rec/slanet_plus 目录即为该 SLANet+ 表结构模型的实现落点；
• 增加对跨页表格合并的支持，同时支持pipeline和vlm后端，进一步提升表格解析的完整性和准确性（后续 2.6.2、2.7.2 又持续优化，形成一条清晰的表格能力演进线）。

其他更新

• pipeline后端增加 270 度旋转的表格解析能力，现已支持 0/90/270 度三个方向；
• pipeline增加对泰文、希腊文的 OCR 能力支持，并更新英文 OCR 模型至最新版：英文识别精度提升 11%，泰文识别模型精度 82.68%，希腊文识别模型精度 89.28%（by PPOCRv5）；
• 在输出的content_list.json中增加bbox字段（映射至 0-1000 范围内），方便用户直接获取每个内容块的位置信息；
• 移除pipeline_old_linux安装可选项，不再支持 CentOS 7 等老版本 Linux 系统，以便对uv的sync/run等命令进行更好的支持。

六、2.1 系列：2.0 大版本后的功能补齐与快速修复

2.1 系列由密集的小版本 bug 修复和依赖适配组成，其中 2.1.0 是本阶段的功能里程碑。

• 2.1.10（2025/08/01）：修复pipeline后端因 block 覆盖导致的解析结果与预期不符（issue #3232）；
• 2.1.9（2025/07/30）：transformers4.54.1 版本适配；
• 2.1.8（2025/07/28）：sglang0.4.9.post5 版本适配；
• 2.1.7（2025/07/27）：transformers4.54.0 版本适配；
• 2.1.6（2025/07/26）：修复vlm后端解析部分手写文档时的表格异常问题；修复文档旋转时可视化框位置漂移问题（issue #3175）；
• 2.1.5（2025/07/24）：sglang0.4.9 版本适配，同步升级 dockerfile 基础镜像为 sglang 0.4.9.post3；
• 2.1.4（2025/07/23）：修复pipeline后端中MFR步骤在某些情况下显存消耗过大的问题（issue #2771）；修复某些情况下image/table与caption/footnote匹配不准确的问题（issue #3129）；
• 2.1.1（2025/07/16）：修复pipeline在某些情况可能发生的文本块内容丢失问题（issue #3005）；修复sglang-client需要安装torch等不必要包的问题（issue #2968）；更新 dockerfile 修复 linux 字体缺失导致的解析文本内容不完整问题（issue #2915）；易用性方面更新compose.yaml便于直接启动sglang-server、mineru-api、mineru-gradio服务，并启用在线文档站点；
• 2.1.0（2025/07/05）：MinerU 2 的第一个大版本更新。

2.1.0 性能优化

• 大幅提升某些特定分辨率（长边 2000 像素左右）文档的预处理速度；
• 大幅提升pipeline后端批量处理大量页数较少（<10）文档时的后处理速度；
• pipeline后端的 layout 分析速度提升约 20%。

2.1.0 体验优化

• 内置开箱即用的fastapi服务和gradiowebui（当前仓库对应 fast_api.py、gradio_app.py 及各自的mineru-api/mineru-gradio入口）；
• sglang适配 0.4.8 版本，大幅降低vlm-sglang后端的显存要求，最低可在 8G 显存（Turing 及以后架构）的显卡上运行；
• 对所有命令增加sglang的参数透传，使sglang-engine后端可以与sglang-server一致接收sglang的所有参数；
• 支持基于配置文件的功能扩展：自定义公式标识符、开启标题分级功能、自定义本地模型目录。仓库根目录提供了 mineru.template.json 作为该配置模板，用户可复制为个人配置使用。

2.1.0 新特性

• pipeline后端更新 PP-OCRv5 多语种文本识别模型，支持法语、西班牙语、葡萄牙语、俄语、韩语等 37 种语言的文字识别，平均精度涨幅超 30%；
• pipeline后端增加对竖排文本的有限支持。

七、2.0 系列：架构深度重构的起点

2.0.6（2025/06/20）

• 修复vlm模式下某些偶发的无效块内容导致解析中断的问题；
• 修复vlm模式下某些不完整的表结构导致的解析中断问题。

2.0.5（2025/06/17）

• 修复sglang-client模式下依然需要下载模型的问题；
• 修复sglang-client模式依赖torch等实际运行不需要的包的问题；
• 修复同一进程内尝试通过多个 url 启动多个sglang-client实例时只有第一个生效的问题。

2.0.3（2025/06/15）

• 修复下载模型类型设置为all时配置文件出现键值更新错误的问题；
• 修复命令行模式下公式和表格功能开关不生效导致功能无法关闭的问题；
• 修复sglang-engine模式下 0.4.7 版本 sglang 的兼容性问题；
• 更新 sglang 环境下部署完整版 MinerU 的 Dockerfile 和相关安装文档（当前仓库的 docker 目录按 china/global 及各家国产卡组织 Dockerfile）。

2.0.0（2025/06/13）：全新架构

全新架构

MinerU 2.0 在代码结构和交互方式上进行深度重构，显著提升了易用性、可维护性与扩展能力：

• 去除第三方依赖限制：彻底移除对pymupdf的依赖，推动项目向更开放、合规的开源方向迈进。当前 pyproject.toml 中 PDF 渲染相关依赖为pypdfium2与pypdf，印证了这一替换；
• 开箱即用，配置便捷：无需手动编辑 JSON 配置文件，绝大多数参数已支持命令行或 API 直接设置；
• 模型自动管理：新增模型自动下载与更新机制，用户无需手动干预即可完成模型部署（对应 models_download_utils.py 与mineru-models-download命令）；
• 离线部署友好：提供内置模型下载命令，支持完全断网环境下的部署需求；
• 代码结构精简：移除数千行冗余代码，简化类继承逻辑；
• 统一中间格式输出：采用标准化的middle_json格式，兼容多数基于该格式的二次开发场景，确保生态业务无缝迁移。

全新模型

• 小模型，大能力：模型参数不足 1B，却在解析精度上超越传统 72B 级别的视觉语言模型（VLM）；
• 多功能合一：单模型覆盖多语言识别、手写识别、版面分析、表格解析、公式识别、阅读顺序排序等核心任务；
• 极致推理速度：在单卡 NVIDIA 4090 上通过sglang加速，达到峰值吞吐量超过 10,000 token/s。

不兼容变更说明

• Python 包名从magic-pdf更改为mineru，命令行工具也由magic-pdf改为mineru，请同步更新脚本与调用命令（当前 pyproject.toml 的[project.scripts]段即全部mineru前缀入口）；
• 出于系统模块化设计与生态一致性考虑，MinerU 2.0 不再内置 LibreOffice 文档转换模块。如需处理 Office 文档，建议通过独立部署的 LibreOffice 服务先行转换为 PDF，再进行后续解析。（注：当前仓库又新增了office后端，可直接解析 DOCX/PPTX/XLSX，见 mineru/backend/office，属于后续版本的再演进。）

八、1.x 系列：OCR 模型迭代与安装兼容性打磨

1.3.12（2025/05/24）：PP-OCRv5 与手写文档支持

增加 ppocrv5 模型支持：ch_server模型更新为PP-OCRv5_rec_server，ch_lite更新为PP-OCRv5_rec_mobile（需更新模型）。测试发现 ppocrv5(server) 对手写文档效果有一定提升，但其余类别文档精度略差于 v4_server_doc，因此默认 ch 模型保持不变。可通过lang参数（python apilang='ch_server'或命令行--lang ch_server）选择：

同时增加手写文档支持：通过优化 layout 对手写文本区域的识别，现已支持手写文档解析（默认开启，无需额外配置；手动选择 ppocrv5 模型可获得更好的手写解析效果）。

1.3.10（2025/04/29）～1.3.7（2025/04/22）

• 1.3.10：支持使用自定义公式标识符，可通过修改用户目录下magic-pdf.json的latex-delimiter-config项实现（2.0 之后该能力纳入配置文件扩展体系，模板见 mineru.template.json）；
• 1.3.9：优化公式解析功能，提升公式渲染成功率；
• 1.3.8：ocr默认模型（ch）更新为PP-OCRv4_server_rec_doc（需更新模型）。该模型在PP-OCRv4_server_rec基础上混合更多中文文档数据和 PP-OCR 训练数据训练而成，支持 1.5 万+ 字符，在中英日繁单语或混合场景精度均有明显提升；小部分纯英文场景可能出现单词粘连，此类场景可改用lang='ch_server'（PP-OCRv4_server_rec）；
• 1.3.7：修复表格解析模型初始化时 lang 参数失效的问题；修复 cpu 模式下 OCR 和表格解析速度大幅下降的问题。

1.3.4（2025/04/16）～1.3.0（2025/04/03）

• 1.3.4：通过移除无用块小幅提升 ocr-det 速度；修复部分情况下由 footnote 导致的页面内排序错误；
• 1.3.2：修复 Windows 系统 python 3.13 环境安装时的依赖版本不兼容问题；优化批量推理内存占用；优化旋转 90 度表格与财报超大表格的解析效果；修复未指定 OCR 语言时英文文本区域偶发单词黏连问题；
• 1.3.1：支持 python 3.13；为部分过时的 linux 系统（如 CentOS 7）做最后适配，不再保证后续版本继续支持；
• 1.3.0：
  • 安装与兼容性：移除 layout 中layoutlmv3的使用，解决detectron2兼容问题；torch 兼容 2.2~2.6（2.5 除外）；cuda 兼容 11.8/12.4/12.6/12.8（由 torch 决定）；python 兼容 3.10~3.12；离线部署成功后不需要联网下载任何模型文件；
  • 性能优化：支持多个 pdf 文件的 batch 处理（当时提供批处理脚本样例，当前仓库的演示入口为 demo/demo.py），相比 1.0.1 版本公式解析速度最高提升超过 1400%、整体解析速度最高提升超过 500%；优化 mfr 模型加载降低显存占用；整体显存最低降至 6GB；优化 mps 设备运行速度；
  • 解析效果：mfr 模型更新到unimernet(2503)，解决多行公式换行丢失问题；
  • 易用性：通过paddleocr2torch完全替代paddle框架与paddleocr的使用，解决 paddle 与 torch 冲突及线程不安全问题；解析过程增加实时进度条。

1.2.1（2025/03/03）～1.1.0（2025/01/22）

• 1.2.1：修复字母与数字全角转半角操作对标点符号的影响；修复部分情况下 caption 匹配不准确问题；修复部分情况下的公式 span 丢失问题；
• 1.2.0：auto 模式下 pdf 文档分类速度提升；优化含水印文档的解析逻辑，显著提升解析效果；改进单页内多个图像/表格与 caption 的匹配逻辑；修复图片/表格 span 被填充进 textblock 的异常；修复标题 block 为空的问题；
• 1.1.0：布局识别模型升级到doclayout_yolo(2501)，公式解析模型升级到unimernet(2501)（均需重新执行模型下载流程以增量更新）；在显存 16GB+ 设备上通过资源占用优化和流水线重构，整体解析速度提升 50% 以上；在线 demo 新增标题分级功能（测试版本，默认开启）。

1.0.1（2025/01/10）：首个正式版本

• 全新 API 接口：数据侧引入 Dataset 类，支持图像（.jpg/.png）、PDF、Word（.doc/.docx）、PowerPoint（.ppt/.pptx）等多种格式；用户侧将处理流程设计为可组合的 Stage 阶段，用户可自定义新 Stage 并自由组合出专属处理流程；
• 更广泛的兼容性适配：优化依赖环境确保 ARM 架构 Linux 稳定运行；深度适配华为昇腾 NPU 加速；
• 自动语言识别：引入全新语言识别模型，lang配置为auto时自动选择合适的 OCR 语言模型，提升扫描类文档解析准确性（对应当前源码中的 language.py 等语言识别模块）。

九、0.x 系列：解析流水线的奠基

• 0.10.0（2024/11/22）：引入混合 OCR 文本提取能力——在公式密集、span 区域不规范、部分文本以图像呈现等复杂文本分布场景下解析效果显著提升；兼具文本模式内容提取准确快速、OCR 模式 span/line 区域识别更准的双重优势；
• 0.9.3（2024/11/15）：表格识别接入 RapidTable，单表解析速度提升 10 倍以上，准确率更高、显存占用更低；
• 0.9.2（2024/11/06）：表格识别接入StructTable-InternVL2-1B模型；
• 0.9.0（2024/10/31）：大量代码重构的全新版本：
  • 重构排序模块，使用 layoutreader 进行阅读顺序排序，确保各种排版下的高准确率；
  • 重构段落拼接模块，跨栏、跨页、跨图、跨表情况下均能良好拼接；
  • 重构列表和目录识别，极大提升列表块和目录块识别准确率；
  • 重构图、表与描述性文本的匹配逻辑，大幅提升 caption 和 footnote 匹配准确率，描述性文本丢失率降至接近 0；
  • OCR 多语言支持扩展到 84 种语言的检测与识别；
  • 增加显存回收逻辑：开启 layout/公式/OCR 加速（不含表格加速）的显存需求从 16GB 降至 8GB，全加速从 24GB 降至 10GB；
  • 优化配置开关，增加独立公式检测开关，无需公式检测时可大幅提升速度和效果；
  • 集成 PDF-Extract-Kit 1.0：加入自研doclayout_yolo模型（相近解析效果下比原方案提速 10 倍以上，可与layoutlmv3自由切换），公式解析升级至unimernet 0.2.1；因仓库更换需要重新下载模型；
• 0.8.1（2024/09/27）：修复若干 bug，提供在线 demo 的本地化部署版本和前端界面；
• 0.8.0（2024/09/09）：支持 Dockerfile 快速部署，上线 HuggingFace、ModelScope demo；
• 0.7.1（2024/08/30）：集成 paddle tablemaster 表格识别功能；
• 0.7.0b1（2024/08/09）：简化安装步骤提升易用性，加入表格识别功能；
• 0.6.2b1（2024/08/01）：优化依赖冲突问题和安装文档；
• 首次开源（2024/07/05）：MinerU 项目首次开源发布。

十、实战速查：环境变量与源码落点对照

将更新日志中散落各版本的环境变量汇总如下，所有源码位置均已在当前仓库中核实，可直接跳转查看实现细节：

十一、按版本选型与升级的实用结论

• 后端选择：2.7.0 起默认后端为 hybrid 系（hybrid-auto-engine，现规范名为hybrid-engine），文本 PDF 走原生文本抽取、扫描件走多语言 OCR，兼顾速度与幻觉控制；pipeline与vlm后端仍保留可选，远程调用则对应*-http-client模式（见 backend_options.py）；
• 模型兼容边界：需要运行 MinerU2.0-2505-0.9B 模型时，2.2.2 是最后的可用版本；MinerU2.5 模型从 2.5.2 起成为 vlm 后端的唯一支持对象，且推理代码已解耦至mineru-vl-utils依赖包；
• 推理引擎按平台选择：Linux 用 vllm、Windows 用 lmdeploy、Apple Silicon 用 MLX，mineru[all]会依据sys_platform自动挑选对应加速依赖；
• 国产算力部署：11 家平台的适配文档集中在 docs/zh/usage/acceleration_cards，建议按文档内的状态说明选择平台与场景；
• 升级前必读：middle.json/content_list.json在 2.5.2 发生过结构调整，lang模型选择在 1.3.x 多次换代，命令行包名在 2.0 从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