mcpField
D
dynamo-router-starter

dynamo-router-starter

github.com/nvidia云与 DevOps3.8k1.9k 次安装今天更新
代码仓库

关于 dynamo-router-starter

dynamo-router-starter 指导在本地或 Kubernetes 上启动 Dynamo 前端路由、选择路由模式并执行健康冒烟测试，面向部署和验证 Dynamo 路由的用户。

主要功能

  1. 01配置六种路由模式
  2. 02启用 KV 感知路由
  3. 03运行前端健康冒烟测试
  4. 04检查模型列表与聊天请求
  5. 05提示近似 KV 模式限制

适用场景

  1. 01启动本地 Dynamo 前端
  2. 02为 Kubernetes 前端切换路由模式
  3. 03验证模型与聊天接口可用
  4. 04初步比较轮询与 KV 路由

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/nvidia/skills --skill dynamo-router-starter

安装后在 Claude Code 中输入/dynamo-router-starter确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

BENCHMARK.md
skill-card.md
skill.oms.sig
evals/
evals.json
references/
router-modes.md
scripts/
check_router_health.py

详细介绍

Dynamo Router 入门指南

目的

轻松启用 Dynamo 路由：先运行基线路由模式，在适当情况下启用 KV 感知路由，并验证端点是否正常工作。让用户专注于准确的命令和成功标志，而不是路由器内部机制。

前置条件

  • Python 3.10+，且可导入 dynamo 包（python3 -m dynamo.frontend --help 可正常运行）。
  • 对于 Kubernetes 运行：已配置可访问目标命名空间的 kubectl，且已部署 Dynamo 配方。
  • 可通过网络访问前端服务（端口转发或直连）。
  • 至少一个工作进程已加载模型（/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"])

示例

在端口 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

通过 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 进行端点冒烟测试。

评论

支持 Markdown