Objectif

Déployer le microservice de dense-captioning RT-VLM de manière autonome 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.
• Identifiants de 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 tout 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 les profils VSS complets.

Instructions

Suivez les tables de routage et les flux de travail étape par étape ci-dessous. Chaque section qui se termine par workflow, quick start, ou flow est censée être exécutée de haut en bas. Le matériel de référence détaillé se trouve dans references/; exécutez directement les workflows documentés sauf si une future révision nomme un helper concret.

Exemples

Les exemples end-to-end travaillés 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. 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 sujets aux rate-limits, aux exigences en mémoire GPU, et aux 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 .env en dehors de git et des logs; n'affichez pas les valeurs d'identifiants et ne les incluez pas dans les réponses finales.
• L'accès au groupe Docker et sudo sont effectivement des privilèges au niveau root. Utilisez la protection non-interactive sudo -n 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 est indisponible.

Dépannage

• Erreur : L'appel REST retourne connexion refusée. Cause : microservice cible non exécuté. Solution : testez /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/expiré. 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 : passez à 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-language en temps réel de NVIDIA : décodez la vidéo (fichier ou RTSP), segmentez-la en chunks, exécutez une VLM (cosmos-reason1, cosmos-reason2, ou tout modèle compatible OpenAI), diffusez les captions denses en retour via SSE/HTTP, et publiez les captions, alertes d'incident, et erreurs vers 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 du 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 gère le routage du profil, generated.env, resolved.yml, le dimensionnement multi-services, et le déploiement/teardown de la pile complète.

Si l'utilisateur demande un dense captioning RT-VLM autonome, ou qu'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. Ceci suit le même motif centré sur compose que vss-deploy-profile : recueillez le contexte, exécutez les preflights, travaillez à partir d'une copie locale, dry-run avec docker compose config, examinez, déployez, puis attendez la santé.

Flux 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
#    vers 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 flottant autonome-uniquement de la copie.
# 4. Créez un .env gitignored avec les valeurs RT-VLM requises.
# 5. Préparez les chemins de bind de l'hôte comme $VSS_DATA_DIR/data_log/vst/clip_storage.
#    Utilisez `sudo -n` pour les corrections de propriété; si sudo sans mot de passe est indisponible,
#    arrêtez-vous et demandez au propriétaire de l'hôte d'exécuter la commande imprimée manuellement.
# 6. docker compose --env-file .env -f rtvi-vlm-docker-compose.yml config --quiet
# 7. docker pull l'étiquette exacte de l'image RT-VLM.
# 8. docker compose ... up -d rtvi-vlm, attendez la disponibilité, puis test de fumée.

Exécutez les preflights avant tout pull ou up; arrêtez-vous 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 d'un seul fichier, n'exécutez 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 voisins qui sont seulement définis dans le projet compose VSS/met-blueprints complet. La référence autonome montre comment copier le fichier compose, dériver l'étiquette d'image actuelle, supprimer le bloc depends_on, et valider le résultat avant up.

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

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

Valeurs .env autonomes minimales :

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:-}}" # 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.

Test de fumée 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

Protection pour RTSP Sample Stream

Quand une tâche ou eval nomme RTSP_SAMPLE_URL, traitez cette variable d'environnement exacte comme une entrée obligatoire. Vérifiez qu'elle est définie et non-vide avant de tester ou d'enregistrer tout stream; si elle manque, arrêtez-vous avec un message d'échec clair. Ne dérivez pas de substitut à partir de NvStreamer, VIOS, bundles sample-data, ou tout 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

Démarrage rapide — captions denses à partir d'une vidéo locale

# 1. Uploadez la vidéo, capturez son file id
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 les captions + alertes (flux SSE de réponses chunked)
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 de média multipart; passez le fichier retourné id 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 du modèle retournée par GET /v1/models; les alias comme cosmos-reason2 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 stream ids à partir de results[0].id.
• POST /v1/chat/completions pour les appels texte et multimodaux compatibles OpenAI. Les versions 26.05 actuelles retournent HTTP 400 pour /v1/completions texte-uniquement; traitez cela comme attendu lors de la validation du comportement hérité.
• GET /v1/health/ready, /v1/models, /v1/assets/stats, et /v1/metrics pour les sondes de service. N'assumez pas que /v1/license existe à moins que l'OpenAPI le liste.

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

Workflows courants

• Captioning de fichier stocké : upload avec POST /v1/files, appelez /v1/generate_captions avec le fichier retourné id, utilisez stream=true pour SSE, puis supprimez le fichier pour libérer le stockage.
• Captioning RTSP en direct : quand l'appelant fournit RTSP_SAMPLE_URL, utilisez cette URL exacte et exécutez la Protection pour RTSP Sample Stream avant l'enregistrement. Ne dérivez pas un stream de remplacement à partir de NvStreamer ou VIOS quand RTSP_SAMPLE_URL est vide; échouez rapidement à la place. Exigez une entrée de flux vidéo/caps réelle avant l'enregistrement; ajoutez le stream, captionnez-le, puis désenregistrez-le.
• Prompts d'alerte : incluez une ligne déterministe Anomaly Detected: Yes/No. La publication Kafka est une configuration côté serveur, additive aux réponses HTTP, et documentée dans references/kafka-workflows.md.
• Validation Kafka : fiez-vous à l'environnement vss-rtvi-vlm en direct pour les noms de topics. Dans un profil real-time d'alertes VSS complet, utilisez le conteneur VSS Kafka existant mdx-kafka pour les vérifications CLI et les commandes finales de consommateur d'incident. Pour la validation autonome, utilisez un broker qui annonce ${HOST_IP}:9092; ne stoppez ou ne remplacez jamais un broker préexistant sans confirmation de l'utilisateur.

Référence d'erreur

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