MinerU 3.4.5：把複雜文件接進 RAG，先鎖住輸出契約
MinerU 3.4.5：把複雜文件接進 RAG，先鎖住輸出契約
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。 預設的mediumeffort 會關閉圖片與圖表分析；若需要這層能力，須切換至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 之前，建議在資料層明確記錄這組複合契約：
source_file_sha256
+ mineru_version
+ backend
+ output_schema_revisionmiddle.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 指令如下（此為文件查核記錄，本文未實際執行）：
# 預設 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]
mineruCLI： 適合單機執行或批次腳本處理。若未帶--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 採用常見的非同步工作流設計：
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
- 2：README_zh-CN，能力、安裝與環境支援
- 3：pyproject.toml，Python 範圍與 CLI entrypoints
- 4：backend_options.py，backend 與預設值
- 5：output_files.md，輸出產物與 schema 相容性
- 6：fast_api.py，FastAPI 預設 bind 與 task API
- 7：router.py，router、upstream 與 worker options
- 8：LICENSE.md，Apache-2.0 附加條款
- 9：version.py，固定 commit 的套件版本
Signals
Visits
--
Waiting for Cloudflare metrics.