Objectif

Déployer le microservice RT-VLM de sous-titrage dense de manière autonome et tester chaque point de terminaison qu’il expose (téléchargement de fichiers, génération de sous-titres, ajout/suppression de flux, complétions de chat, sujets Kafka).

Prérequis

Pour un déploiement autonome de RT-VLM :

• Docker, Docker Compose, NVIDIA Container Toolkit et un GPU accessible.
• Identifiants du registre NGC dans $NGC_CLI_API_KEY pour la connexion Docker à nvcr.io, le téléchargement d’images et le téléchargement local de modèles/artefacts NGC.
• curl, jq et tout répertoire de travail accessible en écriture pour la copie autonome de Compose.

Pour les appels API vers un service existant :

• Service RT-VLM en cours d’exécution accessible à l’adresse $BASE_URL.
• Un jeton Bearer dans $RTVI_VLM_API_KEY ou $NGC_CLI_API_KEY, selon la manière dont le service a été configuré.

Pour le déploiement complet d’un profil VSS :

• Utilisez ../vss-deploy-profile/SKILL.md; cette compétence ne déploie pas les profils VSS complets.

Instructions

Suivez les tables de routage et les workflows étape par étape ci-dessous. Chaque section se terminant par « workflow », « quick start » ou « flow » est destinée à être exécutée de haut en bas. La documentation détaillée se trouve dans le répertoire references/; exécutez directement les workflows documentés, sauf si une future révision désigne un assistant spécifique.

Exemples

Des exemples complets et fonctionnels sont conservés dans le répertoire evals/ (chaque manifeste *.json contient un scénario exécutable) et intégrés dans les blocs curl spécifiques à chaque workflow ci-dessous. Exécutez une évaluation de niveau 3 avec nv-base validate --agent-eval pour les reproduire.

Limitations

• Nécessite soit un service RT-VLM autonome déployé via cette compétence, soit un service RT-VLM existant accessible depuis l’appelant.
• Les modèles hébergés sur NGC et les NIM peuvent être soumis à des limites de débit, à des exigences en matière 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 de composition du profil.
• Ne placez pas les fichiers NGC_CLI_API_KEY, RTVI_VLM_API_KEY et .env dans git ni dans les journaux ; n’affichez pas les valeurs des identifiants et ne les incluez pas dans les réponses finales.
• L’accès au groupe Docker et la commande sudo confèrent de facto des privilèges de niveau root. Utilisez la commande sudo -n (mode non interactif) dans la référence de déploiement et attendez l’intervention du propriétaire de l’hôte lorsque le sudo sans mot de passe n’est pas disponible.

Dépannage

• Erreur: l’appel REST renvoie une connexion refusée. Cause: le microservice cible ne s’exécute pas. Solution: effectuez une vérification sur /docs ou /health; redéployez via vss-deploy-profile ou la compétence vss-deploy-* correspondante.
• Erreur: code HTTP 401/403 lors des requêtes NGC. Cause: clé NGC_CLI_API_KEY manquante ou périmée. Solution: effectuez une connexion Docker sur nvcr.io et réexportez la clé avant de réessayer.
• Erreur: le conteneur est en OOM ou le modèle ne parvient pas à se charger. Cause: mémoire GPU insuffisante pour le profil sélectionné. Solution: optez pour une variante plus légère ou libérez des GPU via ` docker compose down`.

Déploiement et utilisation de RT-VLM Dense Captioning (VSS 3.2)

RT-VLM est le microservice de vision-langage en temps réel de NVIDIA : décodez une vidéo (fichier ou RTSP), segmentez-la en morceaux, exécutez un modèle VLM (cosmos-reason1, cosmos-reason2 ou tout autre modèle compatible avec OpenAI), renvoie les sous-titres denses via SSE/HTTP et publie les sous-titres, les alertes d’incident et les erreurs vers Kafka. Utilisez cette compétence pour déployer le service RT-VLM autonome lorsqu’aucun profil VSS complet n’est déjà en cours d’exécution, puis appelez son API /v1/... pour la génération de légendes, le téléchargement de fichiers, la gestion du flux en direct, les vérifications d’intégrité, les complétions de chat compatibles NIM ou les métriques Prometheus. Référence de l’API : https://docs.nvidia.com/vss/latest/real-time-vlm-api.html.

Routage du déploiement

Si l’utilisateur demande le déploiement d’un profil VSS complet, utilisez ../vss-deploy-profile/SKILL.md. Cette compétence gère le routage des profils, le fichier generated.env, le fichier resolved.yml, le dimensionnement multi-services et le déploiement/démantèlement de la pile complète.

Si l’utilisateur demande un sous-titrage dense RT-VLM autonome, ou si aucun profil VSS n’est déjà en cours d’exécution, utilisez le flux RT-VLM autonome dans references/deploy-rt-vlm-service.md avant d’appeler l’API. Ce processus suit le même modèle centré sur Docker Compose que vss-deploy-profile: collecte du contexte, exécution des pré-vérifications, travail à partir d’une copie locale, simulation avec la configuration Docker Compose, vérification, déploiement, puis attente de la validation de l’état de santé.

Flux de déploiement autonome

Suivez toujours cette séquence. Ne sautez jamais la simulation.

# 1. Copiez le fichier deploy/docker/services/rtvi/rtvi-vlm/rtvi-vlm-docker-compose.yml
#    dans n’importe quel répertoire de travail autonome accessible en écriture.
# 2. Déterminez la valeur de RTVI_VLM_IMAGE_TAG à partir de cette copie de Compose.
# 3. Supprimez de la copie le bloc `depends_on` superflu, réservé à l’installation autonome.
# 4. Créez un fichier .env ignoré par Git contenant les valeurs RT-VLM requises.
# 5. Préparez les chemins de montage de l’hôte, tels que $VSS_DATA_DIR/data_log/vst/clip_storage.
#    Utilisez `sudo -n` pour corriger les droits de propriété ; si le sudo sans mot de passe n’est pas disponible,
#    arrêtez-vous et demandez au propriétaire de l’hôte d’exécuter manuellement la commande affichée.
# 6. docker compose --env-file .env -f rtvi-vlm-docker-compose.yml config --quiet
# 7. Récupérez l’image RT-VLM avec la balise exacte à l’aide de `docker pull`.
# 8. Exécutez `docker compose ... up -d rtvi-vlm`, attendez que le système soit prêt, puis effectuez un test de fonctionnement.

Exécutez les pré-vérifications avant toute commande `pull` ou ` up`; arrêtez-vous et corrigez les échecs à ce stade avant de déboguer RT-VLM lui-même :

nvidia-smi --query-gpu=index,name --format=csv,noheader
nvidia-container-cli info
docker compose version
docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

Pour les déploiements autonomes à fichier unique, n’exécutez pas directement le fichier brut deploy/docker/services/rtvi/rtvi-vlm/rtvi-vlm-docker-compose.yml: il contient des références depends_on à des services VLM/NIM frères qui ne sont définis dans le projet Compose complet VSS/met-blueprints. La référence « standalone » indique comment copier le fichier Compose, en dériver la balise d’image actuelle, supprimer le bloc `depends_on ` et valider le résultat avant l’exécution de la commande `up`.

Pour une validation pilotée par l’agent, ne laissez jamais l’invite sudo s’afficher de manière interactive. Avant toute opération privilégiée ou opération Docker, utilisez la protection non interactive décrite dans references/deploy-rt-vlm-service.md: privilégiez docker en mode simple ; sinon, utilisez sudo -n docker; si sudo -n échoue, arrêtez-vous en utilisant la commande manuelle exacte pour le propriétaire de l’hôte au lieu de réessayer avec sudo en mode interactif ou d’affaiblir les permissions.

Si la commande `docker pull` échoue avec une erreur « containerd snapshotter/unpack » sous Docker 28 ou version supérieure, appliquez la correction ` /etc/docker/daemon.json containerd-snapshotter=false ` dans la référence « standalone » avant de réessayer.

Valeurs minimales du fichier .env pour le mode autonome :

Configuration

export BASE_URL="http://localhost:${RTVI_VLM_PORT:-8018}"  # port RT-VLM côté hôte
export API_KEY="${NGC_CLI_API_KEY:-${RTVI_VLM_API_KEY:-}}" # jeton « bearer » utilisé par les commandes curl côté hôte
: "${API_KEY:?Définissez NGC_CLI_API_KEY ou RTVI_VLM_API_KEY avant d’appeler les points de terminaison authentifiés}"

Chaque requête ci-dessous utilise Authorization: Bearer $API_KEY. Les points de terminaison de santé (/v1/health/*, /v1/ready, /v1/live, /v1/startup) fonctionnent généralement sans authentification.

Test de fonctionnement avant utilisation :

curl -fsS "$BASE_URL/v1/health/ready"
MODEL_ID="$(curl -fsS "$BASE_URL/v1/models" -H "Authorization: Bearer $API_KEY" | jq -r '.data[0].id // .id')"
curl -fsS "$BASE_URL/openapi.json" | jq -r '.paths | keys[]' | sort

Exemple de Stream Guard RTSP

Lorsqu’une tâche ou une évaluation mentionne RTSP_SAMPLE_URL, considérez cette variable d’environnement exacte comme une entrée obligatoire. Vérifiez qu’elle est définie et non vide avant d’interroger ou d’ enregistrer un flux ; si elle est manquante, arrêtez-vous en affichant un message d’échec clair. Ne dérivez pas de valeur de remplacement à partir de NvStreamer, VIOS, des paquets de données d’échantillon ou de toute autre solution de secours, car cela validerait un flux différent de celui demandé par l’appelant.

: "${RTSP_SAMPLE_URL:?Définissez RTSP_SAMPLE_URL sur un flux d'échantillon RTSP accessible avant la validation RTSP}"
case "$RTSP_SAMPLE_URL" in
  rtsp://*) ;;
  *) echo "RTSP_SAMPLE_URL doit être une URL de type rtsp://, valeur reçue : $RTSP_SAMPLE_URL" >&2; exit 1 ;;
esac

if command -v ffprobe >/dev/null 2>&1; then
  ffprobe -v error -rtsp_transport tcp \
    -select_streams v:0 -show_entries stream=codec_type \
    -of csv=p=0 "$RTSP_SAMPLE_URL" | grep -qx video
elif command -v gst-discoverer-1.0 >/dev/null 2>&1; then
  gst-discoverer-1.0 "$RTSP_SAMPLE_URL" | grep -qi 'video'
else
  echo "Installez ffprobe ou gst-discoverer-1.0 avant la validation RTSP." >&2
  exit 1
fi

Démarrage rapide — sous-titres denses à partir d’une vidéo locale

# 1. Téléchargez la vidéo, récupérez son identifiant de fichier
FILE_ID=$(curl -fsS -X POST "$BASE_URL/v1/files" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@/path/to/warehouse.mp4" \
  -F "purpose=vision" \
  -F "media_type=video" | jq -r '.id')

# 2. Générer des sous-titres et des alertes (flux SSE de réponses par morceaux)
curl -N -X POST "$BASE_URL/v1/generate_captions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"id\": \"$FILE_ID\",
    \"prompt\": \"Rédigez une légende concise et percutante pour chaque segment de 10 secondes de cette vidéo d’entrepôt.\",
    \"model\": \"$MODEL_ID\",
    \"chunk_duration\": 10,
    \"stream\": true
  }"

Interface API

Utilisez l’OpenAPI en direct comme source de référence avant d’appeler les points de terminaison facultatifs :

curl -fsS "$BASE_URL/openapi.json" | jq -r '.paths | keys[]' | sort

Les chemins d’accès principaux pour VSS 3.2 sont les suivants :

• POST /v1/files pour le téléchargement de fichiers multimédias en plusieurs parties ; transmettez l’identifiant du fichier renvoyé à la génération de sous-titres et supprimez le fichier une fois l’opération terminée.
• POST /v1/generate_captions pour le sous-titrage de fichiers ou de flux. Utilisez l’ identifiant de modèle exact renvoyé par GET /v1/models; les alias tels que cosmos-reason2 sont des sélecteurs de backend, et non des identifiants de modèle de requête.
• POST /v1/streams/add, GET /v1/streams/get-stream-info et DELETE /v1/streams/delete/{stream_id} pour le cycle de vie RTSP. Analysez les identifiants de flux à partir de results[0].id.
• POST /v1/chat/completions pour les appels textuels et multimodaux compatibles OpenAI. Les versions actuelles 26.05 renvoient un code HTTP 400 pour les appels /v1/completions en texte seul ; considérez cela comme normal lors de la validation du comportement hérité.
• GET /v1/health/ready, /v1/models, /v1/assets/stats et /v1/metrics pour les tests de disponibilité du service. Ne présumez pas que /v1/license existe, sauf si OpenAPI le mentionne.

Les schémas détaillés des points de terminaison, les formats de réponse, les points de terminaison de flux singuliers de type CV, ainsi que les notes de compatibilité avec la version 26.05 se trouvent dans references/api-surface-26.05.md.

Workflows courants

• Sous-titrage de fichiers stockés : effectuez un envoi avec POST /v1/files, appelez /v1/generate_captions avec l’identifiant du fichier renvoyé, utilisez stream=true pour SSE, puis supprimez le fichier pour libérer de l’espace de stockage.
• Sous-titrage en direct RTSP : lorsque l’appelant fournit RTSP_SAMPLE_URL, utilisez cette URL exacte et exécutez le RTSP Sample Stream Guard avant l’enregistrement. Ne dérivez pas de flux de remplacement à partir de NvStreamer ou VIOS lorsque RTSP_SAMPLE_URL est vide ; optez plutôt pour un échec rapide. Exigez une entrée « stream/caps » de vidéo réelle avant l’enregistrement ; ajoutez le flux, sous-titrez-le, puis désenregistrez-le.
• Messages d’alerte : incluez une ligne déterministe « Anomalie détectée : Oui/Non ». La publication sur Kafka est une configuration côté serveur, s’ajoutant aux réponses HTTP, et documentée dans references/kafka-workflows.md.
• Validation Kafka : se fier à l’environnement vss-rtvi-vlm en production pour les noms de sujets. Dans un profil d’alertes VSS en temps réel complet, utiliser le conteneur Kafka VSS existant mdx-kafka pour les vérifications via l’interface en ligne de commande et les commandes finales de traitement des incidents. Pour une validation autonome, utilisez un broker qui publie ${HOST_IP}:9092; n’arrêtez et ne remplacez jamais un broker préexistant sans confirmation de l’utilisateur.

Référence des erreurs

Causes courantes : 400 pour une structure de requête ou un identifiant de modèle non valide, 401/403 pour un jeton « bearer » manquant ou incorrect, 404 pour des fichiers/flux supprimés ou des points de terminaison non pris en charge, 413 pour des téléchargements trop volumineux, 422 pour la validation du schéma, 429 pour un nombre trop élevé de connexions simultanées, 500 pour des échecs d’inférence ou d’exécution, et 503 lorsque le démarrage est encore en cours. Consultez les journaux Docker « vss-rtvi-vlm » pour les défaillances côté service.