为了在 ROCm 镜像中开箱即用地使用 MooncakeConnector 和 MooncakeStoreConnector KV 传输连接器，需要为 vLLM ROCm 构建添加 AMD ROCm 对 Mooncake 的支持。这解决了 issue #51193。相关的是 LMCache 在 #51208 中的添加，并遵循了已有的在镜像内从源码构建 wheel 的模式（例如用于 aiter、MoRI 和 FlashAttention）。这是一个短期解决方案：一旦 Mooncake 发布了官方 ROCm wheel，这个阶段就可以被替换。(引自 PR body)。核心动机是让依赖 Mooncake 的分布式推理和 KV 缓存卸载功能在 ROCm 环境下可用，而无需用户手动构建依赖项。commit SHA pinning（df508641d76be20803349bf715d3bfc5205a7b58）的原因是 ROCm 构建支持已合并至上游（kvcache-ai/Mooncake#3184）但尚未随 tag 发布，使用 tag 会静默生成 CUDA 版本的 wheel。为解决上游 dependencies.sh 安装的旧版 patchelf (0.14.3) 在 auditwheel repair 时损坏 RPATH 的 bug，本 PR 在构建约束中强制安装 patchelf>=0.17 进行覆盖，确保 wheel 在目标镜像中能正确导入共享库。最后，通过设置 PLATFORM_TAG=auto，避免了因基础镜像 gcc-13 libstdc++ 版本导致的 manylinux 策略不兼容问题，使生成的 wheel 能在基于 glibc 2.35 的镜像中正常安装和使用。上游 Mooncake ROCm CI 的烟雾测试只验证了 mooncake_master --version，未测试 Python 模块导入，因此上述 RPATH 问题未能被其捕获，而本 PR 的测试计划涵盖了完整的导入和功能验证。这些决策共同确保了 Mooncake ROCm wheel 构建的正确性和在 vLLM 镜像中的可用性。影响范围包括 ROCm 用户的部署体验和 CI 构建流程。

本 PR 是一个有意义的基础设施变更，为 ROCm 生态补全了重要的 KV 传输能力。它本身不是核心功能或性能优化，因此对于不关注 ROCm 部署或 KV 连接器的开发者，精读价值中等。然而，其构建策略（如何安全地集成一个上游尚未正式发布的依赖、处理上游构建脚本的 bug、利用 Docker 多阶段构建和 CI 缓存）值得所有负责维护构建系统的工程师关注。特别是强制升级 patchelf 以修复 silent failure、使用 commit SHA pinning、以及将依赖构建与缓存分离的模式，是处理类似情况的良好实践。建议 ROCm 团队和 CI 维护者仔细审阅其 Dockerfile 和缓存逻辑。

实现过程分为四个主要步骤，涉及三个关键文件的协同修改。

1. 定义构建参数与来源：在 docker/Dockerfile.rocm 顶部新增 MOONCAKE_BRANCH, MOONCAKE_REPO, MOONCAKE_GO_VERSION, MOONCAKE_GO_SHA256 四个 ARG。这指定了要构建的 Mooncake 具体版本（一个特定的提交 SHA）、代码仓库地址，以及构建所需的 Go 语言版本和其安装包的校验和，确保构建的可重复性和安全性。此变更位于 Dockerfile 头部，是后续所有 Mooncake 构建阶段的基础配置。

2. 分阶段构建 Mooncake Wheel：在 Dockerfile 中新增四个连续的构建阶段。
   a. mooncake_source：克隆 Mooncake 仓库，检出指定提交，运行其 dependencies.sh 安装所有构建和运行时依赖。此步骤复用了上游的依赖管理，避免了依赖列表漂移。
   b. build_mooncake：在克隆的 Mooncake 源码目录中，使用 CMake 配置并编译项目，启用 HIP 支持，关闭 CUDA、单元测试等。编译产物被安装到默认位置（如 /usr/local）。
   c. package_mooncake：这是关键步骤。通过 PIP_CONSTRAINT 环境变量固定了 pip、build、setuptools、wheel、auditwheel、patchelf 等工具的版本，尤其是强制 patchelf>=0.17 以修复上游依赖中的 RPATH 生成 bug。然后调用 Mooncake 的 scripts/build_wheel.sh 脚本，并设置 HIP_BUILD=1 和 PLATFORM_TAG=manylinux_2_35_x86_64 来生成名为 mooncake_transfer_engine_rocm 的 wheel 文件。构建完成后验证 wheel 数量并将 wheel 复制到导出目录。
   d. export_mooncake：使用 COPY --from=package_mooncake 将构建好的 wheel 文件从 package_mooncake 阶段导出到一个 scratch 镜像中，供后续阶段使用。
   这一序列化阶段将构建、打包和导出分离，利用了 Docker 层缓存，特别是通过外部挂载的 --mount=type=cache 缓存了 Go 模块和构建目录，加速重复构建。此变更将 Mooncake 的构建完全封装在 Docker 多阶段构建中，不影响后续 vLLM 的构建阶段，但为其提供了可用的 wheel 文件。

3. 集成 CI 构建与缓存：修改 .buildkite/scripts/ci-bake-rocm.sh 和 docker/ci-rocm.hcl。
   a. 在脚本中，将 MOONCAKE_BRANCH 加入 extract_dependency_pins 函数的变量循环，使其可以被显式设置。
   b. 在 compute_dependency_cache_keys 函数中，为 Mooncake 新增了缓存键计算逻辑，该键基于 MOONCAKE_BRANCH 和相关 Docker 构建阶段（mooncake_source, build_mooncake, package_mooncake, export_mooncake）的内容哈希组合而成。
   c. 新增了针对 mooncake-rocm-ci 目标的 dependency_cache_ref_for_target 和 dependency_cache_ref_exists 处理逻辑，使其能从 Registry 缓存导入或导出 Mooncake 的构建层缓存。
   d. 在 HCL 文件中，定义了 MOONCAKE_BRANCH 和 MOONCAKE_CACHE_KEY 变量，新增了 get_cache_to_rocm_mooncake 函数，并创建了 mooncake-rocm-ci 构建目标，该目标专门输出 Mooncake 构建阶段的缓存，并加入了 ci-base-rocm-ci-with-deps 构建组。
   这些改动确保了 Mooncake 的构建产物能被 CI 系统高效缓存和复用，避免了每次构建都重新执行耗时的编译和打包步骤，显著提升了 CI 效率。此变更与现有的 NIXL、ROCshmem、DeepEP 等依赖的缓存模式保持一致。

4. 在基础镜像中安装与验证：在 docker/Dockerfile.rocm 的发布构建和测试构建阶段，添加安装和验证命令。
   a. 在发布构建阶段（vllm）和测试构建阶段（test），均使用 --mount=type=bind,from=export_mooncake,src=/,target=/mooncake_install,ro 挂载之前导出的 wheel 文件。
   b. 使用 uv pip install --system --no-deps 安装 wheel（--no-deps 避免拉取 Python 依赖，因为 wheel 是 C++/RDMA 引擎，核心依赖由 dependencies.sh 安装）。
   c. 安装后立即运行一系列验证命令：python3 -c "import aiohttp, msgpack, requests" 检查 Python 依赖；python3 -c "from mooncake.engine import SUPPORT_HIP, TransferEngine; assert SUPPORT_HIP" 验证 Mooncake 引擎模块可导入且识别 HIP 环境；python3 -c "from mooncake.store import MooncakeDistributedStore" 验证存储模块可导入；mooncake_master --version 验证命令行工具可用。
   d. 在最终镜像的 versions.txt 中记录 MOONCAKE_BRANCH 和 MOONCAKE_REPO，提供构建溯源信息。
   这一步将构建好的 Mooncake wheel 集成到最终面向用户的 vLLM 镜像中，并通过一系列即时检查确保了安装的正确性和基本功能。这为用户提供了开箱即用的 Mooncake 支持，无需额外安装步骤。

风险主要集中在构建的可靠性和维护负担上：

1. 构建失败风险：Mooncake 上游仓库的 dependencies.sh 脚本或其依赖项（如 Go 版本、yalantinglibs 等）发生变化可能导致 CI 构建失败。虽然使用了 SHA pinning 缓解了此风险，但 dependencies.sh 本身可能从远程安装其他版本化的依赖。CI 缓存策略（MOONCAKE_CACHE_KEY）能在一定程度上减轻此影响，但根本解决依赖于上游的稳定性。
2. 依赖版本 Pinning：强制使用 patchelf>=0.17 是为了修复一个特定 bug，但引入了额外的版本约束。如果 Mooncake 上游修复了此问题并依赖特定版本的 patchelf，可能需要重新调整。目前 patchelf==0.19.1.0 是较新稳定版本，风险较低。
3. 构建时间增加：在 CI 构建中增加了 Mooncake 的编译步骤（虽然结果被缓存），可能会增加首次构建或缓存失效时的 CI 时间。这被缓解措施（并行构建、利用 Docker 层缓存）部分抵消，但仍是一个潜在的 CI 资源消耗点。
4. 镜像体积增大：最终的 vLLM ROCm 镜像中新增了 Mooncake 引擎及其依赖（yalantinglibs, etcd-cpp-apiv3, Go runtime 等），会增加镜像的磁盘占用。这是为提供新功能所付出的必要成本。
5. 兼容性：wheel 的构建使用了 PLATFORM_TAG=manylinux_2_35_x86_64，并期望在基础镜像的 glibc 2.35 环境中运行。理论上，如果基础镜像升级到更高版本的 glibc，此 wheel 可能仍兼容（因 manylinux_2_39 标签），但需关注。Mooncake 引擎本身是无设备内核的 C++ 代码，对 ROCm 版本应有一定宽容度，但建议定期测试以确保兼容性。
6. 维护负担：引入了对外部仓库特定提交的依赖。需要定期关注 Mooncake 上游的 ROCm 正式发布，以便及时将构建方式切换为使用官方 wheel，减少维护复杂度。目前此 PR 明确为短期方案，符合预期。

影响范围明确：

• 用户影响：直接正面影响。使用 ROCm 基础镜像的 vLLM 用户（特别是需要分布式推理或 KV 缓存卸载的场景）现在可以无缝使用 MooncakeConnector 和 MooncakeStoreConnector，无需自行构建和安装 Mooncake。这降低了使用门槛，扩展了 vLLM 在 AMD GPU 上的功能生态。
• 系统影响：对 vLLM 的 ROCm 构建系统和 CI 流水线有直接影响。增加了构建阶段的复杂度和构建时间（首次或缓存失效时）。通过引入 mooncake-rocm-ci 缓存目标，优化了依赖构建的缓存机制，长期看有利于构建效率。不会影响 vLLM 的核心运行时性能或 CUDA 路径的逻辑。
• 团队影响：负责 ROCm 构建和基础设施的团队需要理解并维护这套新的 Mooncake 构建流程，包括监控上游变更、维护缓存键、确保依赖版本兼容。这是一个标准的依赖集成维护工作，但因其涉及跨项目协作（Mooncake 上游），需要一定的关注。