MinerU：把 PDF 與 Office 文件轉成 LLM 可用的 Markdown／JSON

在 RAG、企業知識庫與 Agent 工作流中，文件解析經常是最容易被低估的一層。把 PDF 直接轉成純文字，雖然能快速完成 demo，卻很容易遺失標題階層、表格欄列、數學公式、圖片與跨頁關係；後面的切 chunk、embedding 和檢索，也會一起放大這些錯誤。

OpenDataLab/MinerU 提供一個開源的文件解析引擎，將 PDF、圖片、DOCX、PPTX 與 XLSX 轉換成適合機器處理的 Markdown、JSON 等格式。它的定位不是聊天機器人，而是放在「原始文件 → 可檢索資料」之間，負責把複雜版面整理成下游模型能消化的結構化輸入。

截至本文查證時，專案在 GitHub 擁有超過 7.7 萬顆星，且近期仍持續發布版本。這讓 MinerU 值得被當成一個可以實際整合進資料管線的工程工具，而不只是展示型的文件 OCR demo。

先理解：為什麼純文字抽取不夠

一般 PDF 文字抽取器通常擅長「把字拿出來」，卻未必知道文字在頁面上的角色。例如：

兩欄論文可能被交錯讀取，段落順序因此失真。
表格被攤平成連續文字後，欄名與數值的對應關係消失。
公式、上下標與特殊符號在 OCR 後變成不可用的字串。
圖片、圖說與正文之間的關聯被切斷。
掃描文件需要 OCR，但 OCR 結果還必須和版面分析結合，才能恢復閱讀順序。

對人類讀者而言，這些資訊可以靠視覺補回來；對 embedding 模型和 LLM 而言，輸入文字就是它們能看到的世界。文件解析品質會直接影響檢索召回、引用正確性與回答可信度。

MinerU 的價值在於，它把文件理解當成一個完整流程處理，而不是只提供單一 OCR 函式。官方 README 列出的能力涵蓋版面分析、文字與表格辨識、公式處理、圖片描述，以及輸出為 Markdown、JSON 和中間結果等用途。實際效果仍取決於文件類型與模型後端，因此官方也建議先用線上 demo 評估自己的樣本。

MinerU 的工作方式

可以把 MinerU 放進以下管線：

PDF／DOCX／PPTX／XLSX／圖片
              │
              ▼
     版面分析與 OCR／VLM
              │
              ▼
   標題、段落、表格、公式、圖片
              │
              ▼
       Markdown／JSON／中間結果
              │
              ▼
        清理、切分、Embedding
              │
              ▼
          RAG 或 Agent 應用

這個分層很重要。MinerU 不會替你決定 chunk size、向量資料庫 schema 或 prompt；它先把「文件長什麼樣」整理好，讓下游元件可以基於更穩定的結構工作。對工程團隊來說，這比把所有責任塞進一個端到端問答服務更容易測試與替換。

官方目前提供多種使用介面：本機 CLI、FastAPI、Gradio WebUI、Docker 部署，以及用於多服務與多 GPU 路由的 mineru-router。因此你可以先用 CLI 驗證單份文件，再逐步演進成 API 服務，而不必一開始就建置完整平台。

最小可行用法

官方 README 提供以 uv 安裝完整功能的方式：

uv pip install -U "mineru[all]"

如果想從原始碼安裝：

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

最基本的 CLI 用法是指定輸入與輸出路徑：

mineru -p ./documents/report.pdf -o ./outputs

也可以明確指定 pipeline backend：

mineru -p ./documents/report.pdf -o ./outputs -b pipeline

這些指令適合先建立一個可重現的基準。建議不要直接拿整個歷史文件庫開始跑，而是先準備一組代表性樣本，包含雙欄論文、掃描 PDF、表格密集文件、含公式文件和簡報，再比較輸出品質與處理時間。

對 RAG 管線最有用的三個設計點

1. 先保留結構，再決定怎麼切分

如果先把文件壓成一個沒有階層的純文字，再交給 splitter，後面很難知道一段文字屬於哪個章節或表格。較穩健的做法是保留 Markdown heading、表格和圖片描述，並在切分時把章節路徑當成 metadata：

{
  "text": "本節討論混合檢索……",
  "metadata": {
    "source": "annual-report.pdf",
    "section": "第三章／檢索架構",
    "page": 18,
    "content_type": "paragraph"
  }
}

這樣做不代表所有文件都能自動得到完美 metadata，而是讓解析結果保留足夠訊息，方便你在自己的資料清理層補上來源、頁碼與章節。

2. 表格不要急著轉成一般段落

表格常常包含最有價值的比較資料，但也最容易在純文字化時失去語意。對表格內容，可以考慮同時保存兩份表示：一份是適合人類閱讀的 Markdown table，另一份是供程式處理的 JSON 結構。問答時再依問題類型決定要用文字檢索、欄位過濾，或交給模型做表格推理。

3. 把解析品質納入可觀測性

文件解析不是一次性腳本。建議在管線中記錄：輸入檔案 hash、頁數、解析 backend、處理耗時、輸出字數、表格數量、OCR 頁面數和失敗原因。當使用者回報「答案引用錯誤」時，你才能判斷問題出在解析、切分、檢索或生成，而不是只能重新跑整條流程。

Pipeline、VLM 與服務化的取捨

MinerU 的 README 將 pipeline 與 VLM 類型的後端放在同一個產品脈絡中。可以用一個務實的方式理解它們：

pipeline 適合先建立穩定、可批次處理的本機流程，並針對常見文件格式做效能與輸出評估。
VLM 類型的解析更適合需要視覺理解的複雜頁面，但要把模型大小、GPU 記憶體、延遲與成本納入部署設計。
當單機 CLI 已經驗證品質，再考慮以 API、Docker 或 router 服務化，讓多個上游系統共用解析能力。

專案近期的更新也聚焦於批次處理、模型快取、長文件、非同步任務、多執行緒與多 GPU 路由。這些能力對真正的文件平台比單次 demo 更重要，因為生產環境通常面對的是長時間任務、重試、並行量和資源隔離。

不要忽略授權與資料治理

MinerU README 目前標示專案使用 MinerU Open Source License，該授權以 Apache 2.0 為基礎並附加條件。若要用於商業產品、代客處理機密文件，或把模型與服務重新包裝，應在導入前閱讀倉庫中的 LICENSE.md，並讓法務確認適用範圍。

另外，文件解析常涉及合約、財務報表、醫療或內部規範。即使工具可以在本機執行，也仍應設計暫存檔清理、權限隔離、輸出脫敏和稽核紀錄。把文件送到第三方 API 前，也要先確認資料是否允許離開自己的環境。

適合誰使用？

MinerU 特別適合以下情境：

需要把大量 PDF 或 Office 文件導入 RAG 知識庫。
需要保留表格、公式、章節和圖片語意，而不滿足於純 OCR。
想先用 CLI 或 WebUI 驗證，再逐步部署成 API 服務。
需要在本機或自有 GPU 環境處理文件，降低外部服務依賴。
想把文件解析和切分、Embedding、向量搜尋、LLM 生成分離，建立可替換的資料管線。

它不一定適合所有文件。版面極度特殊、手寫內容比例很高、低品質掃描或需要高度領域校正的文件，仍然要用自己的資料集做評估。官方也明確提醒，複雜版面、掃描頁面和手寫內容可能出現不符合預期的結果。

結語：把文件解析當成 AI 系統的基礎設施

RAG 專案最常見的錯誤之一，是太早討論向量資料庫和 prompt，卻沒有先確認「進入系統的文件是否仍然保有正確結構」。MinerU 的定位很清楚：它是文件到機器可讀資料之間的解析層，讓團隊可以用 Markdown、JSON、CLI、API 或服務路由，把這個步驟納入可測試、可觀測、可擴展的工程流程。

如果你的文件工作流目前仍是「PDF 轉純文字，再直接切 chunk」，MinerU 值得作為下一個基準工具。先挑一小組真實文件比較輸出，再根據表格、公式、圖片和長文件的結果決定是否導入；這比只看 demo 或星數，更能判斷它是否適合你的 AI Chain。