VSS Summarize Video

Instructions

• Exécutez les cinq étapes du workflow ci-dessous dans l'ordre.
• Exécutez vous-même les commandes API ; ne demandez pas à l'utilisateur de les exécuter.
• Utilisez les références requises à leurs points de décision nommés.

Examples

Les scénarios exécutables se trouvent sous evals/. Les implémentations des commandes sont dans references/end-to-end-example.md.

When to Use

Utilisez cette compétence pour résumer une vidéo enregistrée via LVS avec contrôle HITL, afin de produire un résumé narratif poli avec des événements horodatés quand LVS est disponible.

N'utilisez pas cette compétence pour :

• Sous-titrage RTSP en direct : utilisez vss-deploy-dense-captioning.
• Rapports d'incident ou de fenêtre d'alerte : utilisez vss-generate-video-report Mode B.
• Recherche d'archive : utilisez vss-search-archive.

Required References

Chargez ces fichiers uniquement comme indiqué :

• references/end-to-end-example.md : chargez avant d'exécuter le workflow de vidéo enregistrée. Il contient les commandes exactes pour la préparation de la disponibilité, la préparation VIOS, le résumé en une seule exécution et le fallback VLM.
• references/cli_usage.md : chargez avant l'étape 4. vss summarize run émet la demande de résumé et applique la politique de mémoire configurée de l'opérateur ; cette référence contient ses drapeaux, codes de sortie, forme de sortie et verbes de lecture.
• references/video-summarization-api.md : chargez avant de construire une opération LVS en direct manuellement — une question API directe, ou le fallback VLM approuvé. Suivez sa procédure Runtime OpenAPI Discovery sur Docker. Sur Kubernetes, suivez la note K8s là — le LVS Ingress stock ne publie pas LVS /openapi.json. Le workflow ordonné ne construit pas de payload de résumé ; le CLI en est propriétaire.
• references/hitl-prompts.md : chargez lors de la collecte du scénario LVS, des événements et des objets d'intérêt optionnels.
• references/video-summarization-debugging.md : chargez uniquement lors du diagnostic d'une réponse échouée ou vide.
• references/video-summarization-deployment.md : chargez uniquement pour le déploiement, la configuration, les journaux ou les opérations de service.
• references/video-summarization-environment-variables.md et assets/video-summarization.env.example : utilisez lors de la configuration de l'environnement du service.
• ../vss-build-vision-ai/references/deployment_resolution.md : contrat Kubernetes VSS_PUBLIC_URL et le montage /lvs.
• references/deploy-lvs-service.md : chargez quand on vous demande des informations sur l'image de conteneur propre à LVS, le dimensionnement GPU/CPU/stockage, ou le contrat de déploiement en tant que service pair (plus complet que video-summarization-deployment.md, qui couvre l'exploitation d'un déploiement déjà en cours d'exécution).
• references/integrate-lvs-service.md : chargez quand un autre agent ou compétence doit s'intégrer à LVS en tant que service pair — les services pairs requis, les interfaces d'intégration, le schéma API et les exigences réseau.

Core Invariants

• Acheminez selon la disponibilité de LVS, jamais selon la durée de la vidéo.
• HTTP 200 depuis /v1/ready sélectionne LVS. Les corps de réponse vides ne signifient pas indisponible.
• Une fois LVS sélectionné, n'appelez pas un endpoint VLM /v1/chat/completions.
• Émettez exactement un vss summarize run par demande de résumé de l'utilisateur. Une exécution est un POST /v1/summarize. Ne réessayez jamais, ne couvrez jamais, n'élargissez pas les événements et ne lancez jamais un second backend automatiquement.
• Les endpoints proviennent du déploiement vss configure enregistré. Ne transmettez jamais un drapeau endpoint, index ou modèle que l'appelant n'a pas nommé, et ne remplacez jamais une exécution échouée par un curl manuel contre /v1/summarize.
• Enregistrez la commande complète et son stdout. Diagnostiquez les échecs à partir de ces fichiers, du code de sortie de l'exécution elle-même, des journaux du service et des demandes GET non mutantes.
• Rendez video_summary et chaque événement retourné textuellement. Ne paraphrasez pas, ne tronquez pas les descriptions, n'ajoutez pas de champs et ne fabriquez pas id.
• Le fallback VLM direct nécessite une approbation utilisateur explicite à moins que la demande originale ne l'ait préautorisée.

Prerequisites

• Profile VSS lvs accessible soit sur Docker ($HOST_IP:38111), soit via l'Ingress public à ${VSS_PUBLIC_URL}/lvs.
• curl et jq sur l'hôte de l'agent.
• Accessibilité réseau du service LVS à l'URL finale du clip VIOS (Docker : depuis vss-lvs ; Kubernetes : le déploiement doit générer une URL que le pod LVS peut récupérer).
• Un checkout contenant services/agent et l'hôte uv, pour vss summarize run.
• Une origine de déploiement enregistrée. Configurez-la une fois, avant l'étape 4 :

VSS_REPO_ROOT="${VSS_REPO_ROOT:-$HOME/video-search-and-summarization}"
test -f "${VSS_REPO_ROOT}/services/agent/pyproject.toml" || {
  echo "VSS checkout not found at ${VSS_REPO_ROOT}; set VSS_REPO_ROOT explicitly" >&2
  exit 1
}
VSS=(uv run --project "${VSS_REPO_ROOT}/services/agent" --no-dev --extra cli vss)
cd "${VSS_REPO_ROOT}" && "${VSS[@]}" summarize run --help >/dev/null || exit 1
# Compose publishes the ingress on :7777; Kubernetes uses VSS_PUBLIC_URL.
VSS_ORIGIN="${VSS_PUBLIC_URL:-http://${HOST_IP:-localhost}:7777}"
"${VSS[@]}" configure --base-url "${VSS_ORIGIN%/}" || exit 1

--extra cli est obligatoire : la distribution de base contient les bibliothèques essentielles, tandis que nvidia-vss-cli déclare l'exécutable vss. Configurez contre l'origine ingress, jamais :38111 — ce port de conteneur LVS n'expose aucun Elasticsearch, donc un déploiement enregistré à partir de celui-ci ne peut pas persister.

La compétence vss-deploy-profile peut déployer le profile. Un VLM fallback distant doit pouvoir récupérer l'URL du clip ; il ne peut généralement pas récupérer localhost ou des adresses privées.

Limitations

• Le fallback VLM direct ne peut pas cibler les scénarios ou événements LVS et est de qualité inférieure.
• Les URL VIOS privées peuvent être inaccessibles depuis les endpoints VLM distants.
• Chaque demande utilisateur permet un seul vss summarize run, sans réessai automatique.
• La persistance nécessite un Elasticsearch routé. Un déploiement sans celui-ci résume et rapporte le résultat non persisté plutôt que d'échouer le travail.
• Les deux extrémités sont configurées pour attendre une heure, correspondant au défaut du CLI lui-même, donc une longue résumé n'est pas coupée court par un 504 qui serait enregistré comme un travail échoué. Un Ingress que le déploiement substitue plus court plafonne toujours l'attente.
• Le LVS Helm Ingress stock ne publie pas LVS /models, LVS /openapi.json, /recommended_config ou /metrics — ceux-ci restent Docker :38111 uniquement.

Endpoint resolution (Kubernetes vs Docker)

Résolvez les endpoints une fois avant de sonder. Suivez ../vss-build-vision-ai/references/deployment_resolution.md.

# Prefer VSS_PUBLIC_URL; accept legacy VSS_ENDPOINT as the same public origin.
if [ -z "${VSS_PUBLIC_URL:-}" ] && [ -n "${VSS_ENDPOINT:-}" ]; then
  VSS_PUBLIC_URL="${VSS_ENDPOINT}"
fi

if [ -n "${VSS_PUBLIC_URL:-}" ]; then
  DEPLOYMENT_KIND="kubernetes"
  VSS_PUBLIC_URL="${VSS_PUBLIC_URL%/}"
  # Force public origin — ignore leftover Docker LVS_BACKEND_URL / VLM_* env.
  # The /lvs mount, not the origin — skill appends /v1/ready and /v1/summarize,
  # and the gateway strips /lvs before the backend sees them.
  LVS_BACKEND_URL="${VSS_PUBLIC_URL}/lvs"
  VIDEO_SUMMARIZATION_URL="${LVS_BACKEND_URL}"
  VSS_VIOS_URL="${VSS_PUBLIC_URL}/vst"
  VST_API_BASE="${VSS_VIOS_URL}/api/v1"
  # RT-VLM is at its own mount; /v1/models and /v1/chat/completions hang off it.
  VLM="${VSS_PUBLIC_URL}/rtvi-vlm"
else
  DEPLOYMENT_KIND="docker"
  LVS_BACKEND_URL="${LVS_BACKEND_URL:-http://${HOST_IP:-localhost}:38111}"
  VIDEO_SUMMARIZATION_URL="${LVS_BACKEND_URL}"
  VSS_VIOS_URL="http://${HOST_IP:-localhost}:30888/vst"
  VST_API_BASE="${VSS_VIOS_URL}/api/v1"
  VLM="${VLM_BASE_URL:-${RTVI_VLM_BASE_URL:-http://${HOST_IP:-localhost}:8018}}"
  VLM="${VLM%/v1}"
fi

Sur Kubernetes, n'utilisez pas kubectl port-forward, le DNS du Service, les NodePorts, docker exec ou docker inspect. N'ajoutez pas /v1 à LVS_BACKEND_URL. Ignorez LVS_BACKEND_URL / VLM_BASE_URL / RTVI_VLM_BASE_URL dérivé de Docker quand VSS_PUBLIC_URL est défini. Ne traitez pas /openapi.json public comme le schéma LVS (ce chemin est Agent sur l'Ingress stock).

Routing

Supprimez un /v1 de fin de la base VLM parce que cette compétence l'ajoute. Ne scannez pas les ports et n'inspectez pas les fichiers de configuration pour deviner les endpoints.

Sondez LVS /v1/ready en utilisant la boucle dans la référence de bout en bout. La disponibilité est le statut HTTP uniquement : réessayez les réponses de réchauffage 503 pendant environ 30 secondes et n'inspectez pas le corps.

Si LVS est indisponible, demandez :

Le profile lvs de VSS n'est pas accessible (${VSS_PUBLIC_URL:-$HOST_IP:38111}). Dois-je le déployer maintenant en utilisant /vss-deploy-profile -p lvs ? Répondez no pour arrêter ici ; je peux utiliser le fallback VLM de qualité inférieure uniquement si vous le demandez explicitement.

• Déploiement approuvé ou préautorisé : invoquez vss-deploy-profile, sondez à nouveau et continuez uniquement après que LVS retourne 200.
• Déploiement refusé : demandez séparément s'il faut utiliser le fallback VLM. Arrêtez à moins que l'utilisateur ne l'approuve.
• Fallback préautorisé : utilisez le fallback sans une autre invite.
• Exécution non interactive : la tâche originale est la seule source d'approbation. Si elle ne préautorise ni le déploiement ni le fallback, rapportez le blocage et arrêtez.

Recorded Video Workflow

Stage 1: Select the Backend

Chargez les références de bout en bout et du CLI. Exécutez la sonde de disponibilité LVS avant de préparer le clip. Sondez également VLM /v1/models de sorte qu'un fallback approuvé puisse être validé, mais ne déduisez pas par rapport à celui-ci pendant que LVS est prêt.

Le modèle de résumé n'a pas besoin de découverte : vss configure a enregistré l'id que LVS rapporte en cours d'exécution, et vss summarize run le défaut sur Docker et Kubernetes. Passez --model uniquement quand l'appelant en a nommé un, et lisez la valeur enregistrée depuis vss configure show quand elle doit être rapportée.

Découvrez un id de modèle manuellement uniquement pour un fallback VLM approuvé, qui ne s'exécute pas via le CLI :

• Docker : honorez ${VLM_NAME} uniquement s'il correspond à un id du LVS GET /models ; sinon utilisez l'id unique affiché LVS.
• Kubernetes : préférez ${VLM_NAME} quand défini ; sinon prenez l'id unique depuis GET ${LVS_BACKEND_URL}/models (LVS) ou GET ${VLM}/v1/models (RT-VLM). Si plusieurs ids existent et aucune préférence valide n'en sélectionne un, rapportez-les et arrêtez.

Un résultat de disponibilité LVS non-200 après réchauffage est le seul signal d'indisponibilité. Un résumé vide, des événements vides, des champs optionnels manquants ou stdout de disponibilité vide ne doivent pas déclencher le fallback.

Stage 2: Prepare the Video Through VIOS

Exécutez les opérations API VIOS directement comme faisant partie de ce workflow ; n'invoquez pas de compétence séparée. Suivez Prepare the video through VIOS dans la référence de bout en bout (utilise ${VST_API_BASE}).

1. Listez les capteurs et réutilisez l'enregistrement exact demandé quand présent.
2. S'il est absent et le fichier local exact est disponible, téléchargez-le via l'API fichier VIOS. Pour les médias téléchargés ou exemple sans horodatage demandé, utilisez 2025-01-01T00:00:00.000Z de sorte que la résolution de la chronologie soit déterministe.
3. Sondez les chronologies du flux retourné et obtenez l'heure de début minimale complète et l'heure de fin maximale.
4. Générez une URL MP4 temporaire fraîche pour cet intervalle complet avec l'audio désactivé. Passez cette URL générée à --url tel que retourné (après suppression d'un schéma http:// doublé si présent). Ne la réécrivez pas pour les chemins Ingress navigateur avant l'exécution du résumé.
5. Si LVS a été sélectionné, vérifiez l'accessibilité d'un octet :
   • Docker : docker exec vss-lvs sonde Python range dans la référence.
   • Kubernetes : GET Range borné de l'URL générée depuis l'hôte de l'agent (pas docker exec / kubectl exec). Le déploiement doit générer une URL que le pod LVS peut récupérer.

Exigez l'enregistrement exact, la chronologie complète et l'URL du clip fraîche avant de continuer. Quand le fichier source est disponible, comparez la durée de la chronologie VIOS avec la durée source. Une réponse de téléchargement ou une sonde d'octet prouve l'accessibilité, pas la préparation complète du média.

Si la préparation échoue, arrêtez et rapportez la condition préalable manquante. Ne choisissez pas une vidéo /tmp arbitraire, un enregistrement alternatif, un serveur HTTP local, NvStreamer ou une source RTSP à moins que l'utilisateur ne l'ait explicitement demandé.

N'utilisez pas le shim curl léger du conteneur vss-lvs pour l'accessibilité ; il peut écrire la vidéo entière dans la sortie de l'outil. Utilisez la sonde Python d'un octet sur Docker.

Stage 3: Collect LVS Settings

Quand LVS est sélectionné, chargez la référence HITL et collectez scenario, events et objects_of_interest optionnels avant l'exécution du résumé.

Quand l'appelant dit explicitement de s'exécuter de manière autonome sans invitation et demande des défauts ou ne fournit aucun paramètre, utilisez ces valeurs textuellement :

scenario="activity monitoring"
events=["notable activity"]

C'est le seul contournement HITL. Ne déduisez pas de défauts à partir de noms de fichiers ou de noms de capteurs. Mentionnez les défauts dans la réponse finale et proposez une ré-exécution séparée avec des paramètres spécifiques.

Stage 4: Submit Once Through the CLI

Chargez la référence du CLI. vss summarize run émet la demande de résumé sur Docker et Kubernetes, et persiste uniquement quand la politique de mémoire statique l'active. Ne construisez pas un payload /v1/summarize manuellement et ne récupérez pas /openapi.json pour en construire un — le CLI est propriétaire de la forme de la demande, vss configure est propriétaire de l'endpoint et vss configure memory est propriétaire de la persistance.

Utilisez l'invocation dans la référence de bout en bout. Elle passe l'URL VIOS fraîche de l'étape 2, les valeurs HITL exactes de l'étape 3, --chunk-duration 10 et --seed 1 ; répétez --event par événement et ajoutez --object-of-interest uniquement quand l'appelant a fourni des objets. Ne passez aucun drapeau endpoint.

Ne passez pas --persist ou --memory-index ; ces contrôles par demande n'existent pas. Le workflow standard ne passe pas non plus --no-persist, de sorte que le défaut de persistance configuré de l'opérateur s'applique. Quand la persistance est activée, l'enregistrement a besoin de deux valeurs :

• --video-id, requis aux côtés de --url. Utilisez l'id de capteur VIOS de l'enregistrement — depuis sensor/list ou depuis sensorId qu'un téléchargement retourne — jamais l'id de flux. Il devient le capteur de l'enregistrement, sur lequel list --sensor-id et la fenêtre temporelle clés de rappel. Sans --video-id, l'exécution se termine 2 avant la résumé plutôt qu'après.
• --creation-time, le début absolu du média. LVS rapporte les heures des événements comme des décalages dans le clip à moins que celui-ci ne les ancre, et la mémoire unifiée stocke les instants — donc sans celui-ci les événements ne peuvent pas être écrits et l'exécution se dégrade à la sortie 6. Pour les médias exemple téléchargés, utilisez le même 2025-01-01T00:00:00.000Z que l'étape 2 a téléchargé avec.

Ne passez pas --num-frames-per-chunk dans le workflow standard. RT-VLM est propriétaire de l'échantillonnage des images ; les champs non définis sont absents de la demande, de sorte que le défaut propre du déploiement s'applique.

La dernière ligne de stdout est un objet JSON nommant le travail. Lisez cette ligne et le code de sortie ; la prose sur stderr est un diagnostic, pas le résultat. Un appel refusé avant l'existence d'un travail n'imprime aucun marqueur du tout et stderr est le résultat entier — vérifiez que stdout n'est pas vide avant de l'analyser. Le vide, pas le code de sortie, est ce qui dit si un travail a été créé.

Les sorties 6 et 7 signifient toutes deux que la résumé s'est déjà produite. Ne répétez jamais l'exécution pour obtenir une vue différente, et ne la répétez jamais pour le diagnostic — une deuxième exécution nécessite une demande utilisateur séparée. La sortie 2 qui porte un marqueur est la même histoire plus tôt : la demande a atteint LVS et est revenue refusée, donc la seule soumission que cette demande avait a été dépensée et un appel corrigé appartient à une nouvelle demande. Une fois qu'un travail existe, chaque résultat nomme son job_id ; utilisez-le plutôt que de réexécuter. Un appel refusé avant l'existence d'un travail ne nomme rien, ce qui est pourquoi le stdout vide est le test.

Le booléen persisted du marqueur d'achèvement est le résultat Elasticsearch autoritaire. Le corps du résultat inclut persist uniquement quand la persistance a été tentée et rapporte son index et nombre d'événements ; le statut Markdown optionnel est séparé sous memory_note. record dit ce que job_id vaut pour une lecture ultérieure : closed, absent quand la politique a ignoré la persistance, ou stale quand un enregistrement soumis n'a pas pu être fermé. Ne lisez pas le disque en arrière pour confirmer, et ne lisez jamais Elasticsearch directement — la mémorisation de la mémoire est le travail d'une compétence séparée. La seule lecture qui appartient ici est de réconcilier une sortie 7, dont le résultat est véritablement inconnu jusqu'à ce que vss summarize get --job-id <job_id> réponde.

Si video_summary et events sont vides, inspectez summary.usage.total_chunks_processed du même payload. Un entier positif confirme le traitement ; zéro ou manquant signifie que le traitement n'a pas été confirmé. Ne prétendez pas « aucune détection ».

VLM Fallback for Stages 3-4

Utilisez la commande fallback dans la référence de bout en bout uniquement quand LVS est resté indisponible après le réchauffage et que l'utilisateur a explicitement approuvé le fallback. N'exécutez pas HITL LVS et n'utilisez jamais le fallback pour réparer ou remplacer une réponse LVS.

Avant le résultat, incluez :

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

Si le VLM ne peut pas récupérer l'URL VIOS, rapportez ce bloqueur au lieu d'envoyer une demande d'inférence.

Stage 5: Present the Result

Commencez par exactement un en-tête :

Summary of <video_name> (<duration>)

Utilisez Ns en dessous de 60 secondes et Mm Ss sinon.

Pour LVS, le CLI imbrique l'enveloppe propre du service sous summary : analysez la chaîne JSON dans summary.choices[0].message.content en préservant summary.usage. Rendez video_summary textuellement, suivi de chaque événement dans l'ordre du service. Préservez chaque champ retourné et la description complète ; utilisez une liste par événement si un tableau tronquerait le texte.

Fermez avec l'identité du travail : le job_id, la valeur persisted du marqueur d'achèvement et tout résultat memory_note séparé. Un objet persist absent avec persisted=false signifie que la politique statique a choisi l'exécution stdout uniquement, pas un échec.

Pour VLM, rendez choices[0].message.content textuellement. Pour la sortie Cosmos, omettez le bloc <think>...</think> et montrez la réponse. N'ajoutez pas d'emoji et ne reformulez pas le contenu de l'un ou l'autre backend.

Troubleshooting

Utilisez la référence de débogage pour des diagnostics plus approfondis et la référence de déploiement pour les journaux ou la configuration. L'image LVS est un manifest multi-arch, donc LVS_TAG=3.3.0-rc2 est le défaut x86/Jetson Thor ; utilisez 3.3.0-rc2-sbsa sur SBSA/DGX Spark/Grace. RT-VLM a également besoin d'une balise correspondant à l'hôte (3.3.0-26.08.2 sur x86/Jetson Thor, 3.3.0-26.08.2-sbsa sur SBSA/DGX Spark/Grace).

Direct API and Service Operations

Pour les questions API directes telles que les modèles, la disponibilité, la configuration recommandée, les métriques, les schémas ou les réponses 422, utilisez la référence API au lieu du workflow de vidéo enregistrée. /lvs est un montage Prefix, donc tout ce que LVS sert est public en dessous sur Kubernetes — /lvs/v1/ready, /lvs/v1/summarize, /lvs/models, /lvs/metrics — où le précédent Ingress de chemin exact n'a publié que la disponibilité et la résumé. Pour le déploiement, le redémarrage, la suppression, la sélection du backend ou les journaux de service, préférez vss-deploy-profile et utilisez la référence de déploiement.

Cross-reference

• vss-deploy-profile : déploie le profile lvs.
• vss-manage-video-io-storage : administration générale VIOS en dehors de ce workflow ordonné.
• vss-search-archive : recherche une vidéo archivée.
• vss-query-analytics : interroge les incidents et événements stockés.
• vss-generate-video-report : Mode A délègue ici quand LVS /v1/ready est 200.

bump:3