1. 为什么要在内网离线部署 MonkeyOCRv2做过企业级文档处理项目的人都有一个共识数据不出内网这条红线比任何技术选型都重要。MonkeyOCRv2 作为一套文档识别与结构化提取能力相当完整的方案在票据识别、合同解析、档案数字化这些场景里表现很稳但它的默认部署方式高度依赖公网拉取依赖和模型权重。一旦落到金融、政务、医疗这类内网环境网络隔离就成了第一道坎。我这次接到的需求很典型一台内网服务器装了 NVIDIA 显卡要求把 MonkeyOCRv2 完整跑起来全程不能访问外网。听起来简单实际操作下来从镜像构建到 GPU 调优中间踩的坑足够写一篇长文。核心难点集中在三块15GB 级别的 Docker 镜像怎么在内网落地、NVIDIA 驱动与容器运行时怎么打通、vLLM 推理引擎在有限显存下怎么调优。这篇文章面向的是有一定 Linux 和 Docker 基础、正在做内网 AI 服务部署的工程师。如果你手上正好有一台带 NVIDIA 显卡的机器需要离线部署 OCR 或大模型推理服务这里面的思路和参数可以直接抄。我会把镜像分层构建、离线依赖打包、GPU 直通配置、vLLM 显存调优这几个环节拆开讲每个参数为什么这么设我都会给出计算过程。先说结论性的判断MonkeyOCRv2 这类方案在内网部署镜像体积大不是问题问题是分层不合理导致每次改动都要重传 15GB。解决办法是把基础环境、Python 依赖、模型权重分成三层模型权重单独做一层这样后续调优只需要重建最上层。这个思路贯穿全文后面会反复用到。2. 离线部署的整体设计与分层思路2.1 为什么选择 Docker 而不是裸机部署裸机部署 MonkeyOCRv2 不是不行但内网环境下一旦 Python 依赖冲突排查成本极高。我见过太多因为 CUDA 版本、PyTorch 版本、vLLM 版本三者不匹配导致推理直接崩掉的案例。Docker 的价值在于把运行时环境冻结成一个不可变镜像内网机器只需要能跑容器不需要关心底层 Python 环境。具体到 MonkeyOCRv2它的依赖链大概是这样的底层是 CUDA 和 cuDNN中间是 PyTorch上层是 vLLM 推理引擎最上面才是 MonkeyOCRv2 自己的业务代码和模型权重。这四层里前三层都是重依赖加起来轻松超过 10GB。用 Docker 分层可以把前三层做成一个稳定的基础镜像业务层单独构建后续迭代只动最上面一层。提示内网部署时基础镜像一旦验证通过就不要轻易改动。任何底层改动都意味着要重新走一遍离线传输流程15GB 的镜像通过内网文件服务器传输快则十几分钟慢则半小时以上。2.2 15GB 镜像的体积构成拆解很多人看到 15GB 就头疼其实拆开看并不夸张。我实测下来一个典型的 MonkeyOCRv2 镜像体积分布大致如下层级内容体积占比是否可复用基础系统层Ubuntu 22.04 基础工具约 1.5GB高度可复用CUDA 运行时层CUDA 12.x cuDNN约 4GB高度可复用Python 依赖层PyTorch vLLM 其他库约 5GB中等可复用模型权重层MonkeyOCRv2 权重文件约 3.5GB按版本复用业务代码层推理服务代码约 0.1GB频繁变动看清楚这个分布优化方向就明确了业务代码层只有 100MB 左右调优时只需要重建这一层。模型权重层虽然大但版本稳定后基本不动。真正需要一次性搞定的是前三层也就是那个约 10.5GB 的基础镜像。2.3 离线传输方案的选择逻辑内网传输大镜像常见方案有三种直接docker save成 tar 包、用私有镜像仓库、用文件服务器加docker load。我最终选的是私有镜像仓库加分层推送理由是后续迭代只需要推送变动层而不是每次传整个 15GB。如果内网连私有仓库都不允许那就退回到docker save方案。这里有个技巧docker save支持按镜像名导出导出后的 tar 包可以用split命令切成多个小文件方便通过限制单文件大小的传输通道搬运。切分和合并的命令后面实操部分会给。3. 基础镜像构建与离线依赖打包3.1 基础镜像的 Dockerfile 设计基础镜像的目标是提供一个CUDA 加 PyTorch 加 vLLM 都能跑的稳定环境。我选的是 NVIDIA 官方 CUDA 基础镜像作为起点而不是从 Ubuntu 裸装原因是官方镜像已经把驱动兼容层处理好了省去大量调试时间。FROM nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04 ENV DEBIAN_FRONTENDnoninteractive ENV PYTHONUNBUFFERED1 ENV TZAsia/Shanghai RUN apt-get update apt-get install -y \ python3.10 python3-pip python3.10-venv \ libgl1 libglib2.0-0 libsm6 libxext6 libxrender-dev \ rm -rf /var/lib/apt/lists/* RUN ln -s /usr/bin/python3.10 /usr/bin/python WORKDIR /app COPY requirements-base.txt . RUN pip install --no-cache-dir -r requirements-base.txt这里有几个细节值得说。第一libgl1这一串系统库是 OpenCV 的依赖MonkeyOCRv2 做图像预处理时会用到不装的话运行时报错很难定位。第二--no-cache-dir必须加否则 pip 缓存会让镜像凭空多出 2GB 以上。第三时区设置成Asia/Shanghai避免日志时间戳对不上。3.2 Python 依赖的离线打包内网机器不能pip install所以依赖必须提前在外网机器上打包成 wheel 文件。这里有个坑直接pip download下载的 wheel 可能和运行环境的平台不匹配。正确做法是在和目标环境相同架构的机器上执行下载。pip download -r requirements-base.txt \ -d ./offline_wheels \ --platform manylinux2014_x86_64 \ --python-version 310 \ --only-binary:all:--platform和--python-version这两个参数是关键它们保证下载的 wheel 能在目标环境安装。如果某个包没有预编译 wheel--only-binary:all:会直接报错这时候就需要单独处理要么找替代包要么在外网机器上编译好再打包。注意vLLM 的 wheel 对 CUDA 版本很敏感。CUDA 12.4 环境下要选对应编译版本的 vLLM装错版本会在导入时直接报undefined symbol错误而且报错信息不会直接告诉你是版本问题。3.3 模型权重的离线准备MonkeyOCRv2 的模型权重约 3.5GB这部分必须提前下载好。下载完成后建议做一次完整性校验记录每个文件的 SHA256 值。内网传输过程中文件损坏是常有的事没有校验值的话推理时报错你根本不知道是权重坏了还是代码有问题。find ./model_weights -type f -exec sha256sum {} \; weights_checksum.txt传输到内网后用sha256sum -c weights_checksum.txt校验一遍全部通过再继续。这一步花不了几分钟但能省掉后面几小时的排查时间。4. GPU 环境打通与容器运行时配置4.1 NVIDIA 驱动安装的版本匹配内网服务器装 NVIDIA 驱动最容易出问题的地方是驱动版本和 CUDA 版本不匹配。CUDA 12.4 要求驱动版本不低于 550.54.14。我一般先用nvidia-smi看当前驱动版本如果低于要求就得先升级驱动。驱动安装包也需要离线准备。从 NVIDIA 官网下载.run文件时注意选对显卡架构。RTX 4060 Laptop 这类消费级显卡和 H100 这类数据中心卡驱动包是不同的。下载完成后传到内网执行chmod x NVIDIA-Linux-x86_64-550.xx.run sudo ./NVIDIA-Linux-x86_64-550.xx.run --no-opengl-files --dkms--no-opengl-files这个参数很重要它避免驱动覆盖系统的 OpenGL 库否则可能导致图形界面起不来。--dkms则是让驱动在系统内核升级后自动重新编译省去后续维护麻烦。4.2 NVIDIA Container Toolkit 的离线安装Docker 容器要用 GPU必须装 NVIDIA Container Toolkit。这个组件在内网安装稍微麻烦一点因为它依赖几个 apt 包。我的做法是提前在外网机器上把相关 deb 包全部下载好一起打包传进去。# 外网机器上准备 apt-get download nvidia-container-toolkit \ nvidia-container-toolkit-base \ libnvidia-container-tools \ libnvidia-container1传到内网后dpkg -i *.deb一次性安装。装完后配置 Docker 运行时sudo nvidia-ctk runtime configure --runtimedocker sudo systemctl restart docker验证是否成功跑一个测试容器docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi能正常输出显卡信息说明 GPU 直通配置成功。如果报could not select device driver错误八成是 toolkit 没装好或者 Docker 没重启。4.3 显存分配与多卡策略MonkeyOCRv2 在单卡上跑显存占用主要分三块模型权重、KV Cache、推理时的中间激活。以 RTX 4060 Laptop 的 8GB 显存为例模型权重占 3.5GB剩下 4.5GB 要留给 KV Cache 和激活。vLLM 的gpu-memory-utilization参数控制显存使用上限默认 0.9。在 8GB 卡上我建议设成 0.85留一点余量给系统。计算公式大致是可用显存 总显存 × gpu-memory-utilization - 模型权重 KV Cache 显存 可用显存 × 0.9按 8GB 卡算可用显存约 6.8GB减去 3.5GB 权重剩 3.3GB 给 KV Cache。这个量对于 OCR 场景的短序列推理够用但如果要处理长文档就得考虑多卡或者换更大显存的卡。5. vLLM 推理引擎的部署与调优5.1 vLLM 启动参数的核心配置vLLM 是 MonkeyOCRv2 的推理后端它的启动参数直接决定服务能不能跑起来、跑得快不快。我常用的启动命令是这样的python -m vllm.entrypoints.openai.api_server \ --model /app/model_weights \ --served-model-name monkey-ocr \ --tensor-parallel-size 1 \ --gpu-memory-utilization 0.85 \ --max-model-len 4096 \ --dtype float16 \ --port 8000逐个参数解释。--tensor-parallel-size 1表示单卡推理多卡的话改成卡数。--max-model-len 4096是最大序列长度OCR 场景一般不需要太长设太大反而浪费 KV Cache。--dtype float16用半精度推理显存占用减半精度损失在 OCR 任务里几乎看不出来。提示如果启动时报CUDA out of memory先把--gpu-memory-utilization降到 0.7 试试。还不行就降--max-model-len这两个参数是显存占用的主要调节旋钮。5.2 显存不足时的降级策略内网环境经常遇到显卡显存不够的情况。我整理了一套降级顺序从影响最小的开始降级手段显存节省性能影响推荐优先级降低 gpu-memory-utilization中等小1降低 max-model-len中等中2启用量化int8大中3启用 CPU offload很大大4量化是最有效的显存节省手段int8 量化能把模型权重压到原来的一半。但 MonkeyOCRv2 的权重是否支持量化需要看具体模型结构。如果模型里有不支持量化的算子强行量化会导致精度崩掉。5.3 推理性能的实测调优调优不能靠猜得实测。我一般用vllm自带的 benchmark 工具跑一组数据记录吞吐和延迟。关键指标有两个TTFT首 token 延迟和TPOT每 token 输出时间。OCR 场景对 TTFT 更敏感因为用户等的是第一眼结果。实测下来--max-num-seqs这个参数对吞吐影响很大。默认值是 256但在 8GB 卡上设这么大反而会因为 KV Cache 频繁换入换出导致性能下降。我一般设成 32 到 64 之间具体值用 benchmark 跑出来。python -m vllm.benchmarks.benchmark_serving \ --model /app/model_weights \ --num-prompts 100 \ --request-rate 10跑完看输出里的Throughput和Mean TTFT调参的目标就是在 TTFT 可接受的前提下把吞吐拉满。6. 常见问题与排查技巧实录6.1 镜像构建阶段的典型报错构建阶段最常见的问题是 pip 安装超时或失败。内网环境下如果requirements-base.txt里有包没提前下载构建会直接卡住。解决办法是在 Dockerfile 里加--no-index --find-links参数强制 pip 只从本地 wheel 目录安装RUN pip install --no-cache-dir \ --no-index \ --find-links/app/offline_wheels \ -r requirements-base.txt这样一旦有包缺失构建会立刻报错而不是傻等超时。报错信息会明确告诉你缺哪个包补下载就行。6.2 GPU 直通失败的排查路径docker run --gpus all报错时按这个顺序排查nvidia-smi在宿主机上能不能正常输出不能就是驱动问题nvidia-container-cli --version有没有输出没有就是 toolkit 没装好docker info | grep -i runtime看 nvidia runtime 有没有注册检查/etc/docker/daemon.json里runtimes配置是否正确我遇到过最隐蔽的一个问题是宿主机装了驱动但 Docker 服务是在装驱动之前启动的导致 Docker 进程没有加载到 NVIDIA 库。解决办法就是systemctl restart docker重启后就好了。6.3 vLLM 启动失败的常见原因vLLM 启动失败报错信息往往很长但核心原因就那么几个。我整理了一张速查表报错关键词根本原因解决办法CUDA out of memory显存不足降 gpu-memory-utilizationundefined symbol版本不匹配检查 vLLM 和 CUDA 版本no kernel image显卡架构不支持换编译版本或降级connection refused端口被占用换端口或杀进程model not found权重路径错误检查挂载路径no kernel image这个错误在消费级显卡上比较常见原因是 vLLM 预编译的 kernel 可能没有覆盖你的显卡架构。解决办法是从源码编译或者找对应架构的预编译版本。6.4 内网传输的实用技巧15GB 镜像传输如果内网带宽有限建议用split切分# 切分 split -b 2G monkey-ocr-v2.tar monkey-ocr-v2.tar.part_ # 合并 cat monkey-ocr-v2.tar.part_* monkey-ocr-v2.tar切分后每个文件 2GB方便通过限制单文件大小的通道传输。合并后记得校验 SHA256确保传输过程没有损坏。注意docker save导出的 tar 包用docker load导入时镜像名和标签会保留。如果导入后docker images看不到检查一下是不是导入到了错误的 Docker 上下文。7. 我踩过的坑和几条实在建议第一个坑是镜像层顺序。我一开始把模型权重放在 Dockerfile 靠前的位置结果每次改业务代码都要重新复制 3.5GB 权重构建一次要十几分钟。后来把权重层挪到最后业务代码改动只需要重建最上面一层构建时间降到几十秒。这个顺序调整带来的效率提升比任何调优都明显。第二个坑是vLLM 版本选择。我试过用最新版 vLLM结果和 MonkeyOCRv2 的模型结构不兼容报了一堆看不懂的算子错误。后来退回到一个经过验证的稳定版本问题消失。内网部署稳定比新更重要不要追最新版。第三个坑是显存碎片。长时间运行后vLLM 的显存池会出现碎片导致原本够用的显存突然不够。解决办法是设置--swap-space参数给显存池留一点交换空间或者定期重启服务。我现在的做法是每天凌晨定时重启一次推理服务运行稳定性明显提升。最后分享一个实用技巧内网部署完成后写一个健康检查脚本定时请求推理接口记录响应时间和成功率。这个脚本能在服务出问题时第一时间告警比等到用户反馈再排查要主动得多。脚本很简单用 curl 请求一下/health接口超过阈值就发邮件通知。这个习惯让我在内网环境下的服务可用性提升了不少。