VSS Deploy

Scripts disponibles

Routage des profils

Associez la demande de l'utilisateur à un profil, puis chargez la référence de ce profil pour le dimensionnement, les services, les recettes env et le débogage.

Routage du matériel edge (DGX Spark, AGX/IGX Thor) : voir references/edge.md. DGX Spark utilise le Nano 9B standalone local LLM sur le port 30081 ; AGX/IGX Thor utilise le fallback vLLM Edge 4B standalone.

Chaque référence de profil gère sa propre table de dimensionnement. Ne choisissez pas une forme de déploiement dans ce fichier — ouvrez la référence du profil et vérifiez le nombre minimum de GPU pour le matériel de l'hôte par rapport à la matrice (mode × plateforme) qui s'y trouve.

Instructions

Le flux de déploiement est toujours : copier .env dans generated.env, appliquer les surcharges, faire un dry-run de compose vers resolved.yml, vérifier, normaliser, déployer, puis attendre que le système soit prêt.

# 1. cp dev-profile-<profile>/.env dev-profile-<profile>/generated.env  (copie propre)
# 2. Appliquez les surcharges env à generated.env  (le source .env reste inchangé)
# 3. docker compose --env-file generated.env config > resolved.yml      (dry-run)
# 4. Vérifiez resolved.yml
# 5. docker compose --env-file generated.env -f resolved.yml up -d

.env contient les valeurs par défaut vérifiées en lecture seule ; generated.env est la copie de travail pour chaque déploiement. L'étape 1c couvre cela en détail.

Prérequis

1. Chemin du repo — détectez automatiquement video-search-and-summarization/ avant de demander à l'utilisateur. Utilisez le chemin détecté comme $REPO pour toutes les commandes suivantes.
2. Portails de credentials — voir references/credentials.md : NGC_CLI_API_KEY pour les pulls NIM locaux/local_shared, NVIDIA_API_KEY pour les endpoints NIM distants, et HF_TOKEN pour les recettes edge utilisant des modèles HF gérés.
3. Prérequis système (driver GPU, Docker, NVIDIA Container Toolkit, sysctls kernel, et — si ufw est actif — l'autorisation firewall Docker-bridge→host pour que les NIMs bridge puissent récupérer des clips depuis VST en mode host) — vérifications complètes dans references/prerequisites.md. La matrice hardware/driver canonique se trouve sur la page prérequis VSS.

L'extrait de détection automatique (racine git, puis une sonde de chemin commun contrôlée par deploy/docker/compose.yml + dev-profile.sh + skills/vss-deploy-profile) se trouve dans references/prerequisites.md. Exportez le $REPO résolu ; si la détection échoue, demandez le chemin du checkout à l'utilisateur.

Vérification pré-vol

Exécutez avant chaque déploiement. La liste de contrôle système complète et les étapes de correction se trouvent dans references/prerequisites.md. Pour DGX Spark / IGX Thor / AGX Thor, exécutez aussi la vérification du nettoyage de cache dans references/edge.md.

Détectez d'abord le mode sudo. Plusieurs corrections pré-vol et l'installateur du nettoyage de cache edge appellent sudo. Si l'hôte nécessite un mot de passe sudo, ces étapes seront silencieusement ignorées sous sudo -n et laisseront le déploiement dans un état semi-préparé.

if sudo -n true 2>/dev/null; then
  echo "sudo sans mot de passe — pré-vol installera automatiquement les éléments manquants"
else
  echo "sudo nécessite un mot de passe — pré-vol n'installera PAS automatiquement ; passez les commandes à l'utilisateur"
fi

Quand sudo nécessite un mot de passe, la skill ne doit pas exécuter elle-même les installateurs privilégiés. Présentez le bloc de commande copiable depuis references/prerequisites.md à l'utilisateur avec un handoff « exécutez ceci une fois et confirmez », puis reprenez après la réponse de l'utilisateur.

Test de fumée minimal (doit réussir) :

nvidia-smi --query-gpu=index,name --format=csv,noheader
docker info 2>/dev/null | grep -qi runtimes \
  && docker run --rm --gpus all ubuntu:22.04 nvidia-smi >/dev/null 2>&1 \
  && echo "nvidia runtime OK"

Si le test de fumée échoue, ne continuez pas ; ouvrez references/prerequisites.md pour l'arborescence de correction.

Sélection du modèle

• $LLM_REMOTE_URL / $VLM_REMOTE_URL si l'utilisateur demande un accès distant
• $NGC_CLI_API_KEY (NIMs locaux) ou $NVIDIA_API_KEY (distant)

Portail d'intention d'endpoint. N'inférez pas le placement distant à partir de variables env isolées (LLM_ENDPOINT_URL, VLM_ENDPOINT_URL, LLM_BASE_URL, VLM_BASE_URL peuvent être des restes). Utilisez LLM/VLM distant seulement quand (1) l'utilisateur a demandé / fourni un endpoint distant, (2) le dimensionnement local ne peut pas accueillir les modèles sélectionnés et l'utilisateur accepte, ou (3) une recette edge nécessite un service local standalone que VSS traite comme remote (p.ex. Nano 9B DGX Spark sur localhost:30081). Si une variable d'endpoint est définie mais l'utilisateur n'a pas demandé distant, signalez-le à l'étape 1 et posez la question — ne déployez jamais silencieusement distant parce qu'une variable existe.

Si aucune combinaison sur cet hôte ne satisfait les exigences de dimensionnement du profil, arrêtez et signalez le bloquant — ne choisissez pas silencieusement une autre forme.

Le mode partagé edge est spécifique à la plateforme. Les recettes complètes se trouvent dans references/edge.md.

Flux de déploiement

Suivez toujours cette séquence. Ne sautez jamais le dry-run.

Étape 0 — Détruisez tout déploiement existant + videz les volumes de données

Si un déploiement existe déjà, détruisez-le ET videz les anciens volumes de données avant de redéployer.

La procédure complète se trouve dans references/teardown.md.

Étape 0a — Portail de credentials (exécutez avant toute mutation env)

Validez chaque credential et endpoint distant sélectionné que le profil choisi nécessite avant que l'étape 1c copie .env vers generated.env. Un 401 ici est un échec de 30 secondes ; le même 401 pendant un démarrage à froid NIM est un échec de 10–20 min. Exécutez le flux de découverte et test dans references/credentials.md, incluant scripts/probe_remote_models.sh pour tout endpoint LLM/VLM que vous prévoyez d'écrire dans generated.env. Associez le résultat au mode choisi : les credentials/endpoints requis manquants ou invalides sont des bloquants, les credentials optionnels ne le sont pas.

Étape 1 — Rassemblez le contexte

Avant de construire les surcharges env, confirmez :

Avant docker compose up, vérifiez que EXTERNAL_IP, HAPROXY_PORT, VSS_PUBLIC_HOST, et VSS_PUBLIC_PORT sont remplis avec des valeurs accessibles par le navigateur. Sinon, la pile peut sembler saine tandis que les liens UI/API/VST retournent 404 ou boucle via Cloudflare Access.

Étape 1b — Préparez le répertoire de données

La mise en page (chemins d'assets, propriété, points de montage, sous-répertoires spécifiques au profil) est documentée dans references/data-directory.md. Lisez ce fichier avant de déployer pour la première fois sur un hôte ou en changeant de profil.

Étape 1c — Initialisez generated.env

La copie de travail par déploiement de la skill. Commencez toujours par une copie fraîche du source .env, ne mutez jamais le source.

PROFILE=base
ENV_SRC=$REPO/deploy/docker/developer-profiles/dev-profile-$PROFILE/.env
ENV_GEN=$REPO/deploy/docker/developer-profiles/dev-profile-$PROFILE/generated.env

cp "$ENV_SRC" "$ENV_GEN"

Toutes les écritures suivantes (Brev EXTERNAL_IP, le dict env_overrides de l'étape 2) vont dans $ENV_GEN. $ENV_SRC est en lecture seule à partir d'ici.

Étape 1d — Brev uniquement : détectez d'abord, puis définissez EXTERNAL_IP au domaine secure-link

Détectez Brev avant toute chose — une instance provisionée par Brev définit BREV_ENV_ID dans /etc/environment ; rien d'autre ne le fait :

grep -qE '^BREV_ENV_ID=' /etc/environment && echo "sur Brev" || echo "pas sur Brev"

• pas sur Brev → sautez le reste de cette étape et ne lisez pas references/brev.md ; conservez le EXTERNAL_IP basé sur ${HOST_IP} normal.
• sur Brev → appliquez les surcharges Brev secure-link de references/brev.md § Flux de setup à generated.env (PAS .env). Celles-ci définissent EXTERNAL_IP / VSS_PUBLIC_HOST au domaine secure-link et VSS_PUBLIC_HTTP_PROTOCOL=https / VSS_PUBLIC_WS_PROTOCOL=wss / VSS_PUBLIC_PORT=443 — définir seul EXTERNAL_IP laisse les liens UI/API/WS http://…:7777 que le navigateur bloque comme contenu mixte.

Étape 2 — Construisez env_overrides

Produisez un dict env_overrides à partir de la demande de l'utilisateur et du contexte rassemblé : choisissez explicitement LLM/VLM distant/local, définissez les credentials, pointez vers les endpoints, définissez les drapeaux spécifiques à la plateforme. Ne laissez pas les variables env shell existantes choisir silencieusement le placement ; écrivez le LLM_MODE / VLM_MODE sélectionné et les champs d'endpoint/modèle correspondants dans generated.env. La mise en correspondance complète (chaque clé de surcharge, quand elle s'applique, les valeurs par défaut, les différences spécifiques au profil) se trouve dans references/env-overrides.md. Chaque référence de profil a des exemples travaillés pour les scénarios courants de ce profil.

Étape 3 — Appliquez les surcharges + dry-run

Fichier env de travail : <repo>/deploy/docker/developer-profiles/dev-profile-<profile>/generated.env (créé à l'étape 1c).

Rappel (voir étape 1c) : appliquez toutes les surcharges (dict de l'étape 2 + Brev EXTERNAL_IP) à generated.env ; --env-file le pointe toujours, et les vérificateurs post-déploiement le lisent pour les valeurs effectivement déployées.

# (L'étape 1c a déjà exécuté : cp $ENV_SRC $ENV_GEN)

# Appliquez le dict env_overrides de l'étape 2 à generated.env
# (lisez les lignes, mettez à jour les clés correspondantes, ajoutez de nouvelles clés, écrivez)
# Exemple :
#   sed -i "s|^LLM_MODE=.*|LLM_MODE=remote|" "$ENV_GEN"
#   sed -i "s|^LLM_BASE_URL=.*|LLM_BASE_URL=http://localhost:30081|" "$ENV_GEN"

# Résolvez compose
cd $REPO/deploy/docker
docker compose --env-file $ENV_GEN config > resolved.yml

Le YAML résolu est sauvegardé dans <repo>/deploy/docker/resolved.yml.

Étape 3b — Vérifiez que resolved.yml n'a pas de tokens ${...} non développés

Les tokens ${VAR} non développés dans resolved.yml signifient que compose n'a pas vu ces valeurs env. La procédure de diagnostic et les culprits communs se trouvent dans references/troubleshooting.md.

Étape 3c — Vérifiez l'accès aux artefacts NGC sélectionnés

Faites cela après que resolved.yml existe et avant docker compose up. La sonde token NGC à l'étape 0a prouve seulement que la clé s'authentifie ; elle ne prouve pas que l'org/équipe de la clé peut accéder aux repos d'image ou de modèle sélectionnés.

Construisez la liste d'artefacts à partir du déploiement réellement sélectionné :

• resolved.yml : chaque image: sous nvcr.io/... que Compose téléchargera.
• $ENV_GEN : chemins de modèle/ressource soutenus par NGC tels que RTVI_VLM_MODEL_PATH=ngc:nim/nvidia/cosmos-reason2-8b:hf-1208. Ignorez none, git:..., les chemins locaux, et les URLs d'endpoint distant.
• Étapes de staging du profil : tout téléchargement de modèle/ressource NGC documenté dans la référence du profil, tel que le staging du modèle de perception pour alertes/recherche.

Sondez chaque artefact sélectionné avec la clé NGC normalisée avant de continuer :

• Images de conteneur : docker manifest inspect <nvcr.io/...> après docker login nvcr.io — pour les repos nvcr.io gérés, un 401/403 ici est un signal définitif d'absence de droit d'accès (la lecture de manifest nécessite le même droit d'accès org/équipe que le pull de couche) ; ou la commande ngc registry image info ... correspondante quand l'artefact se mappe proprement à un chemin d'image NGC.
• Chemins de modèle/ressource NGC (p.ex. le checkpoint Cosmos RT-VLM que télécharge à l'exécution) : exécutez le ngc registry model info ... ou ngc registry resource info ... correspondant pour le repo/tag exact que le profil chargera ou téléchargera ; ceux-ci utilisent l'auth à portée de NGC. N'ESSAYEZ PAS de sonder un modèle avec docker manifest inspect (retourne « no such manifest » parce qu'un modèle n'est pas une image OCI) ou un appel REST brut Authorization: Bearer <key> (retourne 403 parce que ce n'est pas le flux d'auth de NGC) ; les deux sont des faux négatifs attendus, pas des échecs de droit d'accès. Si la CLI ngc est indisponible, traitez la sonde d'image de conteneur ci-dessus comme le signal de droit d'accès, puisque NGC accorde l'accès org/équipe entre images et modèles ensemble.
• Modèles TAO/perception stagés du profil : exécutez le ngc registry model info ... / resource info ... correspondant pour chaque repo/tag avant que le bloc de staging télécharge les fichiers.

Si une sonde retourne 401, 403, permission, not being a member of the organization that owns the repo, org/repo manquant, ou une erreur d'accès similaire, arrêtez et invitez l'utilisateur à fournir une clé NGC d'une org/équipe avec droit d'accès à ces artefacts. Ne lancez pas Compose et découvrez l'échec pendant le démarrage à froid NIM.

Étape 3d — Supprimez les depends_on optionnels en suspend de resolved.yml

DOIT s'exécuter après l'étape 3, avant l'étape 5. Sauter cela abandonne le déploiement :

Normalisez - supprimez les dépendances optionnelles pour les services filtrés de resolved.yml

# Depuis la racine du repo
uv run skills/vss-deploy-profile/scripts/normalize_resolved_yml.py "$REPO/deploy/docker/resolved.yml"

Si uv n'est pas sur l'hôte, installez-le une fois avec curl -LsSf https://astral.sh/uv/install.sh | sh (aucune racine nécessaire). Revalidez avant up -d :

docker compose -f "$REPO/deploy/docker/resolved.yml" config --quiet && echo "resolved.yml OK"

Si la validation échoue encore après l'exécution du normaliseur, capturez l'erreur et inspecter — c'est un autre bug (une dépendance qui n'est pas optionnelle, ou une autre violation de schéma), pas le cas dangling-depends_on.

Étape 4 — Vérifiez

Montrez à l'utilisateur un résumé de ce qui sera déployé :

• Nom du profil et matériel
• Modèles LLM/VLM et mode (local/distant/local_shared)
• Services qui vont démarrer
• Attribution des appareils GPU
• Endpoints clés (port UI, port agent)

Demandez : « Ça vous paraît bon — déployer maintenant ? » et attendez la confirmation avant l'étape 5.

Exception — mode autonome. Si la demande de l'utilisateur vous demande déjà de fonctionner en autonome (p.ex. « déployer X de façon autonome », « exécuter sans confirmation », « non-interactif »), sautez l'invite de confirmation et allez directement à l'étape 5. Ce chemin existe pour que les évaluations automatisées / les invocations CI ne restent pas bloquées en attente d'une réponse humaine qu'elles ne recevront jamais. Dans tous les autres cas, un humain doit approuver.

Étape 5 — Déployez

cd $REPO/deploy/docker
docker compose --env-file $ENV_GEN -f resolved.yml up -d

--env-file est obligatoire. Sans le même generated.env utilisé à l'étape 3, COMPOSE_PROFILES peut être indéfini et up -d peut terminer avec 0 services sélectionnés.

Évitez un large --force-recreate sur les tentatives ordinaires — il détruit les conteneurs NIM chauds (encore 3–5 min torch.compile + capture CUDA-graph chacun). Corrigez la cause racine (généralement perms ou une typo env) et relancez simplement up -d ; utilisez --force-recreate --no-deps <service...> ciblé seulement quand une référence de profil le documente comme le chemin de récupération.

docker compose up -d crée seulement des conteneurs ; il n'attend pas que les services internes finissent de se réchauffer. Ne déclarez jamais le déploiement réussi tant que les portails de readiness ne passent pas.

Étape 5b — Attendez que la pile soit réellement saine

Portail 0 — le nombre de conteneurs doit être > 0. Refusez de progresser après up -d tant que le nombre de conteneurs lancés (docker compose -f resolved.yml ps -q | wc -l) n'est pas non-zéro et ≥ au nombre attendu (config --services | wc -l) ; un nombre zéro/court signifie presque toujours un --env-file manquant à l'étape 5. Le portail exact plus la procédure de readiness complète se trouvent dans references/readiness.md.

Les déploiements à froid peuvent prendre 10–20 min, et chaque référence de profil liste les endpoints requis. Ne déclarez jamais le déploiement terminé après up -d ; seulement après que chaque endpoint documenté réussisse.

Destruction

Pour détruire un déploiement — reclamation d'hôte complète ou redéploiement/changement de profil préservant le cache — suivez references/teardown.md. Détruisez toujours par le projet mdx avec -v --remove-orphans ; un simple docker compose down laisse les volumes et réseaux derrière.

Débogage d'un déploiement

Utilisez ce flux de travail quand l'utilisateur demande « déboguer le déploiement », « vérifier que ça fonctionne », « pourquoi l'agent ne répond pas », ou similaire. L'objectif est de confirmer le chemin complet de l'ingestion vidéo vers la réponse de l'agent, pas seulement que les conteneurs sont « Up ».

Chaque référence de profil a une section Debugging listant les commandes exactes et la table de modes de défaillance pour ce profil.

Vérifications rapides (tous les profils)

# 1. Tous les conteneurs attendus Up
docker ps --format 'table {{.Names}}\t{{.Status}}'

# 2. API Agent + UI répondent
curl -sf http://localhost:8000/health >/dev/null && echo "agent OK"
curl -sf http://localhost:3000/ >/dev/null && echo "ui OK"

Les sondes NIM LLM/VLM — incluant la manipulation *_MODE=remote qui saute localhost:3008x (où une connection refused est attendue) et teste le *_BASE_URL/v1/models sélectionné via scripts/probe_remote_models.sh — sont dans references/troubleshooting.md.

Limitations

• Cette skill déploie seulement les profils VSS basés sur compose ; le déploiement de microservices standalone appartient à la skill vss-deploy-* correspondante.
• Le dimensionnement du matériel, le placement de modèle, et la readiness spécifique au profil sont gérés par les références de profil ; ne les inférez pas de la mémoire.
• Les corrections d'hôte privilégiées nécessitent l'approbation de l'utilisateur quand sudo sans mot de passe est indisponible.

Dépannage

La référence rapide d'erreurs communes, la table symptôme → cause → correction complète, le diagnostic ${...} non développé, et les sondes d'endpoint NIM sont consolidés dans references/troubleshooting.md — commencez là pour tout échec de déploiement, runtime, ou sonde, puis continuez dans la section Debugging du référence de profil correspondant.