1. 為什么要在 Windows 上折騰 MinerU 4.0 本地部署RAG 做久了你會(huì)發(fā)現(xiàn)一個(gè)很尷尬的事實(shí)模型換了一茬又一茬向量庫(kù)從 FAISS 換到 Milvus 再換到 Qdrant檢索策略從樸素向量召回一路升級(jí)到混合檢索加重排序但整個(gè)鏈路里最拖后腿的往往不是這些高級(jí)環(huán)節(jié)而是最不起眼的 PDF 解析。我見(jiàn)過(guò)太多項(xiàng)目檢索效果差、答非所問(wèn)、表格數(shù)據(jù)全亂追根溯源最后都指向同一個(gè)問(wèn)題——文檔預(yù)處理階段把內(nèi)容喂壞了。MinerU 4.0 就是沖著這個(gè)痛點(diǎn)來(lái)的。它本質(zhì)上是一個(gè)面向 RAG 場(chǎng)景優(yōu)化的文檔解析工具能把 PDF、圖片、Office 文檔轉(zhuǎn)成結(jié)構(gòu)清晰的 Markdown 和 JSON尤其是對(duì)公式、表格、多欄排版的處理比市面上大多數(shù)通用解析庫(kù)要靠譜得多。而本地部署這四個(gè)字對(duì)很多團(tuán)隊(duì)來(lái)說(shuō)是剛需合同、財(cái)報(bào)、內(nèi)部技術(shù)文檔這些東西你不可能往公有云 API 上扔。所以這篇就聊聊怎么在 Windows 上把 MinerU 4.0 跑起來(lái)并且真正用到 RAG 的文檔預(yù)處理流程里。這篇文章適合三類人看一是正在搭 RAG 知識(shí)庫(kù)、被 PDF 解析折磨過(guò)的工程師二是需要在離線環(huán)境處理敏感文檔的團(tuán)隊(duì)三是想搞清楚 MinerU 到底值不值得從別的方案遷移過(guò)來(lái)的技術(shù)選型者。我會(huì)把環(huán)境準(zhǔn)備、模型下載、參數(shù)調(diào)優(yōu)、批量處理腳本、常見(jiàn)報(bào)錯(cuò)排查都講透盡量讓你照著做就能跑通而不是看完還得自己猜。先說(shuō)結(jié)論Windows 上部署 MinerU 4.0 完全可行但坑比 Linux 多主要集中在 CUDA 環(huán)境、模型下載和路徑處理這三塊。下面按實(shí)操順序展開(kāi)。2. 部署前的整體思路與環(huán)境選型2.1 為什么選本地部署而不是調(diào) API很多人第一反應(yīng)是直接用 MinerU 的在線 API省事。但實(shí)際項(xiàng)目里本地部署有三個(gè)繞不開(kāi)的理由。第一是數(shù)據(jù)合規(guī)。RAG 知識(shí)庫(kù)處理的文檔往往包含未公開(kāi)的商業(yè)信息走外部接口意味著數(shù)據(jù)出了你的邊界這在很多行業(yè)是直接一票否決的。第二是成本可控。API 按量計(jì)費(fèi)文檔量一大費(fèi)用漲得比算力還快而本地部署是一次性投入后續(xù)邊際成本幾乎為零。第三是可定制。本地部署你能改解析參數(shù)、能接自己的后處理邏輯、能控制并發(fā)和緩存策略API 只能用它給你的那套。當(dāng)然本地部署也有代價(jià)你得有塊像樣的顯卡。MinerU 4.0 的模型推理對(duì)顯存有要求后面會(huì)具體說(shuō)。2.2 硬件與系統(tǒng)的最低門檻我把實(shí)測(cè)下來(lái)能跑和跑得舒服的配置列一下方便你對(duì)號(hào)入座。配置項(xiàng)最低可用推薦配置說(shuō)明操作系統(tǒng)Windows 10 64位Windows 11 22H2需要支持 WSL2 或原生 CUDA顯卡GTX 1660 6GBRTX 3060 12GB 及以上顯存決定能跑哪些模型內(nèi)存16GB32GB批量處理時(shí)內(nèi)存吃緊硬盤20GB 空閑50GB SSD模型文件本身就有十幾個(gè) GPython3.103.10 或 3.113.12 部分依賴還沒(méi)跟上這里要特別提醒一句顯存是硬門檻。6GB 顯存只能跑輕量模式表格和公式識(shí)別會(huì)降級(jí)12GB 才能比較舒服地跑完整流程。如果你只有核顯或者顯存不夠也不是完全沒(méi)戲可以用 CPU 模式但速度會(huì)慢到讓你懷疑人生一篇幾十頁(yè)的 PDF 可能要跑好幾分鐘。2.3 部署路線的兩種選擇Windows 上部署 MinerU 有兩條路一是原生 Windows 環(huán)境直接裝二是走 WSL2。我的建議是如果你只是偶爾處理幾篇文檔原生裝就行如果要批量處理、要長(zhǎng)期跑服務(wù)強(qiáng)烈建議上 WSL2。原因很實(shí)際MinerU 底層依賴的一些庫(kù)在 Windows 原生環(huán)境下編譯經(jīng)常出問(wèn)題尤其是涉及 CUDA 擴(kuò)展的部分。WSL2 里跑的是完整的 Linux 環(huán)境依賴安裝順暢得多而且性能損耗很小。不過(guò) WSL2 也有它的麻煩比如文件系統(tǒng)跨系統(tǒng)訪問(wèn)慢、GPU 直通需要額外配置。下面我兩條路都會(huì)講你根據(jù)自己的情況選。3. 原生 Windows 環(huán)境搭建實(shí)操3.1 Python 環(huán)境與虛擬環(huán)境隔離第一步永遠(yuǎn)是環(huán)境隔離。我踩過(guò)太多次坑系統(tǒng) Python 里裝了一堆東西最后依賴沖突到?jīng)]法排查。用 conda 或者 venv 都行我個(gè)人習(xí)慣 conda因?yàn)楣芾?CUDA 版本方便。conda create -n mineru python3.10 -y conda activate mineru創(chuàng)建完先別急著裝 MinerU先把 pip 源換一下不然下載速度能讓你等到睡著。國(guó)內(nèi)的話用清華源或者阿里源都行。pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple這里有個(gè)細(xì)節(jié)MinerU 4.0 對(duì) PyTorch 版本有要求不要自己先裝 PyTorch讓它作為依賴自動(dòng)裝否則版本對(duì)不上會(huì)報(bào)一堆莫名其妙的錯(cuò)。3.2 CUDA 與 PyTorch 的版本匹配這是 Windows 部署最容易翻車的地方。CUDA 版本、顯卡驅(qū)動(dòng)、PyTorch 版本三者必須匹配錯(cuò)一個(gè)就跑不起來(lái)。先確認(rèn)你的顯卡驅(qū)動(dòng)支持的 CUDA 版本命令行執(zhí)行nvidia-smi右上角會(huì)顯示 CUDA Version。注意這個(gè)是你驅(qū)動(dòng)支持的最高版本不是你必須裝的版本。然后去 PyTorch 官網(wǎng)查對(duì)應(yīng)關(guān)系比如 CUDA 11.8 對(duì)應(yīng)cu118的安裝包。# 以 CUDA 11.8 為例裝完后 MinerU 會(huì)自動(dòng)拉取匹配的 torch pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118裝完驗(yàn)證一下 GPU 是否可用import torch print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0))如果輸出True和你的顯卡型號(hào)說(shuō)明環(huán)境沒(méi)問(wèn)題。如果輸出False八成是 CUDA 版本和 PyTorch 不匹配或者驅(qū)動(dòng)太舊回去檢查。注意不要同時(shí)裝 CPU 版和 GPU 版的 PyTorch會(huì)沖突。如果之前裝過(guò)先pip uninstall torch torchvision卸干凈再重裝。3.3 安裝 MinerU 4.0 本體環(huán)境對(duì)了裝 MinerU 就簡(jiǎn)單了。官方推薦用 pip 裝也可以從源碼裝。pip install mineru如果你要用最新的 4.0 特性建議從源碼裝git clone https://github.com/opendatalab/MinerU.git cd MinerU pip install -e .裝完之后跑一下mineru --version確認(rèn)安裝成功。第一次運(yùn)行會(huì)自動(dòng)下載模型這一步是很多人卡住的地方因?yàn)槟Ｐ臀募泻脦讉€(gè) G網(wǎng)絡(luò)不好會(huì)一直卡在獲取中。3.4 模型文件的離線下載與放置模型下載慢或者下不動(dòng)是 Windows 部署的高頻問(wèn)題。解決辦法是手動(dòng)下載模型文件然后放到指定目錄。MinerU 的模型默認(rèn)放在用戶目錄下的.cache/mineru或者配置指定的路徑。你可以先跑一次讓它創(chuàng)建目錄結(jié)構(gòu)然后去 HuggingFace 或者 ModelScope 手動(dòng)下載對(duì)應(yīng)的模型文件解壓后放進(jìn)去。模型主要分幾塊版面分析模型、公式識(shí)別模型、表格識(shí)別模型、OCR 模型。如果你只處理電子版 PDF文字可選中的那種OCR 模型可以不裝能省不少空間。實(shí)操心得模型下載建議用 ModelScope 的鏡像國(guó)內(nèi)速度快很多。下載完記得校驗(yàn)文件完整性我遇到過(guò)一次模型文件下了一半結(jié)果解析出來(lái)全是亂碼排查了半天才發(fā)現(xiàn)是模型損壞。4. 用 WSL2 部署的進(jìn)階方案4.1 WSL2 環(huán)境準(zhǔn)備與 GPU 直通如果你決定走 WSL2先在 PowerShell 里裝好 WSL2 和一個(gè) Ubuntu 發(fā)行版。wsl --install -d Ubuntu-22.04裝完進(jìn) Ubuntu更新一下系統(tǒng)然后裝 CUDA Toolkit。WSL2 的 GPU 直通需要 Windows 側(cè)的驅(qū)動(dòng)支持只要你的顯卡驅(qū)動(dòng)是較新版本W(wǎng)SL2 里直接就能用nvidia-smi看到顯卡。sudo apt update sudo apt upgrade -y sudo apt install -y build-essential python3-pip python3-venvWSL2 里裝 CUDA 不用裝完整驅(qū)動(dòng)只裝 toolkit 就行驅(qū)動(dòng)是 Windows 側(cè)提供的。4.2 WSL2 下的依賴安裝與驗(yàn)證WSL2 里裝 MinerU 和原生 Windows 差不多但依賴編譯順暢得多。python3 -m venv mineru-env source mineru-env/bin/activate pip install --upgrade pip pip install mineru驗(yàn)證 GPUpython -c import torch; print(torch.cuda.is_available())WSL2 的一個(gè)坑是文件系統(tǒng)性能。如果你把文檔放在 Windows 的/mnt/c/下讀寫會(huì)非常慢。建議把待處理文檔復(fù)制到 WSL2 的 Linux 文件系統(tǒng)里比如~/data/處理速度能快好幾倍。4.3 兩種方案怎么選簡(jiǎn)單給個(gè)決策建議單次處理、文檔量小、不想折騰選原生 Windows批量處理、要跑服務(wù)、追求穩(wěn)定選 WSL2。我自己的生產(chǎn)環(huán)境是 WSL2開(kāi)發(fā)調(diào)試用原生兩邊都留著。5. 核心解析流程與參數(shù)調(diào)優(yōu)5.1 單文件解析的最小可用命令MinerU 的命令行接口設(shè)計(jì)得挺直觀最基礎(chǔ)的用法就一行mineru -p input.pdf -o output_dir它會(huì)輸出 Markdown 和 JSON 兩種格式。Markdown 適合直接喂給 RAG 的文本切分環(huán)節(jié)JSON 保留了版面結(jié)構(gòu)信息適合做更精細(xì)的處理。但默認(rèn)參數(shù)不一定適合你的場(chǎng)景下面幾個(gè)參數(shù)是必須調(diào)的。5.2 關(guān)鍵參數(shù)逐個(gè)拆解--method解析方法有auto、txt、ocr三個(gè)選項(xiàng)。電子版 PDF 用txt最快掃描件必須用ocrauto讓它自己判斷。我一般電子版直接指定txt省得它誤判。--lang語(yǔ)言設(shè)置中文文檔一定要指定ch不然 OCR 識(shí)別率會(huì)掉一大截。--device指定cuda或cpu。有顯卡就cuda別猶豫。--batch-size批處理大小顯存夠就調(diào)大能提升吞吐。12GB 顯存可以設(shè)到 8 或 166GB 就老實(shí)設(shè) 2 或 4。--formula和--table是否啟用公式和表格識(shí)別。這兩個(gè)功能吃顯存如果文檔里沒(méi)有公式表格關(guān)掉能快不少。一個(gè)比較通用的命令長(zhǎng)這樣mineru -p input.pdf -o output_dir --method txt --lang ch --device cuda --batch-size 8 --formula --table5.3 輸出結(jié)果的結(jié)構(gòu)解讀解析完的輸出目錄里你會(huì)看到幾個(gè)文件。.md是轉(zhuǎn)換后的 Markdown.json是結(jié)構(gòu)化數(shù)據(jù)還有images/目錄存的是從 PDF 里抽出來(lái)的圖片。JSON 的結(jié)構(gòu)值得研究一下它把每個(gè)元素都標(biāo)了類型text、title、table、formula、image。做 RAG 的時(shí)候你可以根據(jù)類型做差異化處理——標(biāo)題作為層級(jí)切分依據(jù)表格單獨(dú)走結(jié)構(gòu)化存儲(chǔ)公式轉(zhuǎn)成 LaTeX 保留。實(shí)操心得不要直接把 Markdown 整篇丟進(jìn)向量庫(kù)。MinerU 輸出的 Markdown 里表格是 HTML 格式的直接切分會(huì)把表格切碎。正確做法是先按標(biāo)題層級(jí)切分表格單獨(dú)抽出來(lái)做結(jié)構(gòu)化處理再?zèng)Q定是轉(zhuǎn)成文本描述還是存成結(jié)構(gòu)化數(shù)據(jù)。6. 接入 RAG 文檔預(yù)處理流水線6.1 從解析到切分的完整鏈路MinerU 只是預(yù)處理的第一步后面還要接切分、向量化、入庫(kù)。我一般這么設(shè)計(jì)流水線MinerU 解析 PDF輸出 Markdown 和 JSON按 JSON 里的標(biāo)題層級(jí)做語(yǔ)義切分而不是按固定字?jǐn)?shù)硬切表格和公式單獨(dú)處理表格轉(zhuǎn)成自然語(yǔ)言描述或結(jié)構(gòu)化存儲(chǔ)切分后的 chunk 做向量化連同元數(shù)據(jù)一起入庫(kù)這個(gè)鏈路里第 2 步是關(guān)鍵。固定字?jǐn)?shù)切分是最偷懶也最傷效果的做法它會(huì)把一個(gè)完整的語(yǔ)義單元切碎。用 MinerU 給的標(biāo)題層級(jí)做切分能保證每個(gè) chunk 語(yǔ)義完整。6.2 批量處理的腳本實(shí)現(xiàn)單文件處理用命令行就夠了批量處理得寫腳本。下面這個(gè)腳本是我實(shí)際在用的做了并發(fā)控制和錯(cuò)誤重試。import os import subprocess from concurrent.futures import ThreadPoolExecutor, as_completed from pathlib import Path def parse_pdf(pdf_path, output_root): pdf_path Path(pdf_path) out_dir Path(output_root) / pdf_path.stem out_dir.mkdir(parentsTrue, exist_okTrue) cmd [ mineru, -p, str(pdf_path), -o, str(out_dir), --method, txt, --lang, ch, --device, cuda, --batch-size, 8 ] try: subprocess.run(cmd, checkTrue, capture_outputTrue, timeout600) return pdf_path.name, True, except subprocess.TimeoutExpired: return pdf_path.name, False, timeout except subprocess.CalledProcessError as e: return pdf_path.name, False, e.stderr.decode()[:200] def batch_parse(input_dir, output_dir, max_workers2): pdfs list(Path(input_dir).glob(*.pdf)) results [] with ThreadPoolExecutor(max_workersmax_workers) as executor: futures {executor.submit(parse_pdf, p, output_dir): p for p in pdfs} for future in as_completed(futures): name, ok, msg future.result() results.append((name, ok, msg)) print(f{name}: {OK if ok else FAIL - msg}) return results if __name__ __main__: batch_parse(./pdfs, ./parsed, max_workers2)這里max_workers不要設(shè)太大因?yàn)槊總€(gè)進(jìn)程都要占顯存設(shè)成 2 比較穩(wěn)。設(shè)太大反而會(huì)因?yàn)轱@存不足頻繁失敗。6.3 表格與公式的特殊處理RAG 里表格是最難處理的部分。MinerU 能把表格識(shí)別成 HTML但 HTML 直接進(jìn)向量庫(kù)效果很差。我的做法是把表格轉(zhuǎn)成 Markdown 表格再給表格加一段自然語(yǔ)言摘要兩者一起存。公式的話MinerU 輸出的是 LaTeX直接保留就行。檢索時(shí)如果用戶問(wèn)的是公式相關(guān)內(nèi)容LaTeX 文本也能被匹配到。注意表格識(shí)別不是百分百準(zhǔn)確尤其是跨頁(yè)表格和復(fù)雜合并單元格。批量處理完一定要抽樣檢查別全信自動(dòng)結(jié)果。7. 常見(jiàn)報(bào)錯(cuò)與排查速查7.1 模型下載卡住或失敗最常見(jiàn)的報(bào)錯(cuò)就是一直顯示獲取中。原因基本是網(wǎng)絡(luò)問(wèn)題。解決辦法是手動(dòng)下載模型放到緩存目錄或者配置鏡像源。export HF_ENDPOINThttps://hf-mirror.comWindows 下用set代替export。設(shè)完再跑下載速度會(huì)正常。7.2 CUDA out of memory顯存不夠。解決辦法按優(yōu)先級(jí)調(diào)小--batch-size、關(guān)掉--formula和--table、換更小的模型、實(shí)在不行上 CPU。7.3 中文亂碼或識(shí)別錯(cuò)誤檢查--lang是不是設(shè)成了ch。另外確認(rèn)模型文件完整損壞的模型會(huì)導(dǎo)致輸出亂碼。7.4 路徑含中文或空格導(dǎo)致失敗Windows 下路徑帶中文或空格經(jīng)常出問(wèn)題。把待處理文件放到純英文、無(wú)空格的路徑下能避免一大類莫名其妙的錯(cuò)誤。報(bào)錯(cuò)現(xiàn)象可能原因解決方向一直獲取中網(wǎng)絡(luò)問(wèn)題配鏡像或手動(dòng)下模型CUDA OOM顯存不足調(diào)小 batch、關(guān)功能輸出亂碼模型損壞或語(yǔ)言設(shè)錯(cuò)校驗(yàn)?zāi)Ｐ?、設(shè) lang路徑報(bào)錯(cuò)中文/空格路徑換純英文路徑依賴沖突環(huán)境不干凈重建虛擬環(huán)境7.5 排查思路的通用原則遇到報(bào)錯(cuò)先看日志MinerU 的日志會(huì)告訴你卡在哪一步。是模型加載失敗還是推理過(guò)程出錯(cuò)還是輸出寫入失敗定位到具體環(huán)節(jié)再對(duì)癥下藥。別一上來(lái)就重裝那樣只會(huì)浪費(fèi) time。8. 性能優(yōu)化與生產(chǎn)化建議8.1 提升吞吐的幾個(gè)手段批處理大小、并發(fā)數(shù)、模型選擇這三個(gè)是影響吞吐的主要因素。顯存夠的話把 batch-size 調(diào)大是最直接的。另外如果文檔里大部分是純文本關(guān)掉公式和表格識(shí)別能快一倍以上。還有一個(gè)容易被忽略的點(diǎn)把模型常駐內(nèi)存。如果你要連續(xù)處理大量文檔別每次都重新加載模型寫個(gè)常駐服務(wù)模型加載一次反復(fù)用。8.2 緩存策略同一份文檔可能被處理多次加個(gè)緩存能省很多算力。用文件哈希做 key處理過(guò)的直接讀緩存結(jié)果。import hashlib def file_hash(path): h hashlib.md5() with open(path, rb) as f: for chunk in iter(lambda: f.read(8192), b): h.update(chunk) return h.hexdigest()8.3 與向量庫(kù)的對(duì)接解析完的 chunk 要入庫(kù)。我一般用 Milvus 或 Qdrant元數(shù)據(jù)里存上來(lái)源文件名、頁(yè)碼、元素類型方便檢索時(shí)做過(guò)濾和溯源。這一步別偷懶元數(shù)據(jù)設(shè)計(jì)好了后面做引用回溯會(huì)輕松很多。9. 我踩過(guò)的坑和幾條實(shí)在建議部署 MinerU 這一路坑是真不少。最開(kāi)始我在原生 Windows 上裝CUDA 版本和 PyTorch 對(duì)不上折騰了一下午。后來(lái)?yè)Q WSL2順暢多了但文件系統(tǒng)跨系統(tǒng)訪問(wèn)慢的問(wèn)題又冒出來(lái)把文檔挪到 Linux 側(cè)才解決。模型下載那塊也吃過(guò)虧第一次下到一半斷了沒(méi)校驗(yàn)就用結(jié)果解析出來(lái)全是亂碼還以為是參數(shù)問(wèn)題查了半天才發(fā)現(xiàn)是模型文件損壞。從那以后我養(yǎng)成了下載完先校驗(yàn)的習(xí)慣。還有一點(diǎn)別迷信自動(dòng)解析的結(jié)果。表格、公式、復(fù)雜排版自動(dòng)識(shí)別總有出錯(cuò)的時(shí)候。生產(chǎn)環(huán)境一定要加人工抽檢環(huán)節(jié)尤其是關(guān)鍵文檔。RAG 的效果上限很大程度上取決于預(yù)處理的質(zhì)量這一步偷懶后面檢索再花哨也救不回來(lái)。如果你剛開(kāi)始搞我的建議是先拿幾篇有代表性的文檔跑通全流程把參數(shù)調(diào)順了再上批量。別一上來(lái)就幾百篇一起跑出了問(wèn)題你都不知道是哪篇、哪個(gè)環(huán)節(jié)的鍋。穩(wěn)扎穩(wěn)打比什么都強(qiáng)。