尧图网页设计 
PyTorch CI/CD Docker 镜像体系构建环境参数化设计与新增基础镜像实战指南【免费下载链接】pytorchTensors and Dynamic neural networks in Python with strong GPU acceleration项目地址: https://gitcode.com/GitHub_Trending/py/pytorch本文以 .ci/docker/README.md 为蓝本完整拆解 PyTorch 官方 CI 基础 Docker 镜像的参数化构建机制如何通过构建环境build environment字符串驱动少数几个 Dockerfile 生成数十种 CI/CD 镜像.ci/docker/build.sh的分发逻辑、docker-builds.yml工作流的自动重建与推送流程以及新增一个基础镜像的完整操作步骤。读完本文你可以独立理解 PyTorch CI 镜像的命名规范、版本解析规则与后构建校验机制并能按仓库约定安全地扩展新镜像。一、整体设计用构建环境字符串统一驱动镜像构建.ci/docker/目录包含了构建 PyTorch CI 所用全部 Docker 镜像所需的文件。其核心设计思想可以概括为一句话Dockerfile 是参数化的条件性地执行不同的构建阶段具体执行哪些阶段由传给docker build的构建参数决定。这样只需要维护少数几个 Dockerfile就能产出大量配置各异的镜像。这些不同配置通过一个自由格式的字符串来标识官方称之为build environment构建环境。该字符串会被持久化写入每一个镜像中作为BUILD_ENVIRONMENT环境变量——这一点在 Ubuntu Dockerfile 的结尾可以直接看到# Include BUILD_ENVIRONMENT environment variable in image ARG BUILD_ENVIRONMENT ENV BUILD_ENVIRONMENT${BUILD_ENVIRONMENT}而合法的构建环境有哪些则由 build.sh 中的巨型case语句原文档称之为 the giant switch硬编码定义。二、目录结构总览README 列出的目录职责如下结合当前仓库实际目录结构补充说明目录/文件职责build.sh分发脚本启动所有镜像构建common/执行单个 Docker 构建阶段的脚本集合install_base.sh、install_python.sh、install_cuda.sh、install_triton.sh等数十个安装脚本ubuntu/CPU 构建与测试任务使用的 Ubuntu 镜像 Dockerfile含可选 CUDA 阶段ubuntu-rocm/支持 ROCm 的 Ubuntu 镜像ubuntu-xpu/支持 Intel XPU 的 Ubuntu 镜像manywheel/夜间 manywheel 构建用的 Dockerfile 与 build.sh含Dockerfile_2_28、Dockerfile_s390x、Dockerfile_cuda_aarch64等变体此外从当前仓库结构还可以确认若干 README 未逐一列出的 Dockerfilelinter/Dockerfile、linter-cuda/Dockerfile、almalinux/Dockerfile、ubuntu-cross-riscv/Dockerfile。它们分别服务于代码 lint、AlmaLinux 构建与 RISC-V 交叉编译等场景由 build.sh 根据镜像名中的关键字路由过去详见下节。关于 CD 镜像README 提到的conda夜间 conda 构建与manywheel夜间 manywheel 构建两类 CD 镜像中manywheel 在当前仓库的.ci/docker/manywheel/下可确认存在其下还有s390_scripts/用于 s390x 大端架构的构建辅助脚本。三、本地使用方式README 给出的标准用法可直接复制# 构建指定镜像 ./build.sh pytorch-linux-bionic-py3.8-gcc9 -t myimage:latest # 通过环境变量设置开关详见 build.sh后构建 sudo bash -c TRITON1 ./build.sh pytorch-linux-bionic-py3.8-gcc9 -t myimage:latest说明两点实际约束示例中的pytorch-linux-bionic-py3.8-gcc9是 README 的历史示例当前 build.sh 的case分支中CUDA 系列主流构建环境已是pytorch-linux-jammy-cuda13.0-cudnn9-py3-gcc11、pytorch-linux-jammy-cuda13.2-cudnn9-py3-gcc11等 jammyUbuntu 22.04 CUDA 13.x 组合与 docker-builds.yml 矩阵中的镜像名一一对应。前缀环境变量如TRITON1能生效是因为 build.sh 在拼docker build命令时会把对应 shell 变量原样透传为--build-arg见下节参数列表Dockerfile 内部再以[ -n ${ARG} ]判断是否执行该阶段。四、build.sh 分发脚本深度解析build.sh 顶部注释说明了它的三段职责根据镜像名提取 docker build 所需参数集合用这些参数执行docker build运行构建出的镜像打印并校验已安装包的实际版本与期望版本是否一致。4.1 镜像名解析镜像名形如pytorch-linux-jammy-cuda12.8-cudnn9-py3-gcc11是语义段 版本号的连字符拼接。解析入口是extract_all_from_image_name按-切分后用 Perl 正则提取每段中字母前缀 版本号再映射到对应的环境变量其中py是特例映射为ANACONDA_PYTHON_VERSIONfunction extract_version_from_image_name() { eval export $2$(echo ${image} | perl -n -e/$1(\d(\.\d)?(\.\d)?t?)/ print \$1) ... }此外还有两处前置推断逻辑Ubuntu 版本镜像名含jammy→22.04含noble→24.04否则尝试从名字里提取ubuntuver见 build.sh#L53-L59。Dockerfile 路由默认ubuntu/Dockerfile镜像名含rocm→ubuntu-rocm/Dockerfile含xpu→ubuntu-xpu/Dockerfile含cuda…linter→linter-cuda/Dockerfile仅含linter→linter/Dockerfile含riscv…cross→ubuntu-cross-riscv/Dockerfile见 build.sh#L68-L82。特殊地名字含xla的镜像直接复用 PyTorch/XLA 预构建镜像本脚本不做构建。4.2 硬编码的构建环境giant switch摘录case分支中每个构建环境是一组 shell 变量赋值。摘录当前仓库中的代表性配置完整列表见 build.sh#L93-L358pytorch-linux-jammy-cuda13.2-cudnn9-py3.12-gcc11) CUDA_VERSION13.2.1 ANACONDA_PYTHON_VERSION3.12 GCC_VERSION11 KATEXyes TRITONyes INSTALL_MINGWyes ;; pytorch-linux-jammy-rocm-n-py3 | pytorch-linux-jammy-rocm-n-py3-benchmarks | pytorch-linux-noble-rocm-n-py3) ANACONDA_PYTHON_VERSION3.12 # noblejammy 为 3.10 GCC_VERSION13 ROCM_VERSION10.0 THEROCK_INDEX_URLhttps://stable.repo.amd.com/rocm/whl-next/ TRITONyes KATEXyes PYTORCH_ROCM_ARCHgfx90a;gfx942;gfx950;gfx1100 ;; pytorch-linux-noble-xpu-n-py3 | pytorch-linux-noble-xpu-n-py3-client | pytorch-linux-noble-xpu-n-py3-inductor-benchmarks) ANACONDA_PYTHON_VERSION3.10 GCC_VERSION13 XPU_VERSION2026.1 XPU_DRIVER_TYPELTS # 名字含 client 时为 CLIENT TRITONyes ;;其余常见维度还包括INDUCTOR_BENCHMARKS额外装入 HF/timm/torchbench 等基准依赖、EXECUTORCH、HALIDE、PALLAS/TPUJAX 相关、TVM、TRITON_CPU、ONNX、DOCS、ACL/OPENBLASaarch64 路线、TSANfree-threaded Python 名字带t后缀时自动开启见 catch-all 分支 build.sh#L325-L333。case末尾的*)catch-all 分支用于兜底对未硬编码的镜像名尽力从名字里提取py/cuda/rocm/gcc/clang/devtoolset/glibc版本若一个py版本号以t结尾如py3.14t会自动剥掉t并置PYTHON_FREETHREADED1与TSANyes用于 GIL 移除版本的线程 sanitizer 测试。4.3 透传给 docker build 的构建参数build_image()函数把上述变量统一注入docker buildx build见 build.sh#L394-L439。关键参数包括标识类BUILD_ENVIRONMENT即镜像名本身、IMAGE_NAME基础版本类UBUNTU_VERSION、GCC_VERSION、CLANG_VERSION、PYTHON_VERSION、ANACONDA_PYTHON_VERSION、PYTHON_FREETHREADED、CUDA_VERSION、ROCM_VERSION、XPU_VERSION、XPU_DRIVER_TYPE、THEROCK_INDEX_URL、USE_MSLK、PYTORCH_ROCM_ARCH、PIP_EXTRA_INDEX_URL、PIP_PREFER_BINARY功能开关类KATEX、TRITON、TRITON_CPU、ONNX、TVM、DOCS、INDUCTOR_BENCHMARKS、EXECUTORCH、HALIDE、PALLAS、TPU、TSAN、ACL、OPENBLAS、SKIP_SCCACHE_INSTALL、INSTALL_MINGW。从源码结构看这套参数的消费端正是各 Dockerfile 中的ARGif [ -n ${...} ]条件执行模式例如 ubuntu/DockerfileARG INSTALL_MINGW COPY ./common/install_mingw.sh install_mingw.sh RUN if [ -n ${INSTALL_MINGW} ]; then bash ./install_mingw.sh; fi RUN rm install_mingw.sh4.4 远程 BuildKit 与缓存策略build.sh 对两种执行模式做了区分本地模式--load -t tmp_tag构建后落本地 daemonREMOTE_BUILDKIT 模式改为--push直推镜像仓库调用方需已登录并用--cache-from/--cache-to typeregistry以镜像名-buildcache后缀作为共享缓存 refmodemax缓存中间层、image-manifesttrue,oci-mediatypestrue保持 ECR 兼容见 build.sh#L376-L391。远程模式下还有一段连接重试逻辑自扩缩容的 BuildKit 池冷启动时 gRPC 连接可能失败脚本会对连接类错误waiting for connection、context deadline exceeded等以默认 15s 间隔重试最多 360 次约 2 小时而真正的构建错误则立即退出见 build.sh#L441-L471。4.5 后构建健全性检查本地模式下build.sh 会用drun即docker run --rm对刚构建的镜像逐项断言lsb_release输出须匹配 Ubuntu 及UBUNTU_VERSIONpython --version须匹配ANACONDA_PYTHON_VERSIONgcc --versionRISC-V 交叉镜像检查riscv64-linux-gnu-gcc、clang --version须匹配期望版本KATEX打开时katex --version必须可执行Triton 双向断言TRITON/TRITON_CPU打开时import triton必须成功未打开时若意外能 import 也会失败见 build.sh#L546-L555。任何一项不符都会exit 1保证镜像内容与其命名承诺一致。五、docker-builds.yml基础镜像的自动重建与发布README 指出.ci/docker/下的基础镜像由docker-builds.yml工作流构建且只要.ci/docker/*目录下的文件发生变更镜像构建就会自动触发从而保证所有镜像与最新依赖、配置保持同步。这一点在 docker-builds.yml 中可直接验证on: workflow_dispatch: push: branches: [main, release/*] tags: [ciflow/docker/*] paths: - .ci/docker/** - .github/workflows/docker-builds.yml - .lintrunner.toml schedule: - cron: 1 3 * * 3 # 每周三定时重建工作流的关键机制均取自 docker-builds.yml 原文镜像矩阵strategy.matrix.docker-image-name列出约 35 个构建环境名与 build.sh 的 case 分支对应aarch64 镜像通过include指定独立的 arm64 BuildKit 地址与 runner 标签远程 BuildKit按架构连接tcp://buildkitd-amd64.buildkit:1234/ arm64 对应地址用docker buildx create --driver remote --use注册刻意不用setup-buildx-action的 bootstrap以免冷启动 20s 超时镜像标签计算DOCKER_TAG$(git rev-parse HEAD:.ci/docker)——即.ci/docker目录的 git 树哈希保证目录内容相同 → 标签相同的去重语义最终推送为 ECR 上的pytorch/ci-image:image-name-DOCKER_TAG双仓库发布构建并推送到 ECR 后通过docker buildx imagetools create做服务器端跨仓库复制镜像到ghcr.io/pytorch/ci-image同时打上name-tag与name两个 tagROCm 产物输出ROCm 镜像名会额外写docker-builds-output-*.txt并上传为 artifact供下游工作流消费。六、镜像如何被 PyTorch 构建与测试工作流复用README 用 linux-build / linux-test 两个例子描述了镜像的消费链路构建链路linux-build镜像由docker-builds.yml产出后在_linux-build.yml见.github/workflows/_linux-build.yml中通过calculate-docker-image步骤决定要使用哪个镜像 → 拉取该镜像并启动容器 → 在容器内执行 .ci/pytorch/build.sh 构建 PyTorch wheel 等产物。测试链路linux-test同样的镜像在_linux-test.yml见.github/workflows/_linux-test.yml中被复用calculate-docker-image步骤选定镜像 → 拉取并起容器 → 安装由 PyTorch 构建 job 产出的 wheel 工件 → 在容器内执行测试脚本如 .ci/pytorch/test.sh 或 .ci/pytorch/multigpu-test.sh。注意区分两个同名脚本.ci/docker/build.sh是构建基础镜像用的由docker-builds.yml执行包含各构建环境的配置.ci/pytorch/build.sh是在容器内构建 PyTorch 本体用的由_linux-build.yml等工作流在容器启动后调用产出 wheel 等工件。七、两套 ci_commit_pins 的职责边界目录用途变更影响.ci/docker/ci_commit_pins/构建基础镜像时锁定依赖版本确保 PyTorch 构建环境一致变更会触发基础镜像重建因工作流监听.ci/docker/**.github/ci_commit_pins/在容器内进行 PyTorch 构建与测试时锁定依赖版本如vision.txt、fbgemm.txt、torchao.txt等被容器内运行的构建脚本消费.ci/docker/ci_commit_pins/下的文件都是库名 → commit的单行文本例如triton.txt、nccl.txt、executorch.txt、torchbench.txt、timm.txt、halide.txt、jax.txt等。它们在 Dockerfile 中以COPY进构建上下文再由common/下的安装脚本读取例如 ubuntu/Dockerfile 中 TVM 的安装即通过get_pinned_commit从这两个 pin 文件取值COPY ci_commit_pins/tvm.txt tvm.txt COPY ci_commit_pins/tvm-ffi.txt tvm-ffi.txt RUN if [ -n ${TVM} ]; then bash -c source ./common_utils.sh \ pip_install apache-tvm$(get_pinned_commit tvm) \ apache-tvm-ffi$(get_pinned_commit tvm-ffi) python -c import tvm; ficommon_utils.sh中的get_pinned_commit帮助函数即 common/common_utils.sh 的一部分是各安装脚本读取 pin 文件的统一入口。八、新增一个基础 Docker 镜像的分步指南以下完整继承 README 的官方 Guidance并结合仓库现状做了路径级补充。原则只有当你需要在 CI 上构建 PyTorch 之前做特定的环境变更或依赖安装时才应创建/修改基础镜像。步骤 1添加固定 commit如需要PyTorch 用 pinned commits 保证构建稳定性nightly.yml工作流每天会检查并更新若干仓库依赖的 pin。如果新镜像需要从特定 commit 安装或源码构建某个库在nightly.yml与merge-rules.yml中添加要跟踪的仓库在 .ci/docker/ci_commit_pins/ 中添加初始 pin 文件文件名须与步骤 1 中定义的一致现有示例triton.txt、nccl.txt、rust.txt。步骤 2配置基础镜像(a) 在 build.sh 中添加新构建环境配置。README 给的官方示例当前仓库中已存在pytorch-linux-jammy-cuda12.8-cudnn9-py3.12-gcc11-new1这类分支的写法风格pytorch-linux-jammy-cuda12.8-cudnn9-py3.12-gcc11-new1) CUDA_VERSION12.8.1 ANACONDA_PYTHON_VERSION3.12 GCC_VERSION11 VISIONyes KATEXyes TRITONyes NEW_ARG_1yes ;;(b) 在 build.sh 的 docker build 步骤中追加构建参数。若引入了新参数必须同步加进build_image()的参数列表docker build \ .... --build-arg NEW_ARG_1${NEW_ARG_1}(c) 更新 Dockerfile 逻辑。以 ubuntu/Dockerfile 为例ARG NEW_ARG_1 # Set up environment for NEW_ARG_1 RUN if [ -n ${NEW_ARG_1} ]; then bash ./do_something.sh; fi(d) 在 .github/workflows/docker-builds.yml 中登记。把新镜像名加入matrix.docker-image-name数组。由于该工作流会在.ci/docker/目录内容变化时预构建所有镜像包括 pin 文件更新登记后下次触发即自动产出并推送。九、实战提示与常见坑镜像名即契约名字中的pyX.Yt后缀表示 free-threaded 构建自动开启TSAN-benchmarks后缀开启INDUCTOR_BENCHMARKS-client影响 XPU 驱动类型。命名不规范会导致 catch-all 解析失败或行为不符预期。Ubuntu 版本别写错jammy22.04、noble24.04 是 build.sh 硬编码映射名字中直接出现ubuntuver才会走正则提取。本地构建与远程构建的行为差异远程 BuildKit 模式下镜像直接推送、不会加载到本地因此所有drun健全性检查会被跳过脚本会打印说明并提前退出——本地调试时务必不设REMOTE_BUILDKIT以启用校验。Triton 阶段独立ubuntu/Dockerfile 用triton-builder多阶段构建 wheel仅当TRITON/TRITON_CPU非空时安装配合 4.5 节的双向断言可放心按开关裁剪镜像体积。改动即重建任何对.ci/docker/**含ci_commit_pins/的提交都会触发docker-builds.yml且镜像 tag 基于目录树哈希——同名镜像只有在目录内容变化时才会产生新 tag这正是 CI 能稳定复用缓存镜像的基础。十、小结PyTorch 的 CI 基础镜像体系是一个单一字符串入口 参数化 Dockerfile 双向版本断言的完整闭环.ci/docker/build.sh把构建环境名解析为构建参数并驱动构建docker-builds.yml负责在目录内容变化时自动重建并向 ECR/GHCR 双发布_linux-build.yml/_linux-test.yml则通过calculate-docker-image复用这些镜像完成 PyTorch 的构建与测试。新增镜像时只需按pin 文件 → build.sh 配置 → Dockerfile ARG → docker-builds.yml 矩阵登记四步走即可安全接入整个 CI/CD 流水线。【免费下载链接】pytorchTensors and Dynamic neural networks in Python with strong GPU acceleration项目地址: https://gitcode.com/GitHub_Trending/py/pytorch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PyTorch CI/CD Docker 镜像体系：构建环境参数化设计与新增基础镜像实战指南
PyTorch CI/CD Docker 镜像体系构建环境参数化设计与新增基础镜像实战指南【免费下载链接】pytorchTensors and Dynamic neural networks in Python with strong GPU acceleration项目地址: https://gitcode.com/GitHub_Trending/py/pytorch本文以 .ci/docker/README.md 为蓝本完整拆解 PyTorch 官方 CI 基础 Docker 镜像的参数化构建机制如何通过构建环境build environment字符串驱动少数几个 Dockerfile 生成数十种 CI/CD 镜像.ci/docker/build.sh的分发逻辑、docker-builds.yml工作流的自动重建与推送流程以及新增一个基础镜像的完整操作步骤。读完本文你可以独立理解 PyTorch CI 镜像的命名规范、版本解析规则与后构建校验机制并能按仓库约定安全地扩展新镜像。一、整体设计用构建环境字符串统一驱动镜像构建.ci/docker/目录包含了构建 PyTorch CI 所用全部 Docker 镜像所需的文件。其核心设计思想可以概括为一句话Dockerfile 是参数化的条件性地执行不同的构建阶段具体执行哪些阶段由传给docker build的构建参数决定。这样只需要维护少数几个 Dockerfile就能产出大量配置各异的镜像。这些不同配置通过一个自由格式的字符串来标识官方称之为build environment构建环境。该字符串会被持久化写入每一个镜像中作为BUILD_ENVIRONMENT环境变量——这一点在 Ubuntu Dockerfile 的结尾可以直接看到# Include BUILD_ENVIRONMENT environment variable in image ARG BUILD_ENVIRONMENT ENV BUILD_ENVIRONMENT${BUILD_ENVIRONMENT}而合法的构建环境有哪些则由 build.sh 中的巨型case语句原文档称之为 the giant switch硬编码定义。二、目录结构总览README 列出的目录职责如下结合当前仓库实际目录结构补充说明目录/文件职责build.sh分发脚本启动所有镜像构建common/执行单个 Docker 构建阶段的脚本集合install_base.sh、install_python.sh、install_cuda.sh、install_triton.sh等数十个安装脚本ubuntu/CPU 构建与测试任务使用的 Ubuntu 镜像 Dockerfile含可选 CUDA 阶段ubuntu-rocm/支持 ROCm 的 Ubuntu 镜像ubuntu-xpu/支持 Intel XPU 的 Ubuntu 镜像manywheel/夜间 manywheel 构建用的 Dockerfile 与 build.sh含Dockerfile_2_28、Dockerfile_s390x、Dockerfile_cuda_aarch64等变体此外从当前仓库结构还可以确认若干 README 未逐一列出的 Dockerfilelinter/Dockerfile、linter-cuda/Dockerfile、almalinux/Dockerfile、ubuntu-cross-riscv/Dockerfile。它们分别服务于代码 lint、AlmaLinux 构建与 RISC-V 交叉编译等场景由 build.sh 根据镜像名中的关键字路由过去详见下节。关于 CD 镜像README 提到的conda夜间 conda 构建与manywheel夜间 manywheel 构建两类 CD 镜像中manywheel 在当前仓库的.ci/docker/manywheel/下可确认存在其下还有s390_scripts/用于 s390x 大端架构的构建辅助脚本。三、本地使用方式README 给出的标准用法可直接复制# 构建指定镜像 ./build.sh pytorch-linux-bionic-py3.8-gcc9 -t myimage:latest # 通过环境变量设置开关详见 build.sh后构建 sudo bash -c TRITON1 ./build.sh pytorch-linux-bionic-py3.8-gcc9 -t myimage:latest说明两点实际约束示例中的pytorch-linux-bionic-py3.8-gcc9是 README 的历史示例当前 build.sh 的case分支中CUDA 系列主流构建环境已是pytorch-linux-jammy-cuda13.0-cudnn9-py3-gcc11、pytorch-linux-jammy-cuda13.2-cudnn9-py3-gcc11等 jammyUbuntu 22.04 CUDA 13.x 组合与 docker-builds.yml 矩阵中的镜像名一一对应。前缀环境变量如TRITON1能生效是因为 build.sh 在拼docker build命令时会把对应 shell 变量原样透传为--build-arg见下节参数列表Dockerfile 内部再以[ -n ${ARG} ]判断是否执行该阶段。四、build.sh 分发脚本深度解析build.sh 顶部注释说明了它的三段职责根据镜像名提取 docker build 所需参数集合用这些参数执行docker build运行构建出的镜像打印并校验已安装包的实际版本与期望版本是否一致。4.1 镜像名解析镜像名形如pytorch-linux-jammy-cuda12.8-cudnn9-py3-gcc11是语义段 版本号的连字符拼接。解析入口是extract_all_from_image_name按-切分后用 Perl 正则提取每段中字母前缀 版本号再映射到对应的环境变量其中py是特例映射为ANACONDA_PYTHON_VERSIONfunction extract_version_from_image_name() { eval export $2$(echo ${image} | perl -n -e/$1(\d(\.\d)?(\.\d)?t?)/ print \$1) ... }此外还有两处前置推断逻辑Ubuntu 版本镜像名含jammy→22.04含noble→24.04否则尝试从名字里提取ubuntuver见 build.sh#L53-L59。Dockerfile 路由默认ubuntu/Dockerfile镜像名含rocm→ubuntu-rocm/Dockerfile含xpu→ubuntu-xpu/Dockerfile含cuda…linter→linter-cuda/Dockerfile仅含linter→linter/Dockerfile含riscv…cross→ubuntu-cross-riscv/Dockerfile见 build.sh#L68-L82。特殊地名字含xla的镜像直接复用 PyTorch/XLA 预构建镜像本脚本不做构建。4.2 硬编码的构建环境giant switch摘录case分支中每个构建环境是一组 shell 变量赋值。摘录当前仓库中的代表性配置完整列表见 build.sh#L93-L358pytorch-linux-jammy-cuda13.2-cudnn9-py3.12-gcc11) CUDA_VERSION13.2.1 ANACONDA_PYTHON_VERSION3.12 GCC_VERSION11 KATEXyes TRITONyes INSTALL_MINGWyes ;; pytorch-linux-jammy-rocm-n-py3 | pytorch-linux-jammy-rocm-n-py3-benchmarks | pytorch-linux-noble-rocm-n-py3) ANACONDA_PYTHON_VERSION3.12 # noblejammy 为 3.10 GCC_VERSION13 ROCM_VERSION10.0 THEROCK_INDEX_URLhttps://stable.repo.amd.com/rocm/whl-next/ TRITONyes KATEXyes PYTORCH_ROCM_ARCHgfx90a;gfx942;gfx950;gfx1100 ;; pytorch-linux-noble-xpu-n-py3 | pytorch-linux-noble-xpu-n-py3-client | pytorch-linux-noble-xpu-n-py3-inductor-benchmarks) ANACONDA_PYTHON_VERSION3.10 GCC_VERSION13 XPU_VERSION2026.1 XPU_DRIVER_TYPELTS # 名字含 client 时为 CLIENT TRITONyes ;;其余常见维度还包括INDUCTOR_BENCHMARKS额外装入 HF/timm/torchbench 等基准依赖、EXECUTORCH、HALIDE、PALLAS/TPUJAX 相关、TVM、TRITON_CPU、ONNX、DOCS、ACL/OPENBLASaarch64 路线、TSANfree-threaded Python 名字带t后缀时自动开启见 catch-all 分支 build.sh#L325-L333。case末尾的*)catch-all 分支用于兜底对未硬编码的镜像名尽力从名字里提取py/cuda/rocm/gcc/clang/devtoolset/glibc版本若一个py版本号以t结尾如py3.14t会自动剥掉t并置PYTHON_FREETHREADED1与TSANyes用于 GIL 移除版本的线程 sanitizer 测试。4.3 透传给 docker build 的构建参数build_image()函数把上述变量统一注入docker buildx build见 build.sh#L394-L439。关键参数包括标识类BUILD_ENVIRONMENT即镜像名本身、IMAGE_NAME基础版本类UBUNTU_VERSION、GCC_VERSION、CLANG_VERSION、PYTHON_VERSION、ANACONDA_PYTHON_VERSION、PYTHON_FREETHREADED、CUDA_VERSION、ROCM_VERSION、XPU_VERSION、XPU_DRIVER_TYPE、THEROCK_INDEX_URL、USE_MSLK、PYTORCH_ROCM_ARCH、PIP_EXTRA_INDEX_URL、PIP_PREFER_BINARY功能开关类KATEX、TRITON、TRITON_CPU、ONNX、TVM、DOCS、INDUCTOR_BENCHMARKS、EXECUTORCH、HALIDE、PALLAS、TPU、TSAN、ACL、OPENBLAS、SKIP_SCCACHE_INSTALL、INSTALL_MINGW。从源码结构看这套参数的消费端正是各 Dockerfile 中的ARGif [ -n ${...} ]条件执行模式例如 ubuntu/DockerfileARG INSTALL_MINGW COPY ./common/install_mingw.sh install_mingw.sh RUN if [ -n ${INSTALL_MINGW} ]; then bash ./install_mingw.sh; fi RUN rm install_mingw.sh4.4 远程 BuildKit 与缓存策略build.sh 对两种执行模式做了区分本地模式--load -t tmp_tag构建后落本地 daemonREMOTE_BUILDKIT 模式改为--push直推镜像仓库调用方需已登录并用--cache-from/--cache-to typeregistry以镜像名-buildcache后缀作为共享缓存 refmodemax缓存中间层、image-manifesttrue,oci-mediatypestrue保持 ECR 兼容见 build.sh#L376-L391。远程模式下还有一段连接重试逻辑自扩缩容的 BuildKit 池冷启动时 gRPC 连接可能失败脚本会对连接类错误waiting for connection、context deadline exceeded等以默认 15s 间隔重试最多 360 次约 2 小时而真正的构建错误则立即退出见 build.sh#L441-L471。4.5 后构建健全性检查本地模式下build.sh 会用drun即docker run --rm对刚构建的镜像逐项断言lsb_release输出须匹配 Ubuntu 及UBUNTU_VERSIONpython --version须匹配ANACONDA_PYTHON_VERSIONgcc --versionRISC-V 交叉镜像检查riscv64-linux-gnu-gcc、clang --version须匹配期望版本KATEX打开时katex --version必须可执行Triton 双向断言TRITON/TRITON_CPU打开时import triton必须成功未打开时若意外能 import 也会失败见 build.sh#L546-L555。任何一项不符都会exit 1保证镜像内容与其命名承诺一致。五、docker-builds.yml基础镜像的自动重建与发布README 指出.ci/docker/下的基础镜像由docker-builds.yml工作流构建且只要.ci/docker/*目录下的文件发生变更镜像构建就会自动触发从而保证所有镜像与最新依赖、配置保持同步。这一点在 docker-builds.yml 中可直接验证on: workflow_dispatch: push: branches: [main, release/*] tags: [ciflow/docker/*] paths: - .ci/docker/** - .github/workflows/docker-builds.yml - .lintrunner.toml schedule: - cron: 1 3 * * 3 # 每周三定时重建工作流的关键机制均取自 docker-builds.yml 原文镜像矩阵strategy.matrix.docker-image-name列出约 35 个构建环境名与 build.sh 的 case 分支对应aarch64 镜像通过include指定独立的 arm64 BuildKit 地址与 runner 标签远程 BuildKit按架构连接tcp://buildkitd-amd64.buildkit:1234/ arm64 对应地址用docker buildx create --driver remote --use注册刻意不用setup-buildx-action的 bootstrap以免冷启动 20s 超时镜像标签计算DOCKER_TAG$(git rev-parse HEAD:.ci/docker)——即.ci/docker目录的 git 树哈希保证目录内容相同 → 标签相同的去重语义最终推送为 ECR 上的pytorch/ci-image:image-name-DOCKER_TAG双仓库发布构建并推送到 ECR 后通过docker buildx imagetools create做服务器端跨仓库复制镜像到ghcr.io/pytorch/ci-image同时打上name-tag与name两个 tagROCm 产物输出ROCm 镜像名会额外写docker-builds-output-*.txt并上传为 artifact供下游工作流消费。六、镜像如何被 PyTorch 构建与测试工作流复用README 用 linux-build / linux-test 两个例子描述了镜像的消费链路构建链路linux-build镜像由docker-builds.yml产出后在_linux-build.yml见.github/workflows/_linux-build.yml中通过calculate-docker-image步骤决定要使用哪个镜像 → 拉取该镜像并启动容器 → 在容器内执行 .ci/pytorch/build.sh 构建 PyTorch wheel 等产物。测试链路linux-test同样的镜像在_linux-test.yml见.github/workflows/_linux-test.yml中被复用calculate-docker-image步骤选定镜像 → 拉取并起容器 → 安装由 PyTorch 构建 job 产出的 wheel 工件 → 在容器内执行测试脚本如 .ci/pytorch/test.sh 或 .ci/pytorch/multigpu-test.sh。注意区分两个同名脚本.ci/docker/build.sh是构建基础镜像用的由docker-builds.yml执行包含各构建环境的配置.ci/pytorch/build.sh是在容器内构建 PyTorch 本体用的由_linux-build.yml等工作流在容器启动后调用产出 wheel 等工件。七、两套 ci_commit_pins 的职责边界目录用途变更影响.ci/docker/ci_commit_pins/构建基础镜像时锁定依赖版本确保 PyTorch 构建环境一致变更会触发基础镜像重建因工作流监听.ci/docker/**.github/ci_commit_pins/在容器内进行 PyTorch 构建与测试时锁定依赖版本如vision.txt、fbgemm.txt、torchao.txt等被容器内运行的构建脚本消费.ci/docker/ci_commit_pins/下的文件都是库名 → commit的单行文本例如triton.txt、nccl.txt、executorch.txt、torchbench.txt、timm.txt、halide.txt、jax.txt等。它们在 Dockerfile 中以COPY进构建上下文再由common/下的安装脚本读取例如 ubuntu/Dockerfile 中 TVM 的安装即通过get_pinned_commit从这两个 pin 文件取值COPY ci_commit_pins/tvm.txt tvm.txt COPY ci_commit_pins/tvm-ffi.txt tvm-ffi.txt RUN if [ -n ${TVM} ]; then bash -c source ./common_utils.sh \ pip_install apache-tvm$(get_pinned_commit tvm) \ apache-tvm-ffi$(get_pinned_commit tvm-ffi) python -c import tvm; ficommon_utils.sh中的get_pinned_commit帮助函数即 common/common_utils.sh 的一部分是各安装脚本读取 pin 文件的统一入口。八、新增一个基础 Docker 镜像的分步指南以下完整继承 README 的官方 Guidance并结合仓库现状做了路径级补充。原则只有当你需要在 CI 上构建 PyTorch 之前做特定的环境变更或依赖安装时才应创建/修改基础镜像。步骤 1添加固定 commit如需要PyTorch 用 pinned commits 保证构建稳定性nightly.yml工作流每天会检查并更新若干仓库依赖的 pin。如果新镜像需要从特定 commit 安装或源码构建某个库在nightly.yml与merge-rules.yml中添加要跟踪的仓库在 .ci/docker/ci_commit_pins/ 中添加初始 pin 文件文件名须与步骤 1 中定义的一致现有示例triton.txt、nccl.txt、rust.txt。步骤 2配置基础镜像(a) 在 build.sh 中添加新构建环境配置。README 给的官方示例当前仓库中已存在pytorch-linux-jammy-cuda12.8-cudnn9-py3.12-gcc11-new1这类分支的写法风格pytorch-linux-jammy-cuda12.8-cudnn9-py3.12-gcc11-new1) CUDA_VERSION12.8.1 ANACONDA_PYTHON_VERSION3.12 GCC_VERSION11 VISIONyes KATEXyes TRITONyes NEW_ARG_1yes ;;(b) 在 build.sh 的 docker build 步骤中追加构建参数。若引入了新参数必须同步加进build_image()的参数列表docker build \ .... --build-arg NEW_ARG_1${NEW_ARG_1}(c) 更新 Dockerfile 逻辑。以 ubuntu/Dockerfile 为例ARG NEW_ARG_1 # Set up environment for NEW_ARG_1 RUN if [ -n ${NEW_ARG_1} ]; then bash ./do_something.sh; fi(d) 在 .github/workflows/docker-builds.yml 中登记。把新镜像名加入matrix.docker-image-name数组。由于该工作流会在.ci/docker/目录内容变化时预构建所有镜像包括 pin 文件更新登记后下次触发即自动产出并推送。九、实战提示与常见坑镜像名即契约名字中的pyX.Yt后缀表示 free-threaded 构建自动开启TSAN-benchmarks后缀开启INDUCTOR_BENCHMARKS-client影响 XPU 驱动类型。命名不规范会导致 catch-all 解析失败或行为不符预期。Ubuntu 版本别写错jammy22.04、noble24.04 是 build.sh 硬编码映射名字中直接出现ubuntuver才会走正则提取。本地构建与远程构建的行为差异远程 BuildKit 模式下镜像直接推送、不会加载到本地因此所有drun健全性检查会被跳过脚本会打印说明并提前退出——本地调试时务必不设REMOTE_BUILDKIT以启用校验。Triton 阶段独立ubuntu/Dockerfile 用triton-builder多阶段构建 wheel仅当TRITON/TRITON_CPU非空时安装配合 4.5 节的双向断言可放心按开关裁剪镜像体积。改动即重建任何对.ci/docker/**含ci_commit_pins/的提交都会触发docker-builds.yml且镜像 tag 基于目录树哈希——同名镜像只有在目录内容变化时才会产生新 tag这正是 CI 能稳定复用缓存镜像的基础。十、小结PyTorch 的 CI 基础镜像体系是一个单一字符串入口 参数化 Dockerfile 双向版本断言的完整闭环.ci/docker/build.sh把构建环境名解析为构建参数并驱动构建docker-builds.yml负责在目录内容变化时自动重建并向 ECR/GHCR 双发布_linux-build.yml/_linux-test.yml则通过calculate-docker-image复用这些镜像完成 PyTorch 的构建与测试。新增镜像时只需按pin 文件 → build.sh 配置 → Dockerfile ARG → docker-builds.yml 矩阵登记四步走即可安全接入整个 CI/CD 流水线。【免费下载链接】pytorchTensors and Dynamic neural networks in Python with strong GPU acceleration项目地址: https://gitcode.com/GitHub_Trending/py/pytorch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考