Objectif

Déployer le microservice de dense-captioning RT-VLM en tant que tel et exercer chaque endpoint qu'il expose (upload de fichier, generate_captions, ajout/suppression de stream, chat-completions, topics Kafka).

Prérequis

Pour un déploiement RT-VLM autonome :

• Docker, Docker Compose, NVIDIA Container Toolkit, et un GPU visible.
• Credentials du registre NGC dans $NGC_CLI_API_KEY pour docker login nvcr.io, les pulls d'images, et les téléchargements locaux de modèles/artefacts NGC.
• curl, jq, et n'importe quel répertoire de travail inscriptible pour la copie compose autonome.

Pour les appels API contre un service existant :

• Service RT-VLM en cours d'exécution accessible à $BASE_URL.
• Token Bearer dans $RTVI_VLM_API_KEY ou $NGC_CLI_API_KEY, selon la façon dont le service a été configuré.

Pour un déploiement complet du profil VSS :

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

Instructions

Suivez les tableaux 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. Le matériel de référence détaillé se trouve dans references/ ; exécutez les workflows documentés directement sauf si une révision future nomme un helper concret.

Exemples

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

Limitations

• Nécessite soit un service RT-VLM autonome déployé via cette skill, soit un service RT-VLM existant 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.
• Gardez NGC_CLI_API_KEY, RTVI_VLM_API_KEY, et les fichiers rtvi-vlm.env hors de git et des logs ; ne faites pas d'echo des valeurs de credentials et ne les incluez pas dans les réponses finales.
• L'accès au groupe Docker et sudo sont des privilèges de niveau racine. Utilisez la garde sudo -n non-interactive dans la référence de déploiement et arrêtez-vous pour une action du propriétaire de l'hôte quand sudo sans mot de passe n'est pas disponible.

Dépannage

• Erreur : l'appel REST retourne connection refused. Cause : le microservice cible ne s'exécute pas. Solution : sondez /docs ou /health ; redéployez via vss-deploy-profile ou la skill vss-deploy-* correspondante.
• Erreur : HTTP 401/403 des pulls NGC. Cause : NGC_CLI_API_KEY manquante/expirée. Solution : docker login nvcr.io et réexportez la clé avant de réessayer.
• Erreur : container OOM ou échec du chargement du modèle. Cause : mémoire GPU insuffisante pour le profil sélectionné. Solution : basculez sur une variante plus petite ou libérez les GPUs via docker compose down.

Déployer et utiliser RT-VLM Dense Captioning (VSS 3.2)

RT-VLM est le microservice vision-langage temps réel d'NVIDIA : décodez la vidéo (fichier ou RTSP), segmentez-la en chunks, exécutez un VLM (cosmos-reason1, cosmos-reason2, cosmos-reason3, ou n'importe quel modèle compatible OpenAI), streamez des dense captions en retour via SSE/HTTP, et publiez les captions, les alertes d'incident, et les erreurs sur Kafka. Utilisez cette skill pour déployer le service RT-VLM autonome quand un profil VSS complet n'est pas déjà en cours d'exécution, puis appelez son API /v1/... pour la génération de captions, l'upload de fichier, la gestion de live-stream, les vérifications de santé, les chat completions compatibles NIM, ou les métriques Prometheus. Référence API : https://docs.nvidia.com/vss/latest/real-time-vlm-api.html.

Routage de déploiement

Si l'utilisateur demande de déployer un profil VSS complet, utilisez ../vss-deploy-profile/SKILL.md. Cette skill possède le routage du profil, generated.env, resolved.yml, le dimensionnement multi-service, et le déploiement/démontage full-stack.

Si l'utilisateur demande du dense captioning RT-VLM autonome, ou aucun profil VSS n'est déjà en cours d'exécution, utilisez le flow RT-VLM autonome dans references/deploy-rt-vlm-service.md avant d'appeler l'API. Cela suit le même pattern centré sur compose que vss-deploy-profile : rassemblez le contexte, exécutez les préflights, travaillez à partir d'une copie locale, dry-run avec docker compose config, examinez, déployez, puis attendez la santé.

Flow de déploiement autonome

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

# 1. Copiez deploy/docker/services/rtvi/rtvi-vlm/rtvi-vlm-docker-compose.yml
#    dans n'importe quel répertoire de travail autonome inscriptible.
# 2. Dérivez RTVI_VLM_IMAGE_TAG de cette copie compose.
# 3. Supprimez le bloc depends_on orphelin autonome-only de la copie.
# 4. Créez un rtvi-vlm.env ignoré par git avec les valeurs RT-VLM requises.
# 5. Préparez les chemins de liaison d'hôte comme $VSS_DATA_DIR/data_log/vst/clip_storage.
#    Utilisez `sudo -n` pour les correctifs de propriété ; si sudo sans mot de passe n'est pas disponible,
#    arrêtez et demandez au propriétaire de l'hôte d'exécuter manuellement la commande imprimée.
# 6. docker compose --env-file rtvi-vlm.env -f rtvi-vlm-docker-compose.yml config --quiet
# 7. docker pull la balise d'image RT-VLM exacte.
# 8. docker compose ... up -d rtvi-vlm, attendez la disponibilité, puis effectuez un smoke test.

Exécutez les préflights avant tout pull ou up ; arrêtez et corrigez les défaillances ici 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, ne lancez pas directement le deploy/docker/services/rtvi/rtvi-vlm/rtvi-vlm-docker-compose.yml brut : il contient des références depends_on aux services VLM/NIM frères qui ne sont définis que dans le projet compose VSS/met-blueprints complet. La référence autonome montre comment copier le fichier compose, dériver la balise d'image actuelle, supprimer le bloc depends_on, et valider le résultat avant up.

Pour la validation pilotée par agent, ne laissez jamais sudo inviter de manière interactive. Avant n'importe quelle opération de propriété ou Docker privilégiée, utilisez la garde non-interactive dans references/deploy-rt-vlm-service.md : préférez le docker simple ; sinon utilisez sudo -n docker ; si sudo -n échoue, arrêtez avec la commande manuelle exacte pour le propriétaire de l'hôte au lieu de réessayer avec un sudo interactif ou d'affaiblir les permissions.

Si docker pull échoue avec une erreur de snapshotter/unpack containerd sur Docker 28+, appliquez le correctif containerd-snapshotter=false de /etc/docker/daemon.json dans la référence autonome avant de réessayer.

Valeurs rtvi-vlm.env autonome minimum :

Installation

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:-}}" # token Bearer utilisé par les commandes curl côté hôte
: "${API_KEY:?Set NGC_CLI_API_KEY or RTVI_VLM_API_KEY before calling authenticated endpoints}"

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

Smoke test 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

Garde du stream RTSP exemple

Quand une tâche ou eval nomme RTSP_SAMPLE_URL, traitez cette variable d'environnement exacte comme une entrée requise. Vérifiez qu'elle est définie et non-vide avant de sonder ou d'enregistrer n'importe quel stream ; si elle est manquante, arrêtez avec un message d'échec clair. Ne dérivez pas de substitut de NvStreamer, VIOS, sample-data bundles, ou n'importe quel autre fallback, car cela valide un stream différent de celui demandé par l'appelant.

: "${RTSP_SAMPLE_URL:?Set RTSP_SAMPLE_URL to a reachable RTSP sample stream before RTSP validation}"
case "$RTSP_SAMPLE_URL" in
  rtsp://*) ;;
  *) echo "RTSP_SAMPLE_URL must be an rtsp:// URL, got: $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 "Install ffprobe or gst-discoverer-1.0 before RTSP validation." >&2
  exit 1
fi

Quick Start — dense captions d'une vidéo locale

# 1. Uploadez la vidéo, capturez son id 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érez des captions + alertes (SSE stream de réponses fragmentées)
curl -N -X POST "$BASE_URL/v1/generate_captions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"id\": \"$FILE_ID\",
    \"prompt\": \"Write a concise dense caption for each 10-second segment of this warehouse video.\",
    \"model\": \"$MODEL_ID\",
    \"chunk_duration\": 10,
    \"stream\": true
  }"

Surface API

Utilisez l'OpenAPI en direct comme source de vérité avant d'appeler les endpoints optionnels :

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

Les chemins principaux pour VSS 3.2 sont :

• POST /v1/files pour l'upload multipart de médias ; passez l'id de fichier retourné dans la génération de captions et supprimez le fichier quand vous avez terminé.
• POST /v1/generate_captions pour le captioning de fichier ou de stream. Utilisez l'exacte id de modèle retournée par GET /v1/models ; les alias comme cosmos-reason2 ou cosmos-reason3 sont des sélecteurs backend, pas des ids 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 ids de stream depuis results[0].id.
• POST /v1/chat/completions pour les appels texte et multimodaux compatibles OpenAI. Les builds 26.05 actuels retournent HTTP 400 pour /v1/completions texte-only ; traitez cela comme prévu lors de la validation du comportement legacy.
• GET /v1/health/ready, /v1/models, /v1/assets/stats, et /v1/metrics pour les sondes de service. Ne supposez pas que /v1/license existe à moins que OpenAPI l'énumère.

Les schémas d'endpoint détaillés, les formes de réponse, les endpoints de stream singuliers style CV, et les notes de compatibilité 26.05 se trouvent dans references/api-surface-26.05.md.

Workflows courants

• Captioning de fichier stocké : uploadez avec POST /v1/files, appelez /v1/generate_captions avec l'id de fichier retourné, utilisez stream=true pour SSE, puis supprimez le fichier pour libérer le stockage.
• Captioning live RTSP : quand l'appelant fournit RTSP_SAMPLE_URL, utilisez cette URL exacte et exécutez la Garde du stream RTSP exemple avant l'enregistrement. Ne dérivez pas de stream de remplacement de NvStreamer ou VIOS quand RTSP_SAMPLE_URL est vide ; échouez rapide à la place. Nécessitez une entrée de video stream/caps réelle avant l'enregistrement ; ajoutez le stream, captionnez-le, puis désenregistrez-le.
• Prompts d'alerte : incluez une ligne Anomaly Detected: Yes/No déterministe. La publication Kafka est une config côté serveur, additive aux réponses HTTP, et documentée dans references/kafka-workflows.md.
• Validation Kafka : faites confiance à l'environnement vss-rtvi-vlm en direct pour les noms de topics. Dans un profil temps réel VSS alerts complet, utilisez le container VSS Kafka existant kafka pour les vérifications CLI et les commandes finales d'incident-consumer. Pour la validation autonome, utilisez un broker qui annonce ${HOST_IP}:9092 ; ne arrêtez jamais ou ne remplacez un broker pré-existant sans confirmation de l'utilisateur.

Référence des erreurs

Causes courantes : 400 pour forme de requête ou id de modèle invalides, 401/403 pour token Bearer manquant ou mauvais, 404 pour fichiers/streams supprimés ou endpoints non supportés, 413 pour uploads surdimensionnés, 422 pour validation de schéma, 429 pour trop de concurrence, 500 pour défaillances d'inférence/runtime, et 503 pendant que le startup est toujours en cours. Inspectez docker logs vss-rtvi-vlm pour les défaillances côté service.