1. 为什么要在内网离线环境折腾 MonkeyOCRv2
把 MonkeyOCRv2 部署到内网离线环境，这件事听起来像是"把大象装进冰箱"，但真正动手之后你会发现，难点从来不是"装"，而是"装完之后它能不能跑起来、跑得稳不稳、GPU 有没有真的在干活"。我前后在三个不同的内网环境里部署过这套东西，踩过的坑从 Docker 镜像构建失败、NVIDIA 驱动版本对不上，到 vLLM 引擎启动后显存莫名其妙被吃满，几乎每一环都有一段故事。
先说清楚 MonkeyOCRv2 是什么定位。它是一套面向文档解析的 OCR 推理服务，核心能力是把图片、扫描件、PDF 里的文字和版面结构提取出来，底层通常依赖视觉编码器加语言解码器的组合，推理侧常见做法是用 vLLM 这类高性能推理引擎来托管模型权重。之所以要"内网离线部署"，是因为很多实际场景里，机器根本连不上外网——比如生产车间的质检终端、档案室的扫描工作站、或者某些对数据出域有硬性要求的业务系统。这些地方你没法pip install一下就从云端拉包，所有依赖必须提前打包好，用 U 盘或者内部镜像仓库搬进去。
15GB 的 Docker 镜像这个数字不是随便写的。它大致对应的是：基础 CUDA 运行时镜像（约 3-4GB）+ Python 依赖和系统库（约 2-3GB）+ 模型权重（视量化方式不同，FP16 下可能 6-8GB）+ vLLM 及其编译产物（约 1-2GB）。这个体积意味着你不能指望用docker save之后随手拷来拷去，得考虑分层、压缩、以及目标机器的磁盘余量。我见过有人镜像构建完 15GB，结果目标机器根分区只剩 12GB，直接卡在docker load那一步，白忙活一整天。
这篇文章适合谁看？如果你正在做内网 AI 服务的落地，手上有 NVIDIA 显卡（比如 RTX 4060 Laptop、L20、甚至 MI50 这类），需要把 OCR 或大模型推理服务塞进一个不能上网的环境，那这篇内容基本就是为你写的。我会从镜像构建的取舍讲起，一路说到 GPU 调优和 vLLM 引擎参数怎么调，中间穿插我实际踩过的坑和验证过的参数。不会只给你一堆命令让你抄，而是把"为什么这么选"讲透，这样你换个模型、换个显卡也能自己推。
2. 镜像构建：15GB 是怎么来的，又该怎么瘦身
2.1 基础镜像选型：别一上来就用 latest
构建 MonkeyOCRv2 镜像的第一步是选基础镜像。很多人习惯性写FROM nvidia/cuda:12.1.0-cudnn8-runtime-ubuntu22.04，这没错，但版本号一定要锁死。我吃过亏：某次用了带latest标签的镜像，构建时拉到的 CUDA 版本和宿主机驱动不匹配，容器起来后nvidia-smi能看到卡，但 PyTorch 一调用 CUDA 就报CUDA error: no kernel image is available for execution on the device。这个错误的本质是编译时的 CUDA 架构（sm_XX）和实际显卡的计算能力对不上。
选 runtime 还是 devel？如果你只是跑推理，runtime 镜像足够，体积能小 2-3GB。devel 镜像带编译工具链，只有在你要在容器里现场编译 vLLM 的 CUDA kernel 时才需要。我的建议是：如果 vLLM 用预编译 wheel 安装，就选 runtime；如果要用源码编译（比如为了适配特定显卡架构），那 devel 省不掉。
FROM nvidia/cuda:12.1.0-cudnn8-runtime-ubuntu22.04 ENV DEBIAN_FRONTEND=noninteractive ENV PYTHONUNBUFFERED=1 ENV TZ=Asia/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 libxrender-dev \ && rm -rf /var/lib/apt/lists/*这里libgl1和libglib2.0-0是 OpenCV 的运行时依赖，OCR 项目几乎必装。很多人本地构建时因为宿主机有这些库所以没报错，一到干净的内网机器上就ImportError: libGL.so.1: cannot open shared object file。提前装好，省得后面排查。
2.2 模型权重怎么进镜像：三种方案的成本对比
模型权重是 15GB 里的大头。把权重打进镜像有三种常见做法，各有取舍：
| 方案 | 做法 | 优点 | 缺点 |
|---|---|---|---|
| 打进镜像层 | COPY model_weights /app/weights | 一次构建，分发简单 | 镜像体积暴涨，更新权重需重建 |
| 挂载卷 | 权重放宿主机，-v挂载 | 镜像小，权重可独立更新 | 分发时要额外拷贝权重目录 |
| 构建时下载 | RUN huggingface-cli download ... | 镜像自包含 | 内网构建时根本下不动 |
内网离线场景下，我强烈推荐挂载卷方案。原因很直接：权重文件动辄几个 GB，如果打进镜像，每次微调模型或者换量化版本，你都得重新构建、重新docker save、重新搬运。而挂载卷的话，镜像本身可能只有 5-6GB，权重单独用一个移动硬盘拷过去就行。启动命令大概长这样：
docker run -d --gpus all \ -v /data/models/monkeyocrv2:/app/weights:ro \ -v /data/cache:/root/.cache \ -p 8000:8000 \ --name monkeyocr \ monkeyocrv2:offline注意:ro只读挂载，防止容器内进程意外改写权重。/root/.cache也挂出来，是因为 vLLM 和 HuggingFace 库会在里面写编译缓存和 tokenizer 缓存，不挂的话每次重启容器都要重新编译，慢得让人抓狂。
2.3 依赖安装的离线化处理
内网构建最大的痛点是 pip 装不了包。标准做法是提前在有网机器上把 wheel 包全部下载下来：
pip download -r requirements.txt -d ./wheels \ --platform manylinux2014_x86_64 \ --python-version 310 \ --only-binary=:all:这里--platform和--python-version必须和目标环境一致，否则下下来的 wheel 装不上。我遇到过一次：在有网机器上用 Python 3.11 下载，目标容器是 3.10，结果一堆包报is not a supported wheel on this platform。后来老老实实按目标版本重新下。
vLLM 的安装要特别注意。它依赖torch、xformers、flash-attn这些带 CUDA 扩展的包，版本必须严格对齐。我的经验是直接锁定 vLLM 官方推荐的组合，比如 vLLM 0.4.x 配 torch 2.1.2 + cu121。版本错配的典型症状是启动时报undefined symbol或者推理时 kernel 崩溃。
COPY wheels /tmp/wheels RUN pip3 install --no-index --find-links=/tmp/wheels \ torch==2.1.2+cu121 \ vllm==0.4.2 \ -r /tmp/wheels/requirements.txt \ && rm -rf /tmp/wheels--no-index强制 pip 不去网上找，--find-links指向本地 wheel 目录。这样构建过程完全离线，构建出来的镜像也干净。
2.4 分层缓存与镜像瘦身
Docker 构建的层缓存机制要用好。把不常变的部分（系统依赖、Python 基础包）放前面，常变的部分（业务代码、配置）放后面。这样改代码时不用重装依赖，构建时间能从十几分钟降到一两分钟。
瘦身方面，几个实用手段：rm -rf /root/.cache/pip清掉 pip 缓存，能省 1-2GB；apt-get clean清掉 apt 缓存；如果用了 devel 镜像编译，编译完可以把工具链删掉。但要注意，删的时候用&&串在同一条 RUN 里，否则删掉的文件还在上一层里占着空间。
RUN pip3 install --no-index --find-links=/tmp/wheels -r requirements.txt \ && rm -rf /root/.cache/pip /tmp/wheels \ && apt-get clean \ && rm -rf /var/lib/apt/lists/*最终镜像大小控制在 15GB 左右是合理的。如果超过 20GB，大概率是权重打进去了，或者缓存没清干净。
3. 内网搬运与加载：镜像和权重的实际流转
3.1 docker save 与 load 的正确姿势
镜像构建完，下一步是搬到内网机器。docker save出来的 tar 包体积和镜像一样大，15GB 的镜像就是 15GB 的 tar。传输前建议先压缩：
docker save monkeyocrv2:offline | gzip -1 > monkeyocrv2.tar.gz这里用-1而不是默认压缩级别，是因为镜像里大部分是已经压缩过的二进制（wheel、模型权重），高压缩级别收益很小但耗时翻倍。实测-1能把 15GB 压到 13GB 左右，传输时间省一点是一点。
加载的时候：
gunzip -c monkeyocrv2.tar.gz | docker load注意别先解压再 load，那样磁盘上会同时存在 tar 和解压后的内容，空间不够的机器直接爆盘。管道方式边解压边加载，省一半空间。
提示：
docker load过程中如果中断，可能会留下不完整的镜像层。重新 load 前先docker images确认，必要时docker rmi清掉残留。
3.2 权重文件的校验与放置
权重搬运最怕的是文件损坏。大文件在 U 盘或网络传输中出错是常事，而且往往到推理时才暴露，报个莫名其妙的unexpected EOF或者权重 shape 不匹配。我的做法是搬运前生成校验和：
find /data/models/monkeyocrv2 -type f -exec sha256sum {} \; > checksums.txt到内网后sha256sum -c checksums.txt验证一遍。多花几分钟，能省掉后面几小时的排查。
权重目录结构也要注意。vLLM 加载模型时对目录布局有要求，通常是config.json、tokenizer.json、*.safetensors这些文件平铺在一个目录下。如果是从 HuggingFace 下载的，默认就是这个结构，直接拷过去就行。但如果你自己转换过格式，要确认config.json里的architectures字段和 vLLM 支持的模型类型对得上，否则启动时报Model architecture not supported。
3.3 内网镜像仓库的搭建（可选但推荐）
如果内网机器不止一台，每次都docker save/load太累。可以在内网搭一个轻量镜像仓库：
docker run -d -p 5000:5000 --name registry \ -v /data/registry:/var/lib/registry \ registry:2然后把镜像tag成内网IP:5000/monkeyocrv2:offline再push。其他机器直接pull就行。这个方案的前提是内网机器之间网络通，且能访问仓库端口。注意 Docker 默认要求仓库走 HTTPS，内网用 HTTP 的话需要在每台机器的/etc/docker/daemon.json里加insecure-registries配置，然后重启 Docker。
4. GPU 环境打通：驱动、容器运行时与设备可见性
4.1 宿主机 NVIDIA 驱动的版本匹配逻辑
容器里能不能用 GPU，取决于宿主机驱动和容器内 CUDA 运行时的配合。这里有个关键认知：容器里不需要装完整的 NVIDIA 驱动，只需要 CUDA 运行时，驱动由宿主机提供。NVIDIA Container Toolkit 会把宿主机的驱动库和设备节点映射进容器。
版本匹配的规则是：宿主机驱动版本要 >= 容器内 CUDA 版本要求的最低驱动。比如 CUDA 12.1 要求驱动 >= 530，CUDA 11.8 要求 >= 520。查法很简单，nvidia-smi右上角显示的CUDA Version是驱动支持的最高 CUDA 版本，容器里的 CUDA 不能超过这个。
我遇到过最坑的情况是：宿主机驱动是 470 系列，容器里装了 CUDA 12.1 的 PyTorch，结果torch.cuda.is_available()返回 False，但nvidia-smi在容器里又能正常显示。原因就是驱动太老，不支持 CUDA 12。解决办法要么升级宿主机驱动，要么把容器 CUDA 降到 11.8。
# 宿主机查看驱动版本 nvidia-smi --query-gpu=driver_version --format=csv,noheader # 容器内验证 CUDA 可用性 python3 -c "import torch; print(torch.cuda.is_available(), torch.version.cuda)"4.2 nvidia-container-toolkit 的安装与验证
宿主机要装 NVIDIA Container Toolkit，Docker 才能识别--gpus参数。安装步骤（以 Ubuntu 为例）：
distribution=$(. /etc/os-release; echo $ID$VERSION_ID) curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | apt-key add - curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \ tee /etc/apt/sources.list.d/nvidia-container-toolkit.list apt-get update && apt-get install -y nvidia-container-toolkit nvidia-ctk runtime configure --runtime=docker systemctl restart docker装完验证：
docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi如果这条命令能打印出显卡信息，说明链路通了。如果报could not select device driver "" with capabilities: [[gpu]]，说明 toolkit 没装好或者 Docker 没重启。
注意：内网离线环境下，上面这些 apt 源和 curl 都下不动。需要提前在有网机器上把 deb 包下好，或者直接用 NVIDIA 提供的离线安装包。这一步是内网部署 GPU 环境最容易卡住的地方，务必提前准备。
4.3 多卡与显存可见性控制
如果机器上有多张卡，或者你想限制容器只用某几张，用--gpus参数控制：
# 只用第 0 和第 1 张卡 docker run --gpus '"device=0,1"' ... # 用全部卡 docker run --gpus all ...也可以用环境变量NVIDIA_VISIBLE_DEVICES控制。这个在共享 GPU 的机器上很有用，避免你的容器把别人的卡也占了。
显存方面，vLLM 有个--gpu-memory-utilization参数，默认 0.9，意思是占用 90% 显存。这个值设太高容易 OOM，设太低又浪费。我的经验是：如果机器上只跑这一个服务，0.85-0.9 比较合适；如果还要留显存给其他进程，降到 0.6-0.7。RTX 4060 Laptop 只有 8GB 显存，跑 MonkeyOCRv2 这种模型要特别小心，可能需要用量化版本或者限制并发。
5. vLLM 引擎调优：让 OCR 推理真正跑满 GPU
5.1 vLLM 在 OCR 场景下的角色定位
MonkeyOCRv2 的推理侧用 vLLM 托管，核心原因是 vLLM 的 PagedAttention 机制能大幅提升显存利用率和吞吐。传统推理框架把每个请求的 KV Cache 连续存放，显存碎片严重；vLLM 把 KV Cache 分页管理，像操作系统管理内存一样，碎片率大幅降低。对于 OCR 这种输入长度差异很大的场景（有的图片只有几个字，有的整页文档几千字），这个优势特别明显。
vLLM 的架构里，EngineCore负责调度，Scheduler决定哪些请求进 batch，Executor实际执行模型前向。理解这个流程对调优有帮助：当并发请求多的时候，Scheduler 会把请求打包成 batch，batch 越大 GPU 利用率越高，但显存占用也越大。调优的本质就是在吞吐和显存之间找平衡点。
5.2 关键启动参数与实测取值
启动 vLLM 服务时，几个参数对性能影响最大：
python3 -m vllm.entrypoints.openai.api_server \ --model /app/weights \ --served-model-name monkeyocrv2 \ --gpu-memory-utilization 0.85 \ --max-model-len 4096 \ --max-num-seqs 16 \ --tensor-parallel-size 1 \ --dtype float16 \ --port 8000逐个说：
--gpu-memory-utilization 0.85：留 15% 显存给 CUDA 上下文和其他开销。设 0.95 经常在压力测试时 OOM。--max-model-len 4096：OCR 场景单页文档的 token 数一般不超过 4096。设太大浪费显存，设太小长文档会被截断。--max-num-seqs 16：同时处理的最大请求数。这个值和显存强相关，8GB 显存的卡建议设 8-16，24GB 的卡可以设 32-64。--tensor-parallel-size 1：单卡推理设 1。多卡才需要调大，但 MonkeyOCRv2 这个量级的模型单卡足够。--dtype float16：半精度推理，显存减半，精度损失可接受。如果显卡支持 bfloat16（Ampere 及以上），可以用bfloat16，数值稳定性更好。
实测在 RTX 4060 Laptop（8GB）上，max-num-seqs=8、gpu-memory-utilization=0.8是比较稳的组合，单张 A4 扫描件的推理延迟在 1-2 秒。在 L20（48GB）上，max-num-seqs=64、gpu-memory-utilization=0.9，吞吐能到每秒十几张。
5.3 显存不够时的降级策略
8GB 显存跑 OCR 模型确实紧张。几个降级方向：
第一，用量化版本。GPTQ 或 AWQ 量化能把权重压到 4bit，显存占用降到 FP16 的四分之一左右。代价是精度略降，但 OCR 任务对精度没那么敏感，实测识别准确率下降在 1-2 个百分点以内。
第二，限制max-model-len。如果实际文档都不长，把 4096 降到 2048，KV Cache 显存直接减半。
第三，减小max-num-seqs。并发降下来，显存峰值也降。代价是吞吐下降，但如果你的场景是低频调用，影响不大。
第四，开启--enable-chunked-prefill。这个选项把长 prompt 的 prefill 阶段分块处理，降低显存峰值。对长文档场景特别有用。
--enable-chunked-prefill \ --max-num-batched-tokens 20485.4 推理性能的观测与瓶颈定位
服务跑起来后，怎么知道 GPU 有没有真的在干活？几个观测手段：
nvidia-smi dmon能实时看 GPU 利用率和显存占用。如果利用率长期低于 30%，说明 batch 太小或者请求间隔太长，GPU 在等活干。如果利用率 100% 但吞吐上不去，可能是显存带宽瓶颈或者 kernel 效率问题。
vLLM 自身会打印吞吐指标，包括prompt throughput和generation throughput。OCR 场景主要看 generation throughput，因为它反映的是实际生成文字的速度。
# 实时监控 watch -n 1 nvidia-smi --query-gpu=utilization.gpu,memory.used,memory.total --format=csv如果发现显存占用持续增长不释放，可能是 KV Cache 没回收，检查是不是有请求卡住没结束。vLLM 有--disable-log-requests选项，生产环境建议关掉请求日志，减少 IO 开销。
6. 踩坑实录：那些让我加班到凌晨的问题
6.1 容器内 nvidia-smi 正常但 PyTorch 用不了 GPU
这个问题的排查链路我走过完整一遍。现象是：docker run --gpus all进去后nvidia-smi能显示卡，但torch.cuda.is_available()返回 False。
第一步查驱动版本和 CUDA 版本匹配。nvidia-smi显示的 CUDA Version 是驱动支持的最高版本，如果容器内 PyTorch 编译的 CUDA 版本高于这个，就用不了。
第二步查LD_LIBRARY_PATH。容器内需要能找到libcuda.so，这个由 nvidia-container-toolkit 挂载。如果手动改过环境变量，可能把它覆盖了。
第三步查 PyTorch 是不是 CPU 版本。pip install torch默认可能装 CPU 版，要装torch==2.1.2+cu121这种带 CUDA 标识的。验证方法：python3 -c "import torch; print(torch.version.cuda)"，如果打印 None，就是 CPU 版。
我那次最终原因是驱动太老（470），容器 CUDA 是 12.1。升级驱动到 535 后解决。
6.2 vLLM 启动时报 undefined symbol
这个错误通常是 vLLM 和 torch 版本不匹配，或者 CUDA 扩展编译时用的架构和运行时不一致。排查方法：
python3 -c "import vllm; print(vllm.__version__)" python3 -c "import torch; print(torch.__version__, torch.version.cuda)"对照 vLLM 官方文档的版本兼容表。如果版本对得上还报错，可能是 wheel 包本身有问题，重新下载或者换一个版本。
还有一种情况是flash-attn没装好。vLLM 依赖 flash-attn 做注意力加速，如果它编译时用的 CUDA 架构和实际显卡不匹配，运行时会报 kernel 相关错误。解决办法是设置TORCH_CUDA_ARCH_LIST环境变量，指定实际显卡的架构，比如 RTX 4060 是 sm_89：
export TORCH_CUDA_ARCH_LIST="8.9"6.3 镜像加载后磁盘空间不足
docker load需要临时空间解压镜像层。如果镜像 15GB，加载过程中可能临时占用 30GB。目标机器根分区不够的话，可以改 Docker 的数据目录到有大空间的分区：
# /etc/docker/daemon.json { "data-root": "/data/docker" }改完重启 Docker。注意迁移已有镜像的话，要把原/var/lib/docker的内容拷过去。
6.4 推理结果乱码或截断
OCR 输出乱码，常见原因有几个：tokenizer 和模型不匹配（用了错误的 tokenizer 文件）；max-model-len设太小导致长文档被截断；采样参数不对，OCR 场景应该用贪心解码（temperature=0），不要用随机采样。
--temperature 0 \ --top-p 1.0如果输出里有重复文字，可能是repetition_penalty没设。OCR 场景建议设 1.1 左右，抑制重复生成。
7. 上线前的自检清单与长期维护
7.1 部署完成后的验证步骤
服务起来后，别急着接业务，先跑一遍验证：
- 健康检查：
curl http://localhost:8000/health，返回 200 说明服务活着。 - 模型列表：
curl http://localhost:8000/v1/models，确认模型名对得上。 - 单张图片推理：用一张标准测试图，确认输出文字正确。
- 并发测试：用
ab或wrk压一下，看吞吐和延迟是否符合预期。 - 显存监控：压测时
nvidia-smi看显存峰值，确认没超过安全线。
curl -X POST http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "monkeyocrv2", "messages": [{"role": "user", "content": "识别这张图片的文字"}], "temperature": 0 }'7.2 日志、监控与故障恢复
生产环境一定要配日志轮转，否则 vLLM 的日志能把磁盘写满。Docker 层面可以配：
docker run --log-opt max-size=100m --log-opt max-file=3 ...监控方面，vLLM 暴露了 Prometheus 指标，可以接 Grafana 看吞吐、延迟、显存。如果不想搞那么复杂，至少写个脚本定时检查服务健康状态，挂了自动重启。
# 简单的健康检查脚本 if ! curl -sf http://localhost:8000/health > /dev/null; then docker restart monkeyocr fi7.3 模型更新与镜像迭代的流程
内网环境更新模型是个麻烦事。我的建议是把模型权重和镜像解耦，权重走挂载卷，更新时只换权重目录，容器重启即可。镜像只在依赖或代码变更时才重建。
更新流程：新权重拷到宿主机新目录 -> 校验 sha256 -> 停旧容器 -> 改挂载路径 -> 起新容器 -> 验证。整个过程不用重新搬运 15GB 镜像，几分钟搞定。
如果非要更新镜像，记得保留旧版本 tag，出问题能快速回滚。docker tag和docker rmi配合使用，别把旧镜像直接删了。
8. 一些关于 GPU 选型和成本的实际体会
最后聊点实际的。MonkeyOCRv2 这种 OCR 服务，对显卡的要求其实没有大语言模型那么夸张。RTX 4060 Laptop 8GB 能跑，但并发上不去，适合个人或小团队自用。L20 48GB 是企业级选择，能扛几十并发，但价格不便宜。如果预算有限，二手的 3090 24GB 性价比很高，显存够大，架构也支持 bfloat16。
MI50 这类卡我试过，vLLM 对它的支持不如 NVIDIA 完善，需要额外编译 ROCm 版本的依赖，坑比较多。除非你已经有现成的 MI50 环境，否则不建议为了省钱走这条路。
GPU 租用也是个选项，但内网离线部署的场景通常对数据出域有要求，租用云 GPU 可能不符合合规。这个要结合具体业务判断。
显存永远是稀缺资源。我的经验是：宁可显存留 20% 余量，也不要压到 95% 去追求那点吞吐。OOM 一次带来的排查成本和业务中断，远比多买一张卡贵。调优的时候先用小 batch 跑通，再逐步加大并发，观察显存曲线，找到稳定点就停，别贪。
这套东西我在三个环境里部署过，从最初的磕磕绊绊到现在基本半天能搞定，核心就是把版本匹配、离线依赖、显存预算这三件事提前想清楚。剩下的就是耐心排查，GPU 相关的问题看着吓人，但排查思路和普通软件问题没本质区别——看日志、对版本、做隔离测试。
