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