MinerU 使用指南：把 PDF、Office 和圖片解析成適合 RAG 的 Markdown/JSON

Sun, 07 Jun 2026 23:41:50 +0800

opendatalab/MinerU 是一個面向大型模型資料準備的文件解析工具。它可以把 PDF、圖片、DOCX、PPTX、XLSX 等輸入轉換為 Markdown、JSON 和中間結構化結果，方便後續進入 RAG、資訊抽取、知識庫建置或 Agent 工作流。

它要解決的問題很具體：真實文件往往包含多欄排版、表格、公式、頁眉頁腳、掃描頁、手寫內容和圖片說明。直接把這些內容丟給大型模型，容易出現順序錯亂、表格丟失結構、公式不可讀、OCR 雜訊過多等問題。MinerU 的思路是先做版面、文字、表格、公式和 OCR 解析，再輸出更接近「機器可讀」和「人類閱讀順序」的結果。

適合先解決什麼問題

MinerU 更適合下面幾類場景：

把論文、報告、合約、手冊解析成 Markdown；
給 RAG 知識庫準備更乾淨的文件切分輸入；
從掃描版 PDF 或圖片中提取文字、表格和公式；
把 DOCX、PPTX、XLSX 統一轉成後續流程能消費的結構化資料；
在本地或私有環境裡批次處理文件；
為 LangChain、LlamaIndex、Dify、RAGFlow、FastGPT 等框架準備資料。

如果你的任務只是讀取一份排版簡單的純文字 PDF，直接用常規 PDF 提取工具可能已經足夠。MinerU 的價值主要體現在複雜版式、表格公式、多格式輸入和批次生產文件資料上。

核心能力

根據專案 README，MinerU 支援 PDF、圖片、DOCX、PPTX 和 XLSX 輸入，並能輸出 Markdown、按閱讀順序排列的 JSON，以及用於檢查解析品質的可視化結果。

比較關鍵的能力包括：

自動移除頁眉、頁腳、註腳、頁碼等干擾內容；
按人類閱讀順序輸出文字，適配單欄、多欄和複雜排版；
保留標題、段落、列表等文件結構；
提取圖片、圖片說明、表格、表格標題和註腳；
將公式識別並轉換為 LaTeX；
將表格識別並轉換為 HTML；
自動檢測掃描 PDF 和亂碼 PDF，並啟用 OCR；
OCR 支援 109 種語言；
提供 CLI、FastAPI、Gradio WebUI 和 mineru-router。

2026 年 4 月的 3.1.0 版本還引入了 PPTX 和 XLSX 原生解析，並將主 VLM 模型升級到 MinerU2.5-Pro-2604-1.2B。GitHub release 頁面顯示，2026 年 6 月 4 日發布的 3.2.3 增加了上下標檢測與輸出，並加入了 post-OCR fallback 機制，用於處理私有區字元場景。

安裝方式

如果只是本地試用，官方推薦先安裝 uv，再安裝完整功能包：

1
2
3

pip install --upgrade pip
pip install uv
uv pip install -U "mineru[all]"

也可以從原始碼安裝：

1
2
3

git clone https://github.com/opendatalab/MinerU.git
cd MinerU
uv pip install -e .[all]

mineru[all] 包含核心功能，官方說明相容 Windows、Linux 和 macOS。需要注意的是，文件解析對硬體和依賴比較敏感，尤其是 GPU、推理框架、Python 版本和系統環境。正式部署前建議先用小樣本跑通，再決定是否進入批次處理。

第一次解析文件

最基礎的命令是指定輸入路徑和輸出路徑：

`1`	`mineru -p <input_path> -o <output_path>`

如果裝置不滿足 GPU 加速條件，可以指定 pipeline 後端，用純 CPU 路線執行：

`1`	`mineru -p <input_path> -o <output_path> -b pipeline`

<input_path> 可以是單一檔案，也可以是目錄。實際使用時，可以先準備一個小目錄，只放幾份代表性文件：

`1`	`mineru -p ./samples -o ./output -b pipeline`

這樣可以先觀察輸出品質、耗時、記憶體占用和檔案結構，再決定是否擴大到完整文件庫。

輸出結果怎麼用

MinerU 的輸出可以進入幾類下游流程。

第一類是 RAG。你可以把 Markdown 作為切分和向量化的輸入，讓標題、段落、列表、表格和公式盡量保持原始語義。相比直接 OCR 成一大段文字，結構化 Markdown 更容易做分塊、引用和結果回溯。

第二類是資訊抽取。JSON 和中間結果適合給後續腳本讀取，例如抽取表格、公式、圖片說明或特定章節。對於需要自動整理報告、論文或合約欄位的場景，這比只拿純文字更穩定。

第三類是人工複核。MinerU 提供版面、span 等可視化結果，可以幫助你檢查解析是否漏掉內容、順序是否合理、表格是否變形。做批次處理前，最好先抽樣看這些可視化結果。

後端選擇

MinerU 文件裡主要提到幾類後端路線：

pipeline：相容性好，可以在 CPU 或 GPU 上執行，適合先試用和常規批次處理；
vlm-engine：準確率更高，但硬體要求也更高，適合複雜文件和高品質解析；
hybrid-engine：結合原生文字提取與高準確率解析，適合希望降低幻覺並提升複雜版式品質的場景；
*-http-client：連接 OpenAI API 相容服務，可對接本地或遠端推理服務。

如果你只是想驗證效果，先用 pipeline 更穩。等確認文件類型、品質要求和處理量之後，再考慮 VLM 或混合路線。對於企業內部文件，後端選擇還要結合資料是否允許離開本地環境。

部署方式

MinerU 支援 CLI、本地 API、Gradio WebUI、Docker 和 mineru-router。不同入口適合不同團隊：

個人試用：CLI 最直接；
非技術同事體驗：Gradio WebUI 更友好；
接入現有系統：FastAPI 或 REST API 更合適；
多服務、多 GPU、高併發：考慮 mineru-router；
想降低環境配置成本：Linux 或 WSL2 環境下可以看 Docker 部署。

Docker 部署目前更適合 Linux 和帶 WSL2 的 Windows。macOS 使用者通常優先走 pip / uv 安裝路線。

和普通 OCR 工具有何不同

普通 OCR 工具主要關注「把影像裡的字識別出來」。這當然重要，但對 RAG 來說還不夠。RAG 更關心的是段落順序、標題層級、表格結構、公式表達、圖片上下文和可追溯性。

MinerU 更像文件理解前處理工具。它不只是 OCR，還會處理版面分析、閱讀順序、表格 HTML、公式 LaTeX、多格式輸入和結構化輸出。它更適合把複雜文件整理成下游模型能穩定消費的資料。

這也意味著它不是越重越好。對於簡單發票、單頁圖片或純文字 PDF，輕量 OCR 或 PDF 文字提取工具可能更快。MinerU 更適合文件複雜度已經明顯影響後續效果的場景。

和 PaddleOCR、Marker、Unstructured 怎麼選

這些工具有重疊，但入口不同。

PaddleOCR 更偏 OCR 基礎能力和文字識別元件，適合你需要自己搭建更細粒度的 OCR 流程。Marker 更偏 PDF 到 Markdown，適合快速把文件變成可讀 Markdown。Unstructured 更偏文件資料抽取與企業資料管道，適合多類型文件進入檢索或 ETL 流程。

MinerU 的特點是面向 LLM、RAG 和 Agent 資料準備，強調複雜版式、表格、公式、多格式輸入、VLM + OCR 雙引擎和私有部署。若你的文件主要是論文、報告、教材、PPT、表格檔案，並且後續要進入大型模型應用，它值得單獨試一輪。

批次處理建議

正式批次處理前，可以按下面順序做一次小規模驗證：

選 10 到 20 份代表性文件，覆蓋掃描件、複雜表格、多欄論文、PPT 和 Excel。
先用 pipeline 後端解析，記錄耗時、記憶體、輸出大小和失敗樣例。
抽查 Markdown、JSON 和可視化結果，重點看閱讀順序、表格、公式和圖片說明。
對品質不夠的樣本，再嘗試 VLM 或 hybrid 後端。
確認輸出結構後，再接入 RAG 切分、向量化和引用回溯。

不要一開始就把整庫文件丟進去。文件解析的失敗往往很具體：某類掃描件、某種表格、某個字型、某個語言方向或某些跨頁內容。先找出邊界，再放大規模，會省很多時間。

隱私與合規注意事項

如果處理的是企業內部文件、客戶資料、合約、財務報表或未公開研究資料，先確認部署方式和資料流向。

需要重點檢查：

文件內容是否會發送到外部模型服務；
是否使用本地推理、遠端推理或 OpenAI API 相容服務；
中間檔案裡是否包含完整文字、圖片、表格和業務敏感資訊；
輸出 Markdown / JSON 是否會進入日誌、物件儲存或共享目錄；
批次處理失敗樣本是否會被上傳到 issue、社群或第三方除錯平台。

MinerU 支援私有和離線部署，但這不等於所有配置都天然離線。真實部署前，最好畫清楚從輸入檔案、暫存目錄、模型推理、輸出目錄到日誌系統的完整資料路徑。

什麼時候不適合用

下面幾種情況可以先不引入 MinerU：

文件很簡單，普通 PDF 文字提取已經足夠；
你只需要一次性讀幾頁內容，不需要結構化輸出；
目前機器資源不足，解析成本高於收益；
文件品質太差，OCR 結果需要大量人工校對；
私有文件不能進入目前推理鏈路；
團隊還沒有明確的 RAG、抽取或知識庫下游需求。

文件解析工具最好服務於後續流程，而不是為了「解析而解析」。如果沒有明確的消費方，先把輸出樣例和下游需求對齊，再決定是否批次投入。

小結

MinerU 適合把複雜文件轉換成大型模型應用更容易使用的 Markdown 和 JSON。它覆蓋 PDF、圖片、Office 文件、表格、公式、OCR、多語言識別和本地部署，尤其適合 RAG、知識庫和 Agent 工作流的資料準備。

比較穩妥的使用路線是：先用線上體驗或小樣本本地解析評估品質，再用 pipeline 後端跑通流程，最後根據準確率和吞吐要求決定是否切換到 VLM、hybrid、API 或多服務部署。對於複雜文件，它能明顯減少前處理成本；對於簡單文件，也要注意別把流程做重。

MinerU on KnightLi的博客