錯(cuò)到解析質(zhì)量的完整排障指南)
MinerU 故障排查速查從安裝報(bào)錯(cuò)到解析質(zhì)量的完整排障指南【免費(fèi)下載鏈接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/mi/MinerUMinerU 把 PDF、DOCX、PPTX、XLSX 等文檔解析為可直接喂給 LLM 的 Markdown/JSON。如果你部署時(shí)報(bào)依賴缺失、模型下載失敗或解析結(jié)果缺字亂碼按本文環(huán)境 → 模型 → 參數(shù) → 結(jié)果的排查路線逐層定位基本都能自行修好。先定位問題在哪一層MinerU 排障的五層路線報(bào)錯(cuò)不可怕怕的是在錯(cuò)誤的層上花時(shí)間。絕大多數(shù) MinerU 報(bào)錯(cuò)可以歸入五層之一先判斷層再動(dòng)手。圖中順序即排查順序每一層修完都要回到最小復(fù)現(xiàn)驗(yàn)證不要跳過(guò)驗(yàn)證直接試下一層。環(huán)境層依賴缺失與版本不兼容的快速定位這一層的問題是裝不上、起不來(lái)、出圖缺字先看現(xiàn)象再執(zhí)行對(duì)應(yīng)命令。Python 版本不在 3.10–3.13 區(qū)間現(xiàn)象pip install mineru報(bào)Requires-Python 3.10,3.14或直接裝不上依賴。原因MinerU 只支持 3.10 到 3.13Windows 因部分依賴限制僅到 3.12。動(dòng)作新建 3.10–3.13 的虛擬環(huán)境重裝例如uv venv --python 3.12后執(zhí)行uv pip install -U mineru[all]。驗(yàn)證mineru --version能打印版本號(hào)當(dāng)前倉(cāng)庫(kù)版本為 3.4.4。WSL2/Ubuntu 報(bào)libGL.so.1缺失現(xiàn)象啟動(dòng)即報(bào)ImportError: libGL.so.1: cannot open shared object file。原因鏡像版發(fā)行版尤其 WSL2 的 Ubuntu 22.04缺少 OpenCV 依賴的圖形共享庫(kù)。動(dòng)作sudo apt-get update sudo apt-get install -y libgl1-mesa-glx驗(yàn)證重新運(yùn)行mineru -p input -o output不再出現(xiàn)該 ImportError。Linux 解析結(jié)果缺失 CJK 文字現(xiàn)象Markdown 里中文整段丟失但英文正常。原因MinerU 自 2.0 起用pypdfium2渲染 PDF系統(tǒng)缺少 CJK 字體時(shí)渲染成圖片的過(guò)程會(huì)丟字。動(dòng)作sudo apt install fonts-noto-core fonts-noto-cjk fc-cache -fv驗(yàn)證重新解析同一份 PDF抽查中文字符完整。不想折騰字體的直接用官方 Docker 部署鏡像內(nèi)置這些字體見 Docker 部署文檔。Windows 裝完能跑但推理極慢現(xiàn)象CPU 占用低、GPU 不吃、速度像純 CPU。原因默認(rèn)裝的是無(wú) CUDA 的torch。動(dòng)作到 PyTorch 官網(wǎng)按顯卡對(duì)應(yīng)的 CUDA 版本重裝torch和torchvisionRTX 50 系Blackwell需安裝lmdeploy 0.11.1 cu128的 Windows wheel。驗(yàn)證解析時(shí)nvidia-smi能看到顯存被占用。細(xì)節(jié)見 FAQ。老系統(tǒng)裝不上如 CentOS 7、Ubuntu 18現(xiàn)象編譯依賴如simsimdwheel 失敗。原因官方僅測(cè)試 2019 年及以后的 Linux 發(fā)行版。動(dòng)作優(yōu)先換 Docker 部署沒有條件就上 3.11 干凈 conda 環(huán)境重試pip install -U mineru[all]。模型層下載失敗、切換模型源與本地化模型問題集中在第一次解析時(shí)。默認(rèn)策略是auto先探測(cè) HuggingFace不通再回退 ModelScope并把實(shí)際來(lái)源寫回mineru.json避免每次網(wǎng)絡(luò)波動(dòng)反復(fù)切換。首次運(yùn)行卡在模型下載或直接超時(shí)現(xiàn)象長(zhǎng)時(shí)間無(wú)輸出、ConnectionError或 401/403。原因當(dāng)前網(wǎng)絡(luò)訪問不了 HuggingFace。動(dòng)作export MINERU_MODEL_SOURCEmodelscope mineru -p input_path -o output_path注意MINERU_MODEL_SOURCE只接受huggingface、modelscope、local三個(gè)值不要設(shè)成auto需要自動(dòng)探測(cè)就刪掉這個(gè)環(huán)境變量。想在離線/生產(chǎn)環(huán)境預(yù)先備好模型動(dòng)作先跑mineru-models-download交互式選模型并落盤下載完成后路徑會(huì)寫進(jìn)用戶目錄的mineru.json之后在離線機(jī)上設(shè)置export MINERU_MODEL_SOURCElocal即可。如果要自定義存放位置編輯mineru.json的models-dir分別為pipeline和vlm指定目錄。?? 移動(dòng)模型文件夾到新服務(wù)器時(shí)記得把mineru.json一并帶上并改好路徑否則會(huì)報(bào)找不到模型。完整說(shuō)明見 模型源文檔。參數(shù)與硬件層后端選擇、顯存與并發(fā)調(diào)參這一層決定快不快、會(huì)不會(huì) OOM。先選對(duì)后端再調(diào)顯存和并發(fā)。按硬件和精度需求選后端后端-b取值適用場(chǎng)景顯存最低純 CPU精度OmniDocBenchpipeline簡(jiǎn)單文檔、純 CPU 機(jī)器4GB?86.47hybrid-engine默認(rèn)復(fù)雜版面、追求精度8GB?95.26medium/ 95.39highvlm-engine端到端 VLM 場(chǎng)景8GB?95.30hybrid-http-client/vlm-http-client連接 OpenAI 兼容推理服務(wù)2GBhybrid?與 engine 對(duì)應(yīng)值# 純 CPU 機(jī)器固定走 pipeline mineru -p input_path -o output_path -b pipeline # 連接遠(yuǎn)端 OpenAI 兼容服務(wù)本地?zé)o需 torch 也可跑 vlm-http-client mineru -p input_path -o output_path -b hybrid-http-client -u http://127.0.0.1:30000hybrid后端還可加--effort high提升解析強(qiáng)度代價(jià)是更慢。參數(shù)全貌見 命令行工具說(shuō)明。顯存不夠 OOM 或想壓低客戶端占用hybrid-*后端用環(huán)境變量控制小模型 batch 倍率顯存越小倍率越低單卡/客戶端顯存MINERU_HYBRID_BATCH_RATIO≤ 6GB8≤ 4GB4≤ 3GB2≤ 2GB1并發(fā)與吞吐側(cè)的旋鈕MINERU_API_MAX_CONCURRENT_REQUESTS默認(rèn) 3調(diào)小可降內(nèi)存、MINERU_PROCESSING_WINDOW_SIZE默認(rèn) 64大文檔爆內(nèi)存時(shí)調(diào)小、MINERU_PDF_RENDER_TIMEOUT渲染超時(shí)默認(rèn) 300 秒。多卡場(chǎng)景在命令前加CUDA_VISIBLE_DEVICES1指定卡多卡統(tǒng)一入口用CUDA_VISIBLE_DEVICES0,1,2,3 mineru-router --host 0.0.0.0 --port 8002更多透?jìng)鲄?shù)見 命令行參數(shù)進(jìn)階。結(jié)果質(zhì)量層缺字、公式亂碼與語(yǔ)言適配調(diào)優(yōu)輸出能跑但不準(zhǔn)時(shí)按下面的開關(guān)逐項(xiàng)調(diào)每項(xiàng)只動(dòng)一個(gè)變量以便歸因。公式分隔符與下游渲染對(duì)不上動(dòng)作編輯mineru.json的latex-delimiter-configinline/display分別設(shè)左右分隔符默認(rèn)是$與$$Gradio WebUI 也可用--latex-delimiters-type a|b|all切換$或[]()風(fēng)格。確認(rèn)下游如 RAG 管道按同樣分隔符解析。掃描件/混合語(yǔ)言識(shí)別不準(zhǔn)動(dòng)作給pipeline后端顯式指定語(yǔ)言比自動(dòng)判斷穩(wěn)mineru -p input_path -o output_path -b pipeline -l ch-l可選ch、ch_server、korean、arabic等ch_server面向中英混合與手寫場(chǎng)景。若懷疑是文本層抽取而非 OCR 的問題可試-m ocr強(qiáng)制走識(shí)別路徑。表格或公式解析異常想開關(guān)控制-t表格和-f公式默認(rèn)開啟確認(rèn)問題出在表格結(jié)構(gòu)識(shí)別時(shí)可用MINERU_TABLE_MERGE_ENABLEfalse關(guān)閉跨頁(yè)表格合并觀察差異或用--image-analysis false關(guān)掉 VLM/hybrid 的圖片分析來(lái)排除圖表分析引入的干擾。進(jìn)階調(diào)試最小復(fù)現(xiàn)、日志與多后端交叉驗(yàn)證定位疑難問題先把范圍縮到一頁(yè)再說(shuō)話。最小復(fù)現(xiàn)用-s/-e指定頁(yè)碼從 0 開始只解析出錯(cuò)的那幾頁(yè)例如mineru -p big.pdf -o out/ -s 10 -e 11倉(cāng)庫(kù)自帶demo/pdfs/demo1.pdf可作對(duì)照組。交叉驗(yàn)證同一頁(yè)分別用-b pipeline和默認(rèn)hybrid-engine各跑一次diff 兩份full.md。兩邊一致說(shuō)明是文檔本身問題不一致再按差異定位模型層。服務(wù)化排障mineru-api --host 0.0.0.0 --port 8000起來(lái)后訪問http://127.0.0.1:8000/docs看接口文檔GET /health返回的max_concurrent_requests、processing_window_size可用于核對(duì)服務(wù)側(cè)配置是否符合預(yù)期。排障與上線前檢查清單修復(fù)完成或把 MinerU 納入生產(chǎn)鏈路前過(guò)一遍這張清單Python 版本在 3.10–3.13mineru --version正常Linux 已裝libgl1-mesa-glx與 Noto CJK 字體或改用 DockerMINERU_MODEL_SOURCE已按網(wǎng)絡(luò)環(huán)境固定為huggingface/modelscope/localmineru.json中models-dir、model-source與實(shí)際模型位置一致后端與硬件匹配純 CPU 用pipeline8GB 顯存才上hybrid-engine顯存/并發(fā)已按機(jī)器調(diào)過(guò)MINERU_HYBRID_BATCH_RATIO、MINERU_API_MAX_CONCURRENT_REQUESTS用-s/-e做過(guò)最小頁(yè)級(jí)復(fù)現(xiàn)雙后端交叉驗(yàn)證過(guò)關(guān)鍵頁(yè)面如果清單全過(guò)仍無(wú)解提交 issue 時(shí)附上出錯(cuò)頁(yè)碼、完整命令、報(bào)錯(cuò)棧和一份可復(fù)現(xiàn)的 PDF 樣例demo/pdfs/下的樣例格式即可并說(shuō)明系統(tǒng)、Python 與 MinerU 版本也可以先查 項(xiàng)目 FAQ或在項(xiàng)目社區(qū)渠道求助。排障的關(guān)鍵永遠(yuǎn)是先分層再動(dòng)手。本文基于 MinerU 3.4.4 整理參數(shù)與默認(rèn)值以最新倉(cāng)庫(kù)文檔為準(zhǔn)快速入門、命令行工具說(shuō)明?！久赓M(fèi)下載鏈接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/mi/MinerU創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 MinerU 故障排查速查：從安裝報(bào)錯(cuò)到解析質(zhì)量的完整排障指南
MinerU 故障排查速查從安裝報(bào)錯(cuò)到解析質(zhì)量的完整排障指南【免費(fèi)下載鏈接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/mi/MinerUMinerU 把 PDF、DOCX、PPTX、XLSX 等文檔解析為可直接喂給 LLM 的 Markdown/JSON。如果你部署時(shí)報(bào)依賴缺失、模型下載失敗或解析結(jié)果缺字亂碼按本文環(huán)境 → 模型 → 參數(shù) → 結(jié)果的排查路線逐層定位基本都能自行修好。先定位問題在哪一層MinerU 排障的五層路線報(bào)錯(cuò)不可怕怕的是在錯(cuò)誤的層上花時(shí)間。絕大多數(shù) MinerU 報(bào)錯(cuò)可以歸入五層之一先判斷層再動(dòng)手。圖中順序即排查順序每一層修完都要回到最小復(fù)現(xiàn)驗(yàn)證不要跳過(guò)驗(yàn)證直接試下一層。環(huán)境層依賴缺失與版本不兼容的快速定位這一層的問題是裝不上、起不來(lái)、出圖缺字先看現(xiàn)象再執(zhí)行對(duì)應(yīng)命令。Python 版本不在 3.10–3.13 區(qū)間現(xiàn)象pip install mineru報(bào)Requires-Python 3.10,3.14或直接裝不上依賴。原因MinerU 只支持 3.10 到 3.13Windows 因部分依賴限制僅到 3.12。動(dòng)作新建 3.10–3.13 的虛擬環(huán)境重裝例如uv venv --python 3.12后執(zhí)行uv pip install -U mineru[all]。驗(yàn)證mineru --version能打印版本號(hào)當(dāng)前倉(cāng)庫(kù)版本為 3.4.4。WSL2/Ubuntu 報(bào)libGL.so.1缺失現(xiàn)象啟動(dòng)即報(bào)ImportError: libGL.so.1: cannot open shared object file。原因鏡像版發(fā)行版尤其 WSL2 的 Ubuntu 22.04缺少 OpenCV 依賴的圖形共享庫(kù)。動(dòng)作sudo apt-get update sudo apt-get install -y libgl1-mesa-glx驗(yàn)證重新運(yùn)行mineru -p input -o output不再出現(xiàn)該 ImportError。Linux 解析結(jié)果缺失 CJK 文字現(xiàn)象Markdown 里中文整段丟失但英文正常。原因MinerU 自 2.0 起用pypdfium2渲染 PDF系統(tǒng)缺少 CJK 字體時(shí)渲染成圖片的過(guò)程會(huì)丟字。動(dòng)作sudo apt install fonts-noto-core fonts-noto-cjk fc-cache -fv驗(yàn)證重新解析同一份 PDF抽查中文字符完整。不想折騰字體的直接用官方 Docker 部署鏡像內(nèi)置這些字體見 Docker 部署文檔。Windows 裝完能跑但推理極慢現(xiàn)象CPU 占用低、GPU 不吃、速度像純 CPU。原因默認(rèn)裝的是無(wú) CUDA 的torch。動(dòng)作到 PyTorch 官網(wǎng)按顯卡對(duì)應(yīng)的 CUDA 版本重裝torch和torchvisionRTX 50 系Blackwell需安裝lmdeploy 0.11.1 cu128的 Windows wheel。驗(yàn)證解析時(shí)nvidia-smi能看到顯存被占用。細(xì)節(jié)見 FAQ。老系統(tǒng)裝不上如 CentOS 7、Ubuntu 18現(xiàn)象編譯依賴如simsimdwheel 失敗。原因官方僅測(cè)試 2019 年及以后的 Linux 發(fā)行版。動(dòng)作優(yōu)先換 Docker 部署沒有條件就上 3.11 干凈 conda 環(huán)境重試pip install -U mineru[all]。模型層下載失敗、切換模型源與本地化模型問題集中在第一次解析時(shí)。默認(rèn)策略是auto先探測(cè) HuggingFace不通再回退 ModelScope并把實(shí)際來(lái)源寫回mineru.json避免每次網(wǎng)絡(luò)波動(dòng)反復(fù)切換。首次運(yùn)行卡在模型下載或直接超時(shí)現(xiàn)象長(zhǎng)時(shí)間無(wú)輸出、ConnectionError或 401/403。原因當(dāng)前網(wǎng)絡(luò)訪問不了 HuggingFace。動(dòng)作export MINERU_MODEL_SOURCEmodelscope mineru -p input_path -o output_path注意MINERU_MODEL_SOURCE只接受huggingface、modelscope、local三個(gè)值不要設(shè)成auto需要自動(dòng)探測(cè)就刪掉這個(gè)環(huán)境變量。想在離線/生產(chǎn)環(huán)境預(yù)先備好模型動(dòng)作先跑mineru-models-download交互式選模型并落盤下載完成后路徑會(huì)寫進(jìn)用戶目錄的mineru.json之后在離線機(jī)上設(shè)置export MINERU_MODEL_SOURCElocal即可。如果要自定義存放位置編輯mineru.json的models-dir分別為pipeline和vlm指定目錄。?? 移動(dòng)模型文件夾到新服務(wù)器時(shí)記得把mineru.json一并帶上并改好路徑否則會(huì)報(bào)找不到模型。完整說(shuō)明見 模型源文檔。參數(shù)與硬件層后端選擇、顯存與并發(fā)調(diào)參這一層決定快不快、會(huì)不會(huì) OOM。先選對(duì)后端再調(diào)顯存和并發(fā)。按硬件和精度需求選后端后端-b取值適用場(chǎng)景顯存最低純 CPU精度OmniDocBenchpipeline簡(jiǎn)單文檔、純 CPU 機(jī)器4GB?86.47hybrid-engine默認(rèn)復(fù)雜版面、追求精度8GB?95.26medium/ 95.39highvlm-engine端到端 VLM 場(chǎng)景8GB?95.30hybrid-http-client/vlm-http-client連接 OpenAI 兼容推理服務(wù)2GBhybrid?與 engine 對(duì)應(yīng)值# 純 CPU 機(jī)器固定走 pipeline mineru -p input_path -o output_path -b pipeline # 連接遠(yuǎn)端 OpenAI 兼容服務(wù)本地?zé)o需 torch 也可跑 vlm-http-client mineru -p input_path -o output_path -b hybrid-http-client -u http://127.0.0.1:30000hybrid后端還可加--effort high提升解析強(qiáng)度代價(jià)是更慢。參數(shù)全貌見 命令行工具說(shuō)明。顯存不夠 OOM 或想壓低客戶端占用hybrid-*后端用環(huán)境變量控制小模型 batch 倍率顯存越小倍率越低單卡/客戶端顯存MINERU_HYBRID_BATCH_RATIO≤ 6GB8≤ 4GB4≤ 3GB2≤ 2GB1并發(fā)與吞吐側(cè)的旋鈕MINERU_API_MAX_CONCURRENT_REQUESTS默認(rèn) 3調(diào)小可降內(nèi)存、MINERU_PROCESSING_WINDOW_SIZE默認(rèn) 64大文檔爆內(nèi)存時(shí)調(diào)小、MINERU_PDF_RENDER_TIMEOUT渲染超時(shí)默認(rèn) 300 秒。多卡場(chǎng)景在命令前加CUDA_VISIBLE_DEVICES1指定卡多卡統(tǒng)一入口用CUDA_VISIBLE_DEVICES0,1,2,3 mineru-router --host 0.0.0.0 --port 8002更多透?jìng)鲄?shù)見 命令行參數(shù)進(jìn)階。結(jié)果質(zhì)量層缺字、公式亂碼與語(yǔ)言適配調(diào)優(yōu)輸出能跑但不準(zhǔn)時(shí)按下面的開關(guān)逐項(xiàng)調(diào)每項(xiàng)只動(dòng)一個(gè)變量以便歸因。公式分隔符與下游渲染對(duì)不上動(dòng)作編輯mineru.json的latex-delimiter-configinline/display分別設(shè)左右分隔符默認(rèn)是$與$$Gradio WebUI 也可用--latex-delimiters-type a|b|all切換$或[]()風(fēng)格。確認(rèn)下游如 RAG 管道按同樣分隔符解析。掃描件/混合語(yǔ)言識(shí)別不準(zhǔn)動(dòng)作給pipeline后端顯式指定語(yǔ)言比自動(dòng)判斷穩(wěn)mineru -p input_path -o output_path -b pipeline -l ch-l可選ch、ch_server、korean、arabic等ch_server面向中英混合與手寫場(chǎng)景。若懷疑是文本層抽取而非 OCR 的問題可試-m ocr強(qiáng)制走識(shí)別路徑。表格或公式解析異常想開關(guān)控制-t表格和-f公式默認(rèn)開啟確認(rèn)問題出在表格結(jié)構(gòu)識(shí)別時(shí)可用MINERU_TABLE_MERGE_ENABLEfalse關(guān)閉跨頁(yè)表格合并觀察差異或用--image-analysis false關(guān)掉 VLM/hybrid 的圖片分析來(lái)排除圖表分析引入的干擾。進(jìn)階調(diào)試最小復(fù)現(xiàn)、日志與多后端交叉驗(yàn)證定位疑難問題先把范圍縮到一頁(yè)再說(shuō)話。最小復(fù)現(xiàn)用-s/-e指定頁(yè)碼從 0 開始只解析出錯(cuò)的那幾頁(yè)例如mineru -p big.pdf -o out/ -s 10 -e 11倉(cāng)庫(kù)自帶demo/pdfs/demo1.pdf可作對(duì)照組。交叉驗(yàn)證同一頁(yè)分別用-b pipeline和默認(rèn)hybrid-engine各跑一次diff 兩份full.md。兩邊一致說(shuō)明是文檔本身問題不一致再按差異定位模型層。服務(wù)化排障mineru-api --host 0.0.0.0 --port 8000起來(lái)后訪問http://127.0.0.1:8000/docs看接口文檔GET /health返回的max_concurrent_requests、processing_window_size可用于核對(duì)服務(wù)側(cè)配置是否符合預(yù)期。排障與上線前檢查清單修復(fù)完成或把 MinerU 納入生產(chǎn)鏈路前過(guò)一遍這張清單Python 版本在 3.10–3.13mineru --version正常Linux 已裝libgl1-mesa-glx與 Noto CJK 字體或改用 DockerMINERU_MODEL_SOURCE已按網(wǎng)絡(luò)環(huán)境固定為huggingface/modelscope/localmineru.json中models-dir、model-source與實(shí)際模型位置一致后端與硬件匹配純 CPU 用pipeline8GB 顯存才上hybrid-engine顯存/并發(fā)已按機(jī)器調(diào)過(guò)MINERU_HYBRID_BATCH_RATIO、MINERU_API_MAX_CONCURRENT_REQUESTS用-s/-e做過(guò)最小頁(yè)級(jí)復(fù)現(xiàn)雙后端交叉驗(yàn)證過(guò)關(guān)鍵頁(yè)面如果清單全過(guò)仍無(wú)解提交 issue 時(shí)附上出錯(cuò)頁(yè)碼、完整命令、報(bào)錯(cuò)棧和一份可復(fù)現(xiàn)的 PDF 樣例demo/pdfs/下的樣例格式即可并說(shuō)明系統(tǒng)、Python 與 MinerU 版本也可以先查 項(xiàng)目 FAQ或在項(xiàng)目社區(qū)渠道求助。排障的關(guān)鍵永遠(yuǎn)是先分層再動(dòng)手。本文基于 MinerU 3.4.4 整理參數(shù)與默認(rèn)值以最新倉(cāng)庫(kù)文檔為準(zhǔn)快速入門、命令行工具說(shuō)明?！久赓M(fèi)下載鏈接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/mi/MinerU創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考