如何為自研模型寫一個Recipespark-vllm-docker配方Y(jié)AML字段參考與參數(shù)替換教程【免費下載鏈接】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配方系統(tǒng)就是為你準備的每個 Recipe 是一個簡單的 YAML 文件聲明要下載哪個 HuggingFace 模型、用哪個 Docker 容器鏡像、應用哪些補丁mods、以及最終的vllm serve啟動命令。寫對 YAML 字段、掌握{(diào)參數(shù)}替換機制你的模型就能通過一條./run-recipe.sh命令完成「建鏡像 下模型 起服務」的全流程。 一、30 秒認識 Recipe 系統(tǒng)在 spark-vllm-docker 中Recipe 位于recipes/目錄由 run-recipe.py 解析執(zhí)行。它的核心價值是一鍵部署# 列出所有可用配方 ./run-recipe.sh --list # 單節(jié)點跑一個配方 ./run-recipe.sh gemma4-26b-a4b --solo # 完整流程自動建鏡像 下載模型 啟動服務 ./run-recipe.sh gemma4-26b-a4b --solo --setup # 運行時覆蓋參數(shù) ./run-recipe.sh gemma4-26b-a4b --solo --port 9000 --gpu-mem 0.8首次使用集群前用./run-recipe.sh --discover自動發(fā)現(xiàn)節(jié)點并保存配置到.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?字典注入容器內(nèi)的環(huán)境變量build_args?列表傳給 build-and-copy.sh 的構(gòu)建參數(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。 三、參數(shù)替換機制{占位符}是怎么工作的這是 Recipe 最靈活的部分也是新手最容易踩坑的地方。替換規(guī)則在command中寫{參數(shù)名}運行時它會被替換為「CLI 覆蓋值 defaults 中的值」。例如--port {port}當你運行./run-recipe.sh my-recipe --port 9000時模板中的{port}就被替換成9000。內(nèi)置的可覆蓋參數(shù)包括--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這些自定義參數(shù)只能寫死在 YAML 里或改用命令行--追加參數(shù)。?? 頭號陷阱JSON 花括號必須雙寫命令里若出現(xiàn) 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 用雙括號轉(zhuǎn)義占位符用單括號替換。?? 四、手把手寫你的第一個自研模型 Recipe完整流程只需 4 步第 1 步獲取倉庫代碼git clone https://gitcode.com/gh_mirrors/sp/spark-vllm-docker cd spark-vllm-docker第 2 步創(chuàng)建 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/ 下的現(xiàn)成 mod 寫法模型太大必須集群加cluster_only: truesolo 模式運行時會給出友好報錯需要特殊環(huán)境變量如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預覽將執(zhí)行的完整命令確認無誤后再實際啟動# 預覽命令不實際執(zhí)行 ./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 五、運行與調(diào)試這些開關(guān)能救命命令用途--dry-run只打印將要執(zhí)行的命令不實際運行--setup完整流程構(gòu)建鏡像 下載模型 啟動--build-only/--download-only只做鏡像構(gòu)建或模型下載不啟動--force-build/--force-download強制重建鏡像 / 重新下載模型--port N--tp N--gpu-mem X--max-model-len N覆蓋 defaults 中的對應占位符-e VARVALUE追加容器環(huán)境變量可重復-v 本地路徑:容器路徑掛載數(shù)據(jù)卷可重復-- 參數(shù)...--之后的參數(shù)原樣追加到 vLLM 命令末尾其中--追加參數(shù)非常實用適合臨時調(diào)試而不用改 YAML# 覆蓋加載格式 ./run-recipe.sh my-model --solo -- --load-format safetensors # 自定義 API 名稱 ./run-recipe.sh my-model --solo -- --served-model-name my-api-name # 多個參數(shù)一起追加 ./run-recipe.sh my-model --solo -- --load-format auto --enforce-eager?? 注意如果追加的參數(shù)與 CLI 覆蓋項沖突例如既--port 9000又-- --port 8000運行器會告警且后出現(xiàn)的追加參數(shù)獲勝。能用內(nèi)置覆蓋參數(shù)就別重復追加。? 六、進階build_args、mods 與記憶優(yōu)化組合拳build_args控制鏡像怎么構(gòu)建常用取值參數(shù)說明--exp-b12x使用 B12X 實驗鏡像標簽vllm-node-b12x--exp-mxfp4使用 MXFP4 量化專用 Dockerfile--use-wheels用預編譯 wheel 構(gòu)建而不是拉取官方鏡像mods是 spark-vllm-docker 的特色能力每個 mod 是一個目錄含run.sh和補丁文件在啟動前自動應用。真實案例 recipes/qwen3.5-397b-int4-autoround.yaml 一口氣疊了 4 個 mod 來解決大模型內(nèi)存問題mods: - mods/fix-qwen3.5-chat-template - mods/gpu-mem-util-gb - mods/kv-cache-prealloc-cleanup - mods/drop-caches如果你的自研模型在 Spark 上遇到聊天模板不兼容、內(nèi)存吃緊等問題大概率能在 mods/ 目錄里找到現(xiàn)成方案直接引用即可。? 七、常見問題速查Q1配方文件放哪怎么被找到放在recipes/目錄下擴展名.yaml或.yml。也可以傳完整路徑運行./run-recipe.sh recipes/my-model.yaml。解析順序見 run-recipe.py。Q2占位符替換后還有{}殘留啟動報錯十有八九是 JSON 沒雙寫括號。檢查命令里所有 JSON 結(jié)構(gòu)把{/}改成{{/}}。Q3集群配方跑 solo 報「requires cluster mode」這是cluster_only: true的攔截提示屬于正常保護。先./run-recipe.sh --discover配置節(jié)點再不帶--solo運行。Q4模型需要訪問令牌gated modelexport HF_TOKENYOUR_TOKEN ./run-recipe.sh my-model -e HF_TOKEN$HF_TOKEN --setupQ5怎么驗證我的 YAML 寫對了最快的方式是--dry-run字段缺失或拼寫錯誤會立刻報錯模板替換后的完整命令會打印出來供你檢查。字段規(guī)則與容錯邏輯都在 run-recipe.py 中官方格式說明在 recipes/README.md。 八、參考資料配方系統(tǒng)官方文檔recipes/README.md配方解析源碼run-recipe.py集群網(wǎng)絡配置指南docs/NETWORKING.md集群啟動腳本launch-cluster.sh現(xiàn)成范例庫recipes/含 20 個覆蓋 FP8/NVFP4/AWQ/INT4 各種量化的真實配方掌握以上內(nèi)容從寫 YAML 到服務上線通常只需 10 分鐘。建議先從最簡單的 solo 配方如 recipes/gemma4-26b-a4b.yaml抄起再逐步疊加 mods 與集群配置你的自研模型就能穩(wěn)穩(wěn)跑在 DGX Spark 上了 【免費下載鏈接】spark-vllm-dockerDocker configuration for running VLLM on dual DGX Sparks項目地址: https://gitcode.com/gh_mirrors/sp/spark-vllm-docker創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考