#50314 [CI] Zen5 image build

原始 PR 作者 andy-neuma 合并时间 2026-09-04 05:34 文件变更 2 提交数 5 评论 20 代码增减 +98 / -17

执行摘要

将 Zen CPU 镜像构建独立为专用 Dockerfile，使其具备独立的构建目标与 CI 流程。

根据 PR body 描述，主要动机是将 Zen 镜像构建从通用的 CPU 镜像文件中解耦出来，为其提供独立的 Dockerfile、构建脚本和 CI 步骤。这符合关注点分离原则，有助于 Zen5 专项镜像的独立演进、测试和维护，避免对通用 CPU 镜像产生不必要的影响。

这是一个标准的、有意义的 基础设施重构 PR。其核心价值在于清晰地分离了构建关注点，使得为 AMD Zen CPU 构建定制化 vLLM 镜像有了一个独立、可维护的入口。代码变更本身质量良好，关键逻辑（如平台检查、依赖安装、测试环境准备）清晰。建议精读 docker/Dockerfile.zen 文件，了解其如何通过分层构建实现服务与测试镜像的目标，以及如何通过构建参数控制 zentorch 版本。同时，关注其与 docker/Dockerfile.cpu 的关系，理解依赖链。虽然部分自动化审查建议未采纳，但其中关于版本锁定和非 root 用户运行的建议，是后续可考虑的安全与健壮性改进方向。

讨论亮点

PR 标签问题：维护者 amukho 多次提醒 PR 作者 andy-neuma 需要更新标题以包含有效的 [CPU] 或 [CPU][Zen] 标签，否则 CI 检查会失败。这是确保 PR 能被正确分类和触发必要检查的关键一步。2. 构建触发器与队列选择：在 .buildkite/image_build/image_build.yaml 文件的讨论中，amukho 指出 ROCm 团队建议使用 amd-cpu 队列，而非 PR 中初步设定的 small_cpu_queue_premerge。andy-neuma 回应称当前 PR 仅作为镜像定义，构建触发将在确定合适的“家”之后通过另一个 PR 添加。这反映了 CI 基础设施变更需要协调多方（CPU、ROCm团队）意见的特点。3. CodeRabbit 自动化审查建议：自动化工具提出了多项改进建议，如添加 ARG PYTHON_VERSION、以非 root 用户运行、设置默认构建目标、以及在未固定 ZENTORCH_VERSION 时重新安装以锁定版本。然而，这些建议并未全部被采纳，可能因为项目已有惯例（如基础镜像已是 root）、优先级考虑或与作者的设计意图不符。

实现拆解

核心文件新增与重构：新增 docker/Dockerfile.zen 作为 Zen 镜像的构建入口。该文件定义了两个阶段：vllm-openai-zen 阶段继承自外部 BASE_IMAGE（即已构建好的 vLLM CPU 镜像），通过 uv pip install 安装 zentorch 或指定版本，并添加了详细的 OCI 标签。vllm-zen-test 阶段继承自 vllm-openai-zen，专门用于 CI 测试，它会复制测试代码、配置专用的测试依赖（如创建并编译 requirements/test/zen.in，将 torch 版本固定为 2.13.0），并强制重新安装 zentorch 以确保版本一致性。2. 旧实现清理：修改 docker/Dockerfile.cpu，删除了其中原有的 vllm-openai-zen 构建阶段及其注释（共计删除17行），完成职责剥离。3. CI 配置（未包含在最终合入）：在提交历史和讨论中可见，PR 曾尝试在 .buildkite/image_build/image_build.yaml 中添加一个名为 image-build-zen-cpu 的构建步骤，该步骤依赖于 image-build-cpu，并固定在 small_cpu_queue_premerge 队列上。但此改动在最终提交 1be2d49b 中被移除。根据作者和维护者的讨论，构建触发器将作为独立 PR 添加。

文件	模块	状态	重要度
`docker/Dockerfile.zen`	构建镜像	added	5.61
`docker/Dockerfile.cpu`	构建镜像	modified	3.98

关键源码片段

docker/Dockerfile.zen infrastructure

新增的、核心的构建文件，定义了 AMD Zen CPU 专用的 vLLM 服务与测试 Docker 镜像，是本次 PR 变更的主体。

# Dockerfile.zen 核心构建逻辑示例：从基线镜像构建 Zen 测试镜像
# 继承自已包含 vLLM 的 vllm-openai-zen 服务镜像
FROM vllm-openai-zen AS vllm-zen-test

WORKDIR /vllm-workspace

# 复制测试与构建所需的文件
COPY requirements/common.txt requirements/common.txt
COPY requirements/test/cuda.in requirements/test/zen.in

# 通过 sed 动态修改依赖文件：
# 1. 移除 mamba_ssm 依赖（不兼容或不需要）
# 2. 将 torch 版本固定为 2.13.0
# 3. 放宽 torchaudio/torchvision 版本限制
# 4. 固定 sentence-transformers 版本以保证与 zentorch 的兼容性
RUN sed -i '/mamba_ssm/d' requirements/test/zen.in && \
    sed -i 's/^torch==.*/torch==2.13.0/g' requirements/test/zen.in && \
    sed -i 's/torchaudio.*/torchaudio/g' requirements/test/zen.in && \
    sed -i 's/torchvision.*/torchvision/g' requirements/test/zen.in && \
    sed -i 's/^sentence-transformers.*/sentence-transformers==5.3.0/g' requirements/test/zen.in && \
    # 编译生成锁定后的依赖文件
    uv pip compile requirements/test/zen.in \
    -o requirements/test/zen.txt \
    --index-strategy unsafe-best-match --torch-backend cpu

# 安装测试依赖，并确保 zentorch 的 torch 版本被正确覆盖
RUN --mount=type=cache,target=/root/.cache/uv \
    uv pip install -r requirements/test/zen.txt --torch-backend cpu && \
    if [ -n "${ZENTORCH_VERSION}" ]; then \
        uv pip install --force-reinstall --no-deps "zentorch==${ZENTORCH_VERSION}"; \
    else \
        uv pip install --force-reinstall --no-deps "vllm[zen]"; \
    fi

# 添加测试代码、示例和基准测试等
ADD ./tests/ ./tests/
ADD ./examples/ ./examples/
ADD ./benchmarks/ ./benchmarks/
# ... 其他 ADD 指令与 pip install ...

评论区精华

PR 标签与 CI 检查失败 other

维护者 `amukho` 指出 CI 因缺少有效标签（如 `[CPU]`）而失败，并提醒作者更新 PR 标题。作者 `andy-neuma` 后续完成了标题更新。

结论：PR 标题必须包含符合仓库规范的标签才能通过 CI 检查，这是项目工作流的强制要求。 · 已解决

CI 构建触发器的后续安排 设计

讨论聚焦于 `.buildkite/image_build/image_build.yaml` 中 `image-build-zen-cpu` 步骤的队列选择（`small_cpu_queue_premerge` vs `amd-cpu`）。最终决定本 PR 只合并镜像定义文件，构建触发器的添加将推迟到下一个 PR，并确定合适的构建队列。

结论：基础设施变更（镜像定义与 CI 触发）可以分步进行。当前 PR 的范围被限定为仅提供 Dockerfile。 · 已解决（移出范围）

风险与影响

依赖版本管理风险：Dockerfile.zen 中 vllm-zen-test 阶段通过 sed 命令动态修改 requirements/test/zen.in 以固定 torch 等依赖版本（如 torch==2.13.0）。这种方式相对脆弱，如果上游依赖文件格式发生变化，可能导致构建失败。同时，它引入了与 Dockerfile.cpu 可能不一致的依赖版本管理逻辑。2.构建流程完整性风险：最终合入的代码仅包含镜像定义（Dockerfile.zen），移除了原有的 CI 构建步骤。这意味着在下一个 PR 将构建触发器添加回来之前，该 Dockerfile 不会被自动构建和测试，存在“定义与触发脱节”的窗口期。3. 安全性与最佳实践：自动化审查指出 Dockerfile.zen 以 root 用户运行 vllm serve，这是一个潜在的安全风险（CWE-250）。虽然该风险继承自基础镜像且符合当前项目惯例，但作为新引入的独立 Dockerfile，这是一个可以改进的点。

对团队：正面影响。将 Zen 镜像构建独立化，使其演进、测试和问题排查与通用 CPU 镜像解耦，降低了维护复杂性，为后续针对 Zen5 硬件的优化测试奠定了清晰的基础设施基础。2.对系统：无直接运行时影响。此变更是构建时（build-time）和部署流程的调整。新的 vllm-openai-zen 镜像功能应与之前版本一致，但构建方式更独立。3. 对用户：暂时无直接影响。最终用户使用到的 Zen 服务镜像在内容上可能没有变化，但未来镜像的更新和维护会因构建流程优化而受益。4.依赖关系**：创建了对 docker/Dockerfile.cpu 产出的 BASE_IMAGE 的显式依赖（通过 ARG BASE_IMAGE），这使得镜像构建链路更加清晰，但也要求 Dockerfile.cpu 必须先成功构建。

依赖版本管理 CI 配置不完整

关联 Issue

未识别关联 Issue

当前没有检测到明确关联的 Issue 链接，后续同步到相关引用后会出现在这里。

完整报告

执行摘要

一句话：将 Zen CPU 镜像构建独立为专用 Dockerfile，使其具备独立的构建目标与 CI 流程。
推荐动作：这是一个标准的、有意义的 基础设施重构 PR。其核心价值在于清晰地分离了构建关注点，使得为 AMD Zen CPU 构建定制化 vLLM 镜像有了一个独立、可维护的入口。代码变更本身质量良好，关键逻辑（如平台检查、依赖安装、测试环境准备）清晰。建议精读 docker/Dockerfile.zen 文件，了解其如何通过分层构建实现服务与测试镜像的目标，以及如何通过构建参数控制 zentorch 版本。同时，关注其与 docker/Dockerfile.cpu 的关系，理解依赖链。虽然部分自动化审查建议未采纳，但其中关于版本锁定和非 root 用户运行的建议，是后续可考虑的安全与健壮性改进方向。

功能与动机

实现拆解

核心文件新增与重构：新增 docker/Dockerfile.zen 作为 Zen 镜像的构建入口。该文件定义了两个阶段：vllm-openai-zen 阶段继承自外部 BASE_IMAGE（即已构建好的 vLLM CPU 镜像），通过 uv pip install 安装 zentorch 或指定版本，并添加了详细的 OCI 标签。vllm-zen-test 阶段继承自 vllm-openai-zen，专门用于 CI 测试，它会复制测试代码、配置专用的测试依赖（如创建并编译 requirements/test/zen.in，将 torch 版本固定为 2.13.0），并强制重新安装 zentorch 以确保版本一致性。2. 旧实现清理：修改 docker/Dockerfile.cpu，删除了其中原有的 vllm-openai-zen 构建阶段及其注释（共计删除17行），完成职责剥离。3. CI 配置（未包含在最终合入）：在提交历史和讨论中可见，PR 曾尝试在 .buildkite/image_build/image_build.yaml 中添加一个名为 image-build-zen-cpu 的构建步骤，该步骤依赖于 image-build-cpu，并固定在 small_cpu_queue_premerge 队列上。但此改动在最终提交 1be2d49b 中被移除。根据作者和维护者的讨论，构建触发器将作为独立 PR 添加。

关键文件：

docker/Dockerfile.zen（模块构建镜像；类别 infra；类型 infrastructure）: 新增的、核心的构建文件，定义了 AMD Zen CPU 专用的 vLLM 服务与测试 Docker 镜像，是本次 PR 变更的主体。
docker/Dockerfile.cpu（模块构建镜像；类别 infra；类型 infrastructure）: 被修改以移除旧的 Zen 镜像构建阶段，完成与新 Dockerfile.zen 的职责剥离。

关键符号：未识别

关键源码片段

`docker/Dockerfile.zen`

新增的、核心的构建文件，定义了 AMD Zen CPU 专用的 vLLM 服务与测试 Docker 镜像，是本次 PR 变更的主体。

# Dockerfile.zen 核心构建逻辑示例：从基线镜像构建 Zen 测试镜像
# 继承自已包含 vLLM 的 vllm-openai-zen 服务镜像
FROM vllm-openai-zen AS vllm-zen-test

WORKDIR /vllm-workspace

# 复制测试与构建所需的文件
COPY requirements/common.txt requirements/common.txt
COPY requirements/test/cuda.in requirements/test/zen.in

# 通过 sed 动态修改依赖文件：
# 1. 移除 mamba_ssm 依赖（不兼容或不需要）
# 2. 将 torch 版本固定为 2.13.0
# 3. 放宽 torchaudio/torchvision 版本限制
# 4. 固定 sentence-transformers 版本以保证与 zentorch 的兼容性
RUN sed -i '/mamba_ssm/d' requirements/test/zen.in && \
    sed -i 's/^torch==.*/torch==2.13.0/g' requirements/test/zen.in && \
    sed -i 's/torchaudio.*/torchaudio/g' requirements/test/zen.in && \
    sed -i 's/torchvision.*/torchvision/g' requirements/test/zen.in && \
    sed -i 's/^sentence-transformers.*/sentence-transformers==5.3.0/g' requirements/test/zen.in && \
    # 编译生成锁定后的依赖文件
    uv pip compile requirements/test/zen.in \
    -o requirements/test/zen.txt \
    --index-strategy unsafe-best-match --torch-backend cpu

# 安装测试依赖，并确保 zentorch 的 torch 版本被正确覆盖
RUN --mount=type=cache,target=/root/.cache/uv \
    uv pip install -r requirements/test/zen.txt --torch-backend cpu && \
    if [ -n "${ZENTORCH_VERSION}" ]; then \
        uv pip install --force-reinstall --no-deps "zentorch==${ZENTORCH_VERSION}"; \
    else \
        uv pip install --force-reinstall --no-deps "vllm[zen]"; \
    fi

# 添加测试代码、示例和基准测试等
ADD ./tests/ ./tests/
ADD ./examples/ ./examples/
ADD ./benchmarks/ ./benchmarks/
# ... 其他 ADD 指令与 pip install ...

评论区精华

PR 标签问题：维护者 amukho 多次提醒 PR 作者 andy-neuma 需要更新标题以包含有效的 [CPU] 或 [CPU][Zen] 标签，否则 CI 检查会失败。这是确保 PR 能被正确分类和触发必要检查的关键一步。2. 构建触发器与队列选择：在 .buildkite/image_build/image_build.yaml 文件的讨论中，amukho 指出 ROCm 团队建议使用 amd-cpu 队列，而非 PR 中初步设定的 small_cpu_queue_premerge。andy-neuma 回应称当前 PR 仅作为镜像定义，构建触发将在确定合适的“家”之后通过另一个 PR 添加。这反映了 CI 基础设施变更需要协调多方（CPU、ROCm团队）意见的特点。3. CodeRabbit 自动化审查建议：自动化工具提出了多项改进建议，如添加 ARG PYTHON_VERSION、以非 root 用户运行、设置默认构建目标、以及在未固定 ZENTORCH_VERSION 时重新安装以锁定版本。然而，这些建议并未全部被采纳，可能因为项目已有惯例（如基础镜像已是 root）、优先级考虑或与作者的设计意图不符。

PR 标签与 CI 检查失败 (other): PR 标题必须包含符合仓库规范的标签才能通过 CI 检查，这是项目工作流的强制要求。
CI 构建触发器的后续安排 (design): 基础设施变更（镜像定义与 CI 触发）可以分步进行。当前 PR 的范围被限定为仅提供 Dockerfile。

风险与影响

风险：
1. 依赖版本管理风险：Dockerfile.zen 中 vllm-zen-test 阶段通过 sed 命令动态修改 requirements/test/zen.in 以固定 torch 等依赖版本（如 torch==2.13.0）。这种方式相对脆弱，如果上游依赖文件格式发生变化，可能导致构建失败。同时，它引入了与 Dockerfile.cpu 可能不一致的依赖版本管理逻辑。2.构建流程完整性风险：最终合入的代码仅包含镜像定义（Dockerfile.zen），移除了原有的 CI 构建步骤。这意味着在下一个 PR 将构建触发器添加回来之前，该 Dockerfile 不会被自动构建和测试，存在“定义与触发脱节”的窗口期。3. 安全性与最佳实践：自动化审查指出 Dockerfile.zen 以 root 用户运行 vllm serve，这是一个潜在的安全风险（CWE-250）。虽然该风险继承自基础镜像且符合当前项目惯例，但作为新引入的独立 Dockerfile，这是一个可以改进的点。
影响：
1. 对团队：正面影响。将 Zen 镜像构建独立化，使其演进、测试和问题排查与通用 CPU 镜像解耦，降低了维护复杂性，为后续针对 Zen5 硬件的优化测试奠定了清晰的基础设施基础。2.对系统：无直接运行时影响。此变更是构建时（build-time）和部署流程的调整。新的 vllm-openai-zen 镜像功能应与之前版本一致，但构建方式更独立。3. 对用户：暂时无直接影响。最终用户使用到的 Zen 服务镜像在内容上可能没有变化，但未来镜像的更新和维护会因构建流程优化而受益。4.依赖关系**：创建了对 docker/Dockerfile.cpu 产出的 BASE_IMAGE 的显式依赖（通过 ARG BASE_IMAGE），这使得镜像构建链路更加清晰，但也要求 Dockerfile.cpu 必须先成功构建。
  - 风险标记：依赖版本管理, CI 配置不完整

关联脉络

PR #55094 [CI][AMD] Avoid expandable segments in LoRA TP tests: 同属于 CI/CD 基础设施的维护与修复，涉及 AMD 测试环境配置。表明项目持续在优化和清理其 CI 配置。

#50314 [CI] Zen5 image build

执行摘要

将 Zen CPU 镜像构建独立为专用 Dockerfile，使其具备独立的构建目标与 CI 流程。

实现拆解

评论区精华

风险与影响

关联 Issue

未识别关联 Issue

完整报告

参与讨论