尧图网站建设 
不用重编译镜像也能改vLLMspark-vllm-docker的Mods补丁系统与--apply-vllm-pr实战指南【免费下载链接】spark-vllm-dockerDocker configuration for running VLLM on dual DGX Sparks项目地址: https://gitcode.com/gh_mirrors/sp/spark-vllm-docker 想修改 vLLM 的运行时行为通常意味着重新编译镜像、重新分发到集群——耗时且低效。spark-vllm-docker 的Mods 补丁系统提供了另一条路通过--apply-mod和--apply-vllm-pr两个参数在容器启动瞬间把补丁直接打到运行中的 vLLM 安装目录上无需重编译镜像、无需新增永久文件。本文带你完整理解这套系统的原理与用法。为什么不想每次改代码都重编译镜像spark-vllm-docker 是面向 DGX Spark单机或双机/多机集群的 vLLM Docker 配置项目。默认流程是拉取已测试的 nightly 预构建镜像几分钟内即可开跑git clone https://gitcode.com/gh_mirrors/sp/spark-vllm-docker cd spark-vllm-docker ./build-and-copy.sh # 默认拉取预构建镜像但 vLLM 迭代极快新模型发布时经常遇到上游 PR 还没合并、某个量化格式加载报错、内存分配策略不合心意……如果每次都要走源码构建编译 vLLM、FlashInfer、Triton一轮下来就是几十分钟到数小时。spark-vllm-docker 的思路是预构建镜像负责跑起来补丁系统负责改行为。什么是 Mod一个运行时的补丁单元Mod 是 mods/ 目录下的一个子目录结构非常轻量mods/mod-name/ ├── run.sh # 必需执行补丁的脚本不接受任何参数 └── *.patch # 可选补丁文件或其他资源run.sh在容器启动时被执行典型做法是用patch命令修改已安装的 vLLM 包文件例如 mods/fix-glm-4.7-flash-AWQ/run.sh 会先应用本地性能补丁再检查并拉取上游 PR 补丁修复崩溃问题。补丁是临时性的只对每次新创建的容器生效重建容器时自动重新应用镜像本身保持不变。 补丁也可以是一个与目录结构相同的.zip包解压后同样适用。三步快速应用 Mod--apply-mod 用法第一步确认需要的 Modmods/ 下有现成的见下文清单。第二步在启动命令中加一个--apply-mod参数。第三步启动集群补丁自动随容器分发并应用。./launch-cluster.sh --solo \ --apply-mod mods/gpu-mem-util-gb \ exec vllm serve MODEL_NAME \ --gpu-memory-utilization-gb 110 \ --port 8000 --host 0.0.0.0支持多个 Mod 连续叠加按命令行顺序依次应用./launch-cluster.sh \ --apply-mod mods/fix-Salyut1-GLM-4.7-NVFP4 \ --apply-mod mods/drop-caches \ exec vllm serve Salyut1/GLM-4.7-NVFP4 ...如果你用配方recipe启动模型run-recipe.sh 会把--apply-mod透传给 launch-cluster.sh配方 YAML 中声明的mods:字段先应用命令行传入的排在后面见 recipes/README.md./run-recipe.sh glm-4.7-flash-awq --solo --apply-mod mods/use-official-vllm内置 Mod 清单按模型需求对号入座仓库自带了一批经过实战检验的 Mod覆盖模型兼容性修复内存调优实验特性三类场景Mod 路径用途mods/fix-glm-4.7-flash-AWQ/GLM-4.7-Flash-AWQ 兼容性与推理速度修复mods/fix-Salyut1-GLM-4.7-NVFP4/修复融合量化下 GLM4MoE 解析器不兼容问题mods/gpu-mem-util-gb/新增--gpu-memory-utilization-gb参数按 GiB 固定显存预留适配统一内存架构mods/drop-caches/每分钟清理文件系统缓存解决大模型加载卡死mods/kv-cache-prealloc-cleanup/KV cache 预分配清理策略微调mods/diffusiongemma/DiffusionGemma 模型支持、推理解析与内容通道修复mods/fix-qwen3-coder-next/Qwen3-Coder-Next 运行时与性能修复mods/fix-qwen3.5-chat-template/Qwen3.5 修复版聊天模板mods/nemotron-nano/、mods/nemotron-super/Nemotron 系列推理解析器支持mods/instanttensor-zero-copy/实验性零拷贝权重加载降低内存峰值mods/use-official-vllm/官方 vLLM 镜像的前置Mod安装 git、earlyoom、InstantTensor 并修复 NCCL 挂起问题mods/use-ngc-vllm/让 NGC 官方容器接入集群启动流程 使用官方vllm-openai等镜像时请永远把use-official-vllm放在第一个因为它负责安装其他 Mod 依赖的git等工具。--apply-vllm-pr 实战不建 Mod 目录也能打 vLLM PR 补丁这是整个系统最巧妙的部分。当你发现某个 vLLM 上游 PR 恰好修复了你遇到的问题却不想为它新建一个 Mod 目录时直接在启动命令里写 PR 编号即可./launch-cluster.sh --solo \ --apply-vllm-pr 52816 \ exec vllm serve MODEL_NAME --port 8000 --host 0.0.0.0 # 配方启动同样支持且参数可重复使用 ./run-recipe.sh glm-4.7-flash-awq --solo \ --apply-vllm-pr 12345 \ --apply-vllm-pr 52816参数支持两种形式纯数字从 vLLM 官方仓库选取对应 PR完整 PR URL指定其他公开仓库中的 PR比如实验分支 fork。启动时 launch-cluster.sh 会在头节点做一套完整的安检流程下载一次拉取该 PR 的 diff 文件并缓存运行时校验逐行解析 diff 头部确认 PR 只改动已安装的vllm/包内 Python 文件——测试、文档、CI 配置自动忽略而 CUDA/C 源码、setup.py、CMake 等需要编译或改依赖的文件会直接拒绝并提示你改用构建期方案SHA256 校验补丁文件记录哈希分发到每个节点后逐容器比对防止传输损坏按序应用多个 PR 按指定顺序用git apply打补丁如果检测到补丁已生效会自动跳过幂等。补丁通过标准的 Mod 分发路径送达每个节点因此集群模式下所有容器都会被打上同样的补丁。使用 --apply-vllm-pr 的 4 个硬性前提⚠️ 容器内必须有git。官方 vLLM 镜像默认不带需要先把 mods/use-official-vllm/ 排在 PR 层之前⚠️ 若同名容器已在运行启动器会拒绝--apply-vllm-pr——因为它无法确认旧容器里是否已含该补丁需先./launch-cluster.sh stop⚠️ 补丁必须能干净地应用到当前已安装的 vLLM 版本否则会提示改用构建期方案⚠️ 变更是临时的不写入镜像。每次新建容器都会重新应用这正是设计目标。什么时候该改用构建期补丁当 PR 涉及 C/CUDA 内核、依赖变更或打包改动时运行时应用会被拒绝。此时把同样的参数交给构建脚本让补丁参与镜像构建# 构建期应用 vLLM PR可重复 ./build-and-copy.sh -t vllm-node-custom --apply-vllm-pr 12345 -c # 实验 B12X 镜像 指定仓库的 PR同样在构建期处理 ./build-and-copy.sh --exp-b12x -t vllm-node-b12x --rebuild-vllm \ --apply-vllm-pr 完整PR-URL -c简单记法纯 Python 的 PR → 启动期--apply-vllm-pr秒级生效带编译产物的 PR → 构建期--apply-vllm-pr烧进镜像。自己动手4 步写一个自定义 Mod在 mods/ 下新建目录如mods/my-fix/放入补丁文件.patch或需要的资源文件编写 run.sh可参考现有实现用patch -p1或脚本完成文件修改——注意它不接受任何参数且建议在打补丁前先探测目标文件是否已修改保证幂等启动时用--apply-mod mods/my-fix引用。这套流程特别适合新模型 day-0 兼容修复、实验特性验证、不满足时回滚零成本的快速迭代——镜像不用动仓库git pull一下即可共享。常见坑位速查 现象原因与解法补丁应用失败提示缺git官方镜像先用mods/use-official-vllm--apply-vllm-pr被拒绝容器已在运行先stop再启动PR 被判定not runtime-onlyPR 含编译产物改用build-and-copy.sh --apply-vllm-pr补丁应用报does not apply cleanly当前 vLLM 版本与 PR 基线偏差大重新构建对齐版本配方与命令行 Mod 顺序疑问配方mods:永远先于命令行命令行内按书写顺序小结spark-vllm-docker 把改 vLLM拆成了两层Mods 补丁系统--apply-mod提供可复用的目录级补丁单元运行时 PR 应用--apply-vllm-pr让你用一行命令给任意节点集群打上游补丁。两者都不触碰镜像本身让改代码 → 起服务的循环从小时级缩短到分钟级。配合 recipes/ 配方系统模型兼容修复还能沉淀为 YAML 里的mods:声明随配方一键复用。想上手先跑通./run-recipe.sh --list看看有哪些现成配方再挑一个内置 Mod 试试--apply-mod的威力。【免费下载链接】spark-vllm-dockerDocker configuration for running VLLM on dual DGX Sparks项目地址: https://gitcode.com/gh_mirrors/sp/spark-vllm-docker创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 不用重编译镜像也能改vLLM：spark-vllm-docker的Mods补丁系统与--apply-vllm-pr实战指南
不用重编译镜像也能改vLLMspark-vllm-docker的Mods补丁系统与--apply-vllm-pr实战指南【免费下载链接】spark-vllm-dockerDocker configuration for running VLLM on dual DGX Sparks项目地址: https://gitcode.com/gh_mirrors/sp/spark-vllm-docker 想修改 vLLM 的运行时行为通常意味着重新编译镜像、重新分发到集群——耗时且低效。spark-vllm-docker 的Mods 补丁系统提供了另一条路通过--apply-mod和--apply-vllm-pr两个参数在容器启动瞬间把补丁直接打到运行中的 vLLM 安装目录上无需重编译镜像、无需新增永久文件。本文带你完整理解这套系统的原理与用法。为什么不想每次改代码都重编译镜像spark-vllm-docker 是面向 DGX Spark单机或双机/多机集群的 vLLM Docker 配置项目。默认流程是拉取已测试的 nightly 预构建镜像几分钟内即可开跑git clone https://gitcode.com/gh_mirrors/sp/spark-vllm-docker cd spark-vllm-docker ./build-and-copy.sh # 默认拉取预构建镜像但 vLLM 迭代极快新模型发布时经常遇到上游 PR 还没合并、某个量化格式加载报错、内存分配策略不合心意……如果每次都要走源码构建编译 vLLM、FlashInfer、Triton一轮下来就是几十分钟到数小时。spark-vllm-docker 的思路是预构建镜像负责跑起来补丁系统负责改行为。什么是 Mod一个运行时的补丁单元Mod 是 mods/ 目录下的一个子目录结构非常轻量mods/mod-name/ ├── run.sh # 必需执行补丁的脚本不接受任何参数 └── *.patch # 可选补丁文件或其他资源run.sh在容器启动时被执行典型做法是用patch命令修改已安装的 vLLM 包文件例如 mods/fix-glm-4.7-flash-AWQ/run.sh 会先应用本地性能补丁再检查并拉取上游 PR 补丁修复崩溃问题。补丁是临时性的只对每次新创建的容器生效重建容器时自动重新应用镜像本身保持不变。 补丁也可以是一个与目录结构相同的.zip包解压后同样适用。三步快速应用 Mod--apply-mod 用法第一步确认需要的 Modmods/ 下有现成的见下文清单。第二步在启动命令中加一个--apply-mod参数。第三步启动集群补丁自动随容器分发并应用。./launch-cluster.sh --solo \ --apply-mod mods/gpu-mem-util-gb \ exec vllm serve MODEL_NAME \ --gpu-memory-utilization-gb 110 \ --port 8000 --host 0.0.0.0支持多个 Mod 连续叠加按命令行顺序依次应用./launch-cluster.sh \ --apply-mod mods/fix-Salyut1-GLM-4.7-NVFP4 \ --apply-mod mods/drop-caches \ exec vllm serve Salyut1/GLM-4.7-NVFP4 ...如果你用配方recipe启动模型run-recipe.sh 会把--apply-mod透传给 launch-cluster.sh配方 YAML 中声明的mods:字段先应用命令行传入的排在后面见 recipes/README.md./run-recipe.sh glm-4.7-flash-awq --solo --apply-mod mods/use-official-vllm内置 Mod 清单按模型需求对号入座仓库自带了一批经过实战检验的 Mod覆盖模型兼容性修复内存调优实验特性三类场景Mod 路径用途mods/fix-glm-4.7-flash-AWQ/GLM-4.7-Flash-AWQ 兼容性与推理速度修复mods/fix-Salyut1-GLM-4.7-NVFP4/修复融合量化下 GLM4MoE 解析器不兼容问题mods/gpu-mem-util-gb/新增--gpu-memory-utilization-gb参数按 GiB 固定显存预留适配统一内存架构mods/drop-caches/每分钟清理文件系统缓存解决大模型加载卡死mods/kv-cache-prealloc-cleanup/KV cache 预分配清理策略微调mods/diffusiongemma/DiffusionGemma 模型支持、推理解析与内容通道修复mods/fix-qwen3-coder-next/Qwen3-Coder-Next 运行时与性能修复mods/fix-qwen3.5-chat-template/Qwen3.5 修复版聊天模板mods/nemotron-nano/、mods/nemotron-super/Nemotron 系列推理解析器支持mods/instanttensor-zero-copy/实验性零拷贝权重加载降低内存峰值mods/use-official-vllm/官方 vLLM 镜像的前置Mod安装 git、earlyoom、InstantTensor 并修复 NCCL 挂起问题mods/use-ngc-vllm/让 NGC 官方容器接入集群启动流程 使用官方vllm-openai等镜像时请永远把use-official-vllm放在第一个因为它负责安装其他 Mod 依赖的git等工具。--apply-vllm-pr 实战不建 Mod 目录也能打 vLLM PR 补丁这是整个系统最巧妙的部分。当你发现某个 vLLM 上游 PR 恰好修复了你遇到的问题却不想为它新建一个 Mod 目录时直接在启动命令里写 PR 编号即可./launch-cluster.sh --solo \ --apply-vllm-pr 52816 \ exec vllm serve MODEL_NAME --port 8000 --host 0.0.0.0 # 配方启动同样支持且参数可重复使用 ./run-recipe.sh glm-4.7-flash-awq --solo \ --apply-vllm-pr 12345 \ --apply-vllm-pr 52816参数支持两种形式纯数字从 vLLM 官方仓库选取对应 PR完整 PR URL指定其他公开仓库中的 PR比如实验分支 fork。启动时 launch-cluster.sh 会在头节点做一套完整的安检流程下载一次拉取该 PR 的 diff 文件并缓存运行时校验逐行解析 diff 头部确认 PR 只改动已安装的vllm/包内 Python 文件——测试、文档、CI 配置自动忽略而 CUDA/C 源码、setup.py、CMake 等需要编译或改依赖的文件会直接拒绝并提示你改用构建期方案SHA256 校验补丁文件记录哈希分发到每个节点后逐容器比对防止传输损坏按序应用多个 PR 按指定顺序用git apply打补丁如果检测到补丁已生效会自动跳过幂等。补丁通过标准的 Mod 分发路径送达每个节点因此集群模式下所有容器都会被打上同样的补丁。使用 --apply-vllm-pr 的 4 个硬性前提⚠️ 容器内必须有git。官方 vLLM 镜像默认不带需要先把 mods/use-official-vllm/ 排在 PR 层之前⚠️ 若同名容器已在运行启动器会拒绝--apply-vllm-pr——因为它无法确认旧容器里是否已含该补丁需先./launch-cluster.sh stop⚠️ 补丁必须能干净地应用到当前已安装的 vLLM 版本否则会提示改用构建期方案⚠️ 变更是临时的不写入镜像。每次新建容器都会重新应用这正是设计目标。什么时候该改用构建期补丁当 PR 涉及 C/CUDA 内核、依赖变更或打包改动时运行时应用会被拒绝。此时把同样的参数交给构建脚本让补丁参与镜像构建# 构建期应用 vLLM PR可重复 ./build-and-copy.sh -t vllm-node-custom --apply-vllm-pr 12345 -c # 实验 B12X 镜像 指定仓库的 PR同样在构建期处理 ./build-and-copy.sh --exp-b12x -t vllm-node-b12x --rebuild-vllm \ --apply-vllm-pr 完整PR-URL -c简单记法纯 Python 的 PR → 启动期--apply-vllm-pr秒级生效带编译产物的 PR → 构建期--apply-vllm-pr烧进镜像。自己动手4 步写一个自定义 Mod在 mods/ 下新建目录如mods/my-fix/放入补丁文件.patch或需要的资源文件编写 run.sh可参考现有实现用patch -p1或脚本完成文件修改——注意它不接受任何参数且建议在打补丁前先探测目标文件是否已修改保证幂等启动时用--apply-mod mods/my-fix引用。这套流程特别适合新模型 day-0 兼容修复、实验特性验证、不满足时回滚零成本的快速迭代——镜像不用动仓库git pull一下即可共享。常见坑位速查 现象原因与解法补丁应用失败提示缺git官方镜像先用mods/use-official-vllm--apply-vllm-pr被拒绝容器已在运行先stop再启动PR 被判定not runtime-onlyPR 含编译产物改用build-and-copy.sh --apply-vllm-pr补丁应用报does not apply cleanly当前 vLLM 版本与 PR 基线偏差大重新构建对齐版本配方与命令行 Mod 顺序疑问配方mods:永远先于命令行命令行内按书写顺序小结spark-vllm-docker 把改 vLLM拆成了两层Mods 补丁系统--apply-mod提供可复用的目录级补丁单元运行时 PR 应用--apply-vllm-pr让你用一行命令给任意节点集群打上游补丁。两者都不触碰镜像本身让改代码 → 起服务的循环从小时级缩短到分钟级。配合 recipes/ 配方系统模型兼容修复还能沉淀为 YAML 里的mods:声明随配方一键复用。想上手先跑通./run-recipe.sh --list看看有哪些现成配方再挑一个内置 Mod 试试--apply-mod的威力。【免费下载链接】spark-vllm-dockerDocker configuration for running VLLM on dual DGX Sparks项目地址: https://gitcode.com/gh_mirrors/sp/spark-vllm-docker创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考