★ FEATURED ARTICLE 如何为自研模型写一个Recipespark-vllm-docker配方YAML字段参考与参数替换教程【免费下载链接】spark-vllm-dockerDocker configuration for running VLLM on dual DGX Sparks项目地址: https://gitcode.com/gh_mirrors/sp/spark-vllm-docker想在 DGX Spark 上一键部署自研模型spark-vllm-docker 的Recipe配方系统就是为你准备的每个 Recipe 是一个简单的 YAML 文件声明要下载哪个 HuggingFace 模型、用哪个 Docker 容器镜像、应用哪些补丁mods、以及最终的vllm serve启动命令。写对 YAML 字段、掌握{参数}替换机制你的模型就能通过一条./run-recipe.sh命令完成「建镜像 下模型 起服务」的全流程。 一、30 秒认识 Recipe 系统在 spark-vllm-docker 中Recipe 位于recipes/目录由 run-recipe.py 解析执行。它的核心价值是一键部署# 列出所有可用配方 ./run-recipe.sh --list # 单节点跑一个配方 ./run-recipe.sh gemma4-26b-a4b --solo # 完整流程自动建镜像 下载模型 启动服务 ./run-recipe.sh gemma4-26b-a4b --solo --setup # 运行时覆盖参数 ./run-recipe.sh gemma4-26b-a4b --solo --port 9000 --gpu-mem 0.8首次使用集群前用./run-recipe.sh --discover自动发现节点并保存配置到.env之后的配方运行会自动读取。 二、Recipe YAML 字段完整参考表一个合法 Recipe 必须包含 4 个必填字段其余字段均可选run-recipe.py 中的校验逻辑会检查缺失字段并直接报错。字段必填类型作用name✅字符串配方的人类可读名称recipe_version✅字符串Schema 版本当前固定为1container✅字符串容器镜像标签如vllm-node、vllm-node-b12xcommand✅多行字符串vllm serve命令模板支持{占位符}description⬜字符串简要描述显示在--list列表中model⬜字符串HuggingFace 模型 ID供--setup自动下载mods⬜列表需要应用的 mod/补丁目录如mods/fix-gemma4-tool-parserdefaults⬜字典{占位符}的默认值可被 CLI 覆盖env⬜字典注入容器内的环境变量build_args⬜列表传给 build-and-copy.sh 的构建参数如--exp-b12xcluster_only⬜布尔为true时禁止 solo 模式模型太大solo_only⬜布尔为true时禁止集群模式以官方示例 recipes/minimax-m2-awq.yaml 为例recipe_version: 1 name: MiniMax-M2-AWQ description: vLLM serving MiniMax-M2-AWQ on a multi-node cluster model: QuantTrio/MiniMax-M2-AWQ container: vllm-node cluster_only: true mods: [] defaults: port: 8000 host: 0.0.0.0 tensor_parallel: 2 gpu_memory_utilization: 0.8 max_model_len: 128000 env: {} command: | vllm serve QuantTrio/MiniMax-M2-AWQ \ --port {port} \ --host {host} \ --gpu-memory-utilization {gpu_memory_utilization} \ -tp {tensor_parallel} \ --distributed-executor-backend ray \ --max-model-len {max_model_len} 更多范例可参考recipes/gemma4-26b-a4b.yaml、recipes/deepseek-v4-flash.yaml、recipes/glm-4.7-flash-awq.yaml。 三、参数替换机制{占位符}是怎么工作的这是 Recipe 最灵活的部分也是新手最容易踩坑的地方。替换规则在command中写{参数名}运行时它会被替换为「CLI 覆盖值 defaults 中的值」。例如--port {port}当你运行./run-recipe.sh my-recipe --port 9000时模板中的{port}就被替换成9000。内置的可覆盖参数包括--port、--host、--tp--tensor-parallel、--gpu-mem--gpu-memory-utilization、--max-model-len。但注意defaults可以定义任意自定义占位符如 recipes/qwen3.5-397b-int4-autoround.yaml 中的kv_cache_memory_bytes这些自定义参数只能写死在 YAML 里或改用命令行--追加参数。⚠️ 头号陷阱JSON 花括号必须双写命令里若出现 JSON比如投机解码配置speculative-config其中的花括号会被模板引擎误认为占位符。解决办法是把{和}双写成{{和}}官方配方 recipes/deepseek-v4-flash.yaml 正是这么做的command: | vllm serve deepseek-ai/DeepSeek-V4-Flash \ --speculative-config {{method:mtp,num_speculative_tokens:{num_speculative_tokens}}}上面这行里{{...}}是字面量 JSON 花括号而中间的{num_speculative_tokens}仍是占位符替换后输出为--speculative-config {method:mtp,num_speculative_tokens:2}记住口诀JSON 用双括号转义占位符用单括号替换。✍️ 四、手把手写你的第一个自研模型 Recipe完整流程只需 4 步第 1 步获取仓库代码git clone https://gitcode.com/gh_mirrors/sp/spark-vllm-docker cd spark-vllm-docker第 2 步创建 YAML 文件在recipes/下新建my-model.yaml填入最小可用骨架recipe_version: 1 name: My Custom Model description: vLLM serving my-org/my-model on DGX Spark model: my-org/my-model container: vllm-node defaults: port: 8000 host: 0.0.0.0 tensor_parallel: 1 gpu_memory_utilization: 0.8 max_model_len: 32768 command: | vllm serve my-org/my-model \ --port {port} \ --host {host} \ -tp {tensor_parallel} \ --max-model-len {max_model_len} \ --gpu-memory-utilization {gpu_memory_utilization}第 3 步按需追加可选字段模型需要补丁加mods路径相对仓库根目录参考 mods/ 下的现成 mod 写法模型太大必须集群加cluster_only: truesolo 模式运行时会给出友好报错需要特殊环境变量如DG_JIT_USE_NVRTC: 0填入env写法见 recipes/deepseek-v4-flash.yaml需要 B12X 实验镜像加build_args: [ --exp-b12x ]并把container改为vllm-node-b12x完整范例见 recipes/qwen3.8-flash-next-nvfp4-solo.yaml第 4 步试运行先用--dry-run预览将执行的完整命令确认无误后再实际启动# 预览命令不实际执行 ./run-recipe.sh my-model --solo --dry-run # 完整流程建镜像 下模型 启动 ./run-recipe.sh my-model --solo --setup启动后在另一个终端验证服务curl --fail http://localhost:8000/health curl --fail http://localhost:8000/v1/models 五、运行与调试这些开关能救命命令用途--dry-run只打印将要执行的命令不实际运行--setup完整流程构建镜像 下载模型 启动--build-only/--download-only只做镜像构建或模型下载不启动--force-build/--force-download强制重建镜像 / 重新下载模型--port N--tp N--gpu-mem X--max-model-len N覆盖 defaults 中的对应占位符-e VARVALUE追加容器环境变量可重复-v 本地路径:容器路径挂载数据卷可重复-- 参数...--之后的参数原样追加到 vLLM 命令末尾其中--追加参数非常实用适合临时调试而不用改 YAML# 覆盖加载格式 ./run-recipe.sh my-model --solo -- --load-format safetensors # 自定义 API 名称 ./run-recipe.sh my-model --solo -- --served-model-name my-api-name # 多个参数一起追加 ./run-recipe.sh my-model --solo -- --load-format auto --enforce-eager⚠️ 注意如果追加的参数与 CLI 覆盖项冲突例如既--port 9000又-- --port 8000运行器会告警且后出现的追加参数获胜。能用内置覆盖参数就别重复追加。️ 六、进阶build_args、mods 与记忆优化组合拳build_args控制镜像怎么构建常用取值参数说明--exp-b12x使用 B12X 实验镜像标签vllm-node-b12x--exp-mxfp4使用 MXFP4 量化专用 Dockerfile--use-wheels用预编译 wheel 构建而不是拉取官方镜像mods是 spark-vllm-docker 的特色能力每个 mod 是一个目录含run.sh和补丁文件在启动前自动应用。真实案例 recipes/qwen3.5-397b-int4-autoround.yaml 一口气叠了 4 个 mod 来解决大模型内存问题mods: - mods/fix-qwen3.5-chat-template - mods/gpu-mem-util-gb - mods/kv-cache-prealloc-cleanup - mods/drop-caches如果你的自研模型在 Spark 上遇到聊天模板不兼容、内存吃紧等问题大概率能在 mods/ 目录里找到现成方案直接引用即可。❓ 七、常见问题速查Q1配方文件放哪怎么被找到放在recipes/目录下扩展名.yaml或.yml。也可以传完整路径运行./run-recipe.sh recipes/my-model.yaml。解析顺序见 run-recipe.py。Q2占位符替换后还有{}残留启动报错十有八九是 JSON 没双写括号。检查命令里所有 JSON 结构把{/}改成{{/}}。Q3集群配方跑 solo 报「requires cluster mode」这是cluster_only: true的拦截提示属于正常保护。先./run-recipe.sh --discover配置节点再不带--solo运行。Q4模型需要访问令牌gated modelexport HF_TOKENYOUR_TOKEN ./run-recipe.sh my-model -e HF_TOKEN$HF_TOKEN --setupQ5怎么验证我的 YAML 写对了最快的方式是--dry-run字段缺失或拼写错误会立刻报错模板替换后的完整命令会打印出来供你检查。字段规则与容错逻辑都在 run-recipe.py 中官方格式说明在 recipes/README.md。 八、参考资料配方系统官方文档recipes/README.md配方解析源码run-recipe.py集群网络配置指南docs/NETWORKING.md集群启动脚本launch-cluster.sh现成范例库recipes/含 20 个覆盖 FP8/NVFP4/AWQ/INT4 各种量化的真实配方掌握以上内容从写 YAML 到服务上线通常只需 10 分钟。建议先从最简单的 solo 配方如 recipes/gemma4-26b-a4b.yaml抄起再逐步叠加 mods 与集群配置你的自研模型就能稳稳跑在 DGX Spark 上了 【免费下载链接】spark-vllm-dockerDocker configuration for running VLLM on dual DGX Sparks项目地址: https://gitcode.com/gh_mirrors/sp/spark-vllm-docker创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
