Objet

Déployer, déboguer et exploiter le microservice de détection / suivi 2D RTVI-CV et piloter son API REST.

Prérequis

• Déploiement VSS actif accessible sur $HOST_IP (voir vss-deploy-profile et references/).
• Identifiants NGC dans $NGC_CLI_API_KEY et $NVIDIA_API_KEY pour les pulls d'images.
• curl, jq, et Docker disponibles sur le client.

Instructions

Suivez les tableaux de routage et les workflows étape par étape ci-dessous. Chaque section terminée par workflow, quick start, ou flow est destinée à être exécutée de haut en bas. Les matériaux de référence détaillés se trouvent dans references/ et les scripts d'assistance dans scripts/ — appelez-les via run_script quand la skill pointe vers un script par son nom.

Exemples

Les exemples complets de bout en bout sont conservés sous evals/ (chaque manifeste *.json contient un scénario exécutable) et en ligne dans les blocs curl par workflow ci-dessous. Lancez une évaluation Tier-3 avec nv-base validate <this-skill-dir> --agent-eval pour les rejouer.

Limitations

• Nécessite que le profil VSS / microservice correspondant soit déployé et accessible depuis le client.
• Les modèles et NIMs hébergés sur NGC peuvent être soumis à des limites de débit, des exigences de mémoire GPU et des restrictions de licence.
• Les limites de concurrence, de mémoire GPU et de stockage dépendent du matériel hôte et du fichier compose du profil.

Dépannage

• Erreur : L'appel REST retourne connexion refusée. Cause : microservice cible non exécuté. Solution : sondez /docs ou /health ; redéployez via vss-deploy-profile ou la skill vss-deploy-* correspondante.
• Erreur : HTTP 401/403 depuis les pulls NGC. Cause : NGC_CLI_API_KEY manquant ou expiré. Solution : docker login nvcr.io et réexportez la clé avant de réessayer.
• Erreur : OOM du conteneur ou le modèle ne se charge pas. Cause : mémoire GPU insuffisante pour le profil sélectionné. Solution : basculez vers une variante plus petite ou libérez les GPU via docker compose down.

RTVI-CV — Détection & Suivi (Skill Unifiée)

Skill unifiée pour le microservice Real Time Video Intelligence CV (RTVI-CV). Deux surfaces d'action dans une seule skill :

• Déployer / exploiter / déboguer / démanteler le conteneur RTVI-CV localement → voir references/deploy-vss-detection-tracking-2d.md
• Appeler l'API REST RTVI-CV (streams, santé, métriques, embeddings) sur une instance en cours d'exécution → voir references/usage-vss-detection-tracking-2d.md

Service : rtvi-cv (metropolis_perception_app) Image : nvcr.io/<org>/<repo>:<tag> — fournie par l'utilisateur au moment du déploiement Port REST : 9000 (/api/v1 — /live, /ready, /startup, /metrics, /stream/add, /stream/remove, embeddings) Matériel : x86/aarch64 dGPU (T4, A100, L40, H100, B200, RTX), SBSA (Spark, Grace-Hopper), Jetson (Thor, Orin, Xavier)

Routage des actions — choisir une fois par invocation

Règle de sélection : associez la formulation de l'utilisateur au tableau ci-dessus et chargez immédiatement le fichier de référence correspondant. Ne mélangez pas les flows — DEPLOY suppose aucun conteneur en cours d'exécution ; API USAGE suppose que le conteneur s'exécute déjà sur http://<host>:9000.

Si l'intention est réellement ambiguë (par exemple, l'utilisateur dit simplement « je veux utiliser rtvi-cv »), posez une AskQuestion : déployer une nouvelle instance ou appeler une instance déjà en cours d'exécution ?

Où vivent les choses

vss-deploy-detection-tracking-2d/
├── SKILL.md          # ce fichier (routage + contrats)
├── assets/           # fichiers de données (deploy-defaults.yml — source unique de vérité pour tags / refs / chemins / GPU)
├── evals/            # manifestes eval Tier-3 (deploy-evals.json, usage-evals.json)
├── scripts/          # 23 assistants bash + python (voir `scripts/` pour l'inventaire complet)
└── references/       # runbooks de workflow (déploiement / api-usage / teardown / dépannage / …)

Pour l'inventaire complet par fichier et ce que couvre chaque référence, voir references/workflow-reference.md.

Tous les scripts sont invoqués depuis la racine de la skill via $SKILL_DIR/scripts/<name> — les chemins internes à la doc de déploiement sont conservés tels quels et se résolvent correctement quand l'agent s'exécute depuis la racine de la skill.

Scripts disponibles

Les assistants vivent dans scripts/ et sont invoqués depuis la racine de la skill par nom — appelez chacun via run_script("scripts/<name>") afin que l'agent enregistre une invocation d'outil appropriée.

Pour l'inventaire complet des assistants (cache, vérifications GPU, setup), parcourez scripts/ ; l'option --help de chaque script décrit ses arguments.

Comment utiliser cette skill

1. Lisez d'abord ce fichier. Il ne fait que router — il ne contient pas de workflows.
2. Associez l'intention de l'utilisateur au tableau de routage ci-dessus.
3. Chargez exactement un doc de référence (DEPLOY ou API USAGE). Ne préchargez pas les deux — chaque référence est volumineuse et contient son propre contrat complet.
4. Suivez exactement le doc de référence chargé. Les docs de référence sont les contrats exactement conservés des skills prédécesseurs vss-deploy-detection-tracking-2d (déploiement/teardown/débogage) et rtvicv-api (API REST) — chaque invariant d'ordre d'étape, règle de batching bash, règle de rendu de boîte, et contrat AskQuestion est conservé.
5. Pour DEPLOY, le doc de référence impose son propre contrat de démarrage : accusé de réception d'une ligne → appel d'outil de planification (tableau TodoWrite de 5 todos, OU 5 appels TaskCreate successifs sur Claude Code plus récent) → question de l'étape 1. Ne commentez pas, ne prévolez pas, et n'imprimez jamais « chargement TodoWrite/TaskCreate » ou toute prose de résolution d'outil différé — l'outil de planification est chargé silencieusement.

Contrat de sortie — flux DEPLOY

Lors de l'exécution du flux DEPLOY / TEARDOWN / DEBUG, l'agent DOIT honorer les quatre éléments ci-dessous lors de chaque déploiement réussi. Ce sont le seul canal de rétroaction de l'utilisateur entre les étapes ; ignorer l'un d'eux est une régression comportementale.

1. Rendez la sortie de chaque étape dans une boîte à largeur fixe — étape 1 Deploy targets, étape 2 Pipeline configuration, étape 3 Container, étape 4 Apply configuration, étape 5 Plan + Results. Pas seulement le résumé final. La boîte est le reçu d'étape de l'utilisateur. La géométrie est fixe (voir § « Format de boîte universel » ci-dessous). Les règles contenu par étape (quelles lignes vont dans chaque boîte) vivent dans references/deploy-vss-detection-tracking-2d.md sous « Step N box content rule ».
2. Après la boîte Résultats de l'étape 5, émettez l'AskUserQuestion de l'étape 6 depuis references/next-steps.md § « 11.c » — ne la remplacez jamais par une liste à puces Next steps libre. Le menu est la poignée de sortie du déploiement : il permet à l'utilisateur d'exécuter des métriques, de gérer les streams, de suivre les logs ou de démonter en un clic au lieu de devoir mémoriser les URL curl.
3. Après que l'utilisateur choisisse un bucket d'étape 6, émettez l'AskUserQuestion de suivi depuis references/next-steps.md § « 11.d » — ne remplacez jamais la prose + les exemples curl prêts à copier + une question libre « voulez-vous que j'exécute X ? ». Chaque bucket a son propre menu d'actions concrètes ; l'utilisateur choisit l'action, puis la skill émet la boîte API et exécute le curl. Suivis par bucket :

• Manage streams → Ajouter / Supprimer / Lister. Remove construit ses options dynamiquement depuis /stream/get-stream-info — une option par stream actif libellée <camera_id> · <camera_url> plus « Remove ALL » quand ACTIVE > 1 (spécification complète : § « remove_streams sub-flow »).
• Stop the deployment → Arrêter l'app / Arrêter le conteneur / Teardown complet.
• Check metrics & FPS → pas de suivi ; exécutez collect_metrics.sh directement après impression de la boîte API /api/v1/metrics.
• Check liveness / readiness → pas de suivi ; sondez les trois endpoints de santé après impression de leurs boîtes API.

4. Rendez le CONTENU COMPLET par étape, pas une ligne d'aperçu — rendre la boîte est nécessaire mais insuffisant. Chaque étape a une spécification de composition de lignes dans references/deploy-vss-detection-tracking-2d.md sous « Step N box content rule ». L'étape 4 (Apply configuration) est où l'agent s'effondre le plus souvent — sa liste de clés canonique par cas d'usage vit dans references/apply-config.md § « Per-use-case complete edit list », et l'agent DOIT émettre une ligne ✔ [section] key=value — annotation par clé dans ce tableau pour le cas d'usage actif + paramètres. Une section avec 5 clés → 5 lignes ; une section avec 6 clés → 6 lignes. Jamais une ligne d'aperçu par section.

Interdit (ce sont les raccourcis vers lesquels l'agent revient sous pression, et ils cassent l'UX de l'utilisateur) :

• ❌ Narration de chargement d'outil interne. N'imprimez jamais « I need to load TodoWrite (a deferred tool the skill calls for the task widget) », « Loading TaskCreate… », « Calling ToolSearch for the planning tool… », ou tout autre texte sur la résolution / chargement / récupération d'outils différés. L'agent charge les outils silencieusement. L'utilisateur ne voit que la ligne de résumé ✔ <pinned-values> suivie du widget — jamais aucun échafaudage autour de la résolution d'outil.
• ❌ Effondrer les 5 étapes de déploiement dans le champ description d'un seul TaskCreate. Quand TaskCreate est l'outil de planification disponible, émettez 5 appels TaskCreate séparés dos à dos (un par étape). Voir references/task-list.md § « Initial TaskCreate calls » pour le modèle verbatim. Même règle pour TodoWrite — un appel avec tous les 5 todos dans le tableau todos:[…] ; jamais un todo dont le content est une liste multi-ligne.
• ❌ Choisir silencieusement le mode de stream dynamic. Le défaut de la skill est stream_mode=static — l'agent grave les URLs file:// découvertes automatiquement dans le bloc [source-list] du config principal DS avant le démarrage de l'app. Passez à dynamic uniquement quand l'utilisateur le demande explicitement (« ajouter des streams plus tard via REST », « utiliser le mode de stream dynamique ») OU quand il choisit dynamic dans la AskQuestion de l'étape 2. Choisir dynamic pour une requête générique « déployer rtvi-cv avec N streams » casse la rubrique de déploiement et les attentes /metrics de l'utilisateur. Voir references/pipeline-config.md § « Defaults — the skill is static-mode by default » pour la rationale complète.
• ❌ Une seule ligne ✔ App ready in Ns, N streams, fps total Y à la place de la boîte Résultats de l'étape 5.
• ❌ Caractères de dessin de boîte ASCII (+, -, =, *) au lieu de caractères légers (┌ ─ ┐ │ └ ┘).
• ❌ Ignorer l'étape 6 en supposant « l'utilisateur sait ce qu'il faut faire ensuite ».
• ❌ Après l'étape 6, verser un mur de prose markdown + plusieurs blocs curl + une fermeture « voulez-vous que j'exécute l'un de ceux-ci ? » — c'est la forme vers laquelle l'agent retombe et cela contourne à la fois le menu 11.d et la boîte par appel API. L'utilisateur choisit dans un menu ; la skill affiche la boîte API résolue ; la skill l'exécute. Pas de Q libre.
• ❌ Effondrements d'aperçu de l'étape 4 — ceux-ci sont explicitement interdits par la règle de contenu de l'étape 4 du doc de déploiement :
  • ✔ Batch size 3 (tile grid: 1×3) → requis : 5 lignes séparées ([streammux] batch-size=3, [primary-gie] batch-size=3, [source-list] max-batch-size=3, [tiled-display] rows=1, [tiled-display] columns=3).
  • ✔ Output sink eglsink → requis : une ligne par clé sink (4 clés pour eglsink, par ex. [sink0] enable=1, type=2, sync=0, qos=0 — lire apply-config.md pour la liste exacte).
  • ✔ Sources static (3 streams, http-port=9000) → requis : six lignes [source-list] annotées.
  • ✔ Tile grid 1 row × 3 cols (ligne unique) → requis : deux lignes, [tiled-display] rows=1 et [tiled-display] columns=3.

Format de boîte universel

Le contrat de géométrie pour chaque boîte de sortie d'étape (étape 1 à étape 5 Résultats). La même forme dans chaque boîte ; seuls le titre et les lignes de corps changent par étape.

• Largeur : 128 caractères coin à coin — ┌ à la colonne 1, ┐ à la colonne 128. Les terminaux plus larges laissent la boîte alignée à gauche ; ne l'étirez pas. La zone de contenu intérieur est 124 caractères (avec une marge d'un espace de chaque côté intérieur des bordures │).
• Caractères légers uniquement : ┌ ─ ┐ │ └ ┘. Pas de substituts ASCII +, -, =, *.
• Bordure supérieure — titre CENTRÉ : ┌ + N₁ tirets + ␣ + titre + ␣
  • N₂ tirets + ┐, où N₁ + N₂ + len(titre) + 2 = 126. Distribuez le rembourrage : N₁ = floor((126 − len(titre) − 2) / 2), N₂ = 126 − len(titre) − 2 − N₁. N₁ et N₂ diffèrent d'au plus 1.
• Corps : une │ <contenu rembourré au contenu intérieur 124> │ par fait. Chaque ligne de fait utilise la forme ✔ <clé-rembourée-à-13> <valeur> (deux espaces dedans, glyphe, clé rembourée à droite à 13, deux espaces, valeur).
• Lignes vierges entre groupes : rendez │ <124 espaces> │ entre les groupes logiques (par ex. Identity / Model / Videos à l'étape 1) afin que l'utilisateur puisse scanner la boîte d'un coup d'œil.
• Bordure inférieure : └ + 126 tirets + ┘ — bordure unie, pas de titre.

Titres d'étape standard (utilisés en haut de la boîte de chaque étape) :

┌─────────────────────────────────────────────────────── Deploy targets ───────────────────────────────────────────────────────┐
┌─────────────────────────────────────────────────── Pipeline configuration ───────────────────────────────────────────────────┐
┌───────────────────────────────────────────────────────── Container ──────────────────────────────────────────────────────────┐
┌──────────────────────────────────────────────────── Apply configuration ─────────────────────────────────────────────────────┐
┌──────────────────────────────────────────────── Perception Application — Plan ───────────────────────────────────────────────┐
┌────────────────────────────────────────────── Perception Application — Results ──────────────────────────────────────────────┐

Les règles de contenu par étape (quelles lignes vont dans quelle boîte, masquage de lignes conscient du mode, la disposition sectionnée d'apply-config, le motif PLAN-then-RESULT de l'étape 5, l'exigence de synthèse docker run de l'étape 3) vivent dans references/deploy-vss-detection-tracking-2d.md sous « Step N box content rule » — lisez ceux-ci lors du rendu de l'étape correspondante.

Déclencheurs rapides (mnémonique)

bump:1