MinerU模型下载与离线部署：3步把PDF解析跑进内网-开发者社区

MinerU模型下载与离线部署：3步把PDF解析跑进内网

【免费下载链接】MinerUA high-quality tool for convert PDF to Markdown and JSON.一站式开源高质量数据提取工具，将PDF转换成Markdown和JSON格式。项目地址: https://gitcode.com/OpenDataLab/MinerU

MinerU可以把PDF转成Markdown和JSON，但它背后依赖的7个pipeline模型动辄几个GB。这篇文章教你三件事：模型源怎么切、离线机怎么预置、常见报错怎么排，看完就能在内网环境跑通解析。

🔌 内网一跑就卡下载？

想象你刚把MinerU部署到一台内网服务器，输入一份PDF就等结果。结果进程半天没动静，日志里全是HuggingFace连接超时。

问题不在解析本身，而在模型文件还没落盘。MinerU的下载逻辑是：首次运行需要拉取模型，内网机器拉不到，任务自然卡死。

解决思路只有一条：在联网机器上把模型"搬"到本地，内网只读本地文件。

📥 模型源切换的两种方式

把模型下载想象成快递驿站取件。第一步查库：看本地缓存里有没有货；第二步选网点：HuggingFace和ModelScope两个源，哪个网络通畅走哪个；第三步入库登记：把本地路径写进配置文件，下次直接取件，不再重新下单。

下面这条命令会拉取全部7个pipeline模型并自动完成登记：

# 联网机器上执行，显式指定ModelScope源（国内网络更快） mineru-models-download -s modelscope -m pipeline

不想每次敲参数，也可以用环境变量固定来源：

# 会话级固定模型源，之后所有下载命令都走它 export MINERU_MODEL_SOURCE=modelscope

两种方式的差别在于作用域：命令行参数只管这一次，环境变量管这个终端会话。配置模板在仓库根目录的mineru.template.json，完整机制源码在mineru/utils/models_download_utils.py，想深入可以看这两处。

🚚 离线环境预置模型步骤

整个搬迁过程就4步，全程不需要内网机器碰外网：

在联网机器执行mineru-models-download -s modelscope -m pipeline，下载完成后控制台会打印模型落盘目录。
把该目录用tar或scp整体拷到内网机器的相同路径。
把下载工具自动生成的~/mineru.json一起拷过去，这是模型路径的"取件码"。
在内网机器执行下面命令验证：

# 验证：用本地模型解析一份小PDF mineru -p demo/pdfs/small_ocr.pdf -o ./out

⚙️ 配置文件字段逐项说明

~/mineru.json是唯一的配置入口，每个字段的含义如下：

{ "model-source": "modelscope", // 模型来源：modelscope / huggingface，内网机器可填任意远端值，以models-dir为准 "models-dir": { "pipeline": "/data/mineru_models", // pipeline模型根目录，离线机改成你的实际路径 "vlm": "" // VLM模型根目录，不用VLM留空即可 }, "config_version": "1.3.2" // 配置模板版本，低于当前版本时会自动合并更新 }

要点只有一个：离线机上models-dir.pipeline必须指向真实存在的模型目录，否则程序会回退去联网下载。

⚠️ 排坑：3个高频问题

1. 卡在auto探测阶段auto会先请求HuggingFace列表页探测网络，超时3秒、重试2次才回落到ModelScope。内网机器直接等满超时，像"死机"。 → 显式指定来源，别让程序猜：-s modelscope或export MINERU_MODEL_SOURCE=modelscope。

2. 拷完模型仍然尝试联网只搬了模型目录，没搬~/mineru.json，或者文件里models-dir.pipeline还是空字符串。 → 配置和模型必须成对迁移，迁移后先cat ~/mineru.json核对一遍。

3. 磁盘空间不够7个pipeline模型加上VLM整仓，合计接近40GB，缓存目录默认在用户主目录下。 → 下载前确认主分区余量；空间紧张就只下载用到的类型，比如-m pipeline跳过VLM。

4. 换机器后重复下载换目录、换用户后路径变了，程序找不到旧缓存，重新拉一遍。 → 固定一个模型根目录，机器间保持路径一致，省掉重复下载。