dynamo-recipe-runner

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 token secret、GPU 数量、前端服务名称和路由器模式。

4. 修改最少的配置值

仅修改本次运行所需的配方专属配置值。不要重新格式化整个 YAML 文件。常见修改项：

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

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

5. 部署

如果所选配方的 README 与默认顺序不同，请遵循该 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

通过 Agent 协议执行的等效操作：

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

输出约定

返回：

• 所选配方路径及选择原因
• 修改的准确配置值
• 已运行的命令或待运行的命令
• 端点和冒烟测试结果
• 尚未解决的阻塞项（如有）
• 部署未能正常就绪时的下一步故障排查操作

限制

• 仅对现有的 recipes/ 目录树进行操作，不会编写新的清单。
• 修改集群的应用步骤需要拥有目标命名空间的 kubectl 权限。
• 冒烟测试的覆盖范围有意保持最低限度；如需完整覆盖路由器和端点，请使用 dynamo-router-starter。
• 多节点分离式传输的正确性不在本项目范围内；部署后请使用 dynamo-interconnect-check。

故障排除

症状	可能原因	后续步骤
kubectl 无法连接集群	未设置上下文或 VPN 已断开	返回准确的命令，而不是运行它们；待集群恢复可访问后继续
validate 报告缺少存储类	集群没有默认的 StorageClass	应用前，在模型缓存清单中修改 storageClassName
模型缓存任务卡在 Pending 状态	PVC 未绑定或缺少 HF 密钥	检查 PVC 事件；创建 HF 密钥，或重命名现有密钥以匹配配方
工作器 Pod 出现 ImagePullBackOff	镜像标签已过时或缺少拉取密钥	修改镜像标签；确认命名空间中存在镜像拉取密钥
部署后 /v1/models 返回 4xx/5xx	前端尚未就绪或服务端口错误	等待 Pod 进入 Ready 状态；重新运行端口转发；如果问题仍然存在，请切换到 dynamo-troubleshoot

基准测试

NVCARPS-EVAL 性能报告（由 NVSkills CI 流水线自动生成）请参阅 BENCHMARK.md。如需更新，请在涉及此技能的上游 PR 上重新运行 /nvskills-ci。

参考资料

• 有关命令模板和就绪状态检查，请阅读 references/k8s-recipe-workflow.md。
• 使用 scripts/recipe_tool.py 发现配方并进行轻量验证。