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