拓冰网站定制 
读懂build-and-copy.shspark-vllm-docker镜像构建、预编译Wheel缓存与集群分发机制深度解析【免费下载链接】spark-vllm-dockerDocker configuration for running VLLM on dual DGX Sparks项目地址: https://gitcode.com/gh_mirrors/sp/spark-vllm-dockerspark-vllm-docker 是专为 NVIDIA DGX Spark 双节点/多节点集群打造的 vLLM Docker 配置仓库而它的核心脚本 build-and-copy.sh 一条命令就搞定三件事准备 vLLM 镜像拉取官方测试过的预构建镜像或从预编译 Wheel 缓存/源码本地构建、管理 Wheel 缓存自动下载、校验、增量更新、向集群其他节点分发镜像。本文带你彻底读懂它的运行逻辑与常用参数。一、它解决什么问题在 DGX Spark 集群上跑 vLLM你通常要面对三个麻烦编译太慢vLLM、FlashInfer、NCCL 需要针对 GB10 的12.1asm_121a架构编译动辄数小时节点要一致双 Spark / 多 Spark 集群要求每台节点都有相同镜像版本要新鲜vLLM 迭代极快需要可靠的是否已最新判断避免重复下载或编译。build-and-copy.sh约 1500 行就是围绕这三点设计的编排脚本。它的镜像准备逻辑由一条简单规则决定见 build-and-copy.sh#L1074-L1077除非你显式请求了定制化构建否则默认拉取预构建镜像。# 最常用的一行命令拉取预构建镜像并按需分发到集群 ./build-and-copy.sh -c --copy-parallel二、三条镜像准备路径1️⃣ 默认路径拉取预构建 Runner 镜像不带任何定制参数时脚本执行docker pull eugr/spark-vllm:latest然后打上本地标签vllm-node见 build-and-copy.sh#L1148-L1152。eugr/spark-vllm:latest是 CI 流水线每晚构建并测试过的镜像latest指针只在通过集群/单机多模型测试后才前移--exp-b12x则拉取独立维护的eugr/spark-vllm-b12x:latest并打标签vllm-node-b12x用于 sm12x 高性能内核的实验特性自定义标签用-t tag例如./build-and-copy.sh -t my-vllm。这条路径最快、最省心99% 的用户只需要它。2️⃣ Wheel 缓存路径--use-wheels只做镜像组装如果你改过某些构建参数自定义 vLLM 版本、应用 PR 补丁等脚本进入本地构建路径。它并不会每次都全量编译而是围绕项目根目录下的.wheel-cache/目录定义于 build-and-copy.sh#L79做精细的增量管理缓存剖面路径用途FlashInfer regular.wheel-cache/flashinfer/regular默认架构的官方预编译 FlashInfer 三件套cubin / jit_cache / pythonFlashInfer custom.wheel-cache/flashinfer/custom自定义--flashinfer-ref/--apply-flashinfer-pr/ 非默认--gpu-archvLLM regular / b12x / custom.wheel-cache/vllm/profile三种 vLLM 构建剖面各自的 Wheel 缓存它如何判断缓存已最新核心函数try_download_wheels见 build-and-copy.sh#L343-L551发布资产比对抓取发布页资产列表本地文件全部存在才继续Commit 比对本地.flashinfer-commit/.vllm-commit与发布页记录的 commit 一致则跳过时间戳兜底逐个比较本地 Wheel 的 mtime 与远端Last-Modified头本地更新的本地构建 Wheel不会被覆盖这就是 2026-05-29 更新带来的Wheel 新鲜度检测架构标记校验缓存目录里的.flashinfer-arch/.vllm-arch标记必须与当前--gpu-arch匹配防止把别的架构的 Wheel 错装进镜像。失败即回滚下载前先备份旧 Wheel 到.backup-download-*目录任何一个文件下载失败或 FlashInfer 发布集不完整由 docker/validate_flashinfer_wheels.py 校验 JIT provider 依赖就整体恢复旧缓存绝不让新旧混杂的 Wheel 进入构建。--use-wheels的承诺是只用现成 WheelWheel 缺失且下载失败时直接报错绝不会悄悄退化成源码编译可用--rebuild-vllm/--rebuild-flashinfer显式触发重编。3️⃣ 源码构建路径三阶段导出真正需要编译时Dockerfile 的多阶段设计把工作切成三段每段产物都先写入 staging 目录、校验通过后才原子性地晋升为正式缓存promote_wheel_set见 build-and-copy.sh#L603-L623Stage 2: flashinfer-builder ──► flashinfer-export → .wheel-cache/flashinfer/profile/ Stage 4: vllm-builder ──► vllm-export → .wheel-cache/vllm/profile/ Stage 6: runner安装两组 Wheel 并组装最终镜像 → vllm-node / vllm-node-b12x--vllm-ref sha/branch/tag、--vllm-repo url、--vllm-source-dir 本地干净检出三种方式指定 vLLM 来源本地检出会以 staging 副本形式喂给 Docker主机上的仓库不会被修改--apply-vllm-pr 编号或URL可在构建前叠加任意上游 PR 补丁可重复指定每次成功构建还会生成build-metadata.yaml记录 vLLM/FlashInfer 的 commit、Torch 版本、GPU 架构等方便溯源。三、集群分发机制-c与--copy-parallel镜像准备好后脚本把它分发到集群的每个节点确定目标主机-c host1,host2显式指定省略主机则读.env里的COPY_HOSTS由 autodiscover.sh 自动发现 InfiniBand 直连节点并交互确认保存或用--setup强制重新发现。集群组网细节参见 docs/NETWORKING.md先比对镜像 ID 再传输对每个目标执行ssh host docker image inspect --format {{.Id}}build-and-copy.sh#L249-L253ID 相同的节点直接跳过全部节点都是最新时连docker save都不会执行一次打包逐台或并行推送docker save导出到临时文件后通过cat 镜像 | ssh host docker load推送--copy-parallel让多台节点并发传输并等待全部完成每台节点单独报告耗时计时统计结束时输出 TIMING STATISTICS 汇总表Prebuilt Pull / FlashInfer Build / vLLM Build / Runner Build / Image Copy / Total方便定位慢在哪一步。--no-build -c host则跳过一切准备步骤仅把本机已有镜像拷贝过去适合别的机器刚构建完、只想同步的场景。四、常用参数速查参数作用-t, --tag tag自定义本地镜像标签默认vllm-node-c, --copy-to [hosts]分发镜像到指定主机省略主机则用.env/自动发现--copy-parallel与-c搭配并发分发--use-wheels只用预编译 Wheel 构建 Runner缺失即报错绝不隐式编译--rebuild-vllm/--rebuild-flashinfer强制从源码重编对应 Wheel--force-download跳过新鲜度检查强制重新下载全部预编译 Wheel--vllm-ref/--vllm-repo/--vllm-source-dir指定 vLLM 版本 / 仓库 / 本地干净检出--apply-vllm-pr pr构建前应用上游 PR 补丁可多次--flashinfer-ref ref/--apply-flashinfer-pr指定 FlashInfer 版本或补丁进入 custom 缓存剖面--exp-b12x切换到 B12X 实验镜像/源码构建--no-build跳过镜像准备只做分发--cleanup清空所有.wheel-cache剖面里的 Wheel 与标记文件--config file指定自定义集群配置文件-j, --build-jobs并行编译任务数默认 16完整帮助随时可查./build-and-copy.sh --help。五、典型工作流示例# 场景1单机跑模型最简单 ./build-and-copy.sh ./hf-download.sh nvidia/Qwen3.8-27B-NVFP4 ./launch-cluster.sh --solo -t vllm-node exec vllm serve nvidia/Qwen3.8-27B-NVFP4 ... # 场景2双 Spark 集群镜像模型一次分发到位 ./build-and-copy.sh --exp-b12x -c --copy-parallel ./hf-download.sh deepseek-ai/DeepSeek-V4-Flash-Vision-Exp -c --copy-parallel # 场景3给上游 vLLM 打补丁重建PR 会叠加到 main 分支之上 ./build-and-copy.sh --apply-vllm-pr 12345 -c小贴士如果构建/分发后想释放磁盘./build-and-copy.sh --cleanup会清掉全部 Wheel 缓存再次构建时脚本会自动重新下载无需手工干预。六、想深入源码build-and-copy.sh主脚本缓存新鲜度逻辑在try_download_wheels第 343 行起分发逻辑在第 1407 行起Dockerfile六阶段多阶段构建flashinfer-export/vllm-export/runner是三个关键阶段autodiscover.sh.env加载、节点与COPY_HOSTS自动发现docker/validate_flashinfer_wheels.pyFlashInfer Wheel 集完整性校验tests/test_build_and_copy.sh用假 docker/ssh/curl 覆盖的完整行为测试理解各路径判断条件的最佳教材README.md从 Quick Start 到 CHANGELOG 的完整使用文档。搞懂了这个脚本你就掌握了 spark-vllm-docker 的供给链一条命令从镜像到全集群节点全程自动、可增量、失败可回滚。【免费下载链接】spark-vllm-dockerDocker configuration for running VLLM on dual DGX Sparks项目地址: https://gitcode.com/gh_mirrors/sp/spark-vllm-docker创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 读懂build-and-copy.sh：spark-vllm-docker镜像构建、预编译Wheel缓存与集群分发机制深度解析
读懂build-and-copy.shspark-vllm-docker镜像构建、预编译Wheel缓存与集群分发机制深度解析【免费下载链接】spark-vllm-dockerDocker configuration for running VLLM on dual DGX Sparks项目地址: https://gitcode.com/gh_mirrors/sp/spark-vllm-dockerspark-vllm-docker 是专为 NVIDIA DGX Spark 双节点/多节点集群打造的 vLLM Docker 配置仓库而它的核心脚本 build-and-copy.sh 一条命令就搞定三件事准备 vLLM 镜像拉取官方测试过的预构建镜像或从预编译 Wheel 缓存/源码本地构建、管理 Wheel 缓存自动下载、校验、增量更新、向集群其他节点分发镜像。本文带你彻底读懂它的运行逻辑与常用参数。一、它解决什么问题在 DGX Spark 集群上跑 vLLM你通常要面对三个麻烦编译太慢vLLM、FlashInfer、NCCL 需要针对 GB10 的12.1asm_121a架构编译动辄数小时节点要一致双 Spark / 多 Spark 集群要求每台节点都有相同镜像版本要新鲜vLLM 迭代极快需要可靠的是否已最新判断避免重复下载或编译。build-and-copy.sh约 1500 行就是围绕这三点设计的编排脚本。它的镜像准备逻辑由一条简单规则决定见 build-and-copy.sh#L1074-L1077除非你显式请求了定制化构建否则默认拉取预构建镜像。# 最常用的一行命令拉取预构建镜像并按需分发到集群 ./build-and-copy.sh -c --copy-parallel二、三条镜像准备路径1️⃣ 默认路径拉取预构建 Runner 镜像不带任何定制参数时脚本执行docker pull eugr/spark-vllm:latest然后打上本地标签vllm-node见 build-and-copy.sh#L1148-L1152。eugr/spark-vllm:latest是 CI 流水线每晚构建并测试过的镜像latest指针只在通过集群/单机多模型测试后才前移--exp-b12x则拉取独立维护的eugr/spark-vllm-b12x:latest并打标签vllm-node-b12x用于 sm12x 高性能内核的实验特性自定义标签用-t tag例如./build-and-copy.sh -t my-vllm。这条路径最快、最省心99% 的用户只需要它。2️⃣ Wheel 缓存路径--use-wheels只做镜像组装如果你改过某些构建参数自定义 vLLM 版本、应用 PR 补丁等脚本进入本地构建路径。它并不会每次都全量编译而是围绕项目根目录下的.wheel-cache/目录定义于 build-and-copy.sh#L79做精细的增量管理缓存剖面路径用途FlashInfer regular.wheel-cache/flashinfer/regular默认架构的官方预编译 FlashInfer 三件套cubin / jit_cache / pythonFlashInfer custom.wheel-cache/flashinfer/custom自定义--flashinfer-ref/--apply-flashinfer-pr/ 非默认--gpu-archvLLM regular / b12x / custom.wheel-cache/vllm/profile三种 vLLM 构建剖面各自的 Wheel 缓存它如何判断缓存已最新核心函数try_download_wheels见 build-and-copy.sh#L343-L551发布资产比对抓取发布页资产列表本地文件全部存在才继续Commit 比对本地.flashinfer-commit/.vllm-commit与发布页记录的 commit 一致则跳过时间戳兜底逐个比较本地 Wheel 的 mtime 与远端Last-Modified头本地更新的本地构建 Wheel不会被覆盖这就是 2026-05-29 更新带来的Wheel 新鲜度检测架构标记校验缓存目录里的.flashinfer-arch/.vllm-arch标记必须与当前--gpu-arch匹配防止把别的架构的 Wheel 错装进镜像。失败即回滚下载前先备份旧 Wheel 到.backup-download-*目录任何一个文件下载失败或 FlashInfer 发布集不完整由 docker/validate_flashinfer_wheels.py 校验 JIT provider 依赖就整体恢复旧缓存绝不让新旧混杂的 Wheel 进入构建。--use-wheels的承诺是只用现成 WheelWheel 缺失且下载失败时直接报错绝不会悄悄退化成源码编译可用--rebuild-vllm/--rebuild-flashinfer显式触发重编。3️⃣ 源码构建路径三阶段导出真正需要编译时Dockerfile 的多阶段设计把工作切成三段每段产物都先写入 staging 目录、校验通过后才原子性地晋升为正式缓存promote_wheel_set见 build-and-copy.sh#L603-L623Stage 2: flashinfer-builder ──► flashinfer-export → .wheel-cache/flashinfer/profile/ Stage 4: vllm-builder ──► vllm-export → .wheel-cache/vllm/profile/ Stage 6: runner安装两组 Wheel 并组装最终镜像 → vllm-node / vllm-node-b12x--vllm-ref sha/branch/tag、--vllm-repo url、--vllm-source-dir 本地干净检出三种方式指定 vLLM 来源本地检出会以 staging 副本形式喂给 Docker主机上的仓库不会被修改--apply-vllm-pr 编号或URL可在构建前叠加任意上游 PR 补丁可重复指定每次成功构建还会生成build-metadata.yaml记录 vLLM/FlashInfer 的 commit、Torch 版本、GPU 架构等方便溯源。三、集群分发机制-c与--copy-parallel镜像准备好后脚本把它分发到集群的每个节点确定目标主机-c host1,host2显式指定省略主机则读.env里的COPY_HOSTS由 autodiscover.sh 自动发现 InfiniBand 直连节点并交互确认保存或用--setup强制重新发现。集群组网细节参见 docs/NETWORKING.md先比对镜像 ID 再传输对每个目标执行ssh host docker image inspect --format {{.Id}}build-and-copy.sh#L249-L253ID 相同的节点直接跳过全部节点都是最新时连docker save都不会执行一次打包逐台或并行推送docker save导出到临时文件后通过cat 镜像 | ssh host docker load推送--copy-parallel让多台节点并发传输并等待全部完成每台节点单独报告耗时计时统计结束时输出 TIMING STATISTICS 汇总表Prebuilt Pull / FlashInfer Build / vLLM Build / Runner Build / Image Copy / Total方便定位慢在哪一步。--no-build -c host则跳过一切准备步骤仅把本机已有镜像拷贝过去适合别的机器刚构建完、只想同步的场景。四、常用参数速查参数作用-t, --tag tag自定义本地镜像标签默认vllm-node-c, --copy-to [hosts]分发镜像到指定主机省略主机则用.env/自动发现--copy-parallel与-c搭配并发分发--use-wheels只用预编译 Wheel 构建 Runner缺失即报错绝不隐式编译--rebuild-vllm/--rebuild-flashinfer强制从源码重编对应 Wheel--force-download跳过新鲜度检查强制重新下载全部预编译 Wheel--vllm-ref/--vllm-repo/--vllm-source-dir指定 vLLM 版本 / 仓库 / 本地干净检出--apply-vllm-pr pr构建前应用上游 PR 补丁可多次--flashinfer-ref ref/--apply-flashinfer-pr指定 FlashInfer 版本或补丁进入 custom 缓存剖面--exp-b12x切换到 B12X 实验镜像/源码构建--no-build跳过镜像准备只做分发--cleanup清空所有.wheel-cache剖面里的 Wheel 与标记文件--config file指定自定义集群配置文件-j, --build-jobs并行编译任务数默认 16完整帮助随时可查./build-and-copy.sh --help。五、典型工作流示例# 场景1单机跑模型最简单 ./build-and-copy.sh ./hf-download.sh nvidia/Qwen3.8-27B-NVFP4 ./launch-cluster.sh --solo -t vllm-node exec vllm serve nvidia/Qwen3.8-27B-NVFP4 ... # 场景2双 Spark 集群镜像模型一次分发到位 ./build-and-copy.sh --exp-b12x -c --copy-parallel ./hf-download.sh deepseek-ai/DeepSeek-V4-Flash-Vision-Exp -c --copy-parallel # 场景3给上游 vLLM 打补丁重建PR 会叠加到 main 分支之上 ./build-and-copy.sh --apply-vllm-pr 12345 -c小贴士如果构建/分发后想释放磁盘./build-and-copy.sh --cleanup会清掉全部 Wheel 缓存再次构建时脚本会自动重新下载无需手工干预。六、想深入源码build-and-copy.sh主脚本缓存新鲜度逻辑在try_download_wheels第 343 行起分发逻辑在第 1407 行起Dockerfile六阶段多阶段构建flashinfer-export/vllm-export/runner是三个关键阶段autodiscover.sh.env加载、节点与COPY_HOSTS自动发现docker/validate_flashinfer_wheels.pyFlashInfer Wheel 集完整性校验tests/test_build_and_copy.sh用假 docker/ssh/curl 覆盖的完整行为测试理解各路径判断条件的最佳教材README.md从 Quick Start 到 CHANGELOG 的完整使用文档。搞懂了这个脚本你就掌握了 spark-vllm-docker 的供给链一条命令从镜像到全集群节点全程自动、可增量、失败可回滚。【免费下载链接】spark-vllm-dockerDocker configuration for running VLLM on dual DGX Sparks项目地址: https://gitcode.com/gh_mirrors/sp/spark-vllm-docker创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考