mineru-4.0.0-released

## What's Changed

- 2026/09/16 4.0.0 Released

  MinerU 4.0 is a major release that rebuilds the project around **tiered parsing quality**, **native multi-format document parsing**, **a local document library for agent reading**, and **unified SDK / API / service tools**. The main updates include:

  - Four parsing tiers
    - The 3.x `pipeline` / `vlm` / `hybrid` backend selection is replaced by four quality tiers: `flash`, `basic`, `standard`, and `advanced`.
    - `flash` parses native PDF text and digital documents without inference models, for discovery, preview, and indexing. `basic` runs small models for OCR, formulas, and tables, and can run on CPU. `standard` (the default reading quality) combines small models with the VLM for complex layouts. `advanced` spends more inference compute for maximum quality on difficult documents.
    - PDF and images support all four tiers; Office, OpenDocument, EPUB, OFD, HTML, and CSV/TSV are parsed locally at `flash` tier.

  - Native multi-format parsing
    - Supported inputs now cover PDF, images, DOC/DOCX, PPT/PPTX, XLS/XLSX, RTF, ODT/ODS/ODP, EPUB, OFD, HTML, and CSV/TSV. [DocVortex](https://github.com/myhloli/docvortex) provides native document parsing: no conversion to PDF, no model downloads.
    - Plain-text files (`.txt`, `.md`, ...) are read directly instead of parsed.

  - Local document library and agent reading
    - New `mineru` command family: `parse`, `read`, `find`, `search`, `show`, `list`, `watch`, `scan`, plus cache control (`invalidate`, `forget`, `cleanup`) and a background service (`mineru server start / status`).
    - `mineru parse` defaults to the first 10 PDF pages and returns a continuation command (`next_request`), so long documents are read progressively page by page instead of loaded at once.
    - Stable locators such as `doc:{id}/tier:{tier}/page:{page}/block:{block}` support follow-up reads, page/block image export, and verifiable citations. The README embeds an Agent Guide covering these workflows.
    - Privacy first: parsing is local by default, and documents are uploaded only when `--remote` is passed explicitly; anonymous telemetry can be inspected and disabled (`mineru telemetry status`).

  - Independent model configuration
    - Small models (ONNX or Torch) and the VLM engine (llama.cpp, vLLM, or LMDeploy) are now configured independently via `model.small_backend` and `model.vlm.engine`; `model.stack` / `--stack` are removed.
    - The base package works out of the box: ONNX CPU small models plus a llama.cpp VLM in Vulkan mode. `mineru[torch]` adds Torch small-model dependencies; `mineru[full]` also installs vLLM (Linux) or LMDeploy (Windows); Apple Silicon installs Torch by default and runs the VLM with llama.cpp.
    - New 4.0 model bundles `MinerU-4_models_onnx` / `MinerU-4_models_torch` (PP-DocLayoutV2, PP-OCRv6 Tiny Det + Small Rec, PP-FormulaNet plus-M, seal OCR, and shared table models), downloaded and verified with `mineru-kit models download / verify`.

  - Unified tools and V1 API
    - The Python SDK, stateless batch conversion (`mineru-kit parse`), the multi-service Router, and the Gradio WebUI (`mineru-webui`) share one structured result model.
    - The HTTP service is rebuilt around V1 (`/v1/health`, `/v1/tiers`, `/v1/uploads`, `/v1/parse/jobs`, `/v1/files`); legacy `/file_parse` and `/tasks` are not provided.

  - Structured results and nine rendering targets
    - One document model renders to Markdown, HTML, LaTeX, DOCX, EPUB, PDF, Structured Content, and Content List V1/V2; each entrypoint exposes its own subset of exports. See [Output Formats and Result Contract](https://opendatalab.github.io/MinerU/reference/output_files/).
    - Results carry a versioned shared schema, and PDF page ranges (`1-5,8,r3-r1`; `r1` is the last page, `all` selects the whole document) behave consistently across CLI, library, API, and SDK.

  - Breaking changes and migration
    - Entrypoints: `mineru -p input.pdf -o output` becomes `mineru parse input.pdf --pages all -o output.md` (library) or `mineru-kit parse input.pdf -o output.md` (one-off conversion); `mineru-gradio` becomes `mineru-webui`; `-m all` becomes `mineru-kit models download --tier standard`.
    - Extras and runtime: `mineru[core]` / `mineru[pipeline]` are replaced by the base package, `mineru[torch]`, and `mineru[full]`; Python `>=3.10,<3.15`.
    - Configuration now lives in `$MINERU_HOME/config.yaml`; the old `mineru.json` is no longer read.
    - Legacy result JSON is auto-converted only for cached Doclib history; old artifacts saved elsewhere should be re-parsed.
    - Existing AMD and vendor accelerator adaptations remain on `mineru<4`.
    - See the [3.x → 4.0 migration guide](https://opendatalab.github.io/MinerU/reference/migration_4/) for the full list.

  With 4.0, MinerU grows from a document conversion tool into a privacy-first document platform: tiered quality, native multi-format parsing, a searchable local library with stable citation locators for agents, and unified interfaces. Get started with the [Quick Start](https://opendatalab.github.io/MinerU/quick_start/), [Tiers and runtimes](https://opendatalab.github.io/MinerU/usage/tiers/), and [SDK and API](https://opendatalab.github.io/MinerU/usage/sdk_api/) pages; the full release history is in the [changelog](https://opendatalab.github.io/MinerU/reference/changelog/).

- 2026/09/16 4.0.0 发布

  MinerU 4.0 是一次大版本重构，围绕 **分档解析质量**、**原生多格式文档解析**、**面向 Agent 阅读的本地文档库** 与 **统一的 SDK / API / 服务工具** 重新打造。主要更新内容包括：

  - 四档解析质量（tier）
    - 3.x 的 `pipeline` / `vlm` / `hybrid` 后端选择升级为 `flash`、`basic`、`standard`、`advanced` 四档质量档位。
    - `flash` 原生解析 PDF 文本层与电子文档，无需推理模型，适合发现、预览与索引；`basic` 使用小模型完成 OCR、公式与表格识别，可在 CPU 环境运行；`standard`（默认阅读质量）结合小模型与 VLM 处理复杂版面；`advanced` 在标准能力上投入更多推理算力，应对高难度文档。
    - PDF 与图片支持全部四档；Office、OpenDocument、EPUB、OFD、HTML、CSV/TSV 在本地以 `flash` 档解析。

  - 原生多格式解析
    - 支持的输入覆盖 PDF、图片、DOC/DOCX、PPT/PPTX、XLS/XLSX、RTF、ODT/ODS/ODP、EPUB、OFD、HTML 与 CSV/TSV；[DocVortex](https://github.com/myhloli/docvortex) 提供原生文档解析，无需转 PDF、无需下载模型。
    - 纯文本文件（`.txt`、`.md` 等）直接读取，不做解析。

  - 本地文档库与 Agent 阅读
    - 新增 `mineru` 命令族：`parse`、`read`、`find`、`search`、`show`、`list`、`watch`、`scan`，以及缓存管理（`invalidate`、`forget`、`cleanup`）与后台服务（`mineru server start / status`）。
    - `mineru parse` 默认读取 PDF 前 10 页并返回续读命令（`next_request`），长文档按页渐进阅读，无需一次性载入。
    - `doc:{id}/tier:{tier}/page:{page}/block:{block}` 等稳定定位符支持后续读取、页/块图片导出与可验证引用；README 内置 Agent Guide 描述这些工作流。
    - 隐私优先：默认全程本地解析，只有显式使用 `--remote` 才会上传文档；匿名遥测可随时查看与关闭（`mineru telemetry status`）。

  - 模型配置独立化
    - 小模型（ONNX / Torch）与 VLM 引擎（llama.cpp / vLLM / LMDeploy）通过 `model.small_backend` 与 `model.vlm.engine` 独立配置；移除 `model.stack` 与 `--stack`。
    - 基础包开箱即用：小模型走 ONNX CPU，VLM 使用 llama.cpp Vulkan 模式；`mineru[torch]` 增加 Torch 小模型依赖，`mineru[full]` 额外安装 vLLM（Linux）或 LMDeploy（Windows）；Apple Silicon 默认安装 Torch 并以 llama.cpp 运行 VLM。
    - 新的 4.0 模型包 `MinerU-4_models_onnx` / `MinerU-4_models_torch`（PP-DocLayoutV2、PP-OCRv6 Tiny Det + Small Rec、PP-FormulaNet plus-M、印章识别与共享表格模型），使用 `mineru-kit models download / verify` 下载与校验。

  - 统一工具链与 V1 API
    - Python SDK、无状态批量转换（`mineru-kit parse`）、多服务 Router 与 Gradio WebUI（`mineru-webui`）共享同一套结构化结果。
    - HTTP 服务重构为 V1（`/v1/health`、`/v1/tiers`、`/v1/uploads`、`/v1/parse/jobs`、`/v1/files`）；不再提供旧的 `/file_parse` 与 `/tasks`。

  - 结构化结果与九种渲染目标
    - 一套文档模型渲染为 Markdown、HTML、LaTeX、DOCX、EPUB、PDF、Structured Content 与 Content List V1/V2 九种输出，各入口暴露各自的导出子集，详见[输出格式与结果契约](https://opendatalab.github.io/MinerU/zh/reference/output_files/)。
    - 结果携带带版本号的共享 schema；PDF 页范围（`1-5,8,r3-r1`，`r1` 为最后一页，`all` 表示整本）在 CLI、文档库、API 与 SDK 间行为一致。

  - 破坏性变更与迁移
    - 入口变化：`mineru -p input.pdf -o output` 变为 `mineru parse input.pdf --pages all -o output.md`（文档库）或 `mineru-kit parse input.pdf -o output.md`（一次性转换）；`mineru-gradio` 变为 `mineru-webui`；`-m all` 变为 `mineru-kit models download --tier standard`。
    - 依赖分组：`mineru[core]`、`mineru[pipeline]` 等 extras 调整为基础包、`mineru[torch]`、`mineru[full]`；Python 要求 `>=3.10,<3.15`。
    - 配置迁移至 `$MINERU_HOME/config.yaml`，不再读取旧的 `mineru.json`。
    - 旧版结果 JSON 仅在 Doclib 缓存读取边界内自动转换，其余场景请重新解析源文档。
    - 既有的 AMD 及厂商加速卡适配仍停留在 `mineru<4`。
    - 完整变化清单请参考 [3.x → 4.0 迁移指南](https://opendatalab.github.io/MinerU/zh/reference/migration_4/)。

  在 4.0 版本，MinerU 从文档转换工具升级为隐私优先的文档平台：分档解析质量、原生多格式解析、面向 Agent 的可检索本地文档库与稳定引用定位，以及统一的接口体系。欢迎从[快速开始](https://opendatalab.github.io/MinerU/zh/quick_start/)、[档位与运行时](https://opendatalab.github.io/MinerU/zh/usage/tiers/)与 [SDK 与 API](https://opendatalab.github.io/MinerU/zh/usage/sdk_api/) 入手，完整版本历史见 [changelog](https://opendatalab.github.io/MinerU/zh/reference/changelog/)。

**Full Changelog**: https://github.com/opendatalab/MinerU/compare/mineru-3.4.5-released...mineru-4.0.0-released