MinerU 离线部署实操：3 类文件备齐，断网环境 4 步跑通 PDF 解析

MinerU 离线部署实操3 类文件备齐断网环境 4 步跑通 PDF 解析【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU合规审查要求文档解析全程不碰外网时MinerU 离线部署就是标准解法。MinerU 能把 PDF、DOCX、PPTX、XLSX 和图片解析成 Markdown 和 JSON配合MINERU_MODEL_SOURCElocal解析全程不产生任何网络请求。本文按备料→跑通→调优→排坑给出可复现的步骤。出发前先备齐源码、模型、依赖三类物料本节帮你解决到了断网机才发现少了文件的问题。离线机需要带走三样东西源码、Python 依赖、模型含配置缺一都跑不起来。物料联网侧怎么来断网侧落位源码git clone 仓库任意目录安装后依赖虚拟环境即可Python 依赖uv pip download打 wheel 包offline_pkgs/模型 mineru.jsonmineru-models-download主目录~/.mineru或独立模型盘下面所有打包命令都在联网机上执行。断网前打包命令先把源码拉到本地git clone https://gitcode.com/GitHub_Trending/mi/MinerU.git cd MinerUMinerU 要求 Python 3.10–3.13。用与断网机相同的 Python 版本创建虚拟环境并安装核心依赖[core]覆盖 vlm、pipeline、gradio 三组后端python3.10 -m venv /tmp/venv_offline source /tmp/venv_offline/bin/activate uv pip install mineru[core]导出依赖清单再按清单把所有 wheel 下载到离线目录含传递依赖uv pip freeze requirements-offline.txt uv pip download -r requirements-offline.txt -d ./offline_pkgs下载解析模型。-m pipeline是纯 CPU 可跑的小模型组合-m vlm是 2B 级视觉大模型、体积数 GB按需取舍国内网络建议用modelscope源mineru-models-download -s modelscope -m pipeline # 或 -m vlm / -m all下载完成后模型落在主目录~/.minerumineru.json也在同一处并自动写好了模型路径。把整个~/.mineru原样拷走断网机上放到相同位置就不用改任何配置如果放到独立模型盘再改mineru.json里models-dir的绝对路径。硬件参考来自快速入门pipeline 后端纯 CPU 可跑hybrid/vlm 需要 Volta 及以后架构的 GPU显存 4GB/8GB。内存 16GB 起、推荐 32GB磁盘留 20GB 以上给模型和输出。下一步把offline_pkgs/和~/.mineru拷进断网机开始装环境。最短跑通路径联网机 → 断网机 → 第一份文档本节把安装、配置、首次解析串成一条最短路径验证动作直接嵌在其中跑完就能出 Markdown。断网机的系统基础断网机只需补齐 Python 和字体离线安装不需要 apt 联网# 以 Ubuntu 22.04 为例python3.10 需与打包时一致 apt-get install -y python3.10 python3-pip fonts-noto-cjk libgl1fonts-noto-cjk缺了 OCR 渲染中文会异常libgl1是 OpenCV 的依赖这两个包建议提前用apt-get download一并带走。从本地 wheel 装 MinerU在源码目录里用本地 wheel 目录离线安装cd MinerU uv venv .venv --python /usr/bin/python3.10 uv pip install --no-index --find-links ../offline_pkgs -e .[core] .venv/bin/mineru -v # 输出版本号即安装成功--no-index确保完全不访问 PyPI。指定本地模型切断最后一次联网模型就位后启用 local 源export MINERU_MODEL_SOURCElocal环境变量优先于mineru.json里的model-source设成local后解析过程不再有任何远端请求。注意该变量只在当前终端会话生效建议写进/etc/profile.d或启动脚本。跑通第一份文档解析仓库自带的示例 PDF。没有 GPU 就用-b pipeline走纯 CPU 链路.venv/bin/mineru -p demo/pdfs/demo1.pdf -o ./out -b pipeline打开./out里面有按文档名划分的子目录里面的.md就是解析结果非空且中文无乱码环境就算跑通了。下一步批量任务跑起来前先看下一节的几个关键参数。跑通后再调优4 个真正影响性能的旋钮本节只留决定吞吐和内存占用的参数都是环境变量对所有命令行工具生效改完重开终端即可。旋钮默认什么时候动MINERU_PROCESSING_WINDOW_SIZE64大文档解析时内存吃紧调小如 16–32降峰值MINERU_API_MAX_CONCURRENT_REQUESTS3常驻mineru-api服务时控制并发上限MINERU_INTRA_OP_NUM_THREADS/MINERU_INTER_OP_NUM_THREADS-1自动CPU 核数少时手动限制 onnx 线程避免超卖MINERU_HYBRID_BATCH_RATIO自动hybrid-http-client 按客户端显存设 8/4/2/1≤6GB/4GB/3GB/2GB另外两个后端选择-b pipeline纯 CPU 通用精度略低-b vlm-engine或-b hybrid-engine精度更高但要 GPU。hybrid 可加--effort high换精度、-m ocr强制走 OCR 链路-l ch指定语言可提升 pipeline 后端的 OCR 准确率。模型目录怎么组织mineru.json的models-dir分别记录pipeline和vlm两个目录。版本升级时拷一份新目录、把models-dir指过去、重设MINERU_MODEL_SOURCElocal即可不要直接覆盖正在跑任务的旧目录。全部参数含义以仓库 docs/ 里的命令行工具说明为准。下一步机器如果要 7x24 常驻可选做下面的加固。加固可选容器隔离与只读模型目录这一节按需选做不加固也不影响解析功能。用 Docker 把运行环境和模型固化成镜像适合多机复制部署。构建必须在联网机完成拉取基础镜像需要网络再整体搬过去# 联网机 docker build -t mineru-offline:latest -f docker/china/Dockerfile . docker save mineru-offline:latest -o mineru-offline.tar # 断网机 docker load -i mineru-offline.tar docker run -d --network none --read-only \ -v /data/mineru_models:/root/.mineru:ro \ -v /data/output:/app/output \ mineru-offline:latest--network none让容器全程零网络请求:ro保证模型目录只读。更省事的替代不装 Docker直接用上一节的虚拟环境方案把MINERU_MODEL_SOURCElocal写进系统级环境变量即可。常见卡点3 组现象与解法Q1报模型加载失败或提示找不到模型先看echo $MINERU_MODEL_SOURCE是否为local再看~/.mineru/mineru.json里models-dir的绝对路径是否和断网机实际位置一致。模型搬了盘但没改路径是最常见的错法——改完models-dir再跑一次即可。Q2大文档解析到一半内存溢出把MINERU_PROCESSING_WINDOW_SIZE从默认 64 调小到 16 或 32同时把-s/-e分页提交先跑通 20 页验证配置再逐步放大窗口。Q3输出里中文全是方框或空白断网机没装fonts-noto-cjk或渲染缺少libgl1。补装后重跑同一份 PDF 对比即可确认。验收与后续最终验收动作就一条在断网机上解析demo/pdfs/demo1.pdf确认./out下生成非空.md且内容无乱码。参数细节、输出文件结构查仓库 docs/zh/ 下的快速入门与模型源说明即可遇到装不上的问题先翻 FAQ。【免费下载链接】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），仅供参考