企业官网建设流程全解析

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_SOURCE=local，解析全程不产生任何网络请求。本文按"备料→跑通→调优→排坑"给出可复现的步骤。

出发前先备齐：源码、模型、依赖三类物料

本节帮你解决"到了断网机才发现少了文件"的问题。离线机需要带走三样东西：源码、Python 依赖、模型（含配置），缺一都跑不起来。

下面所有打包命令都在联网机上执行。

断网前打包命令

先把源码拉到本地：

git clone https://gitcode.com/GitHub_Trending/mi/MinerU.git cd MinerU

MinerU 要求 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

下载完成后模型落在主目录~/.mineru，mineru.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 libgl1

fonts-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_SOURCE=local

环境变量优先于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 个真正影响性能的旋钮

本节只留决定吞吐和内存占用的参数，都是环境变量，对所有命令行工具生效，改完重开终端即可。

另外两个后端选择：-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_SOURCE=local即可，不要直接覆盖正在跑任务的旧目录。全部参数含义以仓库 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_SOURCE=local写进系统级环境变量即可。

常见卡点：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