1. 为什么要在内网离线部署 MonkeyOCRv2内网离线部署这件事做过一次就再也不想碰第二次。我这次接到的需求很明确把 MonkeyOCRv2 完整部署到一台没有外网访问权限的 GPU 服务器上所有依赖必须提前打包最终交付一个约 15GB 的 Docker 镜像并且要跑满 GPU 推理性能。听起来就是“打个包、传进去、跑起来”三步但真正动手之后你会发现每一步都有坑在等你。MonkeyOCRv2 是一套面向文档解析的 OCR 推理系统核心能力是把图片或 PDF 里的文字、表格、版面结构识别出来。它依赖的模型权重、推理框架、CUDA 运行时、Python 依赖链加起来体积不小这也是镜像能到 15GB 的原因。内网环境意味着你不能在目标机器上pip install不能docker pull甚至连apt-get update都可能失败。所有东西必须在有网的构建机上准备好然后以镜像或离线包的形式搬进去。这篇文章适合三类人看一是需要在隔离网络环境部署 AI 推理服务的运维或算法工程师二是正在折腾 Docker GPU 组合、被驱动和运行时版本搞到头大的人三是想了解一个完整离线部署项目从构建到调优全流程的技术负责人。我会把构建镜像的每一步、GPU 直通的每一个参数、性能调优的每一个取舍都讲清楚你照着做基本能复现。先说结论性的经验内网离线部署的核心难点不在模型本身而在依赖闭环和运行时一致性。构建机上能跑不代表目标机能跑因为 GPU 驱动版本、CUDA 运行时、Docker 的 NVIDIA 运行时配置这三者必须对齐。我踩过的最大一个坑就是构建机 CUDA 版本比目标机驱动支持的版本高了一档镜像传进去之后容器直接起不来报错信息还特别隐晦。2. 部署方案的整体设计与选型考量2.1 镜像分层策略为什么最终是 15GB15GB 这个体积不是随便来的拆开看大致是这样分布的基础 CUDA 运行时镜像约 3GBPython 及科学计算依赖约 2GBPyTorch 及 CUDA 扩展约 3GBMonkeyOCRv2 模型权重约 5GB剩下的 2GB 是 OCR 相关的预处理模型、字体库、系统工具和缓存。理解这个分布很重要因为它决定了你的优化方向——模型权重是刚需不能砍能优化的是基础镜像和依赖层。我采用的策略是多阶段构建 分层缓存。第一阶段用完整的 CUDA devel 镜像编译需要编译的依赖第二阶段只拷贝运行时产物到精简的 runtime 镜像。这样能把编译工具链gcc、nvcc、头文件从最终镜像里剔除省下大概 2 到 3GB。但要注意MonkeyOCRv2 有些依赖在运行时仍需要动态链接库拷贝的时候不能只拷.so主文件符号链接和依赖链都要带上否则运行时报libxxx.so not found。提示多阶段构建时用ldd检查每个二进制文件的动态库依赖确保运行时镜像里一个都不缺。我习惯在第二阶段镜像里跑一遍ldd $(which python)和模型加载脚本确认没有 missing。2.2 推理框架选型原生 PyTorch 还是 vLLMMonkeyOCRv2 的推理后端有两条路可走直接用 PyTorch 加载模型跑 forward或者用 vLLM 做推理加速。这两者的取舍我纠结了很久。vLLM 的优势在于 PagedAttention 和连续批处理对高并发场景吞吐提升明显但它的代价是额外的依赖体积、对模型结构的适配要求以及版本兼容的脆弱性。我最终的选择是主链路用 PyTorch 保证稳定旁路预留 vLLM 接口。原因是内网环境一旦出问题排查成本极高vLLM 的版本和 CUDA、PyTorch 之间的兼容矩阵太敏感稍有不慎就是一堆编译错误。而 MonkeyOCRv2 的 OCR 推理本身 batch 不大PyTorch 原生推理在单卡 RTX 4060 Laptop 这个级别上已经够用。如果你的场景是批量文档高并发解析那 vLLM 值得上但要提前把版本矩阵锁死。关于 vLLM 的版本选择社区里讨论比较多的是vllm/vllm-openai系列镜像。这类镜像的好处是开箱即用坏处是体积大且定制困难。内网离线场景我更倾向于自己构建把 vLLM 作为可选依赖装进镜像用环境变量控制是否启用。2.3 GPU 直通方案nvidia-container-toolkit 的配置要点Docker 容器要用 GPU靠的是 NVIDIA Container Toolkit。它的原理是在容器启动时把宿主机的 GPU 设备节点、驱动库、CUDA 运行时注入容器。这里有个关键认知容器里不需要装完整的 NVIDIA 驱动只需要驱动暴露出来的用户态库。驱动是宿主机的容器共享。配置流程是安装nvidia-container-toolkit然后配置 Docker 的 runtime。很多人卡在docker: Error response from daemon: could not select device driver with capabilities: [[gpu]]这个报错上根本原因就是 toolkit 装了但 Docker 没重启或者 daemon.json 没配对。我后面会给出完整的配置和验证步骤。3. 构建环境准备与依赖闭环3.1 构建机与目标机的版本对齐这一步是内网部署的命门。构建机和目标机的以下版本必须对齐或兼容GPU 驱动版本、CUDA 驱动 API 版本、Docker 版本、NVIDIA Container Toolkit 版本。其中最容易出问题的是驱动和 CUDA 的兼容关系。CUDA 有一个“驱动 API 版本”的概念宿主机驱动支持的 CUDA 版本是有上限的。比如驱动版本 535 支持到 CUDA 12.2你如果在构建机用了 CUDA 12.4 的镜像拿到驱动 535 的目标机上就会报CUDA driver version is insufficient for CUDA runtime version。我的做法是先上目标机跑nvidia-smi记下右上角的 CUDA Version然后构建机的 CUDA 版本不超过这个值。检查项命令目标机要求驱动版本nvidia-smi记录版本号驱动支持 CUDA 上限nvidia-smi右上角构建镜像 CUDA 不超过此值Docker 版本docker --version建议 20.10 以上Toolkit 版本nvidia-container-cli --version与 Docker 兼容磁盘空间df -h镜像 15GB预留 40GB 以上注意目标机如果是笔记本双显卡比如 Intel UHD NVIDIA RTX 4060 Laptop要确认 NVIDIA 独显处于启用状态且没有被电源管理策略休眠。有些笔记本默认用核显输出独显在空闲时会下电容器启动瞬间可能枚举不到 GPU。3.2 离线依赖包的收集与校验构建机有网目标机没网所以所有依赖必须在构建阶段固化进镜像。我的原则是能进镜像的都进镜像实在进不去的做成离线包。Python 依赖用pip download下载 wheel 到本地目录然后在 Dockerfile 里用pip install --no-index --find-links安装。系统依赖用apt-get download或者直接在有网的构建阶段装好。这里有个细节pip download默认只下载当前平台的 wheel如果构建机和目标机架构不同比如构建机是 x86目标机是 ARM必须加--platform参数。我这次两边都是 x86_64省了这一步但你要注意。模型权重的获取也要提前。MonkeyOCRv2 的权重文件通常托管在模型仓库上构建阶段下载好放进镜像。下载完一定要校验哈希内网传输出错的话模型加载会报各种奇怪的 shape mismatch排查起来很痛苦。# 下载 Python 依赖到本地目录 pip download -r requirements.txt -d ./offline_packages --platform manylinux2014_x86_64 --only-binary:all: # 校验模型权重哈希 sha256sum monkeyocrv2_weights.bin3.3 Dockerfile 的分层编写Dockerfile 的写法直接决定镜像体积和构建速度。我的分层逻辑是变化频率低的放底层变化频率高的放上层。基础 CUDA 镜像、系统依赖、Python 依赖、模型权重、应用代码从下到上依次排列。这样改应用代码时不用重装依赖构建快很多。# 第一阶段构建依赖 FROM nvidia/cuda:12.2.0-devel-ubuntu22.04 AS builder RUN apt-get update apt-get install -y python3-pip python3-dev build-essential COPY requirements.txt . RUN pip download -r requirements.txt -d /wheels # 第二阶段运行时 FROM nvidia/cuda:12.2.0-runtime-ubuntu22.04 RUN apt-get update apt-get install -y python3 python3-pip libgl1 libglib2.0-0 COPY --frombuilder /wheels /wheels RUN pip install --no-index --find-links/wheels -r /wheels/requirements.txt COPY monkeyocrv2_weights /app/weights COPY app /app WORKDIR /app CMD [python3, serve.py]libgl1和libglib2.0-0这两个系统库是 OpenCV 的运行时依赖OCR 项目几乎必装。我见过太多人镜像构建成功但一跑就报ImportError: libGL.so.1就是漏了这两个。4. GPU 直通配置与容器运行时调优4.1 nvidia-container-toolkit 安装与验证在目标机上Toolkit 的安装是 GPU 直通的前提。离线环境下你需要提前下载好 deb 包。安装完成后配置 Docker 的 runtime# 配置 Docker 使用 nvidia runtime sudo nvidia-ctk runtime configure --runtimedocker sudo systemctl restart docker # 验证 GPU 是否可被容器识别 docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi最后这条验证命令非常关键。如果它能正常输出 GPU 信息说明直通链路通了如果报could not select device driver检查 daemon.json 里有没有runtimes: {nvidia: {...}}这段配置。我遇到过配置写对了但 Docker 没重启的情况白白排查了半小时。4.2 容器启动参数与 GPU 资源分配启动容器时的 GPU 参数决定了资源怎么分。--gpus all把所有 GPU 给容器--gpus device0指定某一块。对于多卡机器我建议显式指定设备号避免容器抢占其他任务的卡。docker run -d \ --gpus device0 \ --shm-size8g \ -p 8080:8080 \ -v /data/models:/app/weights:ro \ --name monkeyocr \ monkeyocrv2:offline--shm-size这个参数容易被忽略。Docker 默认的共享内存是 64MBPyTorch 的 DataLoader 多进程加载数据时会用共享内存64MB 根本不够会报Bus error或者DataLoader worker killed。OCR 项目处理大图时尤其明显我一般直接给 8GB。4.3 显存与算力的实际调优RTX 4060 Laptop 的显存是 8GB这个容量跑 MonkeyOCRv2 需要精打细算。我的调优思路是先测出单张图推理的峰值显存再决定 batch size 和是否启用 FP16。实测下来FP32 精度下单张 A4 文档图推理峰值约 2.5GBFP16 能降到 1.6GB 左右。8GB 显存扣掉系统和框架占用留给推理的大概 6GB所以 FP16 下 batch size 可以到 3FP32 只能到 2。如果你的文档图分辨率更高这个数字还要往下调。# 启用 FP16 推理 model model.half().cuda() with torch.no_grad(): output model(input_tensor.half().cuda())提示FP16 对 OCR 精度的影响通常很小但表格识别这种对细节敏感的任务建议先做精度对比测试。我测过一批文档FP16 和 FP32 的字符识别准确率差异在 0.3% 以内可以接受。5. 常见问题排查与避坑实录5.1 GPU 相关报错的排查路径GPU 问题排查有一套固定路径按顺序走能覆盖 90% 的情况。第一步nvidia-smi确认宿主机驱动正常第二步docker run --gpus all确认直通正常第三步容器内nvidia-smi确认运行时注入正常第四步 Python 里torch.cuda.is_available()确认框架识别正常。哪一步断了就查哪一步。报错信息可能原因解决方向could not select device driverToolkit 未配置或 Docker 未重启检查 daemon.json 并重启CUDA driver version insufficient镜像 CUDA 高于驱动支持降级镜像 CUDA 版本no CUDA-capable device detected容器未加 --gpus 参数补上 GPU 参数out of memory显存不足降 batch size 或启用 FP16libcudart.so not found运行时库缺失检查 LD_LIBRARY_PATH5.2 镜像传输与加载的注意事项15GB 的镜像传输本身就是个问题。docker save出来的 tar 包压缩后大概 6 到 8GB用移动硬盘拷贝是最稳的方式。传输完docker load之前先校验 tar 包的哈希传输损坏的话 load 会报unexpected EOF。# 构建机导出 docker save monkeyocrv2:offline | gzip monkeyocrv2_offline.tar.gz sha256sum monkeyocrv2_offline.tar.gz # 目标机校验后加载 sha256sum -c monkeyocrv2_offline.tar.gz.sha256 docker load monkeyocrv2_offline.tar.gz我踩过的坑是导出时没加gziptar 包 15GB拷贝花了两个小时加载又花了半小时。加上压缩后体积减半时间省一大截。5.3 内网环境下的依赖缺失补救即使准备再充分内网部署也难免遇到缺依赖。我的补救策略是预留一个离线包目录把常用的 wheel 和 deb 包多下一些放进去容器里挂载这个目录缺什么临时装。比如pip install --no-index --find-links/offline_packages some_package。另外Python 的site-packages里有些包是纯 Python 的可以直接从构建机拷贝到目标机的容器里。但带 C 扩展的包不行架构和 ABI 必须匹配。这个边界要分清楚否则拷过去也是白搭。6. 性能验证与持续维护6.1 推理性能的基准测试方法部署完不算完得验证性能。我的基准测试方法是准备 100 张典型文档图跑三轮取平均记录单张耗时、吞吐量、峰值显存。这样得到的数字才有参考价值单跑一张的波动太大。import time, torch # 预热 for _ in range(5): model(warmup_input) torch.cuda.synchronize() start time.time() for img in test_images: model(img) torch.cuda.synchronize() elapsed time.time() - start print(f平均单张耗时: {elapsed/len(test_images)*1000:.1f}ms) print(f峰值显存: {torch.cuda.max_memory_allocated()/1024**3:.2f}GB)预热这一步不能省。CUDA 的 kernel 首次执行有编译和加载开销不预热的话第一张图的耗时会虚高好几倍测出来的数据没有意义。6.2 镜像更新与版本管理内网部署的镜像更新是个持续问题。我的做法是给镜像打上日期和版本标签比如monkeyocrv2:20250115-v1同时维护一个变更日志记录每次更新改了什么。这样出问题能快速回滚到上一个可用版本。模型权重和代码分离挂载也是个好习惯。权重用 volume 挂载更新模型时不用重新构建镜像直接替换权重文件重启容器就行。代码同理挂载进去改完重启即可。这样镜像本身可以保持相对稳定只在依赖变化时才重建。6.3 长期运行的稳定性观察容器跑起来之后要观察一段时间。我重点关注三个指标显存是否持续增长内存泄漏、推理耗时是否漂移性能衰减、GPU 温度是否过高散热问题。笔记本 GPU 尤其要注意散热长时间满载容易触发降频推理速度会掉。如果发现显存持续增长大概率是推理代码里有 tensor 没释放或者缓存没清理。PyTorch 的torch.cuda.empty_cache()可以手动清理缓存但治标不治本还是要找到泄漏点。我遇到过一次是日志里把每张图的中间特征存下来了跑久了显存就爆了改成只存统计量就好了。这套流程走下来MonkeyOCRv2 在内网 RTX 4060 Laptop 上跑得挺稳单张 A4 文档 FP16 推理大概 400 到 600 毫秒批量处理吞吐能到每秒 2 到 3 张。对于内网文档解析这个场景够用了。最后分享一个小技巧构建镜像时把pip的缓存目录也清掉RUN pip install ... rm -rf ~/.cache/pip能再省几百 MB别小看这点空间内网传输时每一 MB 都是时间。