Dynamo Router Starter

Objectif

Rendre le routage Dynamo facile en mettant en place un mode routeur de base, en activant le routage conscient du KV si approprié, et en prouvant que l'endpoint fonctionne. Gardez l'utilisateur focalisé sur les commandes exactes et les signaux de succès, pas sur les détails du routeur.

Prérequis

Python 3.10+ avec le package dynamo importable (python3 -m dynamo.frontend --help fonctionne).
Pour les exécutions Kubernetes : kubectl configuré avec accès au namespace cible et une recette Dynamo déployée.
Connectivité réseau au service frontend (port-forward ou accès direct).
Un modèle déjà chargé dans au moins un worker (/v1/models retourne au moins une entrée).

Entrées requises

Collectez ou déduisez :

chemin local Python/CLI ou chemin de recette Kubernetes
mode souhaité : round-robin, kv, least-loaded, device-aware-weighted, direct, ou random
port frontend ou service frontend Kubernetes
si les workers publient des événements KV ; sinon, utiliser le mode KV approximatif
nom du modèle pour les requêtes de test, si /v1/models ne peut pas le découvrir

Instructions

1. Établir une base de référence

Pour un lancement local avec des workers déjà enregistrés :

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

Pour Kubernetes, inspectez la recette sélectionnée deploy.yaml et localisez le service frontend. Si la recette n'est pas déjà déployée, utilisez dynamo-recipe-runner en premier.

2. Activer le routage KV

Pour le frontend local :

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

Pour Kubernetes, corrigez uniquement l'env du service frontend :

envs:
  - name: DYN_ROUTER_MODE
    value: kv

Si les workers backend ne publient pas les événements du cache KV, définissez le mode approximatif au lieu de laisser le routeur attendre les événements :

envs:
  - name: DYN_ROUTER_USE_KV_EVENTS
    value: "false"

3. Test de fumée

Après avoir effectué un port-forward du service frontend ou après avoir démarré le frontend local, exécutez :

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

Cela doit vérifier /v1/models et, quand un modèle est découvrable, une requête /v1/chat/completions.

4. Comparer les modes avec attention

Lors de la comparaison du routage round-robin vs KV :

utiliser le même modèle, les mêmes workers, le même ensemble de prompts, la même concurrence et les mêmes paramètres d'échantillonnage
envoyer des prompts à préfixe répété si vous démontrez la réutilisation du KV
labélisez le résultat comme une comparaison de fumée sauf si suffisamment d'échantillons de benchmark ont été collectés
ne revendiquez pas d'amélioration de débit à partir d'une seule requête de chat

Si l'endpoint n'est pas sain ou si des workers manquent, basculez vers dynamo-troubleshoot.

Scripts disponibles

Script	Objectif	Arguments
`scripts/check_router_health.py`	Test de fumée `/v1/models` et une complétion de chat contre un frontend Dynamo	`--base-url`, `--retries`, `--timeout`

Invoquez via le protocole run_script() d'agentskills.io :

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

Exemples

Frontend routé par KV local sur le port 8000, puis test de fumée :

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

Frontend déployé Kubernetes accessible 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

Équivalent via le protocole agent :

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

Contrat de sortie

Retournez :

mode sélectionné et pourquoi
commande locale ou patch env Kubernetes
service frontend ou URL
résultat du test de fumée
toute limitation, telle que le mode KV approximatif ou les événements KV de worker manquants
prochaine commande à exécuter pour une comparaison plus complète

Limitations

Le test de fumée est une complétion de chat ; ce n'est pas un benchmark. Utilisez dynamo-benchmark pour les nombres de débit/latence.
Le mode conscient du KV sans publication d'événements KV worker se dégrade en mode approximatif ; cette skill signale mais ne corrige pas la configuration sous-jacente du worker.
Les comparaisons de mode nécessitent des charges de travail appariées ; les revendications de latence entre modes nécessitent des exécutions de benchmark distinctes.

Dépannage

Symptôme	Cause probable	Étape suivante
`/v1/models` retourne une liste vide	Aucun worker enregistré avec le frontend	Vérifiez que les pods worker sont Ready ; confirmez qu'ils se connectent au même etcd/NATS
La requête de chat de fumée expire	Frontend actif, workers ne servant pas	Basculez vers `dynamo-troubleshoot` ; inspectez les logs du worker
Le mode KV se bloque	Les workers ne publient pas les événements du cache KV	Définissez `DYN_ROUTER_USE_KV_EVENTS=false` (mode approximatif)
Connexion refusée sur port-forward	Port-forward supprimé ou mauvais nom de service	Relancez le port-forward ; vérifiez que le nom du service frontend correspond à la recette

Benchmark

Voir BENCHMARK.md pour le rapport de performance NVCARPS-EVAL (auto-généré par le pipeline CI NVSkills). Pour actualiser, relancez /nvskills-ci sur une PR en amont touchant cette skill.

Références

Lisez references/router-modes.md pour la carte compact mode/env.
Utilisez scripts/check_router_health.py pour les tests de fumée d'endpoint.

dynamo-router-starter