dynamo-recipe-runner

Dynamo Recipe Runner

目的

ユーザーの意図から、動作する Dynamo レシピのエンドポイントまで、やり取りを最小限に抑えて進めます。新しいガイドコンテンツは作成しません。既存の recipes/ ツリーを操作し、必要最小限のマニフェストを修正します。ユーザーがクラスターにアクセスできる場合はデプロイし、OpenAI 互換のスモークテストリクエストで成功を確認します。

前提条件

• オペレーターのマシンに Python 3.10 以降がインストールされていること。
• kubectl が動作するクラスターコンテキストで設定されていること。
• クラスターにモデルキャッシュ PVC 用のデフォルトストレージクラスがあること。
• Hugging Face トークンが、対象の名前空間にある hf-token-secret という名前の Kubernetes シークレット（または同等のもの）に保存されていること。
• ai-dynamo/dynamo リポジトリの recipes/ ツリーへの読み取りアクセス権があること。

必要な入力

マニフェストを変更する前に、以下の値を収集するか推定してください。

• レシピの対象：モデル、フレームワーク（vllm、sglang、trtllm、tokenspeed）、デプロイモード、GPU の種類と数
• Kubernetes コンテキストと名前空間
• Hugging Face シークレット名（通常は 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 トークンシークレット、GPU 数、フロントエンドのサービス名、ルーターモードです。

4. 最小限の値を修正する

今回の実行に必要な、レシピ固有の値だけを修正してください。YAML ファイル全体を再フォーマットしないでください。よくある修正対象は以下のとおりです。

• storageClassName
• イメージリポジトリ／タグ
• モデルパスまたはモデルキャッシュのマウントパス
• GPU リソースの要求／上限
• フロントエンドの DYN_ROUTER_MODE
• マニフェストに名前空間がハードコードされている場合に限り、名前空間

Hugging Face トークンをファイルやログに書き込まないでください。Kubernetes シークレットを使用してください。

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 とチャット補完を 1 回実行して確認します。

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

dynamo-router-starter もインストールされている場合は、OpenAI 互換のフルスモークテストに scripts/check_router_health.py を優先して使用してください。失敗した場合は 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 を使用してください。
• マルチノードの分離トランスポートの正確性は対象外です。デプロイ後に dynamo-interconnect-check を使用してください。

トラブルシューティング

症状	考えられる原因	次の手順
kubectl でクラスターに接続できない	コンテキストが設定されていない、または VPN が停止している	実行せずにコマンドをそのまま提示し、クラスターに接続できるようになったら再開します
validate でストレージクラスが見つからないと報告される	クラスターにデフォルトの StorageClass がない	適用する前にモデルキャッシュのマニフェストの storageClassName を変更します
モデルキャッシュのジョブが Pending のままになる	PVC がバインドされていない、または HF シークレットがない	PVC のイベントを確認し、レシピに合うように HF シークレットを作成または名前変更します
ワーカーポッドが ImagePullBackOff になる	イメージタグが古い、またはプルシークレットがない	イメージタグを変更し、名前空間内のイメージプルシークレットを確認します
デプロイ後に /v1/models が 4xx/5xx を返す	フロントエンドの準備ができていない、またはサービスのポートが誤っている	ポッドが Ready になるまで待ち、ポートフォワードを再実行します。解決しない場合は dynamo-troubleshoot に切り替えます

ベンチマーク

NVCARPS-EVAL のパフォーマンスレポートについては、BENCHMARK.md を参照してください（NVSkills CI パイプラインによって自動生成されます）。更新するには、このスキルに関連する上流 PR で /nvskills-ci を再実行してください。

参考資料

• コマンドのテンプレートと準備状況の確認については、references/k8s-recipe-workflow.md を参照してください。
• レシピの検出と軽量な検証には、scripts/recipe_tool.py を使用してください。