dynamo-router-starter

Dynamo Router Starter

目的

ベースラインのルーターモードを起動し、適切な場合は KV 対応ルーティングを有効にし、エンドポイントが動作することを確認して、Dynamo のルーティングを簡単に使えるようにします。ルーターの内部構造ではなく、正確なコマンドと成功を示す情報にユーザーの注意を集中させます。

前提条件

• dynamo パッケージをインポートできる Python 3.10 以降（python3 -m dynamo.frontend --help が動作すること）。
• Kubernetes で実行する場合：対象の名前空間へのアクセス権を持つように設定された kubectl と、デプロイ済みの Dynamo レシピ。
• フロントエンドサービスへのネットワーク接続（ポートフォワードまたは直接接続）。
• 少なくとも 1 つのワーカーにモデルが読み込まれていること（/v1/models が 1 件以上のエントリを返すこと）。

必要な入力

以下を収集または推定します。

• ローカルの Python／CLI または Kubernetes レシピのパス
• 希望するモード：round-robin、kv、least-loaded、device-aware-weighted、direct、random
• フロントエンドのポートまたは Kubernetes フロントエンドサービス
• ワーカーが KV イベントを公開するかどうか。公開しない場合は、近似 KV モードを使用します
• /v1/models でモデルを検出できない場合は、スモークリクエストに使用するモデル名

手順

1. ベースラインを確立する

登録済みのワーカーを使ってローカルで起動する場合：

python3 -m dynamo.frontend --router-mode round-robin --http-port 8000

Kubernetes の場合は、選択したレシピの deploy.yaml を確認し、フロントエンドサービスを特定します。レシピがまだデプロイされていない場合は、まず dynamo-recipe-runner を使用します。

2. KV ルーティングを有効にする

ローカルのフロントエンドの場合：

python3 -m dynamo.frontend --router-mode kv --http-port 8000

Kubernetes の場合は、フロントエンドサービスの環境変数だけをパッチします。

envs:
  - name: DYN_ROUTER_MODE
    value: kv

バックエンドワーカーが KV キャッシュイベントを公開していない場合は、ルーターがイベントを待ち続けないように、近似モードを設定します。

envs:
  - name: DYN_ROUTER_USE_KV_EVENTS
    value: "false"

3. スモークテスト

フロントエンドサービスをポートフォワードするか、ローカルのフロントエンドを起動した後、次を実行します。

python3 scripts/check_router_health.py \
  --base-url http://127.0.0.1:8000

これにより、/v1/models と、モデルを検出できる場合は 1 件の /v1/chat/completions リクエストを検証します。

4. モードを慎重に比較する

ラウンドロビンと KV ルーティングを比較する場合：

• 同じモデル、ワーカー、プロンプトセット、同時実行数、サンプリング設定を使用します
• KV の再利用を実証する場合は、同じプレフィックスを繰り返すプロンプトを送信します
• 十分なベンチマークサンプルを収集していない場合は、結果をスモーク比較として明示します
• チャットリクエスト 1 件だけを根拠に、スループットが向上したと主張しないでください

エンドポイントが正常でない場合、またはワーカーが不足している場合は、dynamo-troubleshoot に切り替えます。

利用可能なスクリプト

スクリプト	目的	引数
scripts/check_router_health.py	Dynamo フロントエンドに対して /v1/models と 1 件のチャット補完をスモークテストする	--base-url、--retries、--timeout

agentskills.io の run_script() プロトコルを使って実行します。

run_script("scripts/check_router_health.py", args=["--base-url", "http://127.0.0.1:8000"])

例

ポート 8000 でローカルの KV ルーティング対応フロントエンドを起動し、スモークテストを実行します。

python3 -m dynamo.frontend --router-mode kv --http-port 8000 &
python3 scripts/check_router_health.py --base-url http://127.0.0.1:8000

ポートフォワード経由でアクセス可能な、Kubernetes にデプロイ済みのフロントエンド：

kubectl port-forward svc/qwen-vllm-disagg-frontend 8000:8000 -n dynamo-demo &
python3 scripts/check_router_health.py --base-url http://127.0.0.1:8000 --retries 3

エージェントプロトコルを使った同等の方法：

run_script("scripts/check_router_health.py", args=["--base-url", "http://127.0.0.1:8000", "--retries", "3"])

出力要件

以下を返します。

• 選択したモードとその理由
• ローカルコマンドまたは Kubernetes の環境変数パッチ
• フロントエンドサービスまたは URL
• スモークテストの結果
• 近似 KV モードやワーカーの KV イベントがないなどの制限事項
• より詳細な比較のために次に実行するコマンド

制限事項

• スモークテストはチャット補完 1 件のみで、ベンチマークではありません。スループット／レイテンシの数値には dynamo-benchmark を使用してください。
• ワーカーが KV イベントを公開していない状態で KV 対応モードを使うと、近似モードに移行します。このスキルはその状態を通知しますが、根本原因であるワーカー設定は修正しません。
• モードを比較するには、ワークロードを一致させる必要があります。モード間のレイテンシに関する主張には、別途ベンチマークを実行する必要があります。

トラブルシューティング

症状	考えられる原因	次の手順
/v1/models が空のリストを返す	フロントエンドにワーカーが登録されていない	ワーカーポッドが Ready であることを確認し、同じ etcd/NATS に接続していることを確認します
スモークチャットリクエストがタイムアウトする	フロントエンドは稼働しているが、ワーカーがリクエストを処理していない	dynamo-troubleshoot に切り替え、ワーカーログを確認します
KV モードがハングする	ワーカーが KV キャッシュイベントを公開していない	DYN_ROUTER_USE_KV_EVENTS=false を設定します（近似モード）
ポートフォワードで接続が拒否される	ポートフォワードが切断された、またはサービス名が間違っている	ポートフォワードを再実行し、フロントエンドサービス名がレシピと一致することを確認します

ベンチマーク

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

参考資料

• コンパクトなモード／環境変数の一覧については、references/router-modes.md を参照してください。
• エンドポイントのスモークテストには、scripts/check_router_health.py を使用してください。