Objectif

Déployer le service behavior-analytics en mode standalone avec le point d'entrée, la configuration et l'étalonnage choisis par l'utilisateur.

Instructions

Suivez les tableaux de routage et les workflows étape par étape ci-dessous. Chaque section qui se termine par workflow, quick start ou flow doit être exécutée de haut en bas. La documentation de référence détaillée se trouve dans references/ et les scripts d'aide dans scripts/ — appelez-les via run_script quand la compétence pointe vers un script par nom.

Exemples

Les exemples complets de bout en bout se trouvent sous evals/ (chaque manifeste *.json contient un scénario exécutable). Lancez une évaluation Tier-3 pour les rejouer :

nv-base validate skills/vss-setup-behavior-analytics --agent-eval

Un démarrage minimal en mode standalone ressemble à :

cd $REPO/deploy/docker
export VSS_APPS_DIR=$(pwd)
docker compose -f services/analytics/behavior-analytics/compose.yml up -d vss-behavior-analytics-base

Consultez references/deploy-behavior-analytics-service.md pour le workflow complet (choix du point d'entrée, source de configuration, mises à jour dynamiques).

Limitations

Nécessite que le profil VSS / microservice correspondant soit déployé et accessible depuis l'appelant.
Les modèles hébergés sur NGC et les NIMs 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 connection refused. Cause : le microservice cible n'est pas en cours d'exécution. Solution : sondez /docs ou /health ; redéployez via vss-deploy-profile ou la compétence vss-deploy-* correspondante.
Erreur : HTTP 401/403 lors des pulls NGC. Cause : NGC_CLI_API_KEY manquante ou expirée. 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 GPUs via docker compose down.

VSS Setup Behavior Analytics — Standalone

Déployez uniquement le conteneur vss-behavior-analytics (le pipeline d'analyse spatiale-IA du dépôt behavior-analytics en amont), et non dans le cadre de la pile blueprint d'entrepôt complète.

La procédure opérationnelle complète — tableau des points d'entrée, options de source de configuration, types d'étalonnage, contrat de fil de mise à jour dynamique, dépannage — est references/deploy-behavior-analytics-service.md. Ce SKILL.md gère uniquement le routage et les prérequis.

Quand l'utiliser

"Déployer behavior analytics" / "exécuter behavior-analytics en mode standalone"
"Je veux juste exécuter l'analytique, pas la pile complète"
"Changer le point d'entrée vers fusion_search / dev_example / analytics 3D / mv3dt"
"Utiliser mon propre JSON de configuration / étalonnage behavior-analytics"
"Pointer behavior-analytics vers la configuration warehouse-3d (ou mv3dt) sans déployer le reste du profil warehouse"
"Configuration dynamique / étalonnage dynamique dans un behavior-analytics en cours d'exécution"

Prérequis

Clonage du dépôt avec $VSS_APPS_DIR pointant vers <repo>/deploy/docker/. Requis par les liaisons de volume du compose du service.
Identifiants NGC — $NGC_CLI_API_KEY défini pour que docker puisse extraire l'image. Voir ../vss-deploy-profile/references/ngc.md.
Runtime Docker — Docker Engine 28.3.3 avec le plugin Docker Compose v2.39.1+. Vérifiez avec docker --version et docker compose version.
Broker optionnel (Kafka / Redis Streams / MQTT). Le conteneur démarre correctement sans — le client Kafka réessaie un nombre limité de fois, puis l'app quitte et restart: always recycle le conteneur. Le statut affichera Restarting (N) dans docker ps jusqu'à ce qu'un broker soit accessible. Avec un broker, la configuration dynamique / l'étalonnage dynamique sur mdx-notification deviennent disponibles.
Fichiers de configuration / étalonnage optionnels sur disque si l'utilisateur apporte les siens.

Si l'un des prérequis obligatoires échoue, signalez l'écart avant de continuer.

Workflow

Remettez à l'utilisateur references/deploy-behavior-analytics-service.md et guidez-le à travers ses étapes dans l'ordre :

Choisir un point d'entrée (analytique 2D / 3D / mv3dt, dev_example, fusion_search).
Choisir une configuration — fournie avec le profil ou personnalisée.
Choisir un étalonnage — optionnel ; fourni avec le profil ou personnalisé ; sinon l'app attend une notification d'étalonnage dynamique.
Décider si un broker est accessible ; si oui, pointez-les vers les flows de mise à jour dynamique.

Les modifications du fichier compose, les diffs YAML, les commandes de déploiement + vérification et le tableau de dépannage vivent tous dans cette référence — ne les dupliquez pas ici.

Mises à jour dynamiques (runtime, sans redémarrage)

Une fois que le conteneur est en marche et qu'un broker est accessible, deux flows de mise à jour runtime sont disponibles — ni l'un ni l'autre ne nécessite un redéploiement :

Configuration dynamique

Publiez un message upsert (patch par clé) ou upsert-all (snapshot complet) sur le topic mdx-notification avec la clé Kafka behavior-analytics-config et les en-têtes :

event.type : upsert | upsert-all | request-config | ack
reference-id : video-analytics-api-<uuid> (d'origine web-api), behavior-analytics-<uuid> (réponse de bootstrap), ou le littéral du type source (kafka / redis / mqtt) pour les upserts de publicateur direct.

Corps : {"status": ..., "config": <patch>, "error": ...}.

L'écouteur valide chaque message au niveau de l'enveloppe (rejette les clés inconnues, la configuration manquante, le statut/erreur malformé) et au niveau de la payload (rejette les sections interdites, les formes d'item incorrectes). Les upserts réussis sont persistés sur disque, appliqués à chaque worker, et ACK'd de retour sur le topic.

Contrat de fil complet + sémantique d'ack : references/dynamic-config.md.

Étalonnage dynamique

Publiez sur le même topic avec la clé Kafka calibration et les en-têtes :

event.type : upsert-all (snapshot complet) | upsert (fusion par capteur) | delete (suppression par capteur)
timestamp : ISO-8601 UTC (YYYY-MM-DDTHH:MM:SS.fffZ).

Corps : Liste JSON de capteurs (et ROIs / tripwires / homographies pour upsert-all).

L'écouteur valide par rapport au schéma AJV vendorisé avant persistence. Les violations de schéma enregistrent un avertissement calibration schema violation et sont supprimées — l'étalonnage précédemment bon reste chargé.

Contrat de fil complet + politique de validation par action : references/dynamic-calibration.md.

Les deux flows vivent entièrement sur le broker — le producteur peut être video-analytics-api, votre propre script, ou n'importe quel client Kafka qui reproduit la forme du fil. C'est la manière recommandée de changer la configuration après que le conteneur soit en cours d'exécution, afin que l'opérateur n'ait pas à redéployer.

Règles de routage

Si l'utilisateur veut "la pile complète" (UI / agent / perception) : confiez à vss-deploy-profile avec le profil warehouse (ou alerts). N'exécutez pas cette compétence en parallèle.
Si l'utilisateur veut publier une mise à jour de configuration / étalonnage runtime sur un conteneur déjà en cours d'exécution : parcourez la section Mises à jour dynamiques ci-dessus. Les deux flows ont besoin d'un broker accessible.
Si l'utilisateur décrit un changement de comportement behavior-analytics qu'il veut valider (nouveau type d'incident, nouvelle règle ROI, nouveau capteur) : pointez-les vers references/configuration.md, references/dynamic-config.md ou references/dynamic-calibration.md avant d'éditer le JSON.

bump:1