Objet

Déployer le service REST video-analytics-api de façon autonome avec la configuration de l'utilisateur, la liaison data-log et la connectivité Elasticsearch / Kafka.

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 se trouvent dans scripts/ — appelez-les via run_script quand la skill pointe vers un script par nom.

Exemples

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

nv-base validate skills/vss-setup-video-analytics-api --agent-eval

Un démarrage minimal autonome ressemble à :

cd $REPO/deploy/docker
export VSS_APPS_DIR=$(pwd)
export VSS_DATA_DIR=${VSS_DATA_DIR:-/tmp/vss-data}
mkdir -p "$VSS_DATA_DIR/data_log/vss_video_analytics_api"
docker compose -f services/analytics/video-analytics-api/compose.yml up -d vss-video-analytics-api
curl -sf http://localhost:8081/livez

Suivez references/deploy-video-analytics-api-service.md pour le workflow complet (source de config, liaison data-log, dépendances d'infrastructure, endpoints REST).

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 limitations 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 une connexion refusée. 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 skill vss-deploy-* correspondante.
Erreur : HTTP 401/403 depuis les tirages NGC. Cause : NGC_CLI_API_KEY manquante/expirée. Solution : docker login nvcr.io et réexportez la clé avant de réessayer.
Erreur : conteneur OOM 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.

VSS Setup Video Analytics API — Autonome

Déployez uniquement le conteneur vss-video-analytics-api (l'API REST Node.js du repo upstream video-analytics-api), et non comme partie de la pile blueprint d'entrepôt complète.

La procédure opérationnelle complète — options de source de config, comportement du volume data-log, dépendances d'infrastructure, endpoints API REST, déploiement + vérification, dépannage — se trouve dans references/deploy-video-analytics-api-service.md. Ce SKILL.md gère uniquement le routage et les prérequis.

Quand l'utiliser

« Déployer l'api d'analyse vidéo » / « exécuter video-analytics-api de façon autonome »
« Je veux juste exécuter l'API REST, pas la pile complète »
« Utiliser ma propre config video-analytics-api »
« Diriger l'API vers un autre Elasticsearch / Kafka »
« Démarrer l'API sans Kafka » / « exécuter l'API sans courtier »
« Vérifier quels endpoints REST sont disponibles »

Prérequis

Checkout du repo 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 tirer l'image. Voir ../vss-deploy-profile/references/ngc.md.

Note de gestion sécurisée pour NGC_CLI_API_KEY : cette clé est une credential de longue durée qui tire toutes les images privées NVIDIA disponibles pour votre organisation NGC. Ne commitez jamais la clé, ne la collez jamais dans le chat, ne la stockez jamais dans /tmp. Lisez-la de façon interactive (read -rs NGC_CLI_API_KEY) ou chargez-la depuis votre gestionnaire de secrets (Vault, AWS Secrets Manager, sealed-secrets) au moment du déploiement. Écrivez tout fichier .env dérivé avec umask 077 + chmod 600, ajoutez-les à .gitignore et faites pivoter la clé selon un calendrier défini et après chaque décommissionnement d'hôte. Si elle a jamais été exposée (snapshot d'hôte, écran partagé, pièce jointe de ticket), faites-la pivoter immédiatement.
Runtime Docker — Docker Engine 28.3.3 avec le plugin Docker Compose v2.39.1+. Vérifiez avec docker --version et docker compose version.
Elasticsearch — doit être accessible à l'URL configurée dans elasticsearch.node. Le serveur ping ES au démarrage ; s'il est inaccessible, il se ferme (et restart: always le ramène). Si vous devez aussi démarrer ES, utilisez le compose infra : docker compose -f services/infra/compose.yml up -d elasticsearch.
Courtier Kafka optionnel. L'API peut s'exécuter sans Kafka. Si vous voulez un déploiement quiet sans courtier, utilisez la config intégrée à l'image ou une config personnalisée avec kafka.brokers: [] ; le compose livré avec le service pointe vers localhost:9092, donc les fonctionnalités dépendantes de Kafka (config dynamique, étalonnage dynamique, RTLS/AMR) échoueront jusqu'à ce qu'un courtier soit accessible.
$VSS_DATA_DIR pour le compose par défaut. Le compose de base lie-monte $VSS_DATA_DIR/data_log/vss_video_analytics_api pour la gestion des uploads multipart et les actifs sauvegardés sur fichier tels que les images d'étalonnage. Définissez le répertoire sur un chemin hôte inscriptible et pré-créez-le, ou supprimez cette liaison si les uploads d'images ne sont pas nécessaires.

Si l'un des prérequis requis échoue, signalez le gap avant d'aller plus loin.

Workflow

Remettez à l'utilisateur references/deploy-video-analytics-api-service.md et parcourez ses étapes dans l'ordre :

Choisissez une config — valeur par défaut intégrée à l'image, livrée avec le service ou personnalisée.
Décidez si un volume data-log est nécessaire pour les uploads de fichiers.
Confirmez les dépendances d'infrastructure — Elasticsearch (obligatoire), Kafka (optionnel).
Déployez + vérifiez avec docker compose up et le contrôle de santé.

Les édits de fichier compose, les options de config, les commandes de déploiement + vérification, le tableau d'endpoints API REST et le tableau de dépannage se trouvent tous dans cette référence — ne les dupliquez pas ici.

Capacités de l'API REST

Une fois le conteneur démarré et Elasticsearch accessible, l'API sert les groupes d'endpoints listés dans references/deploy-video-analytics-api-service.md § REST API endpoints.

Le serveur doit s'initialiser par rapport à Elasticsearch avant que /livez puisse retourner un état sain. Les endpoints de requête de données nécessitent également des indices Elasticsearch correspondants et des données. Les endpoints qui publient des notifications (config, étalonnage) ou exposent des flux RTLS / AMR nécessitent également Kafka.

Fonctionnalités dépendantes de Kafka (runtime, nécessite un courtier)

Une fois le conteneur démarré et un courtier Kafka accessible, trois capacités supplémentaires sont disponibles :

Config dynamique

L'API agit en tant que producteur pour les mises à jour de config dynamique. Quand un opérateur envoie une requête POST vers /config, l'API publie un message upsert sur le topic mdx-notification avec la clé Kafka behavior-analytics-config. Le conteneur behavior-analytics en aval consomme cela et envoie un ACK. L'API gère également le flux de bootstrap — quand behavior-analytics démarre, il publie un message request-config, et l'API répond avec upsert-all contenant la config vérifiée la plus récente depuis Elasticsearch.

La validation côté consommateur, la sémantique ACK et le contrat filaire complet sont documentés dans ../vss-setup-behavior-analytics/references/dynamic-config.md.

Étalonnage dynamique

L'API produit des notifications de mise à jour d'étalonnage sur mdx-notification avec la clé Kafka calibration. Prend en charge upsert-all (snapshot complet), upsert (fusion par capteur) et delete (suppression par capteur). Le conteneur behavior-analytics en aval consomme celles-ci et les applique à l'étalonnage live.

La validation côté consommateur et la politique par action sont documentées dans ../vss-setup-behavior-analytics/references/dynamic-calibration.md.

RTLS / AMR

L'API consomme les messages de localisation temps réel (mdx-rtls) et AMR (mdx-amr) de Kafka et les expose via des endpoints REST.

Règles de routage

Si l'utilisateur veut « la pile complète » (UI / agent / perception) : remettez à vss-deploy-profile avec le profil warehouse (ou alerts). N'exécutez pas cette skill en parallèle.
Si l'utilisateur veut déployer le pipeline d'analytics (création de comportement, détection d'incident) : remettez à vss-setup-behavior-analytics.
Si l'utilisateur veut publier une mise à jour de config runtime / étalonnage via l'API REST : confirmez que Kafka est accessible, puis utilisez les endpoints /config ou étalonnage et pointez-les vers les références de mise à jour dynamique de behavior-analytics pour le contrat filaire du consommateur.
Si l'utilisateur veut comprendre le contrat filaire de config dynamique / étalonnage dynamique du côté du consommateur (behavior-analytics) : pointez-les vers ../vss-setup-behavior-analytics/references/dynamic-config.md et ../vss-setup-behavior-analytics/references/dynamic-calibration.md.
Si l'utilisateur veut interroger ou interagir avec les endpoints de l'API REST : le tableau d'endpoints ci-dessus et la référence de déploiement couvrent ce qui est disponible. Pour la spécification OpenAPI complète, voir src/app/specification/openapi.json dans le repo video-analytics-api.