dynamo-router-starter
Start or patch Dynamo router modes and run router endpoint smoke checks. Use for round-robin, KV-aware, least-loaded, or device-aware routing setup; use recipe-runner for recipe deployment and troubleshoot for failure diagnosis.
- License 许可
- Apache-2.0
- 最近更新
- 2026-07-13
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- dynamo-router-starter
- license
- Apache-2.0
- metadata
- { "tags": [ "dynamo", "router", "smoke-test", "bring-up" ], "author": "Dan Gil <dagil@nvidia.com>" }
- description
- Start or patch Dynamo router modes and run router endpoint smoke checks. Use for round-robin, KV-aware, least-loaded, or device-aware routing setup; use recipe-runner for recipe deployment and troubleshoot for failure diagnosis.
02 资源文件 6
- 参考文档BENCHMARK.md2.6 KB
- 参考文档evals/evals.json3.0 KB
- 参考文档references/router-modes.md2.1 KB
- 脚本scripts/check_router_health.py4.7 KB
- 参考文档skill-card.md2.4 KB
- 其他skill.oms.sig5.0 KB
03 SKILL.md 正文
Dynamo Router Starter
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: CC-BY-4.0 -->
Purpose
Make Dynamo routing feel easy by getting a baseline router mode running, enabling KV-aware routing when appropriate, and proving the endpoint works. Keep the user focused on exact commands and success signals, not router internals.
Prerequisites
- Python 3.10+ with the
dynamopackage importable (python3 -m dynamo.frontend --helpworks). - For Kubernetes runs:
kubectlconfigured with access to the target namespace and a deployed Dynamo recipe. - Network reachability to the frontend service (port-forward or direct).
- A model already loaded into at least one worker (
/v1/modelsreturns at least one entry).
Required Inputs
Collect or infer:
- local Python/CLI or Kubernetes recipe path
- desired mode:
round-robin,kv,least-loaded,device-aware-weighted,direct, orrandom - frontend port or Kubernetes frontend service
- whether workers publish KV events; if not, use approximate KV mode
- model name for smoke requests, if
/v1/modelscannot discover it
Instructions
1. Establish A Baseline
For local bring-up with already registered workers:
python3 -m dynamo.frontend --router-mode round-robin --http-port 8000
For Kubernetes, inspect the selected recipe deploy.yaml and locate the
frontend service. If the recipe is not already deployed, use
dynamo-recipe-runner first.
2. Enable KV Routing
For local frontend:
python3 -m dynamo.frontend --router-mode kv --http-port 8000
For Kubernetes, patch only the frontend service env:
envs:
- name: DYN_ROUTER_MODE
value: kv
If backend workers are not publishing KV cache events, set approximate mode instead of leaving the router waiting for events:
envs:
- name: DYN_ROUTER_USE_KV_EVENTS
value: "false"
3. Smoke Test
After port-forwarding the frontend service or starting local frontend, run:
python3 scripts/check_router_health.py \
--base-url http://127.0.0.1:8000
This must verify /v1/models and, when a model is discoverable, one
/v1/chat/completions request.
4. Compare Modes Carefully
When comparing round-robin vs KV routing:
- use the same model, workers, prompt set, concurrency, and sampling settings
- send repeated-prefix prompts if demonstrating KV reuse
- label the result as a smoke comparison unless enough benchmark samples were collected
- do not claim throughput improvement from a single chat request
If the endpoint is unhealthy or workers are missing, switch to
dynamo-troubleshoot.
Available Scripts
| Script | Purpose | Arguments |
|---|---|---|
scripts/check_router_health.py |
Smoke-test /v1/models and one chat completion against a Dynamo frontend |
--base-url, --retries, --timeout |
Invoke via the agentskills.io run_script() protocol:
run_script("scripts/check_router_health.py", args=["--base-url", "http://127.0.0.1:8000"])
Examples
Local KV-routed frontend on port 8000, then smoke-test it:
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-deployed frontend reachable via port-forward:
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
Equivalent through the agent protocol:
run_script("scripts/check_router_health.py", args=["--base-url", "http://127.0.0.1:8000", "--retries", "3"])
Output Contract
Return:
- mode selected and why
- local command or Kubernetes env patch
- frontend service or URL
- smoke-test result
- any limitation, such as approximate KV mode or missing worker KV events
- next command to run for a fuller comparison
Limitations
- Smoke test is one chat completion; it is not a benchmark. Use
dynamo-benchmarkfor throughput/latency numbers. - KV-aware mode without worker KV-event publication degrades to approximate mode; this skill flags but does not fix the underlying worker config.
- Mode comparisons require matched workloads; cross-mode latency claims need separate benchmark runs.
Troubleshooting
| Symptom | Likely cause | Next step |
|---|---|---|
/v1/models returns empty list |
No worker registered with the frontend | Verify worker pods are Ready; confirm they connect to the same etcd/NATS |
| Smoke chat request times out | Frontend up, workers not serving | Switch to dynamo-troubleshoot; inspect worker logs |
| KV mode hangs | Workers do not publish KV cache events | Set DYN_ROUTER_USE_KV_EVENTS=false (approximate mode) |
| Connection refused on port-forward | Port-forward dropped or wrong service name | Re-run port-forward; verify the frontend service name matches the recipe |
Benchmark
See BENCHMARK.md for the NVCARPS-EVAL performance report (auto-generated by the NVSkills CI pipeline). To refresh, re-run /nvskills-ci on an upstream PR touching this skill.
References
- Read
references/router-modes.mdfor the compact mode/env map. - Use
scripts/check_router_health.pyfor endpoint smoke tests.
04 同仓库更多 Skills
zustand-store-creator
Create zustand store creator operations. Auto-activating skill for Frontend Development. Triggers on: zustand store creator, zustand store creator Part of the Frontend Development skill category. Use when working with zustand store creator functionality. Trigger with phrases like "zustand store creator", "zustand creator", "zustand".
zero-trust-config-helper
Configure with zero trust config helper operations. Auto-activating skill for Security Advanced. Triggers on: zero trust config helper, zero trust config helper Part of the Security Advanced skill category. Use when configuring systems or services. Trigger with phrases like "zero trust config helper", "zero helper", "zero".
zapier-integration-helper
Assist with zapier integration helper operations. Auto-activating skill for Business Automation. Triggers on: zapier integration helper, zapier integration helper Part of the Business Automation skill category. Use when working with APIs or building integrations. Trigger with phrases like "zapier integration helper", "zapier helper", "zapier".
yaml-config-validator
Validate yaml config validator operations. Auto-activating skill for DevOps Basics. Triggers on: yaml config validator, yaml config validator Part of the DevOps Basics skill category. Use when configuring systems or services. Trigger with phrases like "yaml config validator", "yaml validator", "yaml".
xvary-stock-research
Thesis-driven equity analysis from public SEC EDGAR and market data; /analyze, /score, /compare workflows with bundled Python tools (Claude Code, Cursor, Codex).
xss-vulnerability-scanner
Scan xss vulnerability scanner operations. Auto-activating skill for Security Fundamentals. Triggers on: xss vulnerability scanner, xss vulnerability scanner Part of the Security Fundamentals skill category. Use when working with xss vulnerability scanner functionality. Trigger with phrases like "xss vulnerability scanner", "xss scanner", "xss".