MinerU 是什麼、怎麼用：把 PDF 等文檔解析成 Markdown（4.0 的安裝、四檔解析與命令）

本文根據 MinerU 官方倉庫的中文 README 整理，資料核對於 2026-10-11。文中命令取自官方 README，沒有在本機運行驗證。MinerU 更新很快，4.0 的命令和舊版差別較大，動手前先看一眼官方 README 的當前內容。

適用於誰

• 搜「mineru 是什麼」「mineru 教學」「mineru github」「mineru api」的人；
• 要把論文、報告、掃描件這類版面複雜的文檔轉成 Markdown，餵給大模型或導入知識庫的人；
• 照舊教學敲命令發現對不上的人。

結論先說

1. MinerU 是一個文檔解析工具。官方現在的定位是「面向 Agent 的文檔解析工具」：把本地文檔轉成可讀的內容，並且支持按頁、按塊續讀，保留穩定的引用位置。
2. 輸入不只是 PDF：圖片、Word、PPT、Excel、EPUB、HTML 等都支持。
3. 解析分四檔：flash、basic、standard、advanced，質素依次提高，速度依次變慢，對硬件的要求也依次提高。
4. 安裝：pip install "mineru>=4.0,<5"，需要 Python 3.10 及以上、3.15 以下。
5. 兩個命令：mineru-kit 做一次性的轉換；mineru 面向文檔庫，帶緩存、搜尋和續讀。
6. 預設在本地處理。README 寫明：預設不會自動將文檔上載到官網服務，遠程解析需要顯式配置。

一、支持的格式

輸入（README 所列）：PDF、圖片、DOC / DOCX、PPT / PPTX、XLS / XLSX、RTF、ODT / ODS / ODP、EPUB、OFD、HTML / MHTML、CSV / TSV。純文本不進入解析流程。

輸出：解析結果是一個統一的文檔模型，可以渲染成九種目標：Markdown、HTML、LaTeX、DOCX、EPUB、PDF、Structured Content、Content List V1、Content List V2。README 註明各個命令行和 API 的導出範圍不完全相同。

二、四檔解析怎麼選

實際的做法：先用 flash 或 basic 把一批文檔過一遍，知道里面有什麼；真正要細讀、要入庫的，再用 standard；standard 仍然處理不好的少數困難文檔，才上 advanced。

README 還提到，預設的 ONNX CPU 推理就可以運行；有 NVIDIA 顯卡的可以安裝 mineru[full]>=4.0。

三、安裝

bash
pip install "mineru>=4.0,<5"

用 uv 的寫法：

bash
uv pip install -U "mineru>=4.0,<5"

Python 版本要求是 >=3.10,<3.15。建議裝在單獨的虛擬環境裏。

解析需要模型文件，按檔位下載：

bash
mineru-kit models download --tier <tier>

把 <tier> 換成 basic、standard 等檔位名。

四、兩個命令的分工

一次性轉換（README 示例）：

bash
mineru-kit parse document.pdf -o document.md --tier standard

圖形介面：

bash
mineru-kit webui

README 說明這是一個 Gradio 的網頁介面。

文檔庫式的用法（README 示例，--json 表示以 JSON 輸出，方便程序和智能體讀取）：

bash
mineru parse document.pdf --json
mineru read "doc:ab12cd3/tier:standard/page:11" --limit 12000 --json
mineru search "liquidated damages" --min-tier basic --json

• parse：解析並進入緩存；
• read：按一個穩定的引用位置（哪份文檔、哪一檔、哪一頁）讀取內容，--limit 限制返回的長度；
• search：在已解析的文檔裏搜尋。

這套設計是為智能體準備的：長文檔不必一次全部塞進上下文，智能體可以先搜尋、再按頁讀取需要的部分，並且引用位置前後一致。

五、其他使用方式

README 提到的還有：Python SDK、V1 API、批處理、多服務的 Router、Docker。README 註明非 NVIDIA 裝置的 Docker 方案仍待更新。

在線體驗的入口有官網 mineru.net，以及 ModelScope、HuggingFace、Colab 上的演示。使用在線服務就意味着文檔會上載，內部資料請用本地方式。

六、從舊版升級

4.0 的命令結構和 2.x、3.x 不同。README 提供了「3.x → 4.0 遷移」指南和完整的更新歷史連結，升級已有的腳本前先讀遷移指南。

網上大量教學是按舊版寫的，命令對不上時，以 README 當前內容為準，不要照着舊命令反覆試。

七、放進 RAG 流程時的注意點

• 先抽查再批量：挑帶表格、公式、雙欄、掃描的樣例各幾份，把結果和原文對一遍；
• 檔位和成本一起考慮：幾千份文檔全用最高檔，時間會很長。按文檔類型分流；
• 公式和表格重點核對：這是版面解析最容易出錯的兩類內容，關鍵數據不要直接採信；
• 保留引用位置：MinerU 提供穩定的頁與塊引用，入庫時把它存進元數據，回答時就能指回原文位置；
• 分段與入庫：見《Dify 知識庫搭建教學》和《ChromaDB 是什麼》。

常見問題

Q：沒有顯卡能用嗎？

README 說明預設的 ONNX CPU 推理可用，basic 和 standard 兩檔都標註了 CPU 可用。速度取決於文檔數量和檔位。

Q：許可證是什麼，能商用嗎？

README 寫的是「MinerU 開源許可證」，以 Apache 2.0 為基礎並附加了條款。商用前請閱讀許可證全文，以官方文本為準。

Q：和 Docling、MarkItDown 怎麼選？

規整的電子文檔先用輕量的 MarkItDown，見《MarkItDown 怎麼用》；版面複雜的 PDF 在 MinerU 和 Docling 之間用自己的樣例對比，見《Docling 使用教學》。沒有哪一個在所有文檔上都最好。

Q：模型下載很慢或失敗？

README 的當前版本用 mineru-kit models download 下載模型，模型來源的設定以官方文檔為準。

參考資料

• opendatalab/MinerU（官方倉庫）：https://github.com/opendatalab/MinerU
• 中文 README：https://github.com/opendatalab/MinerU/blob/master/README_zh-CN.md