---
slug: mineru-document-parsing-rag-output-contract
status: published
title: "MinerU 3.4.5：把複雜文件接進 RAG，先鎖住輸出契約"
excerpt: "MinerU 能把 PDF、Office 文件與圖片轉成 Markdown、JSON 與 QA 產物；真正影響 RAG 可維護性的，是 backend、版本與結構化輸出契約。"
category: AI
tags: [document-parsing, OCR, RAG, agent, markdown, json]
source_repository: "https://github.com/opendatalab/MinerU"
source_ref: "4fe4bde114a23ee5dd637eae99b767f4669bf58c"
research_boundary: "Static repository inspection only; MinerU was not installed, started, or used to parse documents in this review."
author: Seer
author_role: Author
read_time: 9 min
cover: "/static/mineru-document-parsing-rag-output-contract-cover.png"
closing_note: ""
published_at: "2026-09-05T15:30:00Z"
updated_at: "2026-09-05T15:30:00Z"
---

# MinerU 3.4.5：把複雜文件接進 RAG，先鎖住輸出契約

[MinerU](https://github.com/opendatalab/MinerU) 的核心功能是把 `PDF`、圖片、`DOCX`、`PPTX`、`XLSX` 轉成 Markdown、JSON 與供人工檢查的輔助產物。它的定位在 RAG、資料萃取與 agent workflow 的前處理層，負責把難讀的文件拆成可追溯的結構；後續的 chunk、embedding、檢索、ACL 與答案引用，依然要由下游系統處理。[1][2][3]

評估這類工具時，很多團隊會先問「OCR 準不準」或「能不能直接轉 Markdown」。但真正影響知識庫維護成本的，往往是後續的 schema 漂移：同一批文件只要換了 backend、版本或模型路徑，JSON 欄位與內容結構就會跟著改變，而 ingest pipeline 若沒留下記錄便難以追查。MinerU 的 output docs 也已直接提醒：VLM 2.5 的結構化輸出與 pipeline 並不相容。[5]

這篇文章主要探討一個務實問題：MinerU 適不適合放進你既有的 RAG 解析層？整理內容涵蓋它實際輸出的檔案類型、不同 backend 對資料契約的影響、單機與多 worker 介面的分工方式，以及導入前應建立的驗收機制。本文以固定 commit `4fe4bde114a23ee5dd637eae99b767f4669bf58c` 的靜態 source inspection 為準；過程中沒有安裝、下載模型、啟動服務或實際執行文件解析。[1][9]

## 先看重點

- **先鎖定版本與 backend，再串接 RAG。** 每次 ingestion 至少記錄原始檔 hash、MinerU version、backend 與輸出 schema；VLM 2.5 與 pipeline 的 JSON 結構不可直接混用。
- **分開保存 Markdown、結構化 JSON 與 QA PDF。** Markdown 供人工與 LLM 閱讀，JSON 對接 adapter 與 metadata，layout／span PDF 則留給人工驗收與除錯。
- **預設採用 `hybrid-engine`。** 預設的 `medium` effort 會關閉圖片與圖表分析；若需要這層能力，須切換至 `high`。
- **區分 CLI、FastAPI 與 router 三個部署層級。** 單次或批次解析使用 CLI；服務化部署呼叫 `mineru-api`；面對多個 upstream 或本機 GPU worker 排程時，才需要 `mineru-router`。

## 先把 MinerU 放回正確的位置

文件解析產物不等於可直接上線的知識庫。MinerU 提供的是閱讀順序、段落、標題、表格、公式、圖片／圖表區塊與機器可讀的結構；一條完整的 RAG pipeline，後續仍需串接版本控管、chunk 規則、embedding、檢索權限、引用標記與重建機制。[2][5]

| 使用場景 | MinerU 提供什麼 | 下游仍要負責什麼 |
|---|---|---|
| 技術文件知識庫 | Markdown、區塊化 JSON、圖片與表格資產 | chunk、embedding、文件版本、ACL、retrieval citation |
| 掃描 PDF 數位化 | OCR 路徑與 layout／span QA 產物 | 抽樣驗收、錯字／表格修正、敏感資料規則 |
| Office 文件統一 ingest | DOCX、PPTX、XLSX 與 PDF 走進同一解析入口 | 檔案分流、欄位映射、格式差異與回歸測試 |
| 多服務解析平台 | API、非同步 task、router 的 upstream／worker 編排 | 認證、網路邊界、佇列、保存期限、監控與成本 |

這張表的用意很明確：把「文件解析完成」與「知識庫值得信任」兩件事切開。前者是 parser 的工作，後者則是整套 ingest 系統的工程責任。

## Output contract 比模型名稱更早要定

MinerU 目前公開的 backend 包含 `pipeline`、`vlm-engine`、`hybrid-engine`，以及將推理委派給 OpenAI-compatible server 的 `vlm-http-client`／`hybrid-http-client`。固定 commit 的原始碼預設為 `hybrid-engine`，且 Hybrid 的預設 `effort` 為 `medium`。[4]

| Backend | 解析與推理位置 | 適合的起手情境 | 導入時要固定的邊界 |
|---|---|---|---|
| `pipeline` | 本機通用路徑 | CPU 可跑的基線、一般文件、先建立 QA fixture | `auto`／`txt`／`ocr` 是另一組解析選項；輸出不能和 VLM 當作同一 schema |
| `hybrid-engine` | 本機 Hybrid 路徑 | 預設使用方式、文字 PDF 與高精度解析需求並存 | `medium` 會停用圖片／圖表分析；要啟用須選 `high` |
| `vlm-engine` | 本機 VLM 路徑 | 已準備本機 VLM 計算環境 | 為它獨立建立 JSON adapter 與 regression fixtures |
| `*-http-client` | 指定的遠端 OpenAI-compatible server | 已有 vLLM、SGLang、LMDeploy 或遠端推理服務 | 文件資料會離開本機；URL、授權、資料保留與失敗重試需自己治理 |

`hybrid-engine` 的 `medium` 與 `high` 不只是運算負載的差異。CLI option help 載明：`medium` 是針對多數文件設計的平衡預設，會關閉圖片與圖表分析；切換到 `high` 才會啟用該能力。[4]

串接 RAG 之前，建議在資料層明確記錄這組複合契約：

```text
source_file_sha256
  + mineru_version
  + backend
  + output_schema_revision
```

`middle.json` 內部已包含 `_backend` 與 `_version_name`。將這些欄位連同原始檔案 hash 寫入 ingest metadata，日後才能清楚追蹤「特定 chunk 來自哪份文件、由哪條路徑產出、何時需要重新處理」。[5]

## Markdown 之外，留下可以驗收的產物

MinerU 的 output docs 將輸出分為閱讀文本、結構化資料與視覺檢查三類產物，實務上各有不同用途：

- **Markdown 與圖片資產：** 供人工瀏覽或作為 LLM / RAG 前段檢索文本。
- **`middle.json`、`content_list.json`：** 保留頁碼、區塊 type、bbox、閱讀順序與中介結構，方便開發者自訂轉換 adapter。
- **`{filename}_layout.pdf`：** 透過外框與序號標記，輔助檢查 layout 判斷與閱讀順序。
- **`{filename}_span.pdf`：** 為 pipeline 專用產物，用來排查文字缺漏、行內公式或斷詞切分狀況。

若文件會進入正式知識庫，建議將第三類 QA 產物納入例行抽樣驗收。當遇到檢索引用錯誤欄位、表格對齊跑版或掃描檔漏字時，單看 Markdown 往往難以釐清原因；保留 layout 與 span 視覺檔，才能準確判斷問題出在版面辨識、OCR 引擎、結構轉檔，還是下游的 chunking 策略。[5]

## CLI、API 與 router 各自解什麼問題

官方 README 記載的最小 CLI 指令如下（此為文件查核記錄，本文未實際執行）：

```bash
# 預設 backend：fixed source 目前是 hybrid-engine
mineru -p <input_path> -o <output_path>

# 沒有 GPU 加速條件時，README 建議使用 pipeline
mineru -p <input_path> -o <output_path> -b pipeline
```

套件中同時註冊了 `mineru-api`、`mineru-router`、模型 server 與 Gradio 等 entrypoints。[3]

- **`mineru` CLI：** 適合單機執行或批次腳本處理。若未帶 `--api-url`，其 help 宣告會啟動暫時的本機 `mineru-api`。
- **`mineru-api`：** 預設監聽 `127.0.0.1:8000`，提供同步 `POST /file_parse` 與非同步 `POST /tasks` 等介面。
- **`mineru-router`：** 預設監聽 `127.0.0.1:8002`，支援掛載多個 `--upstream-url` 並管理本機 GPU worker，適合開始將解析負載分派給多個服務時使用。

Router 採用常見的非同步工作流設計：

```text
POST /tasks
  → 202 + task id
  → GET /tasks/{task_id}
  → GET /tasks/{task_id}/result
```

上述預設均綁定在 loopback。若需對外提供服務，source 針對 `*-http-client`／`server_url` 設計了 public bind 下的存取控制開關。實務部署時，仍須自行在前端補足身份驗證、上傳大小限制、上游 URL 白名單、暫存清理與審計日誌（audit log）；原始碼能確認端點與保護開關的定義，但正式生產環境的安全與穩定性仍取決於整體架構設計。[6][7]

## macOS 與模型下載：先把環境當成前置條件

README 標註 macOS 的系統需求為 14.0 以上，套件 metadata 的 Python 支援範圍則是 3.10–3.13。Docker 相關文件目前僅涵蓋 Linux 與支援 WSL2 的 Windows；macOS 需透過 pip、uv 或 source install 安裝。此外，README 說明首次執行時預設會自 Hugging Face 下載並快取模型，若網路連線受限，可切換環境變數 `MINERU_MODEL_SOURCE=modelscope`。[2][3]

軟體運作狀況會隨具體環境而異。文件記載的是官方支援與建議規格，實際解析成果仍受文件型態、backend 選擇、模型版本、Apple Silicon／GPU 狀態及記憶體負載影響。在進行技術選型時，建議直接挑選具代表性的文件集建立驗收 fixture，完整保留輸出檔案、QA PDF 與異常樣本，這會比單看環境規格表更能作為評估依據。

## License 要看完整條文

MinerU 的 package metadata 指向自訂的 `LicenseRef-MinerU-Open-Source-License`。其 `LICENSE.md` 以 Apache-2.0 為基礎，並增設了商業規模門檻與線上服務標示要求：[3][8]

- 允許一般商業使用；若使用者及其關係企業合併計算的 MAU 超過 1 億，或單月總營收超過 2,000 萬美元，繼續使用前須另行取得商業授權。
- 若對第三方提供基於 MinerU 的線上服務（online service），產品介面或公開文件中需明確標示使用 MinerU。
- 若未符合授權取得或標示規範，該授權條款將自動終止。

以上為固定 commit 的條文重點摘要，不構成法律建議。若規劃將 MinerU 整合進 SaaS 產品或大規模商用系統，建議由法務團隊針對實際採用的版本重新審核。

## 先跑一個小型 contract pilot，再決定要不要擴大

導入 MinerU 的主要價值在於建立一套可追溯的文件解析層。初期導入時，建議先挑選 10 到 30 份具代表性且結構複雜的文件進行驗證，例如文字 PDF、掃描檔、多欄排版、跨頁長表格、數理公式、DOCX、PPTX 及 XLSX。

測試時為每份文件記錄原始檔案 hash、使用的 backend、套件版本，並完整保留 Markdown、結構化 JSON 與 QA PDF。透過這批 fixture 逐一檢查閱讀順序、文字缺漏、表格結構、公式與圖表還原度，確認產出符合預期後，再將 parser output 對接至正式的 ingest adapter。在前期把驗收契約訂清楚，後續維護向量資料庫的成本會精準許多。

## Sources

- [1：MinerU repository，固定 commit](https://github.com/opendatalab/MinerU/tree/4fe4bde114a23ee5dd637eae99b767f4669bf58c)
- [2：README_zh-CN，能力、安裝與環境支援](https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/README_zh-CN.md)
- [3：pyproject.toml，Python 範圍與 CLI entrypoints](https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/pyproject.toml)
- [4：backend_options.py，backend 與預設值](https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/cli/backend_options.py)
- [5：output_files.md，輸出產物與 schema 相容性](https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/docs/en/reference/output_files.md)
- [6：fast_api.py，FastAPI 預設 bind 與 task API](https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/cli/fast_api.py)
- [7：router.py，router、upstream 與 worker options](https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/cli/router.py)
- [8：LICENSE.md，Apache-2.0 附加條款](https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/LICENSE.md)
- [9：version.py，固定 commit 的套件版本](https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/version.py)