vss-summarize-video

Instructions

Suivez les tableaux de routage et les flux de travail étape par étape ci-dessous. Chaque section se terminant par workflow, quick start, ou flow doit être exécutée de haut en bas. Le matériel de référence détaillé se trouve dans references/.

Exemples

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

Appelez le VLM NIM ou le microservice de synthèse vidéo directement. Exécutez toujours les commandes curl vous-même ; ne demandez jamais à l'utilisateur de les exécuter.

Type de requête de flux de travail vidéo principal : « Résumez cette vidéo. » Les demandes directes d'API de synthèse vidéo et d'exploitation de service sont gérées par les sections routées par référence ci-dessous.

Objectif

Produire un résumé narratif unique et poli d'un clip vidéo enregistré, avec des événements horodatés lorsque le chemin du microservice LVS est accessible.

N'utilisez PAS cette compétence pour :

• Sous-titrage RTSP en direct — utilisez vss-deploy-dense-captioning.
• Génération de rapports, y compris les rapports d'incident ou de fenêtre d'alerte — utilisez vss-generate-video-report Mode B.
• Recherche sémantique dans l'archive — utilisez vss-search-archive.

Prérequis

• Profil VSS lvs en cours d'exécution sur $HOST_IP (port 38111) OU un endpoint VLM/RT-VLM accessible comme solution de secours. La compétence vss-deploy-profile les démarre.
• Accessibilité réseau de l'hôte agent aux deux endpoints ; les URLs de clips de VIOS doivent être accessibles par le backend choisi.
• jq et curl disponibles sur l'hôte agent.

Limitations

• Le recours VLM direct utilise une invite fixe unique et ne peut pas cibler des scénarios/événements — la qualité de sortie est inférieure au chemin LVS.
• Les endpoints VLM distants ne peuvent généralement pas atteindre les URLs de clip localhost/privées.
• Un appel backend par requête ; pas de couverture parallèle ou de résumés multi-passe.

Dépannage

Consultez references/video-summarization-debugging.md pour des diagnostics plus approfondis.

Carte de référence

Utilisez ces références uniquement lorsque l'utilisateur demande le détail pertinent, ou lorsque le flux de travail principal ci-dessous a besoin d'informations plus approfondies sur la synthèse vidéo :

• Détails de l'API de synthèse vidéo : references/video-summarization-api.md pour /v1/summarize, /summarize, /v1/generate_captions, /v1/stream_summarize, sondes de santé, /models, /recommended_config, /metrics, champs de requête, formes de réponse, et pièges de l'API.
• Configuration et exploitation du service de synthèse vidéo : references/video-summarization-deployment.md pour le profil VSS lvs, ports, variables d'environnement requises, journaux, statut, essais à sec, démontage, échanges de modèle/backend, sélection de backend Elasticsearch/Neo4j/ArangoDB, et dépannage au niveau du service.
• Références d'exploitation étendues de synthèse vidéo : references/video-summarization-environment-variables.md, references/video-summarization-debugging.md, et assets/video-summarization.env.example.

Chargez video-summarization-api.md uniquement lorsque vous avez besoin d'un champ de requête, d'une forme de réponse, ou d'un endpoint non couverts par l'exemple LVS ou VLM de secours de l'étape 2 ci-dessous, ou lors du traitement d'une demande directe d'API de synthèse vidéo. Chargez video-summarization-deployment.md uniquement pour le déploiement, la configuration, ou les opérations de service.

Requêtes d'API de synthèse vidéo et d'exploitation de service

Si l'utilisateur demande d'appeler ou déboguer les endpoints de synthèse vidéo directement, répondez à partir de references/video-summarization-api.md au lieu d'exécuter le flux de travail de synthèse vidéo de bout en bout. Exemples : lister les modèles de synthèse vidéo, vérifier la disponibilité, obtenir la configuration de chunking recommandée, inspecter les métriques, expliquer une réponse 422, ou construire un corps de requête /v1/summarize.

Si l'utilisateur demande de configurer, déployer, redémarrer, démanteler, ou dépanner le service de synthèse vidéo, préférez la compétence vss-deploy-profile pour le déploiement complet du profil VSS et utilisez references/video-summarization-deployment.md pour les détails spécifiques à la synthèse vidéo.

Routage

Décidez uniquement en fonction de la disponibilité du service de synthèse vidéo (sondée dans Setup → Availability checks ci-dessous). La durée ne détermine pas le routage.

Message de secours quand le service LVS est inaccessible — copiez verbatim au-dessus du résumé :

⚠ Note : La vidéo d'entrée <name> dure <N>s. Le service de synthèse vidéo n'est pas déployé, donc ce résumé a été produit par le VLM seul avec une invite générique par défaut. Déployez le profil lvs pour des résumés de meilleure qualité avec ciblage de scénario/événements.

Prérequis de déploiement

Le profil lvs VSS sur $HOST_IP est le backend principal. Si la sonde /v1/ready (voir Setup → Availability checks) retourne autre chose que 200 après les tentatives de préchauffage, demandez à l'utilisateur :

« Le profil VSS lvs n'est pas en cours d'exécution sur $HOST_IP. Dois-je le déployer maintenant en utilisant la compétence /vss-deploy-profile avec -p lvs ? Répondez non pour résumer avec la solution de secours VLM uniquement à la place (qualité inférieure, pas de ciblage de scénario/événements). »

• Oui → déléguez à /vss-deploy-profile, puis ressondez et continuez avec l'étape 2 (LVS + HITL).
• Non → allez directement à l'étape 2 secours (VLM avec invite par défaut) et précédez de la note de secours de routage. Ne demandez pas à nouveau, et n'exécutez pas de HITL de scénario/événements.
• Pré-autorisé à déployer de manière autonome (l'appelant l'a dit explicitement) → ignorez la confirmation et invoquez /vss-deploy-profile directement.
• Pré-autorisé à utiliser la solution de secours VLM (« ignorez lvs, utilisez juste le VLM ») → allez directement à la solution de secours de l'étape 2 sans demander.

Setup

Endpoints (valeurs par défaut pour un déploiement VSS lvs local) :

• VLM / RT-VLM : ${VLM_BASE_URL} — valeur par défaut ${RTVI_VLM_BASE_URL:-http://${HOST_IP:-localhost}:8018}
• Service LVS : ${LVS_BACKEND_URL} — valeur par défaut http://${HOST_IP:-localhost}:38111
• VIOS : appartient à vss-manage-video-io-storage ; référez-vous là.

Utilisez les variables d'environnement quand elles sont définies (supprimez le /v1 final du VLM base — la compétence l'ajoute). Sinon, utilisez les valeurs par défaut. Si aucune ne fonctionne, demandez à l'utilisateur — ne scannez pas les ports ou ne lisez pas les fichiers de configuration pour deviner.

Nom du modèle : lisez ${VLM_NAME} (valeur par défaut nim_nvidia_cosmos-reason2-8b_hf-1208). Il doit correspondre à l'id que RT-VLM /v1/models annonce ; ne substituez pas le nom convivial nvidia/cosmos-reason2-8b.

Pour les schémas d'endpoint, les champs optionnels, les enveloppes de réponse, et la gestion des erreurs, voir references/video-summarization-api.md.

Vérifications de disponibilité (exécutez les deux avant le routage). La disponibilité est déterminée par le code de statut HTTP uniquement — le /v1/ready LVS peut légitimement retourner 200 avec un corps vide, donc n'inspectez pas le corps.

VLM="${VLM_BASE_URL:-${RTVI_VLM_BASE_URL:-http://${HOST_IP:-localhost}:8018}}"
VLM="${VLM%/v1}"

# VLM / RT-VLM: 200 on /v1/models
vlm_code=$(curl -s -o /dev/null -w '%{http_code}' --connect-timeout 3 --max-time 10 \
  "$VLM/v1/models")
[ "$vlm_code" = "200" ] && echo "VLM OK" || echo "VLM not reachable (HTTP $vlm_code)"

# Video summarization service: 200 on /v1/ready, with retry on 503 (warmup) for up to ~30s
VIDEO_SUMMARIZATION_URL=${LVS_BACKEND_URL:-http://${HOST_IP:-localhost}:38111}
video_sum_code=000
for i in $(seq 1 10); do
  video_sum_code=$(curl -s -o /dev/null -w '%{http_code}' --connect-timeout 3 --max-time 10 "$VIDEO_SUMMARIZATION_URL/v1/ready")
  case "$video_sum_code" in
    200) echo "video summarization OK"; break ;;
    503) sleep 3 ;;                 # warming up; keep polling
    *)   break ;;                   # any other code = not reachable, stop retrying
  esac
done
[ "$video_sum_code" = "200" ] || echo "video summarization service not reachable (HTTP $video_sum_code)"

Comment interpréter les résultats :

• video_sum_code = 200 → Étape 2 (LVS + HITL) pour chaque vidéo.
• video_sum_code != 200, vlm_code = 200 → Étape 2 secours (VLM) ; précédez de la note de secours de routage.
• vlm_code != 200 → échouer ; au moins un backend doit être accessible.
• Un code LVS non-200 après la boucle de tentatives est le SEUL signal d'indisponibilité. Une sortie vide ou des champs JSON manquants NE SONT PAS « indisponibles ».

Étape 1 - Obtenir l'URL du clip via vss-manage-video-io-storage (sous-tâche, PAS la réponse finale)

Utilisez la compétence vss-manage-video-io-storage pour toutes les interactions VIOS — elle possède les recettes curl canoniques, les valeurs par défaut des paramètres, et les flux de suppression/upload. Ne fabriciquez pas d'URLs ou ne faites pas de requêtes VIOS à la main ; elles dériveront.

Cette étape est une sous-tâche — NE terminez PAS votre tour ici ; NE retournez PAS l'URL du clip comme réponse finale. De VIOS, collectez trois valeurs :

1. streamId (via sensor/list → sensor/<id>/streams, ou directement à partir d'une réponse d'upload).
2. Chronologie - {startTime, endTime} (ISO 8601 UTC). endTime - startTime est la durée ; nécessaire uniquement pour l'en-tête face à l'utilisateur (le routage est déterminé uniquement par /v1/ready).
3. URL du clip MP4 temporaire — la variante /storage/file/<streamId>/url avec container=mp4. Champ de réponse : .videoUrl. Les deux backends ont besoin d'une URL HTTP(S) qu'ils peuvent GET.

Tout le reste (auth, upload, disableAudio, expiry, etc.) se trouve dans la compétence vss-manage-video-io-storage — référez les utilisateurs là si VIOS échoue.

Étape 2 — Primaire : microservice de synthèse vidéo avec HITL

Utilisez ce chemin chaque fois que /v1/ready a retourné 200 lors du Setup. La durée est sans pertinence.

Pour les champs avancés (media_info, schema, sortie structurée, sous-titrage de flux, métriques, config recommandée) voir references/video-summarization-api.md.

HITL : collectez d'abord le scénario et les événements (REQUIS — ne sautez pas)

La procédure complète se trouve dans references/hitl-prompts.md. Exécutez toujours HITL avant d'appeler le service LVS.

Valeurs par défaut du mode autonome. Quand l'appelant a contourné HITL (« exécutez de manière autonome sans demander ») ET la requête originale demande default/defaults (ou n'en donne aucune), utilisez scenario="activity monitoring" et events=["notable activity"] littéralement — ne déduisez pas à partir du nom de fichier ou du nom de capteur. Notez les valeurs par défaut dans la réponse finale et proposez une réexécution avec des paramètres plus spécifiques. C'est le SEUL contournement HITL supporté ; « la vidéo est courte » ou « l'utilisateur semble pressé » ne sont pas des raisons valides.

Préférez POST /v1/summarize (route 3.2 GA) ; /summarize est un alias de compatibilité.

VIDEO_SUMMARIZATION_URL=${LVS_BACKEND_URL:-http://${HOST_IP:-localhost}:38111}

# From HITL reply:
SCENARIO='warehouse monitoring'
EVENTS_JSON='["notable activity"]'
OBJECTS_JSON=''  # '' to omit, else '["forklifts","pallets","workers"]'

curl -s --max-time 300 -X POST "$VIDEO_SUMMARIZATION_URL/v1/summarize" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg url "<clip_url_from_vss_manage_video_io_storage>" \
        --arg model "${VLM_NAME:-nim_nvidia_cosmos-reason2-8b_hf-1208}" \
        --arg scenario "$SCENARIO" \
        --argjson events "$EVENTS_JSON" \
        --argjson objects "${OBJECTS_JSON:-null}" '{
    url: $url,
    model: $model,
    scenario: $scenario,
    events: $events,
    chunk_duration: 10,
    num_frames_per_second_or_fixed_frames_chunk: 20,
    use_fps_for_chunking: false,
    seed: 1
  } + (if $objects == null then {} else {objects_of_interest: $objects} end)')" \
  | jq -r '.choices[0].message.content' \
  | jq '{video_summary, events}'

Si à la fois video_summary et events sont vides, le clip ne contient probablement pas les événements demandés — réexécutez avec un scenario/events plus large, ne signalez pas « aucun contenu ».

Tuning : chunk_duration (valeur par défaut 10s ; 0 = chunk unique), num_frames_per_second_or_fixed_frames_chunk (valeur par défaut 20 ; le sens dépend de use_fps_for_chunking), seed (valeur par défaut 1). num_frames_per_chunk est obsolète.

Étape 2 secours — VLM direct avec invite par défaut

Utilisez ce chemin uniquement quand /v1/ready n'a pas retourné 200 après le préchauffage. N'exécutez PAS HITL — l'utilisateur n'a pas accepté ; vous avez basculé parce que le service manquait. Précédez la note de secours de routage à la réponse.

VLM="${VLM_BASE_URL:-${RTVI_VLM_BASE_URL:-http://${HOST_IP:-localhost}:8018}}"
VLM="${VLM%/v1}"
PROMPT='Describe in detail what is happening in this video,
including all visible people, vehicles, equipments, objects,
actions, and environmental conditions.
OUTPUT REQUIREMENTS:
[timestamp-timestamp] Description of what is happening.
EXAMPLE:
[0.0s-4.0s] <description of the first event>
[4.0s-12.0s] <description of the second event>'

curl -s --max-time 300 -X POST "$VLM/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d "$(jq -n \
        --arg model "${VLM_NAME:-nim_nvidia_cosmos-reason2-8b_hf-1208}" \
        --arg text "$PROMPT" \
        --arg url "<clip_url_from_vss_manage_video_io_storage>" \
        '{
          model: $model,
          temperature: 0.0,
          max_tokens: 1024,
          messages: [{
            role: "user",
            content: [
              {type: "text", text: $text},
              {type: "video_url", video_url: {url: $url}}
            ]
          }]
        }')" | jq -r '.choices[0].message.content'

Réponse : enveloppe chat-completion OpenAI standard. Le résumé est dans choices[0].message.content.

Notes sur le modèle Cosmos : Cosmos Reason 2 supporte le raisonnement via des blocs <think>...</think><answer>...</answer>. Omettez les instructions de raisonnement si vous voulez un résumé simple. L'échantillonnage de frame et les limites de pixels sont appliqués côté serveur ; aucune préparation côté client n'est requise quand vous passez une video_url.

Exemple de bout en bout

Voir references/end-to-end-example.md pour le script complet LVS-ou-VLM-fallback qui sonde /v1/ready et exécute le chemin approprié.

Réponses

• VLM retourne une enveloppe chat-completion OpenAI ; le résumé est choices[0].message.content.
• Service LVS retourne la même enveloppe mais content est une chaîne JSON — exécutez jq -r '.choices[0].message.content' | jq pour atteindre {video_summary, events}.
• Erreurs apparaissent comme HTTP non-2xx plus JSON {error: ...}. LVS 503 signifie généralement préchauffage — réessayez /v1/ready.

Présenter la sortie à l'utilisateur

Exposez la sortie du backend avec transformation minimale — ne paraphrasez pas, ne réinterprez pas, n'ajoutez pas d'emojis, ne reformatez pas. Un appel backend → un rendu : pas de couverture parallèle, pas d'en-têtes dupliqués, n'appelez jamais à la fois LVS et VLM pour la même vidéo.

Ligne d'en-tête. Commencez avec exactement une :

Summary of <video_name> (<duration>)

<duration> = Ns pour < 60 s, sinon Mm Ss (par ex. 3m 30s).

Sortie LVS : rendez video_summary littéralement (rapport poli, tonalité contrôlée — la réécriture perd la fidélité). Rendez chaque entrée events avec ses start_time, end_time, type, et description complète littéralement (tableau quand le client en rend un proprement, sinon une liste par événement). Vous POUVEZ ajouter un en-tête d'une ligne et une offre de réexécution avec des paramètres différents.

Sortie VLM : rendez choices[0].message.content littéralement. Si le modèle a produit des blocs <think>…</think><answer>…</answer>, supprimez le bloc <think> et affichez la réponse.

Avertissement de secours (quand applicable) va au-dessus du résumé, jamais mélangé dedans.

Conseils

• Routez par disponibilité du service, pas par durée. Sondez /v1/ready une fois lors du Setup ; HTTP 200 → LVS+HITL pour chaque clip ; autre chose → secours VLM.
• HITL est obligatoire sur le chemin LVS. L'opt-in defaults est le seul contournement sanctionné. Le chemin de secours VLM est silencieux (pas de HITL).
• Disponibilité = HTTP 200 sur /v1/ready. Rien d'autre. Le corps peut être vide. Utilisez toujours curl -s -o /dev/null -w '%{http_code}' — ne canalisez jamais via jq/grep/head.
• Déléguez VIOS à vss-manage-video-io-storage — c'est une sous-tâche ; la réponse finale est le résumé de l'étape 2, pas l'URL du clip.
• jq deux fois pour la sortie LVS. D'abord déverrouille l'enveloppe OpenAI, ensuite analyse la chaîne JSON à l'intérieur de content.
• Préférez /v1/summarize pour 3.2 GA ; /summarize est un alias de compatibilité.
• Utilisez l'id exact du modèle VLM annoncé par l'endpoint (valeur par défaut nim_nvidia_cosmos-reason2-8b_hf-1208).
• Rendez la sortie littéralement — pas de paraphrase, pas de reformatage, pas de réécriture de video_summary ou choices[0].message.content.
• Un appel, un rendu. Pas de couverture parallèle, pas de doubles rendus.

Référence croisée

• vss-deploy-profile — démarrez le profil base (VLM uniquement) ou lvs (VLM + service de synthèse vidéo)
• vss-manage-video-io-storage (API VIOS) — téléchargez des vidéos, listez les flux, obtenez les URLs de clips
• vss-search-archive — recherche sémantique dans l'archive (profil différent)
• vss-query-analytics — interrogez les incidents/événements d'Elasticsearch
• Référence API de synthèse vidéo — references/video-summarization-api.md
• Référence d'exploitation du service de synthèse vidéo — references/video-summarization-deployment.md

bump:2