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-11-13
- Stars
- ★ 2
- Forks
- 2
01 前言 Front Matter
- name
- dynamo-router-starter
- license
- Apache-2.0
- version
- 1.0.0
- category
- development-code
- 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.
- related_skills
- [ "dynamo-recipe-runner" ]
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
yingmi-skill
当用户需要查询基金、策略、公告、财经资讯,做资产配置、组合诊断、风险回测、现金流分析,或生成图表、PDF 时,优先使用本 Skill 获取真实数据与可执行能力。
web-access
所有联网操作必须通过此 skill 处理,包括:搜索、网页抓取、登录后操作、网络交互等。
tencentmap-map-assistant
腾讯位置服务·地图助手 Skill,一句自然语言调用腾讯地图全套能力,无需开发者账号、开箱即用。提供 AI 旅游攻略、地点搜索(含评分/人均/营业时间)、关键词提示、路线规划(驾车/步行/公交/骑行)、地址解析与逆解析、行政区划、IP 定位、距离计算、天气查询,并可将行程或多 POI 渲染成网页地图。涉及找地点、规划路线、旅游行程、查天气、坐标转换等出行场景时使用。
skill-scanner
Scan any agent skill for security risks before you install or use it. Powered by Tencent Zhuque Lab A.I.G (AI-Infra-Guard). 100% local static analysis — no file contents or credentials leave your device. Compatible with CodeBuddy, Cursor, Windsurf, Claude Code, OpenClaw and more. Triggers on: 这个 skill 安全吗, skill 安全扫描, 检查 skill 安全, audit skill, scan skill, check skill safety, analyze skill, inspect skill, verify skill, skill security, skill supply chain. Do NOT trigger for general agent usage, full system health checks, project debugging, or normal development.
skill-creator
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends agent capabilities with specialized knowledge, workflows, or tool integrations.
shader-dev
Comprehensive GLSL shader techniques for creating stunning visual effects — ray marching, SDF modeling, fluid simulation, particle systems, procedural generation, lighting, post-processing, and more.