MinerU 完整教學 — 高精度文件解析引擎與 AIKT 整合指南

1. 專案定位

什麼是 MinerU？

MinerU 是一款由 OpenDataLab 開發的開源 document parsing (文件解析) 工具，專門將複雜的 PDF、圖片、DOCX、PPTX、XLSX 等文件轉為 LLM-ready 的 Markdown / JSON 結構化格式。專案誕生於 InternLM 大模型預訓練過程中，目前是 GitHub 上最受歡迎的文件解析專案之一（~72K stars）。

核心價值

與同類工具的比較

2. 安裝指南

2.1 系統需求

2.2 pip / uv 安裝（推薦）

1# 方法一：uv（推薦，速度更快）
2pip install --upgrade pip
3pip install uv
4uv pip install -U "mineru[all]"
5
6# 方法二：pip
7pip install -U "mineru[all]"

2.3 從原始碼安裝

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

2.4 Docker 部署

Docker 部署適用於 Linux 及 Windows (WSL2)。MinerU 提供多種 Dockerfile 針對不同硬體（NVIDIA / Ascend / Cambricon / MetaX 等）。

1# 以 NVIDIA GPU 全球版為例
2cd docker/global
3docker build -t mineru:latest -f Dockerfile .

2.5 Extension Modules (擴充模組) 安裝選項

 1# 僅安裝 pipeline 後端（輕量，CPU 可用）
 2uv pip install "mineru[pipeline]"
 3
 4# 安裝 VLM 推理（需 GPU）
 5uv pip install "mineru[vlm]"
 6
 7# 安裝 vLLM backend
 8uv pip install "mineru[vllm]"
 9
10# 安裝 Gradio WebUI
11uv pip install "mineru[gradio]"
12
13# 安裝全部
14uv pip install "mineru[all]"

3. 核心架構解析

3.1 整體架構圖

flowchart TB
    subgraph INPUT["輸入層"]
        PDF[PDF]
        IMG[Image]
        DOCX[DOCX]
        PPTX[PPTX]
        XLSX[XLSX]
    end

    subgraph BACKEND["解析後端"]
        PL["pipeline 後端
Layout + OCR + Table + MFR"]
        HB["hybrid-engine
原生文字 + VLM 補強"]
        VL["vlm-engine
純 VLM 推理"]
        OF["office 後端
DOCX/PPTX/XLSX 原生"]
    end

    subgraph MODEL["模型層"]
        LAYOUT["DocLayoutV2
版面分析"]
        OCRE["PP-OCRv6
109 語言 OCR"]
        MFR["FormulaNet+
公式辨識"]
        TABLE["SLANet+ / UNet
表格辨識"]
        VLM_M["MinerU2.5-Pro
1.2B VLM"]
    end

    subgraph MIDDLE["中間表示"]
        MJ["Middle JSON
標準化中間格式"]
    end

    subgraph OUTPUT["輸出層"]
        MD["Markdown"]
        JSON["Content List JSON"]
        HTML_T["HTML Tables"]
        LATEX["LaTeX Formulas"]
        IMGS["Extracted Images"]
    end

    subgraph SERVE["服務層"]
        CLI["mineru CLI"]
        API["mineru-api
FastAPI"]
        ROUTER["mineru-router
多 GPU 負載均衡"]
        GRADIO["mineru-gradio
WebUI"]
        MCP["MCP Server"]
    end

    PDF & IMG --> PL & HB & VL
    DOCX & PPTX & XLSX --> OF
    PL --> LAYOUT & OCRE & MFR & TABLE
    HB --> VLM_M & OCRE
    VL --> VLM_M
    LAYOUT & OCRE & MFR & TABLE & VLM_M --> MJ
    OF --> MJ
    MJ --> MD & JSON & HTML_T & LATEX & IMGS
    MD & JSON --> CLI & API & ROUTER & GRADIO & MCP

3.2 三大 Parsing Backend (解析後端) 詳解

pipeline 後端：傳統 CV pipeline，由 layout detection (版面偵測) → OCR → formula recognition (公式辨識) → table recognition (表格辨識) 組成。速度快、資源低（純 CPU 可跑），適合大批量文件處理。OmniDocBench v1.6 精度 86.47。

hybrid-engine：結合原生 PDF 文字抽取與 VLM 補強。支援 effort 參數（medium / high），medium 比 high 快 35%–220% 但精度僅差 0.13 分。精度 95.39（high）。

vlm-engine：純 VLM (Vision-Language Model; 視覺語言模型) 推理，使用 MinerU2.5-Pro-1.2B 模型。支援 vLLM / LMDeploy / mlx 等推理框架。精度 95.30。

3.3 資料流程圖

flowchart LR
    A["原始文件
PDF/DOCX/..."] -->|"輸入解析"| B["Backend 選擇
pipeline / hybrid / vlm / office"]
    B -->|"模型推理"| C["Middle JSON
統一中間表示"]
    C -->|"mkcontent 渲染"| D["Markdown + JSON"]
    D -->|"服務端點"| E["CLI / API / Router / MCP"]
    E -->|"下游消費"| F["RAG / LLM / Agent"]

3.4 模組目錄結構

 1mineru/
 2├── backend/          # 四種解析後端
 3│   ├── pipeline/     # 傳統 CV pipeline（layout + OCR + table + formula）
 4│   ├── hybrid/       # 原生文字 + VLM hybrid
 5│   ├── vlm/          # 純 VLM
 6│   └── office/       # DOCX/PPTX/XLSX 原生解析
 7├── cli/              # 所有命令列入口
 8│   ├── client.py     # mineru 主 CLI
 9│   ├── fast_api.py   # mineru-api（FastAPI server）
10│   ├── router.py     # mineru-router（多 GPU 路由）
11│   ├── gradio_app.py # mineru-gradio（WebUI）
12│   └── vlm_server.py # VLM 推理 server（vLLM/LMDeploy/OpenAI）
13├── model/            # 各種 AI 模型
14│   ├── layout/       # DocLayoutV2 版面偵測
15│   ├── ocr/          # PaddleOCR → PyTorch
16│   ├── mfr/          # FormulaNet+ / UniMERNet 公式辨識
17│   ├── table/        # SLANet+ / UNet 表格辨識
18│   ├── vlm/          # vLLM/LMDeploy server
19│   ├── docx/         # DOCX 原生轉換
20│   ├── pptx/         # PPTX 原生轉換
21│   └── xlsx/         # XLSX 原生轉換
22├── data/             # I/O 層（local / S3 / HTTP）
23├── utils/            # 工具函式
24└── resources/        # 靜態資源

4. CLI 命令詳細用法

4.1 基本用法

 1# 標準解析（自動選擇後端）
 2mineru -p input.pdf -o output_dir/
 3
 4# 指定 pipeline 後端（純 CPU 友善）
 5mineru -p input.pdf -o output_dir/ -b pipeline
 6
 7# 指定 hybrid 後端 + effort 等級
 8mineru -p input.pdf -o output_dir/ -b hybrid-engine --effort medium
 9
10# 批次處理整個目錄
11mineru -p docs_folder/ -o output_dir/
12
13# 處理 Office 文件
14mineru -p report.docx -o output_dir/
15mineru -p slides.pptx -o output_dir/
16mineru -p data.xlsx -o output_dir/

4.2 進階 CLI 工具

 1# 啟動 API server
 2mineru-api
 3
 4# 啟動多 GPU router（生產環境推薦）
 5mineru-router
 6
 7# 啟動 Gradio WebUI
 8mineru-gradio
 9
10# 下載模型
11mineru-models-download
12
13# 啟動 VLM 推理 server
14mineru-vllm-server       # vLLM
15mineru-lmdeploy-server   # LMDeploy
16mineru-openai-server     # OpenAI-compatible

4.3 Python API 用法

 1import subprocess
 2import json
 3
 4# 透過 CLI 呼叫（最簡單）
 5result = subprocess.run(
 6    ["mineru", "-p", "input.pdf", "-o", "output/"],
 7    capture_output=True, text=True
 8)
 9
10# 透過 HTTP API
11import httpx
12with open("input.pdf", "rb") as f:
13    response = httpx.post(
14        "http://localhost:8000/file_parse",
15        files={"file": f},
16        data={"parse_method": "auto"}
17    )
18print(response.json())

5. 應用場景

5.1 RAG (Retrieval-Augmented Generation; 檢索增強生成) Pipeline

MinerU 最常見的應用是作為 RAG pipeline 的文件前處理引擎：

1. 文件輸入 → MinerU 解析為 Markdown
2. Markdown → text chunking → embedding
3. 向量存入 vector database
4. 使用者查詢 → retrieval → LLM 生成答案

整合框架：LangChain / LlamaIndex / RAGFlow / Dify / FastGPT / RAG-Anything

5.2 AI Agent 文件理解

透過 MCP Server，AI agent 可直接「看懂」文件：

• Cursor / Claude Desktop / Windsurf 可安裝 MinerU MCP Server
• Agent 可以自主呼叫 MinerU 解析使用者上傳的 PDF / Office 文件

5.3 大模型預訓練資料準備

MinerU 最初就是為 InternLM 預訓練而設計，適合大規模文件的結構化抽取。

5.4 企業文件數位化

• 支援完全離線部署（Docker + GPU）
• 多語 OCR（109 語言）
• 多種國產 AI 晶片支援（Ascend / Cambricon / Enflame 等）

6. 資安掃描報告

掃描範圍

• mineru/cli/ — 所有命令列入口與 API server
• mineru/backend/ — 四種解析後端
• mineru/utils/ — 工具函式
• mineru/data/ — I/O 層

掃描結果

安全等級：🟢 低風險

MinerU 的安全設計值得肯定：

• 無 eval / exec：未發現任何動態程式碼執行
• 無 pickle 反序列化：避免常見的 Python pickle 攻擊向量
• HTTP 存取有 policy 控管：public_http_client_policy.py 提供了存取控管機制
• subprocess 使用安全：僅啟動內部 worker，無 shell=True 風險

7. FAQ

Q1：MinerU 和 Docling 有什麼不同？

A：MinerU 的最大優勢是三引擎架構（pipeline / hybrid / vlm），可根據硬體條件選擇。Docling 更輕量但缺少 VLM 支援。MinerU 的 OCR 支援 109 語言，Office 格式支援也更完整。

Q2：純 CPU 可以跑嗎？

A：可以。使用 pipeline 後端即可在純 CPU 環境運行，精度 86.47（OmniDocBench v1.6），適合大多數場景。

Q3：Windows 上 GPU 加速不生效？

A：請確認 CUDA 版本與 PyTorch 相容。參考官方 FAQ：https://opendatalab.github.io/MinerU/faq/#windows-cuda-acceleration

Q4：如何處理中文文件？

A：MinerU 3.4 起 OCR 模型升級為 PP-OCRv6，中文預設使用 ch 模型，無需額外設定語言參數。

Q5：輸出 Markdown 品質不佳？

A：建議先試用 hybrid-engine（精度 95.39）。若硬體不足，使用 pipeline 後端並啟用 OCR 開關。

8. 進階技巧

8.1 Effort 參數調校

1# medium：速度優先（預設），精度 95.26
2mineru -p doc.pdf -o out/ -b hybrid-engine --effort medium
3
4# high：精度優先，支援 image analysis
5mineru -p doc.pdf -o out/ -b hybrid-engine --effort high

8.2 多 GPU 部署

使用 mineru-router 可一鍵部署多 GPU 負載均衡：

1# 啟動 router，自動發現並分配 GPU worker
2mineru-router

Router 特性：

• 自動 worker 健康檢查與重啟
• 任務佇列 + 負載均衡
• 完全相容 mineru-api 介面

8.3 模型下載加速

MinerU 3.4 新增自動模型來源選擇：

• 首次安裝自動偵測最佳模型來源
• 支援本地模型快取重用
• 配置文件：mineru.template.json

8.4 長文件處理

MinerU 3.0+ 支援 sliding window (滑動視窗) 機制，大幅降低長文件記憶體峰值。上萬頁文件無需手動分割。

9. 與 AIKT Layers 的整合

9.1 AIKT 整合架構圖

flowchart TB
    subgraph MINERU["MinerU 文件解析引擎"]
        M_CLI["mineru CLI"]
        M_API["mineru-api"]
    end

    subgraph AIKT_INPUT["AIKT 輸入層"]
        L1["Layer 1: ai-save"]
        L2["Layer 2: ai-gh-save"]
        L8["Layer 8: docling"]
    end

    subgraph AIKT_PROCESS["AIKT 處理層"]
        L9["Layer 9: paper-search"]
        L10["Layer 10: paper-qa-lite"]
        L15["Layer 15: paper-tutorial"]
        L18["Layer 18: research-pipeline-v2"]
    end

    subgraph AIKT_OUTPUT["AIKT 輸出層"]
        L7["Layer 7: quarkdown"]
        L11["Layer 11: kami"]
        L12["Layer 12: gh-tutorial-qd"]
        L21["Layer 21: blog-publish"]
    end

    MINERU -->|"取代 / 強化 docling"| L8
    MINERU -->|"PDF 全文轉換"| L9
    MINERU -->|"RAG 前處理"| L10
    L8 -->|"結構化 Markdown"| L15
    L9 -->|"paper 全文"| L15 & L18
    L10 -->|"RAG 問答"| L18
    L15 -->|"教學 md"| L7 & L11 & L12
    L7 -->|"HTML 輸出"| L21

9.2 各 Layer 適用場景

Layer 8: docling — 最直接的替代 / 互補關係

MinerU 與 docling 是同類工具，可作為 AIKT Layer 8 的替代或備援引擎：

整合方式：在 scripts/docling-convert.sh 中加入 MinerU fallback，當 docling 失敗時自動切換到 MinerU。

Layer 9: paper-search — 學術論文全文取得

Paper-search 找到 paper 後，需要做全文轉換（PDF → Markdown）。MinerU 的 pipeline 後端特別適合學術論文（公式 → LaTeX、表格 → HTML）。

整合方式：paper read: 流程中，以 mineru -p paper.pdf -o . -b pipeline 取代或補充現有的 docling 全文轉換。

Layer 10: paper-qa-lite — RAG 前處理品質提升

paper-qa-lite 的 RAG 品質直接取決於文件前處理品質。MinerU 的結構化 Markdown 輸出比 markitdown / docling 更能保留表格、公式、圖片說明等關鍵資訊。

Layer 15: paper-tutorial — N 篇 Paper 教學生成

paper-tutorial 需要高品質的 paper 全文作為輸入。MinerU 可確保公式、表格、圖片都被正確轉換，讓生成的教學內容更完整。

Layer 18: research-pipeline-v2 — 多管線研究工作流

在 research pipeline 的 Stage 2（文獻蒐集）中，MinerU 可作為 PDF 全文提取的主力引擎，提升後續分析的資料品質。

Layer 1: ai-save — URL / 文件存入

ai-save 的降級鏈（markitdown → opencli → playwright）可增加 MinerU 作為 PDF 專用路徑。

9.3 AIKT 降級鏈整合圖

flowchart TD
    INPUT["輸入文件"] --> CHECK{"檔案類型？"}
    
    CHECK -->|"PDF（含公式/表格/掃描）"| MINERU["MinerU
pipeline / hybrid"]
    CHECK -->|"PDF（簡單文字）"| DOCLING["docling
快速轉換"]
    CHECK -->|"DOCX / PPTX / XLSX"| MINERU
    CHECK -->|"HTML / 純文字"| MARKITDOWN["markitdown
輕量轉換"]
    
    MINERU -->|"成功"| OUTPUT["Markdown 存入 inbox/"]
    MINERU -->|"失敗"| DOCLING
    DOCLING -->|"成功"| OUTPUT
    DOCLING -->|"失敗"| MARKITDOWN
    MARKITDOWN --> OUTPUT
    
    OUTPUT --> DOWNSTREAM["下游 Layer
paper-qa / quarkdown / kami / ..."]

9.4 實際整合範例

1# 在 AIKT 中使用 MinerU 解析 paper PDF
2mineru -p "inbox/Paper/260629/myfile.pdf" -o "inbox/Paper/260629/mineru-out/" -b pipeline
3
4# 輸出的 Markdown 可直接被 paper-qa-lite 索引
5# pq: "What is the main finding?" "inbox/Paper/260629/mineru-out/"

10. 重點摘要 Checklist

• 安裝：uv pip install -U "mineru[all]" 一行搞定
• 基本用法：mineru -p <input> -o <output> 支援 PDF/圖片/DOCX/PPTX/XLSX
• 後端選擇：pipeline（CPU 友善）→ hybrid（高精度 + effort 調校）→ vlm（純 VLM）
• Effort 調校：medium（預設，速度優先）vs high（精度優先 + image analysis）
• 多 GPU 部署：mineru-router 一鍵多 GPU 負載均衡
• MCP 整合：支援 Cursor / Claude Desktop / Windsurf
• RAG 整合：LangChain / Dify / FastGPT / RAGFlow
• AIKT 整合：可取代/強化 Layer 8 (docling)，提升 Layer 9/10/15/18 品質
• OCR：PP-OCRv6，109 語言，精度提升 11%
• 安全：🟢 低風險，無 eval/exec/pickle，HTTP 有 policy 控管

11. 進一步閱讀

• 官方文件：https://opendatalab.github.io/MinerU/
• MinerU 官網：https://mineru.net/
• 技術報告：
  • MinerU: arXiv:2409.18839
  • MinerU2.5: arXiv:2509.22186
  • MinerU2.5-Pro: arXiv:2604.04771
• DeepWiki AI 助手：https://deepwiki.com/opendatalab/MinerU
• Discord 社群：https://discord.gg/Tdedn9GTXq
• OmniDocBench（評測基準）：https://github.com/opendatalab/OmniDocBench
• PDF-Extract-Kit（姊妹工具）：https://github.com/opendatalab/PDF-Extract-Kit