去年有个交付项目，客户那边的机房和外网完全物理隔离，生产网上既不能下载模型，也不能拉取依赖包。内部选型定的是MonkeyOCRv2做中文识别，最终我把整个OCR服务打成了一个15GB的Docker镜像，通过离线介质导入到三十多台GPU节点上，跑通后顺手做了一轮推理参数调优，单卡吞吐量比默认配置涨了接近一倍。整个流程涉及Docker构建、镜像瘦身、save/load迁移、NVIDIA Container Toolkit配置和显存调优，每一步都有值得记下来的坑。这篇就把我完整的操作记录和排查经验整理出来，给同样需要内网离线部署深度学习服务的同学一个可以直接抄作业的模板。
1. 先想清楚再动手：MonkeyOCRv2离线部署的整体思路
1.1 为什么内网物理隔离下必须用Docker镜像交付
很多项目最初都会问：为什么不直接在目标机器上装Python环境、装CUDA、放模型文件，然后手动启动服务？如果你只有一台机器，这么干没问题。但生产环境往往有几十台GPU服务器，每台手动装一遍很容易出现版本不一致：这台机器是Python 3.9，那台是3.8；这台有cuDNN 8.6，那台可能被别的项目改成了9.x。一旦服务起不来，排查成本极高。
Docker解决的就是“环境一致性”问题。把MonkeyOCRv2所需的整个运行环境固化到一个镜像里，里面包含操作系统的基础库、Python解释器、PyTorch、各种OCR依赖以及模型权重。交付时只需要传输一个镜像文件，目标机器上执行一次docker load，然后docker run就能跑起来。这个方式对内外网隔离的场景尤其合适，因为整个过程不依赖任何网络请求。
MonkeyOCRv2的镜像最终到了15GB，很多不熟悉深度学习部署的同学会觉得很夸张。实际上这个体积非常正常：基础CUDA镜像本身就接近3GB，PyTorch加torchvision、transformers等依赖占2GB左右，再加上模型权重文件、Java或OpenCV等系统库，很容易就超过10GB。镜像大不可怕，怕的是结构混乱导致每层都重复占用空间。后面我会专门说怎么在构建阶段做瘦身。
1.2 15GB镜像从哪里来：基础镜像、模型权重和依赖说明
要理解这个15GB的构成，可以先拆一下我实际用的Dockerfile。基础镜像选择的是nvidia/cuda:11.8-cudnn8-devel-ubuntu20.04，这个镜像自带CUDA运行库和cuDNN，省去在容器里单独配置GPU环境的麻烦。选devel版本而不是runtime版本，是因为MonkeyOCRv2在安装某些依赖时需要编译C扩展，devel版本自带编译器工具链，后面构建能少踩很多坑。
紧接着是Python依赖层。MonkeyOCRv2的核心推理依赖包括PyTorch、torchvision、transformers、opencv-python、Pillow、numpy等。其中PyTorch的CUDA版本安装包就有2GB左右。如果只是CPU推理，镜像可以缩到5GB以内，但我们明确要求GPU加速，所以这部分体积省不掉。
模型权重是另一个大头。MonkeyOCRv2的检测和识别模型加起来约6GB，放在checkpoints/目录下。这里顺便回答一个经常被问到的问题：vLLM或者其他AI服务镜像到底带不带模型？关键看Dockerfile里有没有把模型目录COPY进镜像。有的设计是外挂模型目录，镜像只包含运行环境；有的则像我们这样直接把模型打进镜像，交付时一个包全部搞定。两种方式各有利弊，内网离线场景我更推荐打入镜像，省去单独传模型文件和路径配置的麻烦。
1.3 六步走通的部署路线图
先看整个部署过程的完整链路，后面每一段都会展开说明：
- 在有外网的构建机上编写Dockerfile并构建镜像。
- 做镜像瘦身，清理临时依赖和缓存。
- 使用
docker save导出镜像为压缩tar包。 - 将tar包拷贝到内网环境，执行
docker load导入。 - 配置NVIDIA Container Toolkit，让容器能正常访问GPU。
- 启动服务并针对MonkeyOCRv2推理参数做吞吐量和显存调优。
这个顺序是我经过多次交付后固定下来的。最容易出问题的是第五步，很多节点在导入镜像后才发现容器里调不到GPU，最后又返回去检查驱动和运行时。与其到了现场手忙脚乱，不如在构建机上提前验证好一套参数组合。后续的内容会按照这个路线逐段拆解。
2. 直接可抄的Docker镜像构建流程（含离线导出）
2.1 基础镜像选型和构建机环境准备要点
构建机建议准备一台配置不低于16核CPU、64GB内存、100GB可用磁盘的Linux服务器。磁盘空间要留出余量，因为构建过程中的中间镜像层很容易占掉20GB以上。我最初用40GB磁盘的机器构建，结果在装PyTorch时直接no space left on device，只能重新清理再构建。
基础镜像选型有一个原则：和宿主机GPU驱动兼容。CUDA 11.8镜像对大多数NVIDIA驱动是没问题的，但如果你内网机器驱动版本较老，比如低于525，建议选择CUDA 11.2或者直接问现场运维拿驱动版本号。判断方法也简单：宿主机执行nvidia-smi，看右上角的CUDA Version，镜像的CUDA主版本不要高于这个数字，否则容器里跑模型容易报CUDA driver version is insufficient。
另外需要确认芯片架构。现在不少国产服务器是ARM架构，基础镜像就要换成nvidia/cuda:11.8-cudnn8-devel-ubuntu20.04的arm64版本。如果不确定，可以在构建机上跑uname -m，x86_64对应amd64，aarch64对应arm64。Docker会自动拉取匹配平台，但为了离线交付准确性，建议docker images里确认镜像的ARCH字段。
2.2 Dockerfile写法和分阶段构建示例
我整理了一份简化但结构完整的Dockerfile，实际生产环境可以在此基础上扩展：
ARG BASE_IMAGE=nvidia/cuda:11.8-cudnn8-devel-ubuntu20.04 FROM ${BASE_IMAGE} ENV LANG=C.UTF-8 \ TZ=Asia/Shanghai \ PYTHONUNBUFFERED=1 \ DEBIAN_FRONTEND=noninteractive RUN apt-get update && apt-get install -y --no-install-recommends \ python3.9 python3.9-dev python3-pip cmake build-essential \ libgl1 libglib2.0-0 libtiff5 libjpeg8 libpng16-16 \ && ln -sf /usr/bin/python3.9 /usr/bin/python \ && rm -rf /var/lib/apt/lists/* WORKDIR /app COPY requirements.txt . RUN pip3 install --no-cache-dir -r requirements.txt COPY monkeyocr/ ./monkeyocr/ COPY checkpoints/ ./checkpoints/ RUN groupadd -r ocr && useradd -r -g ocr -m ocruser USER ocruser EXPOSE 8080 CMD ["python3", "-m", "api_server"]requirements.txt里的关键依赖大致是：
torch==1.13.1+cu117 torchvision==0.14.1+cu117 transformers==4.30.0 opencv-python==4.7.0.72 numpy==1.24.3 flask>=2.2注意PyTorch的+cu117后缀代表显卡版，安装时要指定对应的CUDA版本索引，否则pip默认会拉CPU版，虽然镜像体积小了，但GPU推理完全用不上。这个问题我在前期排查看过很多次。
Dockerfile里最后创建了普通用户ocruser，避免容器内所有进程都用root运行。这既是安全习惯，也能防止部分框架在root下因为环境变量问题出幺蛾子。如果你在构建时遇到权限不够，可以先用USER root调试，但最终镜像建议保留非root用户。
2.3 镜像瘦身与构建命令实操
构建命令我一般这样执行：
docker build --network=host -t monkeyocr:v2 .--network=host让构建过程直接使用宿主机的网络栈，在拉取系统包和pip包时更稳定，而且不用额外处理容器内DNS问题。如果你用普通bridge网络且构建机存在DNS设置，构建阶段经常会出现临时解析失败，浪费时间。
瘦身阶段我做了三个动作。第一，在pip install时加上--no-cache-dir，避免pip缓存写进镜像层。第二，apt-get install后用rm -rf /var/lib/apt/lists/*清理包管理器索引。第三，检查是否安装了构建期才需要的工具。如果只是运行模型，cmake和build-essential完全可以不在最终镜像里保留，使用多阶段构建可以彻底解决，下面是个简化思路：
第一阶段用devel镜像完成依赖编译和模型依赖安装；第二阶段从CUDA runtime镜像开始，只把第一阶段生成的site-packages和源码目录拷贝过去。这样最终的15GB可能会进一步降到12GB左右。多阶段构建的代码结构略复杂，但省下来的磁盘和传输时间是很值得的。
构建完成后用docker images确认镜像大小。我这边最终是monkeyocr:v2约15GB。如果你发现某些层很大，可以用docker history查看每一层的体积来源，针对性优化。
2.4 离线交付：docker save导出、传输、load导入与校验
构建完成后的离线交付是整个流程里最容易忽略细节的环节。我一般用管道配合gzip压缩，减小tar包体积：
docker save monkeyocr:v2 | gzip > monkeyocr_v2.tar.gz md5sum monkeyocr_v2.tar.gz > checksum.md5执行完会得到一个类似monkeyocr_v2.tar.gz的文件，实际大小可能在12GB左右，比15GB小是因为gzip压了部分依赖和模型冗余。传输前先把md5值发给现场同事，确保拷贝到内网后文件没有被损坏。这里特别提醒：大文件传输到内网尽量用固态硬盘或者稳定性好的移动介质，不要用普通U盘，容易在中途掉盘导致镜像损坏。
到内网机器上执行导入：
docker load -i monkeyocr_v2.tar.gz docker images | grep monkeyocr如果导入后没有显示镜像名，多半是镜像在save时没有打tag，或者标签被截断。用docker image inspect查一下实际ID，然后重新打tag即可。很多人会在Docker Desktop里问怎么重命名镜像，其实原理和命令行一样，就是docker tag：
docker tag <image-id> monkeyocr:v2另外，如果内网节点很多，逐个load太麻烦，推荐在内网搭一个私有镜像仓库，后面第4.5节会专门讲。不管你打包的是PHP应用、Hadoop集群镜像、Dify这种AI平台镜像，还是MonkeyOCRv2 OCR服务，离线迁移的核心逻辑完全一致，差别只是镜像内容和体积。
3. 容器内GPU调优：从识别慢到吞吐量翻倍
3.1 容器访问GPU的第一前提：NVIDIA Container Toolkit配置
镜像导入后直接docker run启动，容器里大概率看不到GPU。这是因为宿主机还需要装NVIDIA Container Toolkit，让Docker能够把GPU设备和驱动透传到容器内。除非你的Docker版本很老且装了nvidia-docker2，否则现在主流配置都用这套工具链。
配置步骤：
# 安装nvidia-container-toolkit sudo apt-get update sudo apt-get install -y nvidia-container-toolkit # 修改docker配置 sudo nvidia-ctk runtime configure --runtime=docker sudo systemctl restart dockernvidia-ctk runtime configure会自动往/etc/docker/daemon.json里写入nvidia runtime配置。配置完成后启动容器，显式声明GPU资源：
docker run -d --name monkeyocr \ --gpus all \ -e NVIDIA_VISIBLE_DEVICES=0 \ -e NVIDIA_DRIVER_CAPABILITIES=compute,utility \ --shm-size=8g \ -p 8080:8080 \ monkeyocr:v2--shm-size=8g容易被忽略，但它对PyTorch的DataLoader和部分并发读写很重要。默认64MB的共享内存会在批量预处理时频繁报Bus error。进入容器验证GPU：
docker exec -it monkeyocr nvidia-smi能正常打印GPU列表，就说明容器环境没问题。如果宿主机驱动版本在535以上，而镜像内CUDA是11.8，也是可以正常运行的，CUDA小版本兼容通常没问题。
3.2 MonkeyOCRv2关键推理参数整理
GPU通了还得让MonkeyOCRv2真正用起来顺畅。我整理了六个直接影响吞吐量的参数：
第一是batch_size。OCR服务如果每次只处理一张图，GPU利用率通常很低。把请求按批次聚合送入模型，一个batch处理8到16张图，吞吐量能成倍提升。需要注意图片尺寸差异大时，会触发padding，浪费显存，最好在预处理时按比例把所有图缩放到同一宽度。
第二是推理精度。MonkeyOCRv2模型如果支持半精度，可以把模型权重转为FP16：model.half()，推理数据也转成FP16。显存占用大幅下降，速度通常提升40%以上。如果不支持，建议用torch.cuda.amp.autocast()做混合精度推理，只在算子层面自动使用FP16，风险更小。
第三是线程环境变量。容器默认线程数会跟随CPU配额，可以显式设置：
-e OMP_NUM_THREADS=8 \ -e MKL_NUM_THREADS=8 \ -e CUDA_VISIBLE_DEVICES=0线程数不要盲目加到满，建议和物理核心数一致，否则线程切换开销反而拖慢预处理。
第四是显存分配策略。PyTorch默认会给后续张量预分配显存块，频繁启停服务时会看到显存一直不释放。在容器环境里可以设置：
-e PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:128这样显存碎片化问题会缓解很多。
第五是异步预处理。OCR流程里图像解码、归一化、缩放占了不少CPU时间，如果串行处理，GPU会有很多空转。把预处理放到独立线程池，边处理边送入模型，吞吐量还能再涨一截。
第六是模型推理函数的显存清理。每次batch处理完成后调用torch.cuda.empty_cache()，但不要每张图都调，否则会频繁回收显存，反而降低速度。一般每处理完一个批次再调用一次即可。
3.3 我实测的一组参数对比数据
在一台配置为NVIDIA T4、32GB内存的机器上，MonkeyOCRv2默认启动后我记录了几组数据。这里说明一下，实际数值会因GPU型号和图像分辨率不同而变化，但相对趋势可以参考：
| 配置组合 | 吞吐量（张/s） | 单张耗时（ms） | 峰值显存（GiB） |
|---|---|---|---|
| FP32 / batch=1 | 7.8 | 128 | 2.2 |
| FP32 / batch=8 | 16.5 | 60 | 5.4 |
| FP16 / batch=8 | 29.6 | 34 | 4.6 |
| FP16 / batch=16 | 34.2 | 29 | 7.8 |
| FP16 / batch=16 + 异步预处理 | 42.7 | 23 | 8.1 |
从表格可以明显看到，FP16和batch组合带来的提升远比单独调大batch效果好。第一次从默认的FP32 batch=1调到FP16 batch=16，吞吐量已经翻了四倍，再加上异步预处理，整体提升超过五倍。如果还想继续压榨性能，可以考虑TensorRT静态化模型，但构建复杂度会提高不少，离线交付时还要注意TensorRT引擎和GPU型号绑定的问题。
3.4 长期运行稳定性：显存、健康检查与日志
调优后性能上去了，稳定性也得跟上。我一般会给容器设置内存和重启策略：
docker run -d --name monkeyocr \ --gpus all \ --memory=40g \ --shm-size=8g \ --restart unless-stopped \ -e PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:128 \ monkeyocr:v2--memory=40g限制容器总内存，避免Python进程异常占用导致宿主机卡死。--restart unless-stopped让节点宕机后容器自动拉起。
日志方面，建议在Dockerfile里配置Python日志输出到stdout，这样可以用docker logs收集，同时给日志加上按天滚动。如果没有做日志切割，15GB镜像的容器在长期运行后日志文件会涨到很恐怖，影响磁盘和排查效率。
健康检查建议使用 curl 检查/health接口，或者直接docker inspect查看容器状态。我在每个节点上还放了一个定时脚本，每5分钟记录一次nvidia-smi显存占用，连续观察一周就能发现哪一版参数组合会产生显存泄漏。
4. 内网离线部署常见坑与排查速查表
4.1 构建时依赖拉取慢，镜像下载卡住怎么办
很多内网机器构建时不方便直接访问外部仓库，这时候最容易遇到两个问题：基础镜像拉不下来，pip安装包超时。我的经验是，不要在内网做完整构建，而是在有外网的构建机上提前把基础镜像拉好并保存为tar包。比如nvidia/cuda:11.8-cudnn8-devel-ubuntu20.04可以先执行docker pull，再docker save带到内网，后续docker load后就可以直接作为本地镜像使用。
如果只是拉取慢，还可以调整Docker的registry mirror。修改/etc/docker/daemon.json，加入"registry-mirrors": ["https://xxxx.mirror"]，然后重启Docker。但要注意，公共镜像源只能解决一时的下载速度，离线环境下真正的解法还是把所有依赖在构建阶段全部搞定。
pip层面同样可以先在构建机上设置pip源为可访问的PyPI镜像，或者直接把依赖包下载到本地，再COPY进镜像安装。这样离线构建时就不会因为网络超时中断。
4.2 内网load后启动报CUDNN或GLIBC错误
这是离线部署最高频的问题之一。镜像load成功后，docker run启动不了，错误里出现libcudnn.so.8: cannot open shared object file或者GLIBC_2.29 not found。
我采用的排查链路是：先确认镜像基础版本和宿主驱动是否匹配。用docker run --rm --entrypoint /bin/bash monkeyocr:v2 -c "ldd ./monkeyocr/engine.so | grep not found"，能看到缺失的库列表。如果缺libcudnn.so.8，大概率是基础镜像拉错了版本，比如选了cudnn8但实际代码编译时链接的是cudnn9；如果缺GLIBC_2.29，说明基础镜像的Ubuntu版本太老，需要换到nvidia/cuda:11.8-cudnn8-devel-ubuntu20.04或更新版本。
在项目正式交付前，建议先在构建机上把容器完整启动一遍，并执行一次真实图片识别，确认没有动态库缺失再导出镜像。很多人因为赶进度跳过这一步，结果到了内网才发现问题，来回折腾的工时远大于提前验证那几分钟。
4.3 容器里看不到GPU的排查链路
容器内执行nvidia-smi报couldn't communicate with NVIDIA driver，或者提示没有GPU设备，通常不是镜像的问题，而是宿主机环境没有把GPU透传进来。
按顺序排查：
- 宿主机执行
nvidia-smi，确认驱动和GPU本身正常。 - 检查
docker info | grep Runtimes，看有没有nvidia这个runtime。 - 检查
/etc/docker/daemon.json里是否有nvidia runtime配置。 - 执行
docker run --rm --gpus all nvidia/cuda:11.8-base nvidia-smi，测试基础镜像能否访问GPU。 - 如果上面都不行，检查是否在使用非Docker标准运行时，比如Podman或安全容器，它们需要用不同的方式暴露GPU。
如果宿主机是老版本Docker，不支持--gpus参数，就要用--runtime=nvidia启动。这两种方式不能混用，配置错了很容易在容器内看到Unknown runtime specified nvidia错误。
另外还要注意：容器使用的CUDA版本高于宿主机驱动支持的CUDA版本时，也会表现为无法访问GPU。这时候不是容器的问题，而是宿主驱动要升级。
4.4 显存溢出、进程卡死的定位思路
MonkeyOCRv2在高峰并发时很容易出现CUDA out of memory。遇到这个错误，先把batch_size调小，再检查宿主机显存是否被其他进程占用。用fuser -v /dev/nvidia*可以列出当前占用GPU的进程PID，有时候会发现别的容器在后台占了大半显存。
如果进程直接卡死，没有任何日志，可以看dmesg | tail -50，经常能看到NVIDIA相关报错，比如NVRM: Xid异常。这个情况通常和显存过热或供电不足有关，需要联系机房检查散热。软件层面的做法是给容器设置--gpus '"device=0,1"'，避免跨卡访问带来的额外延迟。
调优时如果需要定位是哪一段算子慢，可以临时设置CUDA_LAUNCH_BLOCKING=1，开启后每个CUDA操作都会同步等待，日志能精确定位到卡住的算子。但生产环境千万不要开这个环境变量，否则性能会直线下降。
4.5 自建内网镜像仓库，彻底解决多节点推送问题
当节点数量超过10台以后，逐个docker load已经不是最优方案，我强烈建议在内网搭一个私有镜像仓库。即使内网完全离线，也可以在构建机上先通过docker save把registry:2镜像导入到内网节点，然后运行起来：
docker run -d \ -p 5000:5000 \ -v /data/registry:/var/lib/registry \ --restart=always \ --name registry \ registry:2客户端机器需要在/etc/docker/daemon.json中添加：
{ "insecure-registries": ["registry.internal:5000"] }然后重启Docker，把本地镜像推送上去：
docker tag monkeyocr:v2 registry.internal:5000/monkeyocr:v2 docker push registry.internal:5000/monkeyocr:v2所有节点执行docker pull registry.internal:5000/monkeyocr:v2即可。这样以后有了新版镜像，只需要推一次仓库，所有节点都能拉取。仓库本身可以做简单备份，定期把/data/registry目录打包即可。
这个方案不仅适用于MonkeyOCRv2，PHP应用镜像、Hadoop集群镜像、Dify镜像包，只要走离线交付，都可以套用同一套仓库逻辑。镜像仓库也就成为我在内网环境里的标配组件。
最后说一个我自己的习惯：每次离线交付前，我会先在构建机上把镜像反复跑三轮测试，确认接口返回、识别结果、显存占用都正常后，再用docker save导出并记录md5。镜像到了现场，先在一台备用机上load成功跑通再铺开。这个顺序看起来很保守，但确实帮我避免了很多半夜通宵救火的情况。
