
名称	dynamo-router-starter
描述	启动或修改Dynamo路由器模式，并运行路由器端点冒烟检查。用于轮询、KV感知、最少负载或设备感知路由设置；使用recipe-runner进行配方部署，使用troubleshoot进行故障诊断。
开源协议	Apache-2.0 metadata:
作者	Dan Gil dagil@nvidia.com tags: - dynamo - router - smoke-test - bring-up

Dynamo路由器启动器

目的

让Dynamo路由配置变得更简单：先运行一个基线路由器模式，在适当时启用KV感知路由，并验证端点可用。让用户专注于确切的命令和成功信号，而不是路由器内部细节。

先决条件

安装了Python 3.10+且dynamo包可导入（python3 -m dynamo.frontend --help可用）。
对于Kubernetes运行：配置了能访问目标命名空间的kubectl，并且已部署Dynamo recipe。
与前端服务的网络可达性（端口转发或直连）。
至少一个worker中已经加载了模型（/v1/models至少返回一个条目）。

必需输入

收集或推断：

本地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，并在可发现模型时，发出一次/v1/chat/completions请求。

4. 谨慎比较模式

在比较轮询与KV路由时：

使用相同的模型、工作节点、提示词集合、并发数和采样设置
如果要演示KV复用，发送重复前缀的提示词
除非收集了足够的基准样本，否则将结果标记为冒烟比较
不要从单个聊天请求中断言吞吐量提升

如果端点不健康或缺少工作节点，请切换到dynamo-troubleshoot。

可用脚本

脚本	用途	参数
`scripts/check_router_health.py`	对Dynamo前端进行`/v1/models`和一个聊天补全的冒烟测试	`--base-url`, `--retries`, `--timeout`

通过agentskills.io的run_script()协议调用：

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

示例

本地KV路由前端监听8000端口，然后冒烟测试：

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

通过agent协议等价调用：

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

输出契约

所选择的模式及原因
本地命令或Kubernetes环境变量补丁
前端服务或URL
冒烟测试结果
任何限制，如近似KV模式或缺失工作节点KV事件
为进行更全面比较而需运行的下一条命令

限制

冒烟测试是一次聊天完成，不是基准测试。使用dynamo-benchmark获取吞吐量/延迟数据。
没有工作节点KV事件发布时，KV感知模式会退化为近似模式；本技能会标记但不会修复底层工作节点配置。
模式比较需要匹配的工作负载；跨模式延迟断言需要单独的基准运行。

故障排查

症状	可能原因	后续步骤
`/v1/models`返回空列表	没有工作节点注册到前端	验证工作节点Pod的Ready状态；确认它们连接到同一etcd/NATS
冒烟聊天请求超时	前端已启动，工作节点未服务	切换到`dynamo-troubleshoot`；检查工作节点日志
KV模式挂起	工作节点不发布KV缓存事件	设置`DYN_ROUTER_USE_KV_EVENTS=false`（近似模式）
端口转发连接被拒	端口转发中断或服务名称错误	重新运行端口转发；验证前端服务名称与配方匹配

基准

参见BENCHMARK.md了解NVCARPS-EVAL性能报告（由NVSkills CI流水线自动生成）。如需刷新，请在与该技能相关的上游PR上重新运行/nvskills-ci。

参考

阅读references/router-modes.md了解简洁的模式/环境变量映射。
使用scripts/check_router_health.py进行端点冒烟测试。