1. 为什么要在内网离线环境折腾 MonkeyOCRv2先把场景说清楚。MonkeyOCRv2 是一套文档解析方向的 OCR 模型能对扫描件、PDF 转图、表格、公式混排的版面做结构化识别。很多团队第一次接触它是在公网环境里pip install一把梭模型权重从云端拉跑通了就以为万事大吉。真正的问题出现在把它搬进内网的那一刻目标机器没有外网出口镜像仓库是私有的GPU 驱动版本和公网测试机不一致甚至连docker pull都只能走内网 registry。我这次接到的需求就是典型的离线交付一台带 RTX 4060 Laptop GPU 的机器系统盘空间紧张要求把 MonkeyOCRv2 连同推理依赖打包成一个自包含的 Docker 镜像总体积控制在 15GB 上下交付后现场只做docker load加docker run不允许现场联网装任何东西。关键词里出现的 Docker、GPU、NVIDIA、vLLM 这几个词基本就是这个任务的四条主线容器化封装、显卡直通、驱动匹配、推理引擎选型。为什么体积要卡在 15GB这不是拍脑袋定的。一个纯 CPU 的 OCR 镜像通常 3 到 5GB 就够了但一旦把 CUDA runtime、cuDNN、PyTorch 的 GPU 版本、vLLM 的预编译 wheel、再加上模型权重全塞进去体积会迅速膨胀。15GB 是一个比较现实的平衡点既能装下完整的 GPU 推理栈和量化后的模型权重又不至于让内网的文件摆渡和镜像分发变得难以忍受。超过 20GB 之后很多内网的传输通道和私有 registry 的存储配额就开始吃紧了。这篇文章适合三类人看。第一类是正在做离线 AI 交付的工程师你需要一套可复现的镜像构建流程第二类是被 GPU 直通和驱动版本折磨过的运维你想知道容器里到底该装什么、不该装什么第三类是想把 OCR 类模型跑在自己机器上的开发者你对 vLLM 这类推理引擎的取舍还没拿定主意。我会把构建过程、踩过的坑、参数怎么算、现场怎么验证全部摊开讲。需要提前说明一点MonkeyOCRv2 的具体权重文件和推理接口不同版本差异较大下面涉及模型加载的部分我会给出通用的组织方式和配置思路你拿到实际权重后按同样逻辑替换即可。核心的镜像构建、GPU 调优、离线分发这套方法论是通用的。2. 15GB 预算怎么花镜像分层与依赖取舍2.1 先把体积账算明白很多人构建 GPU 镜像的习惯是直接FROM nvidia/cuda:12.x-devel然后在上面pip install torch。这么干出来的镜像轻松突破 25GB因为 devel 镜像自带完整的编译工具链和静态库而推理场景根本用不到 nvcc 和那些头文件。我的做法是选 runtime 版本的基础镜像把编译需求前置到构建阶段解决。下面是我实际用的体积分配表你可以对照自己的项目调整层内容体积区间是否必需备注CUDA runtime 基础镜像2.5 - 3.5GB必需选 runtime 而非 develcuDNN 运行库0.8 - 1.2GB必需与 CUDA 版本严格对应PyTorch GPU 版2.5 - 3.5GB必需用官方 wheel别自己编译vLLM 及其依赖1.5 - 2.5GB视方案含 xformers、flash-attn 等模型权重量化后3 - 6GB必需FP16 换 INT8/AWQ 能省一半系统依赖与 Python 环境1 - 1.5GB必需精简 apt 缓存应用代码与配置 0.5GB必需忽略不计把这张表加起来控制在 15GB 以内是完全可行的前提是每一层都做减法。我见过最离谱的镜像里同时装了 TensorFlow、PyTorch 和 JAX 三套框架光框架就 10GB这种镜像交付出去就是灾难。2.2 基础镜像的选择逻辑CUDA 基础镜像的 tag 命名有规律12.4.1-cudnn-runtime-ubuntu22.04这种格式里runtime和devel的区别就是有没有编译工具。推理场景一律选 runtime。还有一个细节Ubuntu 版本要和你的 PyTorch wheel 匹配22.04 是目前兼容性最好的选择24.04 上部分预编译包还没跟上。选 CUDA 版本的时候不要盲目追新。RTX 4060 Laptop 是 Ada Lovelace 架构算力 8.9CUDA 12.x 全系都支持。但如果你的目标机器上驱动版本偏老比如只支持到 CUDA 12.2那你用 12.4 的镜像就可能起不来。判断方法很简单在目标机器上跑nvidia-smi右上角会显示CUDA Version: 12.x这个数字是驱动能支持的最高 CUDA 运行时版本你的镜像 CUDA 版本不能超过它。注意nvidia-smi显示的 CUDA Version 是驱动支持的上限不是已安装的 CUDA 版本。容器里的 CUDA 是镜像自带的和宿主机装没装 CUDA toolkit 无关只和驱动版本有关。2.3 模型权重的量化取舍这是省体积最狠的一刀。MonkeyOCRv2 如果按 FP16 存权重假设是 7B 级别的模型光权重就 14GB直接爆预算。换成 INT8 量化能压到 7GB 左右4bit 量化AWQ 或 GPTQ能压到 4GB 以内。但量化不是免费的午餐。OCR 任务对文字细节敏感量化过度会导致小字号、低对比度的文字识别率下降。我的经验是检测阶段文字框定位对量化不敏感可以用 4bit识别阶段文字内容转录建议至少 INT8条件允许就保留 FP16。如果模型支持分离部署把检测和识别拆成两个服务各自用量化策略整体效果和体积都能兼顾。具体到 vLLM 加载量化模型配置里要显式指定量化方式否则引擎会按 FP16 去读权重直接报显存不足或者加载失败。这个参数写错是新手最常见的翻车点之一。3. Dockerfile 逐层拆解与构建实操3.1 一个能跑通的 Dockerfile 骨架下面这份 Dockerfile 是我反复调整后的版本重点看每一层的合并策略和清理动作FROM nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04 ENV DEBIAN_FRONTENDnoninteractive \ PYTHONUNBUFFERED1 \ PIP_NO_CACHE_DIR1 \ TZAsia/Shanghai RUN apt-get update apt-get install -y --no-install-recommends \ python3.10 python3-pip python3.10-dev \ libgl1 libglib2.0-0 libsm6 libxext6 libxrender1 \ fonts-noto-cjk \ rm -rf /var/lib/apt/lists/* \ ln -sf /usr/bin/python3.10 /usr/bin/python WORKDIR /app COPY requirements.txt . RUN pip install --upgrade pip \ pip install -r requirements.txt COPY app/ /app/app/ COPY configs/ /app/configs/ COPY models/ /app/models/ EXPOSE 8000 CMD [python, -m, app.server]几个关键点解释一下。--no-install-recommends能砍掉大量非必要的推荐包rm -rf /var/lib/apt/lists/*清掉 apt 缓存这两步通常能省 300 到 500MB。fonts-noto-cjk是给 OCR 可视化输出用的如果不需要画框标注可以去掉。libgl1这一串是 OpenCV 的运行时依赖缺了会在import cv2时报libGL.so.1 not found这个错我踩过不止一次。3.2 requirements 里的版本锁定离线环境最怕的就是版本漂移。requirements.txt 里所有包都要写死版本号包括间接依赖。我的做法是先在联网机器上用pip freeze导出完整依赖树再手动剔除掉不需要的包。PyTorch 的安装要特别注意不能直接pip install torch那样装的是 CPU 版。GPU 版必须指定 index-urlpip install torch2.4.0 torchvision0.19.0 \ --index-url https://download.pytorch.org/whl/cu124vLLM 的安装更麻烦它对 torch 版本、CUDA 版本、Python 版本都有严格要求。装之前先查 vLLM 官方文档的兼容性矩阵选一个和你的 CUDA 12.4 匹配的版本。我这次用的是 0.6.x 系列它对 Ada 架构的支持比较成熟。如果版本对不上典型症状是 import 时报undefined symbol或者运行时 CUDA kernel 崩溃。3.3 构建阶段的缓存与多阶段技巧如果模型权重需要从原始格式转换比如 HuggingFace 格式转 vLLM 格式这个转换过程会占用大量临时空间。用多阶段构建把转换放在 builder 阶段最终镜像只 COPY 转换后的结果FROM nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04 AS builder # 安装转换工具执行权重转换 RUN python convert.py --input /raw --output /converted FROM nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04 COPY --frombuilder /converted /app/models这样临时文件和转换工具都不会进入最终镜像。构建时用--no-cache会拖慢速度建议在开发阶段保留缓存最后一次正式构建再清缓存确保镜像干净。构建命令本身没什么花头docker build -t monkeyocr-v2:offline-1.0 .但构建完一定要做体积审计看看哪一层最大docker history monkeyocr-v2:offline-1.0 --human --no-trunc如果发现某一层异常大多半是缓存没清干净或者误装了 devel 包。我见过有人在 runtime 镜像里又apt install cuda-toolkit直接把体积干到 8GB纯属自己给自己找麻烦。4. GPU 直通从驱动匹配到容器内可见性验证4.1 宿主机驱动与容器 CUDA 的关系这是整个部署里最容易混淆的概念。宿主机上装的是 NVIDIA 驱动容器里装的是 CUDA runtime两者通过 NVIDIA Container Toolkit 打通。驱动版本决定了容器能用多高的 CUDA 版本但容器里的 CUDA 库是镜像自带的不需要宿主机装 CUDA toolkit。RTX 4060 Laptop 在 Ubuntu 上装驱动最省事的方式是用系统仓库的nvidia-driver-550系列或者用官方 runfile。我倾向于用仓库版本因为升级和卸载都干净。装完重启nvidia-smi能正常输出就说明驱动 OK。然后装 NVIDIA Container Toolkit这是让 Docker 能识别 GPU 的关键组件。装完之后要配置 Docker 的 runtime编辑/etc/docker/daemon.json{ runtimes: { nvidia: { path: nvidia-container-runtime, runtimeArgs: [] } } }改完systemctl restart docker。这一步漏了的话docker run --gpus all会报could not select device driver错误。4.2 容器内验证 GPU 可见性的完整链路镜像构建好、驱动装好之后别急着跑模型先用一个最小命令验证 GPU 能不能透进容器docker run --rm --gpus all monkeyocr-v2:offline-1.0 nvidia-smi如果这条命令能输出和宿主机一样的显卡信息说明直通链路是通的。如果报错按下面的顺序排查报错信息可能原因排查动作could not select device drivertoolkit 没装或 runtime 没配检查 daemon.json 和 toolkit 安装no CUDA-capable device detected驱动没装好或版本不匹配宿主机跑 nvidia-smi 确认CUDA driver version is insufficient镜像 CUDA 高于驱动支持降级镜像 CUDA 版本permission denied on /dev/nvidia*用户权限或 SELinux检查用户组和 SELinux 状态再进一步验证容器内 PyTorch 能不能真正调用 CUDAdocker run --rm --gpus all monkeyocr-v2:offline-1.0 \ python -c import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))输出True和显卡型号才算真正打通。这一步过了模型加载才有意义。4.3 显存分配与共享内存的坑RTX 4060 Laptop 的显存通常是 8GB这个容量跑 OCR 模型要精打细算。vLLM 默认会预分配大部分显存做 KV cache参数是--gpu-memory-utilization默认 0.9。如果你的模型权重加激活值已经占了 6GB剩下 2GB 做 KV cache 可能不够需要调低这个值或者减小--max-model-len。还有一个隐蔽的坑是共享内存。Docker 默认的/dev/shm只有 64MBvLLM 在多进程推理时会用共享内存传数据64MB 直接导致进程崩溃报错信息还特别隐晦通常是Bus error或者 worker 莫名退出。解决办法是启动时加--shm-size8gdocker run --gpus all --shm-size8g -p 8000:8000 monkeyocr-v2:offline-1.0这个参数我强烈建议默认加上8GB 对大多数场景够用代价只是宿主机的内存占用不影响镜像体积。5. vLLM 在离线 OCR 场景的配置与调优5.1 为什么 OCR 场景也考虑 vLLM传统 OCR 推理是 PyTorch 直接 forward简单直接。但 MonkeyOCRv2 如果包含语言模型做后处理或者端到端生成用 vLLM 能拿到明显的吞吐提升尤其是批量处理文档的时候。vLLM 的 PagedAttention 和连续批处理机制让显存利用率和并发能力都比裸 PyTorch 好一截。代价是复杂度上升。vLLM 有自己的模型加载逻辑、调度器、执行器配置项多出错信息不够友好。离线环境里调试成本更高因为没法随时查文档。所以我的建议是如果只是单张图片偶尔识别裸 PyTorch 足够如果是批量文档流水线上 vLLM 值得。5.2 离线加载模型的关键配置vLLM 默认会去 HuggingFace 拉配置和 tokenizer离线环境必须全部指向本地路径。启动参数大致是这样python -m vllm.entrypoints.openai.api_server \ --model /app/models/monkeyocr-v2 \ --served-model-name monkeyocr \ --dtype float16 \ --gpu-memory-utilization 0.85 \ --max-model-len 4096 \ --tensor-parallel-size 1 \ --trust-remote-code \ --host 0.0.0.0 --port 8000--trust-remote-code在加载自定义模型结构时经常是必需的但要注意安全边界离线环境里模型来源可控问题不大。--tensor-parallel-size 1是因为单卡多卡才需要调整。如果模型是量化版本还要加--quantization awq或--quantization gptq。这个参数不写vLLM 会按 FP16 读权重直接显存爆炸。5.3 显存不够时的降级策略8GB 显存跑 OCR 模型遇到显存不足是常态。降级顺序我一般是这样的先降--max-model-len从 4096 降到 2048KV cache 直接减半再降--gpu-memory-utilization从 0.9 降到 0.7给系统留余量换量化权重FP16 换 INT8最后才考虑 CPU offload但 OCR 场景 offload 后延迟会很难看--max-model-len的设定要和实际输入长度匹配。OCR 的文本输出通常不会太长2048 对大多数文档够用。设太大纯属浪费显存。提示vLLM 启动时会打印显存分配日志包括模型权重占用、KV cache 占用、可用块数。这些数字是调优的依据别忽略。6. 离线分发与现场部署的完整流程6.1 镜像导出与压缩构建好的镜像要导出成文件才能摆渡到内网。docker save出来的 tar 包体积和镜像一致15GB 的镜像就是 15GB 的文件。用 gzip 压缩能省一些但 GPU 相关的二进制文件压缩率一般docker save monkeyocr-v2:offline-1.0 | gzip monkeyocr-v2-offline-1.0.tar.gz如果内网传输通道对单文件大小有限制可以分卷压缩split -b 4G monkeyocr-v2-offline-1.0.tar.gz monkeyocr-part-现场合并回来再docker load。docker load的时候注意磁盘空间解压过程需要额外的临时空间至少留出镜像体积两倍的空余。6.2 现场部署的检查清单到了现场按这个顺序走能避免大部分问题确认宿主机驱动版本nvidia-smi能正常输出确认 Docker 和 NVIDIA Container Toolkit 已安装docker load导入镜像docker images确认存在跑nvidia-smi验证 GPU 直通跑 PyTorch CUDA 验证启动服务观察日志中的显存分配用一张测试图片跑端到端识别确认输出正确每一步都过了再往下走不要跳步。我见过现场直接docker run然后报错回头排查发现是 toolkit 没装白白浪费半天。6.3 服务化与开机自启离线环境通常要求服务开机自启。用docker run --restartalways配合 systemd 单元文件比较稳妥。systemd 里写ExecStart调用 docker runExecStop调用 docker stop这样服务管理统一走 systemctl。日志要挂载出来方便排查docker run -d --name monkeyocr \ --gpus all --shm-size8g \ --restartalways \ -p 8000:8000 \ -v /data/logs:/app/logs \ monkeyocr-v2:offline-1.0日志目录挂载到宿主机容器重启日志不丢这是运维的基本素养。7. 几个我实际踩过的坑和对应解法第一个坑是字体缺失导致的可视化输出乱码。OCR 结果里如果有中文标注容器里没有中文字体画出来的框里全是方块。装fonts-noto-cjk解决但要注意装完之后fc-cache -fv刷新字体缓存否则程序还是找不到。第二个坑是 OpenCV 的 headless 问题。服务器环境没有显示器装了带 GUI 的 opencv-python 会在 import 时报 Qt 相关错误。换成opencv-python-headless就好体积还小一些。第三个坑是 vLLM 的版本和 torch 版本打架。vLLM 对 torch 的依赖很严格pip 解析依赖时可能把你指定的 torch 版本覆盖掉。解决办法是先装 torch再用--no-deps装 vLLM然后手动补 vLLM 需要的其他依赖。这个操作有点脏但离线环境里最有效。第四个坑是镜像里的时区问题。容器默认 UTC日志时间戳和本地差 8 小时排查问题时很误导。Dockerfile 里设TZAsia/Shanghai并装tzdata解决。第五个坑是docker save的镜像层顺序。如果镜像层太多load 的时候会慢。构建时尽量合并 RUN 指令减少层数不仅体积小load 也快。8. 关于性能调优的一点个人体会RTX 4060 Laptop 这块卡8GB 显存跑 OCR 模型性能瓶颈往往不在算力而在显存带宽和容量。我实测下来把模型量化到 INT8 之后单张 A4 文档的识别延迟从 1.2 秒降到 0.7 秒左右提升主要来自显存占用下降后 KV cache 能开得更大批处理效率上去了。vLLM 的--gpu-memory-utilization不要设太满0.85 是个比较稳的值。设到 0.95 虽然理论上能多缓存一些请求但系统本身和其他进程也要显存一旦触发 OOM整个服务挂掉得不偿失。还有一点离线环境的模型更新很麻烦。我的做法是在镜像里预留一个模型目录的挂载点模型权重不打包进镜像而是单独作为数据卷挂载。这样更新模型只需要替换宿主机上的权重文件不用重新构建和分发整个镜像。代价是镜像和模型要分开管理但长期看省事得多。这个取舍看你的交付频率如果模型基本不变打包进去更省心如果模型会迭代分离挂载更灵活。