企业官网建设流程全解析

1. 为什么要在内网离线环境折腾 MonkeyOCRv2

先把场景说清楚。MonkeyOCRv2 是一套面向文档解析的 OCR 模型方案，能处理表格、公式、多栏排版这类传统 OCR 容易翻车的版面。很多团队想把它用起来，但生产环境往往是没有外网的内网机器，甚至 GPU 节点连 pip 源都摸不到。这时候“在线拉镜像、在线装依赖”那套流程直接失效，必须走离线部署。

我这次拿到的目标很明确：在一台带 NVIDIA 显卡的内网服务器上，把 MonkeyOCRv2 跑起来，全程不依赖公网，最终交付一个约 15GB 的 Docker 镜像，并且把 GPU 推理性能调到能接受的水平。关键词里出现的 Docker、NVIDIA、GPU、vLLM 基本就是这条链路上的四个核心环节，缺一不可。

为什么镜像会到 15GB 这个量级？因为里面通常要打包 CUDA 运行时、PyTorch、模型权重、OCR 相关的检测与识别模型，再加上 vLLM 这类推理引擎。模型权重本身就占大头，OCR 方案往往不止一个模型，检测、识别、版面分析各一套，加起来几个 GB 很正常。所以别指望能压到很小，重点是把这 15GB 构建得干净、可复现、能离线搬运。

这篇文章适合谁看？如果你正在做内网 AI 服务部署、需要把带 GPU 的推理服务搬进隔离环境、或者单纯想搞清楚 Docker 镜像离线构建和 GPU 调优的完整链路，那这篇就是给你写的。我会把构建思路、离线打包、GPU 直通、性能调优、踩坑排查都讲透，尽量让你能直接抄作业。

提示：内网离线部署最大的坑不是技术难度，而是“信息差”——你在外网能随手查的东西，内网里查不到。所以构建阶段就要把所有依赖、版本、日志都固化下来，别留悬念。

2. 15GB 镜像的构建策略：分层与依赖固化

2.1 基础镜像选型：为什么不用最省事的 latest

构建的第一步是选基础镜像。很多人图省事直接FROM pytorch/pytorch:latest，这在离线场景里是灾难。原因有两个：一是 latest 会随时间漂移，你今天构建的镜像和下周构建的可能依赖版本都不一样，内网复现时对不上；二是 latest 往往体积臃肿，包含大量你用不到的组件。

我的做法是锁定一个带 CUDA 的 PyTorch 基础镜像的具体 tag，比如pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime。选 runtime 而不是 devel，是因为 devel 版本带编译工具链，体积能大出好几个 GB，而推理场景根本不需要编译 CUDA 算子。这一刀下去，基础镜像就能省下 3 到 5GB。

CUDA 版本要和宿主机驱动匹配。这里有个经验公式：宿主机 NVIDIA 驱动版本决定了它能支持的最高 CUDA 运行时版本。比如驱动是 535 系列，一般能支持到 CUDA 12.2。你选的镜像 CUDA 版本不能超过这个上限，否则容器启动后nvidia-smi能看到卡，但 PyTorch 一调用就报 “CUDA driver version is insufficient”。这个坑我在早期项目里踩过，排查了半天才发现是版本错配。

2.2 依赖安装顺序：把最重的放最底层

Docker 镜像是分层的，每一层都会被缓存。构建时要把变化频率最低、体积最大的内容放在最底层，这样后续改代码时不用重新下载几个 GB 的依赖。我的分层顺序是这样的：

1. 基础镜像（CUDA + PyTorch）
2. 系统级依赖（apt 安装的库，如 libgl1、libglib2.0）
3. Python 依赖（requirements.txt 里的包）
4. vLLM 等推理引擎
5. 模型权重
6. 业务代码

模型权重放倒数第二层是有讲究的。权重文件大且基本不变，放太上层会导致每次改代码都重新拷贝权重。但也不能放最底层，因为权重往往需要从外部下载或拷贝，构建时得单独处理。

Python 依赖这块，建议用pip install --no-cache-dir安装，避免 pip 缓存把镜像撑大。另外 requirements.txt 里的版本要全部锁死，用==而不是>=。离线环境里没有版本协商的余地，装错一个版本可能整条链路跑不通。

FROM pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime RUN apt-get update && apt-get install -y --no-install-recommends \ libgl1 libglib2.0-0 libsm6 libxext6 libxrender1 \ && rm -rf /var/lib/apt/lists/* COPY requirements.txt /tmp/requirements.txt RUN pip install --no-cache-dir -r /tmp/requirements.txt COPY models /app/models COPY src /app/src WORKDIR /app

2.3 模型权重的离线打包技巧

模型权重是 15GB 里的绝对大头。MonkeyOCRv2 涉及的模型通常包括文本检测、文本识别、版面分析几个部分。这些权重在外网环境可以从模型仓库下载，但内网机器下不了，必须提前在外网机器上准备好，再通过移动介质或内网文件服务传进去。

我的做法是在外网机器上先把所有权重下载到一个目录，然后用tar打包时开启压缩。注意，模型权重很多是.safetensors或.bin格式，本身已经是二进制，压缩率有限，但tar.gz还是能省一点。更重要的是打包时保留目录结构，因为代码里加载权重是按相对路径找的。

传输到内网后，构建镜像时用COPY把权重目录拷进去。这里有个细节：如果权重目录有几十万个碎文件，COPY会非常慢，甚至触发 Docker 的层数限制。解决办法是先把权重打成一个 tar 包拷进镜像，在 Dockerfile 里用RUN tar -xf解压，然后删掉 tar 包。这样只占一层，构建速度快很多。

注意：解压后删除 tar 包这一步必须和 COPY 在同一层，否则 tar 包会留在镜像历史层里，白白多占几个 GB。用COPY weights.tar.gz /app/ && RUN tar -xf /app/weights.tar.gz -C /app && rm /app/weights.tar.gz这种写法。

2.4 构建产物的体积审计

镜像构建完，别急着导出。先跑docker history看看每一层占多大，找出体积异常的地方。我见过有人镜像 20GB，结果一查发现 apt 缓存没清、pip 缓存没清、还有一堆测试数据被打进去了。

docker history --no-trunc --format "{{.Size}}\t{{.CreatedBy}}" monkeyocr:v2

如果发现某一层特别大，就要回头看对应的 Dockerfile 指令。常见的体积杀手包括：apt 的/var/lib/apt/lists、pip 的~/.cache/pip、conda 的 pkgs 目录、以及没删干净的临时文件。把这些清掉，15GB 往往能压到 12GB 左右。

3. 离线搬运与内网加载：镜像导出导入的实操细节

3.1 docker save 与 load 的正确姿势

镜像构建好之后，要导出成文件搬到内网。用docker save导出成 tar 包：

docker save -o monkeyocr-v2.tar monkeyocr:v2

这里有个坑：docker save默认不压缩，15GB 镜像导出来就是 15GB 的 tar 文件。如果移动介质空间紧张，可以边导出边压缩：

docker save monkeyocr:v2 | gzip > monkeyocr-v2.tar.gz

但要注意，gzip 压缩 15GB 数据很吃 CPU，可能要十几分钟。而且导入时也要先解压，多一道工序。如果介质空间够，我建议直接存未压缩的 tar，省时省心。

导入到内网机器：

docker load -i monkeyocr-v2.tar

导入完成后用docker images确认镜像在列表里。如果导入报错说 “no space left on device”，那是 Docker 的存储目录空间不够。默认在/var/lib/docker，可以通过修改 daemon.json 的>docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

如果这个命令能输出显卡信息，说明 GPU 直通链路是通的。如果报 “could not select device driver”，那就是 Toolkit 没装好或者 Docker 没重启。

4.2 --gpus 参数的几种写法与适用场景

启动容器时指定 GPU 有几种写法，各有适用场景：

我一般用--gpus all做验证，正式部署时按资源规划指定具体卡号。注意--gpus和--runtime=nvidia不要同时写，会冲突。

4.3 驱动版本与 CUDA 运行时的匹配排查

前面提过驱动和 CUDA 版本要匹配，这里展开说排查方法。容器里跑nvidia-smi看到的是宿主机的驱动版本，而nvcc --version或 PyTorch 报的 CUDA 版本是运行时版本。两者关系是：驱动版本决定支持的 CUDA 运行时上限。

如果 PyTorch 报 “CUDA driver version is insufficient for CUDA runtime version”，说明镜像里的 CUDA 运行时版本高于驱动支持的上限。解决办法要么升级宿主机驱动，要么换一个 CUDA 版本更低的基础镜像。内网环境升级驱动往往要走审批流程，所以更现实的做法是构建镜像时就选对版本。

提示：构建前先在目标宿主机上跑nvidia-smi，记下 “CUDA Version” 那一栏的值，这就是驱动支持的上限。镜像里的 CUDA 版本不要超过它。

5. vLLM 推理引擎的接入与显存调优

5.1 为什么 OCR 场景也考虑 vLLM

MonkeyOCRv2 里如果有基于大模型的版面理解或文本生成环节，vLLM 就是很合适的推理引擎。它的核心优势是 PagedAttention，能把显存里的 KV Cache 按页管理，显著提升吞吐。对于 OCR 这种请求密集、序列长度不一的场景，vLLM 的连续批处理能明显拉高 GPU 利用率。

但要注意，vLLM 不是万能的。如果 MonkeyOCRv2 的主体是传统检测识别模型，vLLM 可能只用在其中一小部分。这时候要评估接入成本，别为了用而用。我的判断是：只要有大模型推理环节，且并发请求超过个位数，vLLM 就值得上。

5.2 显存分配参数：gpu-memory-utilization 怎么定

vLLM 启动时有个关键参数--gpu-memory-utilization，默认 0.9，意思是占用 90% 显存。这个值定高了容易 OOM，定低了浪费显存。我的经验是：

• 如果这台机器只跑 MonkeyOCRv2，可以设 0.85 到 0.9
• 如果还要留显存给其他进程，降到 0.6 到 0.7
• 如果模型本身很大，接近显存上限，设 0.95 但要密切监控

显存不够时的典型报错是 “CUDA out of memory”，这时候要么降 utilization，要么减--max-model-len（最大序列长度），要么减--max-num-seqs（最大并发序列数）。这三个参数是联动的，调一个往往要跟着调其他。

5.3 批处理与并发参数的实际调优过程

调优不能拍脑袋，要有数据支撑。我的做法是先跑一个基准测试，用固定并发数压测，记录吞吐和延迟，然后逐步调参。

python -m vllm.entrypoints.openai.api_server \ --model /app/models/monkey-ocr \ --gpu-memory-utilization 0.85 \ --max-model-len 4096 \ --max-num-seqs 16 \ --port 8000

启动后用一个脚本发请求，观察 GPU 利用率和显存占用。如果 GPU 利用率长期低于 50%，说明并发不够，可以加--max-num-seqs；如果延迟飙升，说明批太大，要减。这个过程要反复几轮，找到吞吐和延迟的平衡点。

实测下来，OCR 场景的请求往往比较短，--max-model-len设太大反而浪费显存。可以先从 2048 或 4096 起步，根据实际输入长度调整。

6. 踩坑排查链路：从容器起不来到底层报错

6.1 容器启动即退出的排查顺序

容器起来就退出，是最常见的现象。排查顺序应该是：

1. docker logs <container>看日志，这是第一手信息
2. 如果日志为空，用docker run -it --entrypoint bash <image>进容器手动跑启动命令
3. 检查启动脚本的权限，离线搬运后文件权限可能丢失
4. 检查环境变量，内网环境经常漏配

我遇到过一次容器秒退，日志什么都没有。最后发现是启动脚本的换行符在 Windows 上被改成了 CRLF，Linux 下执行报 “bad interpreter”。这种问题在内网跨平台搬运时特别常见，用dos2unix处理一下就好。

6.2 GPU 可见但推理报错的典型原因

nvidia-smi能看到卡，但一推理就报错，通常是这几类原因：

• CUDA 版本不匹配（前面讲过）
• 显存被其他进程占满，新进程申请不到
• 模型权重加载路径错误，报的却是 CUDA 错误，误导排查方向
• 显卡驱动版本太老，不支持某些算子

排查时先看完整报错栈，别只看最后一行。CUDA 的报错经常是“表象”，真正原因在更早的日志里。我习惯把日志重定向到文件，用grep -i error过滤，再逐条看上下文。

6.3 内网环境特有的依赖缺失问题

内网机器没有外网，很多在线安装能自动搞定的依赖，这里会静默失败。典型的是字体文件、系统库、时区数据。OCR 场景对字体尤其敏感，缺字体可能导致渲染或识别异常。

我的做法是在构建镜像时就把常用字体、时区、locale 都装好，别指望运行时补。另外，Python 包如果有运行时下载行为（比如某些包首次调用会下载模型），在内网会直接卡死。构建阶段就要把这些资源预置进去。

7. 性能调优的实测经验与参数清单

7.1 从 15GB 镜像到稳定服务的完整参数表

把这次部署的关键参数整理成表，方便对照：

7.2 显存与吞吐的平衡：几个实测数据

实测中我发现，--max-num-seqs从 8 提到 16，吞吐能涨约 40%，但延迟也涨了 20% 左右。再往上提到 32，吞吐涨幅放缓到 10%，延迟却涨了 50%。所以 16 是个比较甜的平衡点。

显存利用率从 0.85 提到 0.9，吞吐提升不明显，但 OOM 风险明显上升。所以除非显存特别紧张，否则 0.85 更稳。

这些数据因模型和硬件而异，但调优思路是通用的：先找吞吐瓶颈，再找延迟拐点，最后留安全余量。

7.3 长期运行的稳定性观察点

服务跑起来只是开始，长期稳定才是目标。我重点观察三个指标：显存占用是否随时间上涨（内存泄漏）、GPU 温度是否过高（散热问题）、请求延迟是否有长尾（调度问题）。

显存缓慢上涨往往是 KV Cache 没释放干净，可以通过定期重启或升级 vLLM 版本缓解。GPU 温度超过 85 度要考虑机箱散热。延迟长尾通常是某些超长请求拖累了批处理，可以通过限制单请求长度来改善。

8. 一些个人体会

这套流程走下来，我最大的感受是：内网离线部署的难点不在单点技术，而在“全链路可控”。外网环境里，任何一个环节出问题都能快速查、快速补；内网里，你只能靠构建阶段就把所有变量固化。

15GB 的镜像听起来大，但拆开看每一部分都有存在的理由。真正能优化的是构建方式——分层、清缓存、单层打包权重，这些做下来能省不少。GPU 调优也别追求极限，稳定比峰值重要，留余量比榨干显存划算。

最后分享一个小技巧：构建镜像时在 Dockerfile 里加一行LABEL build_date和LABEL git_commit，把构建时间和代码版本记进去。内网排查问题时，这一行标签能帮你快速确认“这台机器上跑的到底是哪个版本”，省去很多扯皮。