
名称	dynamo-recipe-runner
描述	选择、验证、修补并部署现有的 NVIDIA Dynamo Kubernetes 配方。用于模型/后端/GPU/部署模式的配方启动；仅路由器模式的工作请使用 router-starter，故障排除请使用 troubleshoot。
开源协议	Apache-2.0 metadata:
作者	Dan Gil dagil@nvidia.com tags: - dynamo - kubernetes - recipes - bring-up permissions: - file_read - network - kubectl_exec

Dynamo 配方运行器

目的

以最少来回从用户意图到可工作的 Dynamo 配方端点。不要创建新的指南内容。基于现有的 recipes/ 树进行操作，修补最小的必要清单集，当用户具有集群访问权限时进行部署，并通过 OpenAI 兼容的烟雾请求证明成功。

先决条件

操作机器上安装 Python 3.10+。
kubectl 配置了可用的集群上下文。
集群为模型缓存 PVC 提供默认存储类。
Hugging Face 令牌以名为 hf-token-secret（或等效）的 Kubernetes secret 形式存储，位于目标命名空间。
对 ai-dynamo/dynamo 仓库中的 recipes/ 树有读取权限。

必需输入

修改清单前收集或推断：

配方目标：模型、框架（vllm、sglang、trtllm、tokenspeed）、部署模式和 GPU 类型/数量
Kubernetes 上下文和命名空间
Hugging Face secret 名称，通常是 hf-token-secret
模型缓存 PVC 的存储类
运行时镜像标签（如果配方使用占位符或过时的测试镜像）
是否运行命令还是仅生成精确命令

如果某个必需值缺失且无法从所选配方推断，只询问该值。

说明

1. 预检

首先执行只读检查：

git status --short
python3 scripts/recipe_tool.py list --format table
kubectl config current-context
kubectl get storageclass
kubectl get nodes -o wide
kubectl get namespace "${NAMESPACE}"
kubectl get secret hf-token-secret -n "${NAMESPACE}"

如果 kubectl 不可用或集群不可达，继续选择并验证配方，然后返回精确命令而不是假装部署已运行。

2. 选择配方

使用 recipes/README.md 中的配方矩阵和扫描器：

python3 scripts/recipe_tool.py list \
  --query qwen --framework vllm --mode disagg --format table

优先选择完全匹配的现有配方。除非用户明确要求编写新配方，否则不要发明新清单。

3. 查看并验证

阅读所选配方的 README、模型缓存清单、deploy.yaml 和 perf.yaml（如果存在）。然后运行：

python3 scripts/recipe_tool.py validate \
  recipes/<model>/<framework>/<mode>

应用清单前解决报告的阻塞项：存储类、模型缓存 PVC、镜像标签、HF 令牌 secret、GPU 数量、前端服务名称、路由器模式。

4. 修补最小值

仅修补本次运行所需的配方特定值。不要重新格式化整个 YAML 文件。常见修补：

storageClassName
镜像仓库/标签
模型路径或模型缓存挂载路径
GPU 资源请求/限制
前端 DYN_ROUTER_MODE
仅当清单硬编码命名空间时设置命名空间

绝不将 Hugging Face 令牌写入文件或日志。使用 Kubernetes secrets。

5. 部署

如果所选配方 README 与默认顺序不同，则遵循之。默认顺序是：

kubectl apply -f recipes/<model>/model-cache/ -n "${NAMESPACE}"
kubectl wait --for=condition=Complete job/model-download -n "${NAMESPACE}" --timeout=6000s
kubectl apply -f recipes/<model>/<framework>/<mode>/deploy.yaml -n "${NAMESPACE}"
kubectl get dynamographdeployment -n "${NAMESPACE}"
kubectl get pods -n "${NAMESPACE}" -o wide

在测试前等待前端和工作节点就绪。

6. 烟雾测试

端口转发前端服务，然后验证 /v1/models 和一个聊天补全：

kubectl port-forward svc/<deployment-name>-frontend 8000:8000 -n "${NAMESPACE}"
curl http://127.0.0.1:8000/v1/models

如果还安装了 dynamo-router-starter，请优先使用 scripts/check_router_health.py 进行完整的 OpenAI 兼容烟雾测试。如果失败，切换到 dynamo-troubleshoot。

可用脚本

脚本	用途	参数
`scripts/recipe_tool.py list`	枚举可用配方，可选过滤	`--query`、`--framework`、`--mode`、`--format`
`scripts/recipe_tool.py validate`	应用前验证配方目录	位置参数配方路径

通过 agentskills.io run_script() 协议调用：

run_script("scripts/recipe_tool.py", args=["list", "--framework", "sglang", "--format", "table"])
run_script("scripts/recipe_tool.py", args=["validate", "recipes/nemotron-3-super-fp8/sglang/agg"])

示例

列出适合单节点 8xB200 的 sglang 配方：

python3 scripts/recipe_tool.py list --framework sglang --format table

在应用前验证特定配方并解决阻塞项：

python3 scripts/recipe_tool.py validate recipes/nemotron-3-super-fp8/sglang/agg

通过代理协议的等效命令：

run_script("scripts/recipe_tool.py", args=["validate", "recipes/nemotron-3-super-fp8/sglang/agg"])

输出约定

所选配方路径及其选择原因
补丁的确切值
已运行或要运行的命令
端点和烟雾测试结果
未解决的阻塞项（若有）
当部署未健康时的下一步故障排除步骤

限制

仅操作现有的 recipes/ 树。不编写新清单。
集群变更应用的步骤需要 kubectl 对目标命名空间的权限。
烟雾测试深度有意保持最小；完整的路由器/端点覆盖请使用 dynamo-router-starter。
多节点 disagg 传输正确性不在范围内；部署后请使用 dynamo-interconnect-check。

故障排除

症状	可能原因	下一步
`kubectl` 集群不可达	上下文未设置或 VPN 断开	返回精确命令而不是运行它们；集群可达后恢复
`validate` 报告缺少存储类	集群没有默认 StorageClass	在应用前修补 model-cache 清单上的 `storageClassName`
模型缓存任务卡在 `Pending`	PVC 未绑定或缺少 HF secret	检查 PVC 事件；创建或重命名 HF secret 以匹配配方
工作 Pod `ImagePullBackOff`	镜像标签过时或缺少拉取 secret	修补镜像标签；验证命名空间中的镜像拉取 secret
部署后 `/v1/models` 4xx/5xx	前端未就绪或服务端口错误	等待 Pod Ready；重新运行端口转发；若仍然存在则切换到 `dynamo-troubleshoot`

基准

参见 BENCHMARK.md 中的 NVCARPS-EVAL 性能报告（由 NVSkills CI 流水线自动生成）。要刷新，请在影响此技能的上游 PR 上重新运行 /nvskills-ci。

参考

阅读 references/k8s-recipe-workflow.md 获取命令模板和就绪检查。
使用 scripts/recipe_tool.py 进行配方发现和轻量验证。