离线部署 MinerU从硬件体检到 PDF 批量解析的全流程实操【免费下载链接】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、RAG、Agent 使用的 Markdown 与 JSON。如果你的服务器完全不能上网模型下载、依赖安装、镜像构建都得提前在联网机上备好。本文给出一条完整路径先检查硬件底线再在联网机上把四类物料备齐最后到离线机上一路装到能跑批量任务并附上日常运维和排障方法。全文以 3.4.4 版本为例。上图是 MinerU 典型的解析流程示意。看的时候重点盯两点一是输入端支持多格式文档二是输出端得到阅读顺序正确、公式转 LaTeX、表格转 HTML 的结构化结果——离线部署的验收标准就是复现这条链路。离线部署前必做的环境体检先确认机器够不够用够不上再谈后面的事。MinerU 有两个解析后端理解一下差别有助于定硬件pipeline 后端一套轻量模型流水线版面、OCR、公式、表格识别纯 CPU 就能跑速度稳定、不产生幻觉vlm / hybrid 后端基于视觉大模型精度高但通常需要 GPU 加 vLLM 推理加速Volta 及以后架构、显存 ≥8GB。如果离线机只有 CPU走 pipeline 后端即可下文会给出对应做法。检查项最低要求说明内存8 GB解析 VLM 模型或大文档时建议 16 GB 起磁盘40 GB 空闲源码 pipeline 模型 VLM 模型 依赖加起来不小Python3.10 ~ 3.13pyproject.toml 声明requires-python 3.10,3.14Docker可选想用容器方案才需要注意 Docker 部署仅支持 Linux 与 WSL2不建议在 macOS 上跑GPU可选vllm 加速要求显卡驱动兼容 CUDA 13.0可换 cu129 基础镜像适配 CUDA 12.9在目标机器上执行把结果记下来后面排障要用# Python 版本需要 3.10 及以上 python3 --version # Docker 环境选容器方案才需要 docker --version docker compose version # 磁盘与内存 df -h / free -h | awk /^Mem:/ {print $2} # 有 NVIDIA 卡时顺手确认驱动支持的 CUDA 版本 nvidia-smi | grep -i cuda⚠️ 踩坑提醒vLLM 会预占大量显存同一台机器上不要同时跑多个 vllm 服务。如果你计划用vlm-engine后端先把其他吃显存的进程停掉。联网机备料四样东西一样都不能少离线部署的成败90% 取决于联网机上备料是否完整。清单如下逐项核对源码指定版本克隆别用 main 分支裸跑模型文件pipeline 和 VLM 两套模型离线机上无法再下载Python 依赖提前下载成 wheel 包Docker 镜像容器方案下镜像里已内置依赖和模型只需拷一个 tar。锁定版本并拉取源码# 克隆并固定版本保证离线环境与文档描述可对应 git clone https://gitcode.com/GitHub_Trending/mi/MinerU.git cd MinerU git checkout v3.4.4 # 顺手留一份版本快照回滚和交接都靠它 cat version_snapshot.txt EOF MinerU 版本: $(python3 -c from mineru.version import __version__; print(__version__) 2/dev/null || echo v3.4.4) 源码提交: $(git rev-parse HEAD) 快照日期: $(date %F) EOF下载模型文件模型下载入口在 mineru/cli/models_download.py对应的命令行是mineru-models-download。国内网络用 ModelScope 源通常更快# 在联网机上执行模型默认存入 ~/.cache路径以日志输出为准 mineru-models-download --source modelscope --model_type all # 想只要 pipeline 后端CPU 方案可以只下这一份体积小很多 mineru-models-download -s modelscope -m pipeline命令跑完后会自动把模型目录和模型源写回配置文件这是它比手动拷贝方便的地方。把模型目录整体打包例如tar -cf mineru_models.tar -C ~/.cache 上面日志中提示的模型目录名缓存 Python 依赖在联网机上用与离线机一致的 Python 版本下载 wheelpython3 -m venv prep_env source prep_env/bin/activate pip install -U pip # [core] 同时覆盖 vlm、pipeline、gradio 三个依赖组 pip download mineru[core]3.4.4 -d ./offline_wheels # 如果离线机是纯 CPU只装 pipeline 组即可 # pip download mineru[pipeline]3.4.4 -d ./offline_wheels构建并导出 Docker 镜像容器方案docker/china/Dockerfile 基于 vllm-openai 镜像构建阶段就会装好依赖并下载模型所以导出 tar 后离线机开箱即用。仓库另外提供了一批国产加速卡的构建文件放在 docker/china/ 目录昇腾、燧原、昆仑芯、摩尔线程等有对应硬件的读者可以换用相应 Dockerfilecd MinerU docker build -t mineru:offline -f docker/china/Dockerfile . # 导出成离线可传输的 tar docker save -o mineru_offline_image.tar mineru:offline⚠️ 踩坑提醒构建时若拉不动基础镜像先把 Dockerfile 里注释的 cu129 变体换上来再按自己的网络调整 registry 前缀。国内镜像源前缀在文件顶部有注释示例。离线机落地从拷贝文件到跑通第一个文档把源码目录、mineru_models.tar、offline_wheels/、mineru_offline_image.tar四样通过 U 盘或内网拷贝进离线机。下面两种方案pip 直装 / Docker任选其一核心都是让MINERU_MODEL_SOURCElocal生效让它只找本地模型。方案 Apip 离线安装# 1) 安装依赖与本体全程不联网 pip install --no-index --find-links/opt/mineru/offline_wheels mineru[core]3.4.4 # 2) 展开模型 mkdir -p /opt/mineru/models tar -xf /path/to/mineru_models.tar -C /opt/mineru/models # 3) 指向本地模型写配置文件 cat ~/.mineru.json EOF { model-source: local, models-dir: { pipeline: /opt/mineru/models/pipeline, vlm: /opt/mineru/models/vlm } } EOF # 也可以用环境变量替代配置文件 # export MINERU_TOOLS_CONFIG_JSON/opt/mineru/mineru.json字段结构参考仓库根目录的配置模板 mineru.template.json。 部署小贴士~/.mineru.json丢失或写错时报错通常是找不到模型或尝试联网下载。第一件事就是cat ~/.mineru.json核对models-dir两个路径是否真实存在。方案 B加载 Docker 镜像docker load -i /path/to/mineru_offline_image.tar # 交互式进入确认命令可用 docker run --rm --gpus all -it mineru:offline mineru -v镜像入口默认已注入MINERU_MODEL_SOURCElocal模型随镜像自带无需再挂目录。验证解析用仓库自带的测试 PDF仓库里有一个现成测试文件 tests/unittest/pdfs/test.pdf还有几个更复杂的样例在 demo/pdfs/ 目录扫描版、多栏版都有。export MINERU_MODEL_SOURCElocal # CPU 环境直接用 pipeline 后端有 GPU 可去掉 --backend mineru -p tests/unittest/pdfs/test.pdf -o /tmp/mineru_out --backend pipeline # 找到产物按后端命名输出目录里面有 .md、middle json、content list 和图片 find /tmp/mineru_out -name *.md head -40 $(find /tmp/mineru_out -name *.md | head -1)看到带标题层级、公式和表格的 Markdown这条链路就算通了。需要 Web 界面验收时可以起 Gradio 服务后访问 7860 端口。跑起来之后性能调优、批量任务与日常运维按文档类型挑后端和强度场景推荐配置说明纯 CPU 机器--backend pipeline无需 GPU批量最稳高精度、有 GPUhybrid 后端 --effort high保留图片/图表分析精度优先大批量、速度优先hybrid 后端 --effort medium速度快 35%~220%但自动关闭图片分析显存紧张调低--gpu-memory-utilization从 0.5 起调仍不够就降到 0.4 以下见 docker/compose.yaml 中注释面向其他系统开放 API 服务mineru-api提供 FastAPI 服务自带/health健康检查端点适合被内部系统集成# 前台启动便于看日志 mineru-api --host 0.0.0.0 --port 8000 # 另一个终端验证 curl -sf http://127.0.0.1:8000/health echo API 正常容器化部署时直接用 compose 的 profile 拉起docker/compose.yaml 里定义了 api / openai-server / router / gradio 四组服务docker compose -f docker/compose.yaml --profile api up -d # 多卡或多实例时改用 router 做统一入口支持 --upstream-url 聚合已有 api 服务 docker compose -f docker/compose.yaml --profile router up -d批量处理脚本把未处理文档目录当作工作队列跑完自动归档适合接 cron 定时任务cat /opt/mineru/scripts/batch_mineru.sh EOF #!/bin/bash set -u IN/data/inbox/pdf # 待处理目录 OUT/data/mineru_out # 输出目录 DONE/data/inbox/done export MINERU_MODEL_SOURCElocal mkdir -p $DONE shopt -s nullglob for f in $IN/*.pdf; do echo 处理: $f mkdir -p $OUT/$(basename ${f%.pdf}) if mineru -p $f -o $OUT/$(basename ${f%.pdf}) --backend pipeline; then mv $f $DONE/ else echo 失败保留原文件: $f fi done EOF chmod x /opt/mineru/scripts/batch_mineru.sh故障排查对照表现象先查什么处理方式启动时仍尝试联网下载模型MINERU_MODEL_SOURCE与~/.mineru.json两处都设为local确认models-dir指向真实目录模型加载报错、文件缺失模型目录结构是否完整对照下载日志里的最终目录核对必要时回联网机重下并比对大小解析慢、内存吃紧文档页数与并发按文件拆分输入目录hybrid 换--effort mediumCPU 场景改 pipeline 后端vLLM 启动即 OOM显存占用调低--gpu-memory-utilization并停掉同机其他 vllm 服务输出中文乱码、表格错位系统字体与模型匹配度安装 Noto CJK 字体Dockerfile 里已装确认 OCR 语言参数与文档实际语言一致把这次部署存档更新或交接之前做三件事重新生成一次version_snapshot.txt记录提交号与日期把当前~/.mineru.json和批量脚本备份到版本目录需要升级时先在隔离的联网机把新版本模型和依赖备齐、验证通过再走一遍本文的传输流程——离线环境的升级本质上是再来一次部署留好回滚 tar 即可。更多参数与环境变量可参考仓库内文档 docs/zh/usage/cli_tools.md 与 docs/zh/quick_start/docker_deployment.md。【免费下载链接】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：从硬件体检到 PDF 批量解析的全流程实操
离线部署 MinerU从硬件体检到 PDF 批量解析的全流程实操【免费下载链接】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、RAG、Agent 使用的 Markdown 与 JSON。如果你的服务器完全不能上网模型下载、依赖安装、镜像构建都得提前在联网机上备好。本文给出一条完整路径先检查硬件底线再在联网机上把四类物料备齐最后到离线机上一路装到能跑批量任务并附上日常运维和排障方法。全文以 3.4.4 版本为例。上图是 MinerU 典型的解析流程示意。看的时候重点盯两点一是输入端支持多格式文档二是输出端得到阅读顺序正确、公式转 LaTeX、表格转 HTML 的结构化结果——离线部署的验收标准就是复现这条链路。离线部署前必做的环境体检先确认机器够不够用够不上再谈后面的事。MinerU 有两个解析后端理解一下差别有助于定硬件pipeline 后端一套轻量模型流水线版面、OCR、公式、表格识别纯 CPU 就能跑速度稳定、不产生幻觉vlm / hybrid 后端基于视觉大模型精度高但通常需要 GPU 加 vLLM 推理加速Volta 及以后架构、显存 ≥8GB。如果离线机只有 CPU走 pipeline 后端即可下文会给出对应做法。检查项最低要求说明内存8 GB解析 VLM 模型或大文档时建议 16 GB 起磁盘40 GB 空闲源码 pipeline 模型 VLM 模型 依赖加起来不小Python3.10 ~ 3.13pyproject.toml 声明requires-python 3.10,3.14Docker可选想用容器方案才需要注意 Docker 部署仅支持 Linux 与 WSL2不建议在 macOS 上跑GPU可选vllm 加速要求显卡驱动兼容 CUDA 13.0可换 cu129 基础镜像适配 CUDA 12.9在目标机器上执行把结果记下来后面排障要用# Python 版本需要 3.10 及以上 python3 --version # Docker 环境选容器方案才需要 docker --version docker compose version # 磁盘与内存 df -h / free -h | awk /^Mem:/ {print $2} # 有 NVIDIA 卡时顺手确认驱动支持的 CUDA 版本 nvidia-smi | grep -i cuda⚠️ 踩坑提醒vLLM 会预占大量显存同一台机器上不要同时跑多个 vllm 服务。如果你计划用vlm-engine后端先把其他吃显存的进程停掉。联网机备料四样东西一样都不能少离线部署的成败90% 取决于联网机上备料是否完整。清单如下逐项核对源码指定版本克隆别用 main 分支裸跑模型文件pipeline 和 VLM 两套模型离线机上无法再下载Python 依赖提前下载成 wheel 包Docker 镜像容器方案下镜像里已内置依赖和模型只需拷一个 tar。锁定版本并拉取源码# 克隆并固定版本保证离线环境与文档描述可对应 git clone https://gitcode.com/GitHub_Trending/mi/MinerU.git cd MinerU git checkout v3.4.4 # 顺手留一份版本快照回滚和交接都靠它 cat version_snapshot.txt EOF MinerU 版本: $(python3 -c from mineru.version import __version__; print(__version__) 2/dev/null || echo v3.4.4) 源码提交: $(git rev-parse HEAD) 快照日期: $(date %F) EOF下载模型文件模型下载入口在 mineru/cli/models_download.py对应的命令行是mineru-models-download。国内网络用 ModelScope 源通常更快# 在联网机上执行模型默认存入 ~/.cache路径以日志输出为准 mineru-models-download --source modelscope --model_type all # 想只要 pipeline 后端CPU 方案可以只下这一份体积小很多 mineru-models-download -s modelscope -m pipeline命令跑完后会自动把模型目录和模型源写回配置文件这是它比手动拷贝方便的地方。把模型目录整体打包例如tar -cf mineru_models.tar -C ~/.cache 上面日志中提示的模型目录名缓存 Python 依赖在联网机上用与离线机一致的 Python 版本下载 wheelpython3 -m venv prep_env source prep_env/bin/activate pip install -U pip # [core] 同时覆盖 vlm、pipeline、gradio 三个依赖组 pip download mineru[core]3.4.4 -d ./offline_wheels # 如果离线机是纯 CPU只装 pipeline 组即可 # pip download mineru[pipeline]3.4.4 -d ./offline_wheels构建并导出 Docker 镜像容器方案docker/china/Dockerfile 基于 vllm-openai 镜像构建阶段就会装好依赖并下载模型所以导出 tar 后离线机开箱即用。仓库另外提供了一批国产加速卡的构建文件放在 docker/china/ 目录昇腾、燧原、昆仑芯、摩尔线程等有对应硬件的读者可以换用相应 Dockerfilecd MinerU docker build -t mineru:offline -f docker/china/Dockerfile . # 导出成离线可传输的 tar docker save -o mineru_offline_image.tar mineru:offline⚠️ 踩坑提醒构建时若拉不动基础镜像先把 Dockerfile 里注释的 cu129 变体换上来再按自己的网络调整 registry 前缀。国内镜像源前缀在文件顶部有注释示例。离线机落地从拷贝文件到跑通第一个文档把源码目录、mineru_models.tar、offline_wheels/、mineru_offline_image.tar四样通过 U 盘或内网拷贝进离线机。下面两种方案pip 直装 / Docker任选其一核心都是让MINERU_MODEL_SOURCElocal生效让它只找本地模型。方案 Apip 离线安装# 1) 安装依赖与本体全程不联网 pip install --no-index --find-links/opt/mineru/offline_wheels mineru[core]3.4.4 # 2) 展开模型 mkdir -p /opt/mineru/models tar -xf /path/to/mineru_models.tar -C /opt/mineru/models # 3) 指向本地模型写配置文件 cat ~/.mineru.json EOF { model-source: local, models-dir: { pipeline: /opt/mineru/models/pipeline, vlm: /opt/mineru/models/vlm } } EOF # 也可以用环境变量替代配置文件 # export MINERU_TOOLS_CONFIG_JSON/opt/mineru/mineru.json字段结构参考仓库根目录的配置模板 mineru.template.json。 部署小贴士~/.mineru.json丢失或写错时报错通常是找不到模型或尝试联网下载。第一件事就是cat ~/.mineru.json核对models-dir两个路径是否真实存在。方案 B加载 Docker 镜像docker load -i /path/to/mineru_offline_image.tar # 交互式进入确认命令可用 docker run --rm --gpus all -it mineru:offline mineru -v镜像入口默认已注入MINERU_MODEL_SOURCElocal模型随镜像自带无需再挂目录。验证解析用仓库自带的测试 PDF仓库里有一个现成测试文件 tests/unittest/pdfs/test.pdf还有几个更复杂的样例在 demo/pdfs/ 目录扫描版、多栏版都有。export MINERU_MODEL_SOURCElocal # CPU 环境直接用 pipeline 后端有 GPU 可去掉 --backend mineru -p tests/unittest/pdfs/test.pdf -o /tmp/mineru_out --backend pipeline # 找到产物按后端命名输出目录里面有 .md、middle json、content list 和图片 find /tmp/mineru_out -name *.md head -40 $(find /tmp/mineru_out -name *.md | head -1)看到带标题层级、公式和表格的 Markdown这条链路就算通了。需要 Web 界面验收时可以起 Gradio 服务后访问 7860 端口。跑起来之后性能调优、批量任务与日常运维按文档类型挑后端和强度场景推荐配置说明纯 CPU 机器--backend pipeline无需 GPU批量最稳高精度、有 GPUhybrid 后端 --effort high保留图片/图表分析精度优先大批量、速度优先hybrid 后端 --effort medium速度快 35%~220%但自动关闭图片分析显存紧张调低--gpu-memory-utilization从 0.5 起调仍不够就降到 0.4 以下见 docker/compose.yaml 中注释面向其他系统开放 API 服务mineru-api提供 FastAPI 服务自带/health健康检查端点适合被内部系统集成# 前台启动便于看日志 mineru-api --host 0.0.0.0 --port 8000 # 另一个终端验证 curl -sf http://127.0.0.1:8000/health echo API 正常容器化部署时直接用 compose 的 profile 拉起docker/compose.yaml 里定义了 api / openai-server / router / gradio 四组服务docker compose -f docker/compose.yaml --profile api up -d # 多卡或多实例时改用 router 做统一入口支持 --upstream-url 聚合已有 api 服务 docker compose -f docker/compose.yaml --profile router up -d批量处理脚本把未处理文档目录当作工作队列跑完自动归档适合接 cron 定时任务cat /opt/mineru/scripts/batch_mineru.sh EOF #!/bin/bash set -u IN/data/inbox/pdf # 待处理目录 OUT/data/mineru_out # 输出目录 DONE/data/inbox/done export MINERU_MODEL_SOURCElocal mkdir -p $DONE shopt -s nullglob for f in $IN/*.pdf; do echo 处理: $f mkdir -p $OUT/$(basename ${f%.pdf}) if mineru -p $f -o $OUT/$(basename ${f%.pdf}) --backend pipeline; then mv $f $DONE/ else echo 失败保留原文件: $f fi done EOF chmod x /opt/mineru/scripts/batch_mineru.sh故障排查对照表现象先查什么处理方式启动时仍尝试联网下载模型MINERU_MODEL_SOURCE与~/.mineru.json两处都设为local确认models-dir指向真实目录模型加载报错、文件缺失模型目录结构是否完整对照下载日志里的最终目录核对必要时回联网机重下并比对大小解析慢、内存吃紧文档页数与并发按文件拆分输入目录hybrid 换--effort mediumCPU 场景改 pipeline 后端vLLM 启动即 OOM显存占用调低--gpu-memory-utilization并停掉同机其他 vllm 服务输出中文乱码、表格错位系统字体与模型匹配度安装 Noto CJK 字体Dockerfile 里已装确认 OCR 语言参数与文档实际语言一致把这次部署存档更新或交接之前做三件事重新生成一次version_snapshot.txt记录提交号与日期把当前~/.mineru.json和批量脚本备份到版本目录需要升级时先在隔离的联网机把新版本模型和依赖备齐、验证通过再走一遍本文的传输流程——离线环境的升级本质上是再来一次部署留好回滚 tar 即可。更多参数与环境变量可参考仓库内文档 docs/zh/usage/cli_tools.md 与 docs/zh/quick_start/docker_deployment.md。【免费下载链接】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），仅供参考