# PR #45401 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[Bugfix][CPU] Don't build triton-cpu on arm64 release image
- 合并时间：2026-06-13 05:51
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/45401

---

# 执行摘要

- 一句话：修复 arm64 CPU 镜像构建失败问题
- 推荐动作：此 PR 为轻量级构建修复，建议精读以了解 Docker 多阶段构建中变量继承的陷阱，可记录为团队知识点。

# 功能与动机

arm64 CPU 发布镜像构建失败，错误信息为 `_Float16` 未定义，原因在于 `triton-cpu` 是 x86-only 组件，不应在 arm64 上编译。根本原因是在 #43977 引入的新阶段中，`VLLM_CPU_X86` 变量未被正确继承，导致 guard 逻辑失效。

# 实现拆解

1. **定位问题**：`vllm-triton-cpu-build` 和 `vllm-openai` 阶段均 `FROM base`（而非 `FROM vllm-build`），因此无法继承 `vllm-build` 阶段中声明的 `ARG VLLM_CPU_X86=0`，导致变量为空字符串，guard 条件在 arm64 上误判为真。
2. **修复方案**：在两个缺失的阶段中分别添加 `ARG VLLM_CPU_X86=0` 声明，并附带注释说明原因。
3. **验证**：通过模拟不同架构和构建参数组合，确认修复后 guard 逻辑正确，且不影响 amd64 正常构建和显式 x86 交叉编译场景。

关键文件：
- `docker/Dockerfile.cpu`（模块 部署脚本；类别 infra；类型 infrastructure）: 核心变更文件，修复了多阶段构建中变量继承的缺失，在 two 个阶段中添加了 `ARG VLLM_CPU_X86=0`。

关键符号：未识别

## 关键源码片段

### `docker/Dockerfile.cpu`

核心变更文件，修复了多阶段构建中变量继承的缺失，在 two 个阶段中添加了 `ARG VLLM_CPU_X86=0`。

```dockerfile
# docker/Dockerfile.cpu 相关片段 (diff 上下文 )

# 原有构建阶段 vllm-build 中声明了 VLLM_CPU_X86
# 但 vllm-triton-cpu-build 和 vllm-openai 阶段 FROM base，未继承

######################### TRITON-CPU BUILD IMAGE #########################
FROM base AS vllm-triton-cpu-build
# 修复：重新声明 ARG，默认值 0，使得 guard 在 arm64 上生效
# 之前此处缺失，导致 $VLLM_CPU_X86 为空，guard 错误通过
ARG VLLM_CPU_X86=0

WORKDIR /vllm-workspace
RUN mkdir dist

# ... 之后 guard 逻辑中判断 TARGETARCH 和 VLLM_CPU_X86，决策是否构建 triton-cpu

######################### RELEASE IMAGE #########################
FROM base AS vllm-openai
# 同样重新声明，确保最终镜像安装阶段也正确跳过 arm64
ARG VLLM_CPU_X86=0

WORKDIR /vllm-workspace
# ... 后续根据 $VLLM_CPU_X86 决定是否复制并安装 triton-cpu wheel

```

# 评论区精华

无讨论。两位 reviewer 均直接批准，其中一位承认是自己之前的疏漏。

- 暂无高价值评论线程

# 风险与影响

- 风险：修复仅涉及 Dockerfile 中的变量声明，无代码逻辑变更。主要风险是新增的 ARG 声明可能影响原本期望空值行为的场景，但由于显式设为 `0`，与 `vllm-build` 阶段的默认行为一致，风险极低。
- 影响：直接影响 arm64 CPU 发布镜像的构建流程，修复后 arm64 镜像应能正常完成构建。对 amd64 构建无影响，对显式交叉编译场景无影响。
- 风险标记：构建流程修复 , 低影响

# 关联脉络

- PR #43977 [ 未指定标题 ]: 引入 `vllm-triton-cpu-build` 阶段的 PR，导致了本 PR 修复的变量继承问题。