1. 为什么要在内网离线环境啃下 MonkeyOCRv2 这块硬骨头做过企业级文档智能处理的人都有一个共识真正难的不是模型跑起来而是让它在没有外网、没有镜像仓库、没有 pip 源的内网环境里稳定跑起来。MonkeyOCRv2 作为一套面向文档解析的 OCR 方案模型权重加上依赖环境打包成一个 Docker 镜像轻松就冲到 15GB 上下。这个体积意味着你没法靠现场拉取糊弄过去必须提前把镜像构建好、导出成 tar 包、再搬进内网导入。我最近刚在一个纯离线机房环境里完整走了一遍这套流程从镜像构建、依赖固化、GPU 驱动对齐到 vLLM 推理引擎的显存调优踩的坑比想象中多。这篇文章就把整个过程拆开讲清楚重点放在为什么这么设计和实际会出什么问题上而不是给你一份照抄就完事的命令清单。适合两类人看一类是要在内网部署 OCR/文档解析服务但被离线环境卡住的运维和算法工程师另一类是想搞清楚 Docker 镜像构建、GPU 透传、vLLM 调优这几件事底层逻辑的技术同学。先说清楚 MonkeyOCRv2 这套东西的定位。它本质上是把文档检测、版面分析、文字识别、结构化输出串成一条流水线底层往往依赖 PyTorch 做视觉推理同时用 vLLM 这类高性能推理引擎来加速大模型部分比如版面理解或后处理的语言模型。所以一个完整的部署镜像里通常同时塞了 CUDA 运行时、PyTorch、vLLM、模型权重、以及一堆 Python 依赖。15GB 这个量级基本就是CUDA 基础镜像 框架 权重三层叠加的结果。内网离线部署的核心矛盾在于构建环境有网、运行环境没网而两者之间的唯一通道是一个 tar 包。这就决定了整个流程必须分成构建阶段和迁移阶段两段任何在运行阶段才去下载的东西都是定时炸弹。我见过太多人构建时图省事用了pip install直接联网装结果镜像搬到内网一跑就报缺包。所以下面所有步骤我都会强调离线自包含这个原则。2. 镜像构建阶段把 15GB 的依赖全部焊死在层里2.1 基础镜像选型为什么不用 slim 版本构建 MonkeyOCRv2 镜像的第一步是选基础镜像。很多人第一反应是选python:3.10-slim来减小体积但在这个场景下我强烈不建议。原因很直接slim 版本裁掉了大量系统库而 CUDA、PyTorch、OpenCV 这些组件对系统级依赖比如libgl1、libglib2.0、libsm6、libxext6有硬性要求你后面得一个个手动补补漏一个就是运行时报错。更合理的做法是以 NVIDIA 官方的 CUDA 运行时镜像为底座比如nvidia/cuda:12.1.1-cudnn8-runtime-ubuntu22.04。这里有个关键选择用runtime还是devel。devel版本带了完整的编译工具链体积大好几个 GB但如果你在构建阶段需要编译某些 Python 扩展比如某些 OCR 后处理库的 C 扩展就必须用devel。我的经验是如果构建过程中有任何pip install会触发源码编译就用 devel否则用 runtime 能省下 3-4GB。选 CUDA 版本时还要和宿主机的 GPU 驱动对齐。这里有个常被忽略的规则CUDA 运行时版本不能高于驱动支持的最高版本。比如宿主机驱动是 535 系列它最高支持到 CUDA 12.2那你镜像里用 12.1 是安全的用 12.4 就可能报CUDA driver version is insufficient。查驱动支持版本的方法是在宿主机跑nvidia-smi右上角会显示CUDA Version: 12.x这个数字就是上限。2.2 分层构建策略让 15GB 镜像可维护15GB 的镜像如果写成一个大RUN后续任何改动都要重建整个层构建一次半小时起步调试起来极其痛苦。我的做法是按变化频率分层第一层系统依赖apt 包几乎不变第二层CUDA/cuDNN 相关很少变第三层Python 基础依赖numpy、opencv 等偶尔变第四层PyTorch、vLLM 等重型框架较少变第五层MonkeyOCRv2 代码和模型权重经常变这样改代码时只重建最后一层几秒钟搞定。模型权重这一层尤其要注意权重文件动辄几个 GB如果和代码混在一层每次改一行代码都要重新拷贝权重浪费时间还撑大镜像历史。关于模型权重的处理有个实操细节权重不要用COPY直接拷进镜像层而是考虑用挂载卷。如果内网环境允许挂载宿主机目录把权重放在宿主机、容器启动时-v挂进去镜像体积能直接砍掉一大半。但如果要求镜像完全自包含比如要通过离线 tar 包分发到多台机器那就只能打进镜像这时候记得用.dockerignore排除掉权重目录里的临时文件和缓存。2.3 离线依赖固化pip 的坑最深构建阶段最容易翻车的就是 Python 依赖。联网环境下pip install -r requirements.txt看着没问题但它会去 PyPI 拉包而内网运行时根本没有 PyPI。解决办法是在构建阶段就把所有 wheel 包下载下来固化进镜像。具体做法分两种。第一种是构建时直接装好让依赖留在镜像层里这是最省事的只要构建环境有网就行。第二种是提前用pip download把所有 wheel 下到一个目录构建时用pip install --no-index --find-links/wheels从本地装。第二种更适合需要严格控制版本、或者构建环境也不稳定的场景。这里有个隐藏坑PyTorch 和 vLLM 的版本必须严格匹配 CUDA 版本。比如你装了 CUDA 12.1 的 PyTorch但 vLLM 编译时链接的是 CUDA 11.8 的库运行时就会报符号找不到。我的建议是直接用 vLLM 官方提供的镜像作为参考看它对应哪个 PyTorch 和 CUDA 组合然后照搬。vLLM 的版本迭代很快不同版本对 CUDA 和 PyTorch 的要求不一样选版本时一定要查它的 release note。还有一个经常被忽略的点pip 的缓存目录。默认情况下 pip 会把下载的包缓存在~/.cache/pip如果你在同一个RUN里装完不清缓存这些缓存会被打进镜像层白白多出几个 GB。正确做法是在RUN末尾加 rm -rf ~/.cache/pip或者用pip install --no-cache-dir。3. 从构建机到内网镜像导出与迁移的完整链路3.1 docker save 与镜像瘦身镜像构建完下一步是导出成 tar 包搬进内网。命令本身很简单docker save -o monkeyocrv2.tar monkeyocrv2:latest。但 15GB 的镜像导出来可能变成 16-17GB因为docker save会把所有层原样打包不做压缩。如果内网迁移通道带宽有限比如只能走 U 盘或者慢速内网压缩就很有必要。docker save出来的 tar 可以用 gzip 再压一道docker save monkeyocrv2:latest | gzip monkeyocrv2.tar.gz。实测下来因为镜像里有很多文本和未压缩的库文件gzip 通常能压到 60%-70%也就是 15GB 能压到 9-10GB 左右。如果追求更高压缩率可以用 zstd但内网机器上不一定有 zstd得提前确认。导出前还有一步瘦身值得做清理构建过程中产生的临时文件。比如 apt 的包缓存/var/lib/apt/lists/*、pip 缓存、编译中间产物。这些如果在构建时没清会一直留在镜像里。我一般会在 Dockerfile 里每个 apt 安装步骤后面都跟一句 rm -rf /var/lib/apt/lists/*养成习惯。3.2 内网导入与验证tar 包搬到内网后用docker load -i monkeyocrv2.tar导入。导入完成后第一件事不是急着跑而是验证镜像完整性docker images看大小对不对docker run --rm monkeyocrv2:latest python -c import torch; print(torch.__version__)看关键依赖能不能导入。这里有个高频问题导入后镜像的 tag 可能变成none。这是因为docker save时如果镜像有多个 tag或者导出方式不对导入后 tag 会丢失。解决办法是导出时明确指定 tag导入后用docker tag重新打标签。更稳妥的做法是在构建机上就给镜像打好完整的仓库名:版本号标签导出时带上。验证 GPU 可用性是内网部署的关键一步。在容器里跑python -c import torch; print(torch.cuda.is_available())如果返回False问题通常出在三个地方宿主机没装 NVIDIA 驱动、没装nvidia-container-toolkit、或者容器启动时没加--gpus all。这三个是层层递进的关系得按顺序排查。4. GPU 透传容器里看见显卡的完整条件链4.1 宿主机驱动与 container-toolkit 的配合容器要用 GPU宿主机必须先具备三个条件NVIDIA 驱动装好、nvidia-container-toolkit装好、Docker 配置了 nvidia runtime。这三者缺一不可而且顺序不能乱。驱动安装这块Ubuntu 上用apt install nvidia-driver-535这类方式最省心但要注意装完必须重启否则内核模块没加载nvidia-smi会报couldnt communicate with the NVIDIA driver。如果是 Rocky Linux 这类 RHEL 系驱动安装方式不同通常要用官方 runfile 或者配置 ELRepo 源装完同样要重启并验证nvidia-smi能正常输出。nvidia-container-toolkit是让 Docker 能把 GPU 设备透传进容器的关键组件。装好后要执行nvidia-ctk runtime configure --runtimedocker把 nvidia runtime 注册到 Docker 配置里然后重启 Docker 服务。这一步做完docker run --gpus all才能生效。我见过有人驱动装好了、toolkit 也装了但忘了重启 Docker结果--gpus all一直报错排查半天。验证链路是否打通最直接的方法是在容器里跑nvidia-smi。如果容器里能看到和宿主机一样的 GPU 信息说明透传成功。如果报No devices were found基本就是 toolkit 或 runtime 配置的问题。4.2 多卡与显存可见性控制MonkeyOCRv2 这种规模的模型单卡往往够用但如果宿主机是多卡机器就需要控制容器能看到哪些卡。用--gpus device0,1可以指定只透传 0 号和 1 号卡。这个在共享 GPU 服务器上特别重要避免你的容器把别人的卡也占了。显存可见性还有个细节容器里nvidia-smi显示的显存和宿主机一致但实际可用显存受限于是否有其他进程占用。如果宿主机上已经有别的容器或进程在跑你的容器能用的显存就少了。排查显存不足时先在宿主机nvidia-smi看整体占用再进容器看自己的进程占了多少两边对比才能定位。对于 RTX 4060 Laptop 这类消费级显卡有个坑要注意显存相对有限通常 8GB跑大模型时很容易 OOM。这时候 vLLM 的显存参数就得调得很保守具体怎么调后面讲。5. vLLM 在离线环境下的显存与并发调优5.1 显存分配的核心参数vLLM 启动时最关键的参数是--gpu-memory-utilization它决定 vLLM 能占用多少比例的显存。默认值是 0.9意思是占用 90% 的显存。这个值在独占 GPU 时没问题但在共享环境或者显存本来就小的卡上设太高会导致启动就 OOM。我的经验是8GB 显存的卡这个值设 0.7-0.8 比较稳留出空间给 CUDA 上下文、PyTorch 缓存和其他进程。16GB 以上的卡可以设 0.85-0.9。设太低又浪费显存导致能加载的模型变小或者并发上不去所以要权衡。另一个关键参数是--max-model-len控制模型能处理的最大序列长度。这个值直接决定 KV cache 占多少显存。序列长度设得越大KV cache 越大能并发的请求数就越少。MonkeyOCRv2 如果处理的是长文档序列长度不能太小但也不能盲目设大。我的做法是先估算文档平均 token 数乘以 1.5 的安全系数作为max-model-len的起点然后根据实际显存占用微调。5.2 离线环境下的模型加载vLLM 默认会去 HuggingFace 拉模型内网环境必须改成从本地路径加载。启动时用--model /path/to/model指向容器内的模型目录。这里要注意模型目录的格式vLLM 需要的是 HuggingFace 格式的模型目录包含config.json、tokenizer相关文件和权重文件。如果权重是 safetensors 格式确认 vLLM 版本支持。离线加载还有个坑tokenizer 可能触发联网。某些 tokenizer 实现会去下载配置即使模型是本地路径。解决办法是设置环境变量HF_HUB_OFFLINE1和TRANSFORMERS_OFFLINE1强制所有 HuggingFace 相关组件走离线模式。这两个变量在内网部署时几乎是必设的能避免很多莫名其妙的超时。如果模型权重是分片的比如model-00001-of-00004.safetensors确认所有分片都在目录里缺一个都会加载失败。加载失败时的报错有时候很隐晦只说找不到某个文件所以部署前用ls核对一遍分片数量是最省事的做法。5.3 并发与吞吐的平衡vLLM 的并发能力受限于显存和max-model-len。在显存有限的情况下提高并发的手段主要是降低单请求的序列长度或者用--max-num-seqs限制同时处理的请求数。这个参数设太小吞吐上不去设太大又容易 OOM需要压测找平衡点。我的实测方法是先用小批量请求跑通确认功能正常然后逐步加压观察nvidia-smi的显存占用和 vLLM 日志里的排队情况。当显存接近上限或者请求开始大量排队时就是当前配置的瓶颈。这时候要么降max-model-len要么降max-num-seqs要么加卡。对于 OCR 场景还有个特殊考虑图像预处理和 OCR 推理本身也占显存。如果 MonkeyOCRv2 的视觉部分和 vLLM 的语言部分共用一张卡显存分配要同时考虑两者。这种情况下gpu-memory-utilization不能设太高得给视觉模型留空间。我一般会把视觉和语言部分分到不同卡上或者至少把 vLLM 的显存比例压到 0.6 以下。6. 内网部署中那些文档不会写的坑6.1 镜像层数过多导致的启动慢Docker 镜像层数太多会拖慢容器启动速度因为每层都要挂载。15GB 的镜像如果分成几十层启动时可能要等十几秒。解决办法是在构建末尾用docker squash或者多阶段构建合并层。不过 squash 会丢失层缓存影响后续构建速度所以要权衡。我的做法是开发阶段保留分层方便调试发布阶段用多阶段构建把最终镜像压到尽量少的层。6.2 时区和 locale 引发的诡异问题内网机器经常时区设置不对导致容器里日志时间戳错乱排查问题时对不上时间线。构建镜像时显式设置ENV TZAsia/Shanghai并安装tzdata能避免这个问题。locale 也是类似某些库依赖 UTF-8 locale如果容器里 locale 没设处理中文文档时可能报编码错误。加一句ENV LANGC.UTF-8基本能解决。6.3 共享内存不足导致推理卡死Docker 默认的共享内存是 64MBvLLM 这类多进程推理框架对共享内存需求很大64MB 往往不够表现为推理过程中突然卡死或者报Bus error。解决办法是启动容器时加--shm-size8g或者更大。这个坑特别隐蔽因为报错信息完全不提共享内存很多人会往显存或代码方向排查浪费大量时间。6.4 模型权重的权限问题从构建机拷进内网的权重文件如果权限设置不对容器里的非 root 用户可能读不了。特别是用COPY拷进镜像的权重默认属主是 root如果容器以非 root 用户运行就会报权限拒绝。解决办法是在 Dockerfile 里chown一下或者容器启动时用--user指定有权限的用户。我一般倾向于在 Dockerfile 里统一chown到运行用户避免运行时再处理。7. 一套可复现的部署检查清单把上面这些串起来我给出一份实际部署时会逐项核对的清单。这份清单的价值在于每一项都是踩过坑之后加上的不是凭空想的。检查项验证方法常见问题宿主机驱动nvidia-smi有输出装完没重启container-toolkitdocker run --gpus all nvidia/cuda nvidia-smi没配 runtime镜像完整性docker images大小正常tag 丢失依赖可导入容器内import torch, vllm版本不匹配GPU 可见容器内torch.cuda.is_available()没加 --gpus模型路径ls核对分片数量缺分片离线变量HF_HUB_OFFLINE1tokenizer 联网超时共享内存启动加--shm-size8g推理卡死显存参数gpu-memory-utilization合理启动 OOM时区 locale日志时间正确、中文不乱码编码错误这份清单我每次部署都会过一遍能挡掉 90% 的常见问题。剩下的 10% 往往是环境特有的比如特定型号显卡的驱动兼容性、特定内核版本的模块加载问题这些只能具体问题具体分析。8. 关于 MonkeyOCRv2 部署的一点个人体会整套流程走下来我最大的感受是离线部署的难点从来不在模型本身而在环境的一致性。模型代码是确定的但驱动版本、CUDA 版本、Python 依赖版本、Docker 配置这些环境因素组合起来能产生无数种失败方式。所以我的核心策略是固化一切能固化的东西——镜像里装好所有依赖、权重打进镜像或明确挂载、环境变量写死在启动脚本里让运行阶段尽可能少做决策。另一个体会是关于调试方法。内网环境没法联网查资料所以构建阶段就要把日志打全。我习惯在 Dockerfile 里保留详细的构建日志容器启动脚本里也加上关键环境信息的打印CUDA 版本、驱动版本、显存大小、模型路径。这样一旦出问题看日志就能定位不用反复试。最后说个实际的15GB 镜像的构建和迁移确实费时间但这是内网部署的固有成本。与其想办法压缩流程不如把流程标准化、脚本化让每次部署都能一键复现。我现在的做法是把 Dockerfile、构建脚本、导出脚本、内网导入脚本、启动脚本全部放进一个 git 仓库换台机器 clone 下来就能跑省去了大量重复劳动。这套东西跑顺之后再部署新的 OCR 模型或者升级版本基本就是改几个版本号的事。