3、vLLM镜像构建：Dockerfile编写、基础镜像选择、依赖安装、模型文件打包、镜像优化与瘦身
镜像构建这件事，说白了就是给模型搭一个「运行环境集装箱」。你想想看，K8s 里跑 vLLM 多副本，每个 Pod 都得有一模一样的依赖、库、甚至模型文件。如果镜像没搞好，轻则启动失败，重则副本间行为不一致——我在生产环境里踩过这个坑，后来才明白镜像构建才是多副本部署的基石。
3.1 基础镜像选择：别贪大，也别图省事
基础镜像选错了，后面所有优化都是白费力气。我个人习惯遵循一个原则：够用就好，越小越安全。
vLLM 依赖 CUDA 和 PyTorch，所以基础镜像必须带 CUDA 运行时。常见的选项有这几个：
| 镜像类型 | 大小（约） | 适用场景 |
|---|---|---|
| nvidia/cuda:12.1.0-runtime-ubuntu22.04 | ~1.5GB | 生产环境，仅运行时 |
| nvidia/cuda:12.1.0-devel-ubuntu22.04 | ~3.2GB | 开发/调试，包含编译工具 |
| pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime | ~4.5GB | 省事但臃肿，不推荐生产 |
我建议选 runtime 版本，别碰 devel。为什么？devel 镜像里塞了一堆 gcc、make、头文件，这些在推理服务里根本用不上。我曾经为了省事直接用了 PyTorch 官方镜像，结果镜像体积飙到 5GB 以上，K8s 拉取慢得让人抓狂。
3.2 Dockerfile 编写：分层构建的艺术
Dockerfile 写得好不好，直接决定了镜像的构建速度和最终体积。我习惯把 Dockerfile 分成三层：系统层、依赖层、应用层。
下面是我在生产环境中用过的 Dockerfile 模板：
# ===== 第一层：系统层 =====
FROM nvidia/cuda:12.1.0-runtime-ubuntu22.04 AS base
RUN apt-get update && apt-get install -y --no-install-recommends \
python3.10 \
python3-pip \
curl \
&& rm -rf /var/lib/apt/lists/*
# ===== 第二层：依赖层 =====
FROM base AS dependencies
# 先装 PyTorch，利用 Docker 缓存
RUN pip3 install --no-cache-dir torch==2.1.0 --index-url https://download.pytorch.org/whl/cu121
# 再装 vLLM 核心依赖
RUN pip3 install --no-cache-dir \
vllm==0.4.0 \
transformers==4.36.0 \
accelerate==0.25.0
# ===== 第三层：应用层 =====
FROM dependencies AS final
WORKDIR /app
# 复制启动脚本和配置文件
COPY entrypoint.sh /app/
COPY config.json /app/
RUN chmod +x /app/entrypoint.sh
ENTRYPOINT ["/app/entrypoint.sh"]注意看，我用了多阶段构建（AS base、AS dependencies）。这样做的目的是：把依赖安装和最终镜像分离。如果你后续只改启动脚本，Docker 会直接命中缓存，秒级完成构建。
3.3 依赖安装：版本锁定是底线
依赖安装看似简单，其实最容易出幺蛾子。你想想看，vLLM 对 PyTorch 版本非常敏感，PyTorch 又对 CUDA 版本敏感。一旦某个依赖自动升级了，整个服务可能就崩了。
我的做法是：用 requirements.txt 锁定所有依赖的精确版本。
# requirements.txt
torch==2.1.0
vllm==0.4.0
transformers==4.36.0
accelerate==0.25.0
sentencepiece==0.1.99
ninja==1.11.1 # vLLM 编译需要
psutil==5.9.6
ray==2.9.0 # 多副本分布式需要然后在 Dockerfile 里这样装：
COPY requirements.txt /tmp/
RUN pip3 install --no-cache-dir -r /tmp/requirements.txt为什么要用 --no-cache-dir？因为 pip 的缓存目录会占用镜像空间，而且这些缓存对运行时毫无用处。我见过一个同事的镜像里 pip 缓存占了 800MB，镜像体积直接翻倍。
3.4 模型文件打包：别一股脑塞进去
模型文件怎么处理？这是个灵魂拷问。vLLM 支持从 Hugging Face 在线加载模型，但在生产环境里，我强烈建议把模型文件打包进镜像或者挂载到 PVC 里。
为什么？因为在线下载太不可控了。我曾经遇到 Hugging Face 网络波动，Pod 启动花了 20 分钟，就因为模型下载超时重试了好几次。
打包进镜像的做法：
# 在 Dockerfile 中
COPY ./models/ /app/models/
# 启动时指定模型路径
ENTRYPOINT ["python3", "-m", "vllm.entrypoints.openai.api_server", \
"--model", "/app/models/llama-2-7b-chat"]但要注意：大模型文件会让镜像变得巨大。一个 7B 模型大约 13GB，13B 模型约 25GB。如果每个副本都拉取这么大的镜像，K8s 节点磁盘会很快被打满。
3.5 镜像优化与瘦身：从 5GB 到 2GB 的实战
镜像瘦身是门手艺活。我接手过一个 vLLM 镜像，体积 5.2GB，拉取一次要 3 分钟。经过优化后，瘦到了 1.8GB。怎么做到的？
核心思路就四个字：删、换、合、拆。
- 删：删除 apt 缓存、pip 缓存、临时文件。在 Dockerfile 里用
&& rm -rf /var/lib/apt/lists/*清理。 - 换：把
devel镜像换成runtime镜像，体积直接砍半。 - 合：把多个 RUN 指令合并成一个，减少镜像层数。但别过度合并，否则缓存策略会失效。
- 拆：用多阶段构建，把编译产物和运行产物分离。
下面这张图展示了镜像瘦身的核心逻辑：
除了上面这些，还有一个容易被忽略的点：基础镜像的 tag 要固定。别用 latest，否则哪天基础镜像更新了，你的构建可能就失败了。我习惯用 nvidia/cuda:12.1.0-runtime-ubuntu22.04 这种精确到小版本的 tag。
docker-slim 对最终镜像做一次自动瘦身。它能分析出哪些文件是运行时真正需要的，然后生成一个最小化镜像。我在测试环境试过，能把 1.8GB 再压到 1.2GB 左右。
3.6 构建与验证：别等到部署才发现问题
镜像构建完了，别急着 push。先做三件事验证：
- 本地启动测试：
docker run --gpus all your-image，看看 vLLM 能不能正常加载模型。 - 检查镜像层数：
docker history your-image，确保没有多余的层。理想情况是 10-15 层。 - 扫描安全漏洞：用
trivy image your-image扫一遍，高危漏洞必须修复。
我记得有一次，镜像在本地跑得好好的，推到 K8s 里就报 CUDA 版本不匹配。查了半天，发现是基础镜像的 CUDA 版本和节点驱动版本不一致。从那以后，我每次构建前都会先确认节点驱动版本：nvidia-smi 查看驱动版本，然后选对应的 CUDA 镜像。
嗯，镜像构建这部分就这些了。记住一句话：镜像越小，部署越快，问题越少。你花在瘦身上的每一分钟，都会在后续的部署和运维中加倍回报给你。