Docker 部署 TGI 时版本固定与镜像分层缓存优化构建时间

要在 Docker 部署 TGI（Text Generation Inference）时同时解决版本可复现和构建时间过长的问题，核心思路是把“镜像版本固定”和“构建层缓存复用”分成两件事处理：前者决定你线上跑的是哪一份代码，后者决定你每次改代码后要等多久才能拿到新镜像。版本固定主要靠镜像标签和 Digest 双重锁定；构建时间优化则靠 Dockerfile 分层顺序、依赖项提前缓存和可选的 BuildKit 特性。这两件事不互相冲突，但需要各自单独设计。

建议把 TGI 服务镜像拆成基础依赖层、模型服务层、启动配置层三段来写 Dockerfile。版本固定使用镜像 Digest 或精确版本标签，配合 Lockfile 保存依赖哈希。构建时优先让不常变化的层先构建，并利用 Docker BuildKit 的缓存挂载和远程缓存机制。优化效果需要结合镜像仓库网络和代码变更频率自行测量，不应凭经验套用固定收益。

先固定版本：标签和 Digest 要分开用

TGI 官方镜像通常提供多种标签，常见做法是只使用语义化版本号，例如 1.4.0，而不是 latest。但仅仅使用版本标签仍有风险：同一版本号的镜像可能被重新推送，或者对应不同的平台架构。更严格的锁定方式是在部署清单和基础镜像引用中使用 Digest 地址，形如 ghcr.io/huggingface/text-generation-inference@sha256:xxxx。Digest 指向镜像不可变内容，只要仓库不重新构建，拉取到的内容就不会变化。

如果你需要在自己镜像里继承基础镜像，建议在 Dockerfile 里通过 ARG 传入完整镜像引用，并把 Digest 写在构建参数中。这样升级时只需改一个变量，并且构建日志能看到实际解析结果。验证方式是构建后运行 docker inspect `--format` '{{.Image}}' <container_id> 或使用 docker image inspect `--format` '{{index .RepoDigests 0}}' 查看 Digest 是否与预期一致。注意：不同镜像仓库可能对 Digest 订阅有访问控制，需要结合仓库权限确认。

镜像分层缓存：把不变的层放在前面

Docker 构建缓存按指令逐层判断，如果某一层没有变化，后续未变化的层可以直接复用。对 TGI 这类服务，最容易变化的文件是服务源码、自定义配置和启动脚本；依赖库和系统包通常相对稳定。所以 Dockerfile 顺序应参考以下骨架：

# 阶段一：基础依赖层
FROM ghcr.io/huggingface/text-generation-inference:1.4.0 AS base
# 阶段二：安装 Python 依赖（先复制 requirements，再复制源码）
COPY requirements.txt /tmp/requirements.txt
RUN pip install `--no-cache-dir` -r /tmp/requirements.txt
# 阶段三：复制服务代码
COPY ./src /app/src
COPY ./config /app/config
# 阶段四：设置启动配置
ENV HF_HUB_ENABLE_HF_TRANSFER=1
CMD ["text-generation-launcher"]

这种写法下，修改 src 里文件时，前三层还在缓存中；如果改了 requirements.txt，则 RUN pip install 及后续层都会失效。需要先确认你的依赖文件是否稳定，如果经常增减依赖，则应把依赖安装单独抽出，并用额外的锁文件冻结依赖版本。验证缓存是否生效，可以在构建日志中观察 CACHED 标记；如果某层显示 Running，说明该层及后续层都需要重新执行。

启用 BuildKit 与缓存挂载

Docker 默认的 legacy builder 对缓存处理较弱，建议显式开启 BuildKit。构建命令前加上环境变量 DOCKER_BUILDKIT=1，或直接在 Docker 配置中设置构建器为 BuildKit。BuildKit 支持更细粒度的缓存挂载，适合依赖体积大的场景。以 TGI 常见的 Hugging Face 缓存为例，可以把模型下载缓存挂载到 RUN 中：

# syntax=docker/dockerfile:1.4
FROM ghcr.io/huggingface/text-generation-inference:1.4.0 AS builder
RUN `--mount`=type=cache,target=/root/.cache/huggingface \
    python -c "from huggingface_hub import snapshot_download; snapshot_download(repo_id='your-model-id')"

这里 `--mount`=type=cache 使得同一台机器上多次构建时，/root/.cache/huggingface 目录会保留，不会因为清理构建上下文而丢失。但需要注意两个边界：缓存挂载中的内容不会出现在最终镜像里，如果模型需要在运行时被加载，仍需要通过单独的 COPY 或卷挂载引入；另外，分布式构建时缓存默认是本地共享，不会跨构建节点自动同步，需要配置 registry 作为缓存源。

用远程缓存优化 CI 中的重复构建

团队协作时，本地缓存不能覆盖所有机器。可以把构建缓存推送到镜像仓库，使用 `--cache-from` 和 `--cache-to` 参数。BuildKit 支持 inline 缓存和 registry cache，后者在 CI 中更常用。构建命令类似：

docker buildx build `--cache-from` type=registry,ref=registry.example.com/tgi/cache:buildcache \
                     `--cache-to` type=registry,ref=registry.example.com/tgi/cache:buildcache,mode=max \
                     -t registry.example.com/tgi:latest .

这种方式下，每次 CI 构建都会先拉取远程缓存，没有变化的层直接复用。需要结合自己的镜像仓库容量和拉取耗时来判断是否划算：如果仓库网络延迟很高，缓存拉取带来的时间消耗可能抵消节省的构建时间。建议先用小样本记录一次全量构建时间和一次带远程缓存的增量构建时间，再决定是否投入。

验证清单与风险边界

版本固定是否生效：用 docker image inspect 查看 RepoDigests，确认部署镜像的标签和 Digest 都指向预期内容。
缓存层是否被复用：在构建日志中搜索 CACHED 标记，确认修改源码后依赖层没有被重新执行。
缓存是否有副作用：使用 cache mount 后，注意最终镜像大小和运行时行为；如果模型文件只存在于缓存挂载中，部署到新机器时会缺少文件。
构建时间测量：不要只看一次构建，至少对比三次相同代码的构建时间，避免网络波动干扰。

镜像分层缓存优化不是独立的优化项，它依赖 Dockerfile 的结构、依赖文件的稳定度和构建环境的一致性。版本固定则是独立的安全动作，两者最好同时落地：先锁定基础镜像的 Digest，再通过分层缓存优化迭代速度。如果后续需要跨平台构建或推送多架构镜像，还需要考虑 buildx 的具体配置，这部分要结合你的目标平台逐一确认。