MonkeyOCRv2 的离线部署排期定下来之后我第一反应是这次和之前所有部署任务都不一样。内网隔离的环境里没有外网下载通道15GB 的 Docker 镜像不能靠一条 pull 命令解决GPU 服务器还要过驱动这一关。这篇文章把整个过程的思路、命令、坑位都留个档也给你一个可以直接照着走的参考路径。如果你正好也要在隔离网络里部署 OCR 服务或者手里有一个体积夸张的 Docker 镜像不知道怎么下手这篇文章大概率能帮你省几个通宵。继续之前先交代一下背景这台目标服务器没有绑定外网操作系统是 Ubuntu 20.04机器上有 Intel 核显和 NVIDIA RTX 4060 Laptop GPU 双显卡。MonkeyOCRv2 是我们内部迭代的第二版 OCR 服务负责文档识别、表格结构还原和关键字段抽取模型权重加推理框架加起来很重。为了保证目标环境一次启动成功我选择了 Docker 作为交付介质把整个运行环境锁进镜像里。下面按我的实际操作顺序一条一条说。1. 项目拆解15GB 镜像到底装了什么1.1 MonkeyOCRv2 定位与部署难点MonkeyOCRv2 和普通 OCR 库最大的区别在于它不是一个“输入图片输出文字”的单点工具而是一整套文档解析管线。处理一张 PDF 或高清扫描图通常要经过图像预处理、版面检测、文本行检测、文本识别、表格结构恢复和字段抽取六个环节。其中至少四个环节跑的是神经网络模型两个环节依赖传统图像处理算法。这意味着镜像里必须同时具备深度学习推理框架、传统 CV 库、模型权重和多语言字体文件任何一个环节缺失线上都会以非常难查的方式报错。离线部署的难点在于“不可增量修复”。联网环境下缺一个库可以随手pip install内网环境里每缺一个包就要重新走一遍构建、传输、加载的流程单次成本几十倍上升。所以这个项目从一开始就定了一个原则构建镜像时把所有运行时依赖全部冻结宁可镜像大一点也不能上线后缺文件。15GB 这个数字不是设计目标而是把所有依赖收全之后的真实重量。1.2 镜像体积构成拆解我构建完镜像之后用docker history和du逐层拆解过体积构成。15GB 分布大概是这样的GPU 基础镜像解压后接近 2.8GBPython 环境和系统库约 1.2GBPyTorch、CUDA 运行时库和 cuDNN 约 3.5GB检测识别模型权重和配套资源约 4GB中文字体、图像处理资源、日志组件等约 800MB剩余的是推理服务代码、静态资源和构建过程中残留的包。可以看出来模型权重和深度学习框架是大头这两块几乎动不了能优化的是基础镜像选型和系统依赖。很多人看到 15GB 第一反应是“太大了”但 OCR 场景其实属于“重依赖”业务。对比一下纯 CPU 版镜像通常能做到 2GB 左右GPU 版体积大是因为必须携带 CUDA 运行时。这里有个取舍如果内网 GPU 驱动可以完全匹配宿主机 CUDA 版本理论上可以依赖宿主机的 CUDA 库做瘦身但这样交付物和环境强耦合失去一致性保证。对于交付到隔离环境的场景我倾向于把运行库打进镜像规避“换一台机器就崩”的风险。1.3 为什么坚持用 Docker 交付有人问过为什么不直接把 conda 环境打个包传进去跑我的回答是conda 环境对系统库的隔离不够彻底而且解压大规模环境包时容易因为路径、权限问题失败。Docker 镜像的核心优势是分层和一次性校验。镜像加载完成后docker run起来是什么样和构建时就是一模一样操作系统层面的差异被完全屏蔽。对于要在内网长期运行的服务这种可复现性比节省几个 GB 空间重要得多。另一个实际好处是回滚。每次迭代构建新镜像时旧镜像还留在仓库里出问题一条命令切回去。之前 v1 用的是裸机 Python 环境部署一次依赖升级把生产环境搞挂之后我们花了半天才恢复。Docker 化之后这种事情基本不再发生。2. GPU 环境准备驱动和 NVIDIA Container Toolkit2.1 先搞清楚显卡到底是谁内网服务器的显卡情况需要先确认。登录服务器后先跑lspci | grep -i vga看显卡型号再用nvidia-smi看驱动状态。那台机器比较特殊同时有 Intel UHD Graphics 和 NVIDIA RTX 4060 Laptop GPUnvidia-smi输出里能看到两块显卡的完整状态。双显卡环境下要注意的是容器里默认能识别的显存来自 NVIDIA如果程序跑在了核显对应的渲染设备上会出现“程序能启动但极其卡慢”的情况。驱动版本也有讲究。nvidia-smi第一行会显示 Driver Version 和 CUDA Version这两个值决定了容器里能用的 CUDA 上限。比如驱动支持的 CUDA 版本是 12.1那容器里无论装多新的 CUDA最终执行的 runtime 都会被驱动层约束。我的经验是先看宿主机驱动再定镜像里的 CUDA 版本顺序不能反。否则会出现“容器内程序说 GPU 不可用宿主机明明有显卡”的诡异现象。2.2 离线安装 nvidia-container-toolkitDocker 本身不直接访问显卡它靠 NVIDIA Container Toolkit 把宿主机驱动映射进容器。这个工具离线安装稍麻烦它有几个依赖包光装主包会提示缺少 libnvidia-container1。我在外网机器上用yumdownloader --resolve或者对应的apt download把所有依赖包拉齐传进内网后逐个安装顺序是先装依赖再装主包。安装完成后验证方式很简单跑一段官方测试容器确认docker run --gpus all能识别显卡。如果没有官方镜像可以临时跑一个 python:3.9-slim 容器在里面执行python -c import torch; print(torch.cuda.is_available())。不过这个验证需要镜像里已经有 PyTorch实际操作中我是等镜像构建完一起验证的。需要注意装完 toolkit 之后如果 docker 服务不是在装 toolkit 之前安装的可能需要重启 docker 服务让配置生效。2.3 驱动、CUDA、PyTorch 版本匹配这一块有很多人踩坑。版本匹配不是“越高越好”而是要围绕宿主机驱动支持的 CUDA 版本选择。原则是镜像里的 CUDA 主版本号不能高于宿主机驱动支持的最大 CUDA 版本号。打个比方宿主机驱动支持 CUDA 12.1那么镜像里用 CUDA 11.8 或 12.1 都可以但用 CUDA 12.2 就可能跑不起来。实际这个项目我选了 CUDA 11.8理由有两条。一是 PyTorch 2.0.1 对 cu118 的 wheel 支持最成熟依赖冲突少二是 cu118 镜像在 Ubuntu 20.04 上兼容性极好官方基础镜像体积也相对稳定。我把常用匹配关系整理成一张表方便后面的人查宿主机驱动最大 CUDA 版本推荐镜像 CUDA对应的 PyTorch 版本驱动 ≥ 525CUDA 12.0/12.112.1torch 2.1驱动 ≥ 520CUDA 11.811.8torch 2.0.x驱动 ≥ 470CUDA 11.411.3/11.4torch 1.12~1.13驱动 ≥ 450CUDA 11.011.0torch 1.7~1.9上面这张表不是绝对的驱动版本有向下兼容能力新版驱动通常能跑旧版 CUDA 应用反过来不行。所以稳妥路线是驱动选较新版本镜像里 CUDA 选偏旧稳定版本。另外NVIDIA 的驱动下载需要注册和登录离线环境建议提前在网上准备好对应版本的 .run 文件或 deb/rpm 包包找不到时也可以直接让机器厂商提供。3. 镜像构建实战从 Dockerfile 到 15GB 交付物3.1 基础镜像怎么选devel 还是 runtime构建 GPU 镜像的第一步是选择基础镜像。NVIDIA 官方提供了很多标签常见的有nvidia/cuda:11.8.0-cudnn8-devel-ubuntu20.04和nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu20.04。devel 镜像包含头文件、编译器和完整的 CUDA 工具链体积比 runtime 大不少runtime 镜像只包含运行深度学习应用所需的库文件体积更小。MonkeyOCRv2 的推理服务不涉及自定义 CUDA kernel 编译唯一需要编译的场景是安装某些需要本地编译的 Python 包比如部分 opencv-python 头文件。所以最终选择 runtime 镜像作为基础层Python 依赖里如果遇到必须编译的包就提前在外网构建一个 wheel带进内网安装避免在目标机器上现场编译。这一步直接省掉了约 1.5GB 到 2GB 的体积。如果你需要在容器里临时调试 C/CUDA 算子或者需要编译 PyTorch 自定义扩展那就乖乖用 devel 镜像。不要为了省体积选了 runtime结果发现算子编译报缺头文件又得重新构建反而更耗时。3.2 Dockerfile 的几个关键细节直接放一份我实践下来可用的 Dockerfile 骨架注释里写了关键原因FROM nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu20.04 ENV DEBIAN_FRONTENDnoninteractive \ LANGC.UTF-8 \ LC_ALLC.UTF-8 \ TZAsia/Shanghai RUN apt-get update apt-get install -y --no-install-recommends \ python3.9 python3.9-dev python3-pip libglib2.0-0 libgl1-mesa-glx \ libgomp1 libsm6 libxext6 libxrender1 fonts-noto-cjk curl \ rm -rf /var/lib/apt/lists/* RUN mkdir -p /app/models /app/weights /app/logs COPY requirements.txt /tmp/requirements.txt COPY wheels /tmp/wheels RUN pip3 install --no-cache-dir --no-index --find-links/tmp/wheels \ -r /tmp/requirements.txt COPY ./app /app COPY ./weights /app/weights WORKDIR /app EXPOSE 8080 CMD [uvicorn, main:app, --host, 0.0.0.0, --port, 8080]这份 Dockerfile 里有几个容易被忽略但很重要的点。第一--no-install-recommends必须加它避免 apt 把一堆用不到的推荐包装进镜像。第二libgl1-mesa-glx和libglib2.0-0是 OpenCV 的图像处理依赖少装一个会出现“cv2.imread 能导入但一调用就崩”的经典问题。第三fonts-noto-cjk是中文识别后渲染必需的如果你的服务不需要画框和输出可视化结果可以省掉但 OCR 服务基本都会用到。第四pip 安装用了--no-index --find-links/tmp/wheels这是离线安装的标准姿势把所有 wheel 都放在本地目录不走网络。3.3 离线依赖收集pip download 的正确用法内网环境没有 PyPI所有依赖必须在外网机器上提前下载成 wheel 文件。我用的是 pip download 而不是直接 pip install因为前者适合批量收集依赖包。基本命令pip download -r requirements.txt \ -d /data/wheels \ --platform manylinux2014_x86_64 \ --only-binary:all:这里有个技巧--platform manylinux2014_x86_64和--only-binary:all:的意思是不进行本地 Python 环境的源码编译直接下载可用的二进制 wheel。很多人在这一步偷懒直接pip download结果在内网 pip install 的时候跑到源码编译缺 GCC 缺头文件卡在某个包上半天动不了。如果某个包没有对应平台的 wheel就要提前在兼容环境里把它构建成 wheel再放进 wheels 目录。PyTorch 的 GPU wheel 比较特殊它不在默认 PyPI 源里而是在官方指定的 CUDA 索引地址里。下载时记得在命令行里额外指定索引地址否则装到的可能是 CPU 版。CPU 版 PyTorch 在 GPU 镜像里也能装上但 torch.cuda.is_available() 会一直返回 False这是非常多见却非常隐蔽的错误。3.4 15GB 如何瘦身能省的与不能省的15GB 镜像能不能更小能但要分清楚哪些不能省。模型权重是 OCR 服务的大脑绝对不能省CUDA 库是 GPU 推理的根基绝对不能省。能省的是这几块apt 和 pip 的缓存文件、临时编译产物、不需要的 CUDA 工具链组件、调试符号文件。实际操作中我用三个手段完成了大约 2GB 的瘦身。第一构建完成后用docker export导出容器文件系统过滤掉__pycache__、.pyc和日志文件再重新docker import成镜像。这个方法很暴力但很有效能去掉大量 Python 缓存。第二从基础镜像切到 runtime第三模型文件单独从镜像里拆出去放到宿主机目录挂载进容器。最后一步对镜像体积的影响最明显因为模型权重和配套资源是最大的单一文件块。但别忘了拆分挂载也意味着模型的版本和镜像分离了。如果内网只有一台服务器且模型更新频繁拆分是划算的如果是多台机器要统一部署把权重打进镜像反而省事传一次镜像就完事。这个取舍我在后面还会展开讲。4. 内网离线传输与部署全流程4.1 docker save、压缩与分割传输镜像构建完成后第一件事是用docker save导出。我用的命令是docker save monkeyocr:v2 | gzip monkeyocr_v2.tar.gzgzip 压缩对镜像里的文本文件、Python 源码效果很好实测下来 15GB 的镜像能压到 8GB 左右。不过大文件拷贝有风险我一般会先split切成 2GB 一段传完再合并split -b 2G monkeyocr_v2.tar.gz monkeyocr_v2_part_ cat monkeyocr_v2_part_* monkeyocr_v2.tar.gz分割传输最大的好处不是绕过某个限制而是便于校验。每一段传完都可以对比md5sum或sha256sum哪一段损坏就重传哪一段不用整个文件重新来一遍。我见过有人一次性传 8GB 的文件传到 95% 的时候网络断开又得从头开始分割传输能避免这种悲剧。传到内网后加载命令是docker load -i monkeyocr_v2.tar.gz docker imagesdocker load会保留构建时的镜像名和标签正常情况下docker images能看到monkeyocr:v2。如果看不到或者名字不对说明 save 时用了不同的 tag后面docker run时改用实际的镜像 ID 就行。4.2 内网镜像仓库还是文件传输如果你的目标内网有多台服务器每台都要部署这个服务那用docker save传一次镜像再逐台 load 的效率很低。更合理的方案是在内网搭一个私有 Docker Registry把镜像 push 进去其他机器直接docker pull。内网部署一个 Registry 本身很简单docker run -d -p 5000:5000 --name registry \ -v /data/registry:/var/lib/registry \ registry:2然后给镜像打上内网仓库地址的 tagdocker tag monkeyocr:v2 192.168.10.20:5000/monkeyocr:v2 docker push 192.168.10.20:5000/monkeyocr:v2其他机器上配置一下 docker daemon 的insecure-registries把192.168.10.20:5000加入允许列表然后就能正常 pull 了。Registry 的好处是省去多次手工 load而且镜像还带版本管理但要记得 Registry 本身挂了之后所有机器都没法拉新镜像所以生产环境最好给存储目录做备份。4.3 启动容器与 GPU 挂载参数镜像 load 到内网之后启动容器是关键时刻。我用的启动命令docker run -d --name monkeyocr-v2 \ --gpus all \ --shm-size4g \ -p 8080:8080 \ -e NVIDIA_VISIBLE_DEVICESall \ -e CUDA_VISIBLE_DEVICES1 \ -v /data/models:/app/weights:ro \ --restartalways \ monkeyocr:v2这里几个参数都是血泪经验换来的。--gpus all是让容器能访问宿主机显卡的关键参数没有它容器里 torch.cuda.is_available() 永远是 False。--shm-size4g是很多 PyTorch DataLoader 报错“Bus error”的元凶Docker 默认共享内存只有 64MB多进程数据加载稍微一放量就爆OCR 这种大量图像预处理的场景尤其容易触发。-e CUDA_VISIBLE_DEVICES1在双显卡机器上是必须的因为这台机器有 Intel 核显和 NVIDIA 独显如果不指定一些框架可能自动识别到错误的 GPU 设备导致推理极度缓慢。启动之后用docker logs看启动日志再docker exec -it monkeyocr-v2 bash进入容器确认 GPU 状态。容器内执行nvidia-smi如果能看到和宿主机一样的显卡信息说明 Docker 和 GPU 打通了。4.4 部署后的 OCR 服务验证部署完不能只看进程活着必须做功能验证。我一般会准备一组测试图片分别是印刷体文档、手写体片段、带表格的复杂版面、倾斜的拍照件。每种图片都调一遍 OCR 接口对比识别结果的字符级准召率。之前有一次就是只验证了正常文档上线后才发现表格结构恢复模块没被正确加载导致所有表格类单据全部输出异常。验证接口响应时间的上限也要看。OCR 服务首次请求通常比后续请求慢很多因为模型要完成初始化加载。我一般先跑一次“预热请求”再统计稳定后的延迟不然拿首次请求的数据做性能评估会被带偏。这一步看似简单但很多人忽略往往会得出“部署后性能极差”的错误结论。5. GPU 调优从能用变成好用5.1 先用工具看清楚 GPU 在干什么调优的第一步不是调参数而是搞清楚 GPU 到底在忙什么。我常用的三个工具是nvidia-smi、nvidia-smi dmon和nvidia-smi --query-gpu。nvidia-smi看静态状态dmon一秒钟刷一帧看实时利用率--query-gpu适合脚本化采集数据。在调优之初我发现一个现象GPU 利用率长期不到 30%但显存占用已经很高。这说明模型已经加载进显存但计算并没有满负荷。进一步用nsys profile看时间线发现大部分时间消耗在图像预处理和后处理上——图片解码、缩放、归一化都在 CPU 上跑GPU 在等数据。这是 OCR 服务很典型的瓶颈模式模型小、数据预处理重算力喂不饱。RTX 4060 Laptop GPU 虽然是移动版算力并不弱但 CPU 侧一旦成为瓶颈GPU 就闲在那里数显存。5.2 吞吐优化batch 与并发针对 CPU 瓶颈我做了三件事。第一增大预处理阶段的num_workers从默认 0 改为 4 到 8让图像解码和缩放并行跑第二用 GPU 解码替代 CPU 解码不过这项改造依赖 libnvjpeg在内网环境下要提前确认库文件是否齐全第三把单张推理改成 batch 推理一次处理多张图片摊薄 GPU kernel 启动开销。第三点要注意的是OCR 的 batch 不等同于深度学习的 image batch。OCR 管线里每个环节的 batch 策略不一样文本行检测模型可以把整张图作为一个 batch识别模型则可以把同一批图片里裁出的多个文本行拼成一个 batch。我最终实现的是识别阶段动态 batch用一个小队列攒住待识别的文本行达到 32 条或等待 30ms 就触发一次推理。实测吞吐从每秒 3 张提升到每秒 9 张左右单批次处理时间反而因为 GPU 利用率上去了而下降。5.3 半精度与显存管理GPU 调优的另一个杠杆是精度格式。模型权重从 FP32 换成 FP16 之后显存占用几乎减半推理速度也有明显提升。MonkeyOCRv2 的识别模型对精度不敏感FP16 下识别准确率和 FP32 基本一致这个结论是我分别跑完 500 张测试图统计出来的。如果你的模型对精度敏感可以只对部分算子做 autocastPyTorch 里用torch.cuda.amp.autocast包住 forward 阶段风险更小。不过半精度也不是完全没有代价。FP16 的数值范围有限如果模型里有特别大的激活值或梯度可能出现数值溢出常见表现是输出 NaN。我建议在切半精度之后重新跑一遍回归测试集重点看边界案例的识别结果不要只看准确率数字没掉就觉得安全。另外内网环境的驱动未必支持 FP16 加速老一点架构或驱动版本可能导致 FP16 反而更慢这个要用nvidia-smi --query-gpucompute_cap确认算力版本。5.4 调优前后的实测数据我把核心指标整理成表方便你预判调优收益指标调优前调优后GPU 利用率约 28%约 82%单张推理延迟GPU 侧28ms18ms端到端单张耗时含预处理320ms110ms吞吐并发条件下约 3 张/秒约 9 张/秒显存占用4.1GB2.4GB可以看到端到端耗时的下降幅度明显大于 GPU 侧推理耗时的下降幅度这正好说明 CPU 侧预处理才是原始瓶颈。调优不只是把 GPU 跑满而是让整个管线不卡在任何环节上。很多人在这一步只盯着 GPU 利用率结果把 batch 调得非常大GPU 是满了但单张延迟飙升整体体验反而更差。调优要盯着业务指标延迟、吞吐而不是单纯盯着硬件指标。6. 常见问题与排查实录6.1 典型报错与排查思路离线部署遇到的问题基本都是“环境相关”的比网上能搜到的问题更难排查因为报错信息往往不直接。我挑几个最有代表性的说一说。第一个是“CUDA driver version is insufficient for CUDA runtime version”。这个错误的意思是容器里的 CUDA 版本比宿主机驱动支持的高。排查方法是先看宿主机的nvidia-smi里的 CUDA 版本再对比 docker 镜像里的 CUDA 版本。如果宿主机驱动确实偏低要么换一个更低的 CUDA 基础镜像重新构建要么在内网升级驱动。升级驱动要谨慎最好先在测试机上验证因为驱动升级失败会导致整个 GPU 不可用。第二个是“docker: Error response from daemon: could not select device driver with capabilities: [[gpu]]”。这个错误基本可以断定是 nvidia-container-toolkit 没装好或者 Docker 服务没重启。重装 toolkit 后重启 docker 服务再跑一次docker run --rm --gpus all验证。第三个是容器起来了但程序一直报显存不足。首先要确认是不是别的容器占用了显存用nvidia-smi看进程列表其次确认容器里 CUDA 版本有没有和驱动错配错配会导致程序申请显存失败最后看有没有必要减小 batch 或者开启内存换页。6.2 离线部署避坑速查表我整理了一张速查表覆盖离线部署最常见的坑症状大概率原因处理方式torch.cuda.is_available() 为 False镜像里装的是 CPU 版 PyTorch确认 wheel 来自 cu118 索引地址docker run --gpus all 报错未安装 nvidia-container-toolkit安装并重启 docker加载模型后首次推理极慢模型初始化/预热未完成启动后先跑一次预热请求容器内 nvidia-smi 报错驱动版本过低或驱动未加载检查宿主机驱动状态多进程 DataLoader 报 Bus error--shm-size 默认太小加 --shm-size4g中文识别乱码缺少中文字体安装 fonts-noto-cjkOCR 接口访问 502服务启动失败或依赖缺失docker logs 查看详细日志这张表没法覆盖所有情况但覆盖了我在这个项目里遇到的最频繁的几类问题。如果你遇到表里没有的情况建议先把docker logs和nvidia-smi这两个信息源贴全大概率问题都会出现在这二者的交叉点上。6.3 几个值得记住的经验最后分享几个我个人的操作习惯不一定是最优解但至少帮我在这个项目里少绕了几段路。第一给最终的 Dockerfile 和 wheel 清单打 tag。我在外网构建镜像时会把 requirements.txt 和 wheels 目录打包成一个 tar和镜像一起传进内网。这样即使镜像在传输过程中损坏也能在目标机器上重新用 Dockerfile 构建不用再往外网跑一趟。这个备份思路对于隔离环境特别重要因为你永远不知道一次传输什么时候出问题。第二所有模型路径在容器里用相对固定的绝对路径。我统一放在/app/weights然后通过挂载卷与宿主机/data/models关联。这样模型更新时只需要替换挂载目录的文件再重启容器不需要重建镜像。但要注意挂载目录的文件权限要和容器内用户匹配否则出现 Permission denied 会花很长时间排查。第三日志要落盘且设置轮转。OCR 服务一次请求会产生大量中间日志如果不处理容器磁盘很快会被撑爆。我用的是 logrotate 挂载目录日志上限控制在一个合理的范围内。这个点很少有人写但对长期运行的容器来说是刚需。MonkeyOCRv2 这次离线部署给我最大的感受是离线环境对工程能力的要求其实比联网环境更高因为每一个依赖都必须提前想清楚每一个版本都必须提前验证好。15GB 镜像看起来笨重但它是整套环境一致性的成本是保证服务在内网能稳定跑起来的合理代价。如果你正在做类似的事情希望这篇记录能让你少踩几个我踩过的坑。模型更新时优先校验权重和框架版本是否匹配驱动升级时永远先备份旧驱动。这两条习惯比任何命令都值钱。