做 RAG 的人早晚會遇到一個靈魂拷問辛苦搭好的向量庫為什么檢索出來的內(nèi)容總是答非所問我自己的經(jīng)驗里一半以上問題出在文檔解析這一步。PDF 解析質(zhì)量不行后面向量化、檢索做得再花哨也是白搭。所以這次我決定把 MinerU 4.0 在 Windows 上老老實實本地部署一遍用它做 RAG 文檔預(yù)處理把 PDF 離線解析成結(jié)構(gòu)化 Markdown。這篇東西就是完整記錄從環(huán)境準(zhǔn)備、安裝踩坑、命令行和 Python API 調(diào)用到怎么把它接進(jìn) RAG 流水線全部按實際過程寫直接能抄作業(yè)。MinerU 是一款開源文檔解析工具能把 PDF 識別成帶結(jié)構(gòu)信息的 Markdown重點解決掃描件、復(fù)雜排版、表格和公式這些傳統(tǒng)文本提取工具搞不定的場景。本地部署意味著整個解析過程不依賴公網(wǎng)服務(wù)文檔不用出內(nèi)網(wǎng)對做私有知識庫、企業(yè)文檔庫的朋友來說這一步是剛需。這篇文章適合誰看已經(jīng)在做 RAG 但被 PDF 預(yù)處理折磨過的人打算把 MinerU 接進(jìn)自己知識庫流程的開發(fā)者以及想在 Windows 上跑通 GPU/CPU 解析環(huán)境的新手。我會盡量把原理和操作都講透讓你看完不是只會跑命令而是知道為什么這么做。1. 為什么 RAG 的老毛病出在文檔解析做 RAG 檢索增強(qiáng)生成常規(guī)流程就是文檔加載、文本清洗、切片、向量化、召回、再扔給大模型生成答案。大部分人把精力花在切分策略和向量庫調(diào)優(yōu)上但很少會回頭懷疑一開始的文檔解析質(zhì)量。實際上這一步埋的雷最多。1.1 RAG 鏈路里最容易被低估的解析環(huán)節(jié)拿一本掃描版技術(shù)書或者一份雙欄排版的行業(yè)報告舉例。如果用 PyMuPDF 這類庫直接提取文字掃描件很多時候根本沒有文本層提取出來是空的雙欄排版提取出來則是左欄一段、右欄一段亂七八糟穿插表格會變成一堆無意義的數(shù)字串頁眉頁腳還會混進(jìn)正文語料。這些問題到了向量化階段會放大。切片按長度硬切把兩張表格內(nèi)容、正文段落和頁腳頁碼切進(jìn)同一個 chunk檢索時返回的上下文就是一堆垃圾。大模型拿到這種上下文回答自然天馬行空。我見過太多人折騰 prompt 折騰半天最后發(fā)現(xiàn)是解析環(huán)節(jié)把文檔搞壞了。所以我說RAG 的瓶頸往往不在檢索算法也不在向量庫選型而在最前面那道 PDF 解析工序。1.2 MinerU 不是普通的 PDF 轉(zhuǎn)文本工具M(jìn)inerU 和那些一鍵轉(zhuǎn) Word 的在線工具完全不是一回事。它內(nèi)部是一條完整的文檔解析管線核心做了四件事第一版面分析識別出標(biāo)題、正文、圖表、頁眉頁腳、頁碼這些區(qū)域并給出閱讀順序第二OCR 識別不依賴 PDF 自帶文本層直接對圖像做文字檢測和識別掃描件也能處理第三公式識別把數(shù)學(xué)公式轉(zhuǎn)成 LaTeX 格式而不是拍成一堆亂碼第四表格還原把表格結(jié)構(gòu)化輸出成 Markdown 表格而不是把單元格內(nèi)容擠成一行文字。4.0 版本給我最明顯的感受是整體解析速度更快版面分析模型對復(fù)雜排版的容錯能力也更強(qiáng)。底層模型雖然會隨著版本迭代有變化但核心思路沒變——先理解版面結(jié)構(gòu)再做內(nèi)容提取。這個先結(jié)構(gòu)后內(nèi)容的邏輯就是它和普通文本抽取的本質(zhì)差別。1.3 為什么選擇本地離線部署我選本地部署的原因很簡單要解析的 PDF 里有大量內(nèi)部資料不允許上傳到任何公網(wǎng)服務(wù)。離線部署意味著模型權(quán)重、推理過程全部跑在本地機(jī)器上數(shù)據(jù)不出內(nèi)網(wǎng)合規(guī)性上更讓人放心。另一個原因是批量效率在線接口通常有并發(fā)限制和大小上限本地部署沒有這些束縛解析幾十份幾百份 PDF 都行。當(dāng)然本地部署也有代價主要是環(huán)境維護(hù)和硬件要求。這篇文章我假設(shè)你用的是 Windows 10 或 11后面所有命令都是基于 Windows 環(huán)境寫的。2. 部署前必須想清楚的幾件事很多人拿到一個開源工具就急著 pip install裝完跑不起來才回頭排查環(huán)境。MinerU 不是那種零依賴的小工具部署前先搞清楚三件事用什么方式裝、用什么硬件跑、模型文件放哪里。這三點想明白后面會順暢很多。2.1 三種部署方式的取舍Windows 上跑 MinerU 主要有三條路直接 pip 安裝到原生 Windows、裝 WSL 在 Linux 子系統(tǒng)里跑、用 Docker 容器跑。我的建議是沒有特殊需求就選原生 pip最直接也和本文步驟對得上。WSL 的好處是 Linux 生態(tài)干凈但文件路徑轉(zhuǎn)發(fā)和 GPU 透傳偶爾有毛病Docker 的好處是環(huán)境隔離徹底但 Windows 上 Docker Desktop 本來就吃內(nèi)存再把模型文件塞進(jìn)容器管理起來也麻煩。我實際對比下來的結(jié)論如果你只是想在 Windows 上把 PDF 轉(zhuǎn)成 Markdown原生安裝就夠了。如果你是團(tuán)隊協(xié)作要統(tǒng)一環(huán)境那才考慮 Docker 鏡像。2.2 GPU 和 CPU 的影響有多大MinerU 的解析包含神經(jīng)網(wǎng)絡(luò)推理所以顯卡很關(guān)鍵。有 NVIDIA 顯卡并且裝好了 CUDA解析速度會快很多體驗流暢。沒有 N 卡也沒關(guān)系CPU 模式能跑只是速度慢一份幾十頁的掃描 PDF 可能要等幾分鐘而 GPU 可能十幾秒就完事。怎么判斷自己能不能用 GPU打開 PowerShell 跑一句nvidia-smi。如果正常輸出顯卡信息說明驅(qū)動已經(jīng)就緒。輸出nvidia-smi不是內(nèi)部或外部命令就得先去裝驅(qū)動。有了顯卡驅(qū)動還不夠還得確認(rèn) PyTorch 能調(diào)用 CUDA。這個后面安裝完再驗證。如果機(jī)器配置比較老只有 CPU也不要急著放棄。MinerU 本身支持 CPU 推理模型文件會選中性化一些的配置解析小文件完全可以用。只是批量處理大批 PDF 時CPU 模式的耗時可能讓你懷疑人生。2.3 模型文件與磁盤空間MinerU 是模型驅(qū)動型工具首次運行時需要下載若干模型文件包括 OCR 識別模型、版面分析模型、公式識別模型和表格模型。文件加起來少說幾 GB多則十幾 GB磁盤空間要提前留夠。模型下載地址通?？梢酝ㄟ^環(huán)境變量指定例如使用 ModelScope 魔搭這類模型倉庫按官方文檔配置好對應(yīng)變量就能走國內(nèi)可訪問的下載源。如果你有離線環(huán)境需求可以在一臺聯(lián)網(wǎng)機(jī)器上把模型下載完按緩存目錄結(jié)構(gòu)拷到離線機(jī)器上這樣部署純粹離線完全不依賴外網(wǎng)。Windows 上模型緩存目錄一般在用戶主目錄下的.cache文件夾中具體路徑看日志輸出。3. MinerU 4.0 安裝實操環(huán)境思路理清后安裝本身其實不難但有幾個細(xì)節(jié)不處理會卡住。我按實際操作順序?qū)懹龅降膱箦e也放在后面一起說。3.1 用虛擬環(huán)境隔離避免把系統(tǒng) Python 搞亂我強(qiáng)烈建議先用虛擬環(huán)境隔離。MinerU 依賴的包版本比較倔和公司里其他 Python 項目混在一起容易沖突。具體來說用 conda 或者 Python 自帶的 venv 都行。conda create -n mineru python3.10 -y conda activate mineru如果你不想裝 conda用 venv 也可以python -m venv mineru-env .\mineru-env\Scripts\activate激活后命令行前面會出現(xiàn)(mineru-env)這樣的前綴說明當(dāng)前環(huán)境的 Python 已經(jīng)隔離了。這個步驟很關(guān)鍵后面裝再多的包也不會影響系統(tǒng)里其他項目。3.2 pip 安裝與版本驗證激活環(huán)境后直接裝 MinerUpip install mineru如果下載速度不理想可以臨時指定 pip 鏡像源pip install mineru -i https://pypi.tuna.tsinghua.edu.cn/simple安裝完成后驗證一下mineru --version能輸出版本號就說明裝上了。我在 Windows 上遇到過一個問題裝完命令報不是內(nèi)部或外部命令原因通常是虛擬環(huán)境的 Scripts 目錄沒進(jìn) PATH或者終端沒重啟。重新激活環(huán)境、重開終端一般能解決。3.3 模型下載與首次運行第一次運行 MinerU 時它會自動下載模型這個階段特別考驗網(wǎng)絡(luò)。我的建議是在跑正式文件之前先拿一個小 PDF 試一次故意讓它在模型下載環(huán)節(jié)跑起來這個時候你要盯住日志看模型下載是否成功。如果你有網(wǎng)絡(luò)條件限制可以提前用環(huán)境變量把模型倉庫切到 ModelScope。在 PowerShell 里設(shè)置$env:MODELSCOPE_CACHE D:\models $env:MODELSCOPE_DOMAIN modelscope.cn然后再跑解析命令。模型會下載到指定目錄后面再用就不需要重復(fù)下載了。如果想完全離線把整個緩存目錄拷到目標(biāo)機(jī)器的同樣位置就能復(fù)用。3.4 Windows 上常見安裝報錯我實際踩過的坑不多但確實有幾個典型問題值得提前說。第一個是 Microsoft C Build Tools 缺失。部分依賴包在 Windows 上需要編譯原生代碼報錯信息一般是error: Microsoft Visual C 14.0 is required。解決辦法就是去裝 Visual Studio Build Tools安裝時勾選“使用 C 的桌面開發(fā)”工作負(fù)載。第二個是殺毒軟件攔截進(jìn)程。Windows Defender 有時會把 python 進(jìn)程在解析時的行為誤判成異常導(dǎo)致解析中斷。遇到類似情況先把工作目錄加入 Defender 排除項或者臨時關(guān)掉實時防護(hù)測試。第三個是路徑帶中文或空格導(dǎo)致解析失敗。MinerU 對中文路徑的處理在舊版本上確實有坑4.0 好了很多但還是建議輸入輸出目錄用純英文路徑省心。4. 核心實操把 PDF 變成結(jié)構(gòu)化 Markdown工具裝好、模型跑通之后真正的工作才開始。MinerU 提供了命令行和 Python API 兩套用法日常臨時解析用命令行批量預(yù)處理用 Python 腳本。4.1 命令行把 PDF 轉(zhuǎn)成 Markdown先看最基本的命令mineru -p input.pdf -o ./output --lang zh-p指定輸入的 PDF 文件-o指定輸出目錄--lang指定文檔語言zh表示中文。如果不指定語言MinerU 會自動檢測但中文文檔建議直接顯式指定識別準(zhǔn)確率更高還能省掉自動檢測的時間。執(zhí)行完成后輸出目錄下會生成一個和 PDF 同名的文件夾里面有*.md文件、images子目錄以及 JSON 格式的中間結(jié)果。Markdown 文件就是我們要的結(jié)果它保留了標(biāo)題層級、段落劃分、表格結(jié)構(gòu)公式是 LaTeX 格式圖片則單獨抽出來放在 images 目錄Markdown 里用相對路徑引用。4.2 關(guān)鍵參數(shù)怎么選MinerU 命令行參數(shù)不少但真正影響成敗的就那么幾個。--workers控制并行進(jìn)程數(shù)。CPU 核多的機(jī)器可以調(diào)大一點比如--workers 4解析會快不少。但如果機(jī)器本身內(nèi)存不大并行進(jìn)程開多了容易內(nèi)存暴漲建議保守一點先 2 個試試。--device可以指定設(shè)備類型CPU 模式就是--device cpu。如果你的機(jī)器有 NVIDIA GPU不指定它也會自動優(yōu)先用 GPU但我建議顯式指定避免模型加載時來回試探。--formula和--table分別控制公式和表格識別開關(guān)。默認(rèn)都是開啟的如果確認(rèn)文檔里沒有公式或表格把這些開關(guān)關(guān)掉能明顯提速。反過來遇到數(shù)學(xué)論文或者財務(wù)報表這些開關(guān)必須開著。關(guān)于 OCR 模式MinerU 會自動判斷 PDF 是否需要 OCR。文本型 PDF 會直接走文本提取通道速度很快掃描型 PDF 沒有文本層就自動走 OCR 識別。這種自適應(yīng)邏輯省事但如果你明知道文檔是掃描件想強(qiáng)制 OCR可以看看命令行參數(shù)里有沒有--force-ocr之類的選項按需打開。4.3 Python 批量調(diào)用與參數(shù)控制命令行處理單個 PDF 很方便但 RAG 文檔預(yù)處理往往要一次性處理一個目錄下幾十上百個 PDF。這時候用 Python 封裝最合適。MinerU 提供 Python API可以直接在代碼里調(diào)用解析邏輯。不過我從實用角度建議一種更穩(wěn)的方式用subprocess調(diào)命令行這樣版本升級后只要命令格式?jīng)]大變腳本基本不用改。import subprocess import pathlib import logging LOGGER logging.getLogger(__name__) def parse_pdf(pdf_path, output_root): pdf_path pathlib.Path(pdf_path) output_root pathlib.Path(output_root) output_root.mkdir(parentsTrue, exist_okTrue) result subprocess.run( [ mineru, -p, str(pdf_path), -o, str(output_root), --lang, zh, --workers, 2, ], capture_outputTrue, textTrue, encodingutf-8, ) if result.returncode ! 0: LOGGER.error(f解析失敗: {pdf_path} | {result.stderr}) return False md_file output_root / f{pdf_path.stem}.md if not md_file.exists(): LOGGER.warning(f沒找到 md 文件: {pdf_path}) return False LOGGER.info(f解析完成: {pdf_path} - {md_file}) return True def batch_parse(pdf_dir, output_root): pdf_dir pathlib.Path(pdf_dir) for pdf_path in pdf_dir.glob(*.pdf): parse_pdf(pdf_path, output_root / pdf_path.stem) if __name__ __main__: logging.basicConfig(levellogging.INFO) batch_parse(r./docs, r./parsed)這段腳本有幾個細(xì)節(jié)值得說。第一encodingutf-8很重要Windows 控制臺默認(rèn)編碼是 GBK不指定的話中文報錯信息會亂碼。第二解析完要檢查 md 文件是否存在防止進(jìn)程靜默失敗。第三每個 PDF 對應(yīng)一個獨立輸出目錄這樣后續(xù) RAG 加載器可以直接按目錄掃描。如果你想用 MinerU 的 Python API 而不是 subprocess可以按官方文檔導(dǎo)入對應(yīng)的解析入口類傳入?yún)?shù)幾乎和命令行一一對應(yīng)返回結(jié)果可以直接拿到內(nèi)存里處理省掉文件讀寫環(huán)節(jié)。但批量預(yù)處理場景下subprocess 的方式有天然優(yōu)勢進(jìn)程隔離單個 PDF 崩了不會拖垮整個腳本還可以方便地用外部工具監(jiān)控進(jìn)度。4.4 輸出結(jié)構(gòu)解讀與質(zhì)量檢查解析完成的輸出目錄里除了 Markdown 文件還有 JSON 中間產(chǎn)物很多人不看這些文件其實它們對檢查解析質(zhì)量很有用。JSON 文件記錄了每一頁識別出來的版面結(jié)構(gòu)包括文本塊、圖片區(qū)域、表格區(qū)域的位置和內(nèi)容如果后續(xù)要做自定義后處理這些結(jié)構(gòu)信息比 Markdown 更細(xì)致。質(zhì)量檢查這一環(huán)不能省。我見過太多人跑完命令看都沒看就直接把結(jié)果丟進(jìn)向量庫結(jié)果錯的一塌糊涂。快速檢查方法就是隨機(jī)抽幾頁對照原 PDF 檢查標(biāo)題層級對不對、表格還原對不對、公式是不是 LaTeX、頁眉頁腳是否被正確剔除。如果發(fā)現(xiàn)版面順序錯亂優(yōu)先檢查語言參數(shù)是否指定正確如果表格還原質(zhì)量差考慮該文檔是否排版過于復(fù)雜如果是圖片型掃描件但沒走 OCR看看是否有強(qiáng)制 OCR 選項。質(zhì)量檢查這件事花 5 分鐘能省下后面幾天調(diào)檢索效果的功夫。5. 把 MinerU 接進(jìn) RAG 文檔預(yù)處理鏈路工具單獨能跑只是第一步。真正讓 MinerU 發(fā)揮價值是把它嵌進(jìn) RAG 文檔預(yù)處理流水線里讓解析結(jié)果直接成為向量庫的輸入。這里我分享一套我實際在用的落地姿勢。5.1 預(yù)處理流水線的落地姿勢一個成熟的 RAG 文檔預(yù)處理流水線至少要包含四個階段輸入監(jiān)測、格式解析、內(nèi)容清洗、切片入庫。MinerU 處在“格式解析”環(huán)節(jié)但前后需要其他邏輯銜接。我的方案是維護(hù)兩個目錄inbox放新接收的 PDFparsed放解析好的 Markdown。預(yù)處理腳本掃描inbox發(fā)現(xiàn)新文件就調(diào) MinerU 解析成功后把 PDF 移到processed目錄防止重復(fù)處理同時把 Markdown 路徑寫入一個待處理隊列供后續(xù)切片入庫任務(wù)消費。這種“目錄驅(qū)動”的模式雖然簡單但配合任務(wù)調(diào)度器可以做成自動運行的流水線。新 PDF 一進(jìn)inbox幾分鐘后向量庫里就有它的索引了。Windows 下用計劃任務(wù)定時跑腳本就夠不需要上復(fù)雜的編排系統(tǒng)。5.2 切分加載與向量化建議MinerU 輸出的是 Markdown好處是結(jié)構(gòu)信息都在切分時可以按標(biāo)題切。市面上常見的文檔加載器和切分器大多支持 Markdown 格式他們能識別#標(biāo)題層級按層級切分要比按固定字符長度切科學(xué)得多。接入 LangChain 這類框架時的通用思路是用 Markdown 加載器讀取parsed目錄下的文件然后按標(biāo)題層級切分最后向量化存入向量庫。如果用的是 Ollama 跑本地大模型配合一個簡易 RAG 知識庫流程也是可以的關(guān)鍵是文檔預(yù)處理這一步能直接復(fù)用 MinerU 的輸出。關(guān)于chunk_size和overlap的選擇我的經(jīng)驗是解析質(zhì)量高的情況下可以放心用較大的 chunk比如 800 到 1200 字符overlap 控制在 100 到 200。因為 Markdown 結(jié)構(gòu)完整一個大 chunk 內(nèi)部通常是語義連貫的內(nèi)容解析質(zhì)量差的情況下再小切分也救不回來。這也是為什么我反復(fù)強(qiáng)調(diào)前一步質(zhì)量檢查重要。5.3 小專題知識庫能不能存圖片熱搜里有個問題我覺得挺有意思“RAG 知識庫能存儲圖片嗎”這個得分情況。傳統(tǒng)文本向量庫存的是文本的向量表示PDF 里的圖片本身是不能直接被文本向量庫索引的。MinerU 解析 PDF 時會把圖片抽到images目錄Markdown 里只保留圖片路徑引用。如果 RAG 鏈路用的是通用向量模型圖片內(nèi)容根本無法參與檢索那圖片路徑對檢索結(jié)果沒有影響但 Markdown 里保留了結(jié)構(gòu)信息至少圖片不會變成亂碼字符污染上下文。如果你想真正讓圖片內(nèi)容參與檢索得走多模態(tài)路線先用多模態(tài)模型把圖片生成描述文本再把描述文本向量化。MinerU 抽出圖片后你可以自己加一個步驟對每張圖片調(diào)用多模態(tài)模型生成 caption再把 caption 拼進(jìn)文檔。這套方案成本高一些但確實可行。5.4 解析前后效果對比我拿自己手頭一份幾十頁的中文年報 PDF 做過對比。用傳統(tǒng)文本提取工具直接抽文本出來的內(nèi)容里表格全亂兩欄文字穿插檢索“營收同比”這種關(guān)鍵詞召回的內(nèi)容牛頭不對馬嘴。同樣的文件走 MinerU 解析后表格還原成規(guī)整的 Markdown 表格版面順序恢復(fù)正確公式也轉(zhuǎn)成了 LaTeX向量檢索的命中率提升非常明顯。這不是玄學(xué)而是因為向量化階段吃的是語義完整的文本塊解析質(zhì)量直接決定語義 chunk 的質(zhì)量。所以如果你覺得 RAG 效果一直上不去與其反復(fù)調(diào) prompt不如回頭看看文檔解析這一步有沒有做好。6. 常見問題與排查技巧實錄最后這一部分我把實操中遇到的典型問題和排查思路整理成表格方便你按圖索驥。這些坑很多都不在官方文檔里屬于實戰(zhàn)經(jīng)驗。問題現(xiàn)象可能原因排查與解決辦法顯存不足或內(nèi)存暴漲并行進(jìn)程數(shù)過高調(diào)小--workers或分批處理大 PDF 文件CPU 模式解析極慢沒有識別到 GPU先跑nvidia-smi確認(rèn)驅(qū)動沒 GPU 就接受慢速或換機(jī)器中文識別亂碼未指定語言命令行顯式加--lang zh掃描件識別為空PDF 無文本層且未走 OCR確認(rèn) OCR 開關(guān)是否誤關(guān)必要時強(qiáng)制 OCR模型加載失敗/超時模型文件沒下載完整或網(wǎng)絡(luò)中斷刪除緩存目錄中的不完整模型文件夾重新下載離線機(jī)器用緩存拷貝方式命令報錯找不到 mineru虛擬環(huán)境 PATH 沒生效重新激活環(huán)境或直接用python -m mineru調(diào)用解析進(jìn)程被殺毒軟件中斷Windows Defender 誤報把輸入輸出目錄加入 Defender 排除項中文路徑導(dǎo)致失敗Windows 路徑編碼問題輸入輸出路徑改用純英文再不行升級版本6.1 顯存不足與 CPU 太慢怎么權(quán)衡沒有 GPU 的機(jī)器跑 MinerU確實需要耐心。一份幾頁的文本型 PDF 可能幾秒就完但掃描型 PDF 會慢很多。我的建議是如果只是零散解析幾個文件CPU 模式完全能忍如果你打算在 Windows 上批量處理大量歷史 PDF建議弄一張二手 NVIDIA 顯卡或者租一臺帶 GPU 的 Windows 云主機(jī)跑預(yù)處理處理完再下載結(jié)果這樣性價比最高。顯存不足的問題常見于老顯卡。調(diào)小--workers是最直接的解決辦法。另外可以嘗試關(guān)閉公式或表格識別模型占用會顯著下降。6.2 表格公式識別不準(zhǔn)表格識別不準(zhǔn)的情況多出現(xiàn)在非常復(fù)雜的嵌套表格、跨頁表格上。MinerU 對規(guī)整表格的還原能力很強(qiáng)但遇到復(fù)雜表格輸出多少會有點歪。我的處理方式是如果是重要的表格解析后人工對照修正一下如果不重要接受它的不完美畢竟比直接提取的亂碼強(qiáng)太多。公式識別不準(zhǔn)時檢查 PDF 原圖的分辨率是不是太低低分辨率掃描件里的小字號公式確實難識別。6.3 模型下載失敗與離線緩存模型下載失敗是最煩人的問題之一因為中途失敗會導(dǎo)致緩存目錄里留下不完整文件下次運行仍然報錯。最穩(wěn)妥的流程是先跑一次小文件確認(rèn)所有模型都下載成功再開始批量任務(wù)這樣不會跑到一半才發(fā)現(xiàn)模型有問題。離線機(jī)器的部署方法也不復(fù)雜。在一臺聯(lián)網(wǎng) Windows 機(jī)器上跑一次解析讓模型全部下載到緩存目錄然后把整個緩存目錄拷貝到離線機(jī)器相同位置。只要版本一致解析時會自動找到模型真正做到完全離線運行。6.4 Windows 特有的幾個坑Windows 和 Linux 的差異在 MinerU 使用中有幾個體感明顯的地方。一是終端編碼PowerShell 和 CMD 默認(rèn)編碼不同Python 腳本輸出日志最好顯式指定 UTF-8否則中文亂碼影響排查問題。二是文件占用PDF 被 Excel 或其他程序打開時MinerU 解析可能報權(quán)限錯誤批量處理前先確認(rèn)文件沒有被占用。三是路徑分隔符代碼里拼接路徑時建議用pathlib不要手寫反斜杠否則換個目錄結(jié)構(gòu)就出問題。我還建議把 MinerU 封裝成定時任務(wù)。Windows 任務(wù)計劃程序創(chuàng)建一個每日任務(wù)運行預(yù)處理腳本。配合郵件或日志通知每天自動處理新增 PDFRAG 索引保持最新。這個方案我已經(jīng)跑了一段時間穩(wěn)定省心。整條鏈路里最值得投入精力的還是文檔解析這一步的調(diào)優(yōu)別本末倒置去折騰那些花里胡哨的檢索技巧。