benchmark-video-summarization

Instructions

Suivez le tableau de routage et le flux de travail étape par étape ci-dessous. Exécutez chaque étape dans l'ordre lors d'une première exécution. Pour les exécutions répétées, allez directement à la section Repeat Runs. Le matériel de référence détaillé se trouve dans references/ et les scripts de benchmark dans scripts/.

⚠️ Systèmes GPU partagés : Sur un hôte multi-utilisateur, plusieurs instances LVS peuvent s'exécuter sur des ports différents. Benchmarkez toujours contre l'instance QUE VOUS avez déployée. Ne supposez jamais le port 38111 — utilisez toujours l'URL d'endpoint exacte retournée par vss-deploy-profile lors de votre déploiement de LVS. Si vous n'avez pas déployé d'instance LVS dans cette session, déployez-en d'abord une avant d'exécuter les benchmarks.

Purpose

Mesurer les limites de latence et de débit d'une instance LVS (Long Video Summarization) déployée, identifier les goulets d'étranglement GPU et pipeline, et suggérer des modifications de configuration qui améliorent les performances. Produit des rapports XLSX et des fichiers de résultats JSON par scénario, plus une analyse en langage naturel avec des recommandations d'amélioration.

N'utilisez PAS cette skill pour :

• Déployer LVS — utilisez la skill vss-deploy-profile avec le profil lvs.
• La surveillance ou l'alerte en production — c'est un outil de benchmarking hors ligne.
• Les profils VSS non-LVS (RTVI, search-only, etc.) — l'API /files et l'endpoint /summarize sont spécifiques à LVS.

Routing

Prerequisites

Deploy LVS for Benchmarking

Avant de benchmarker, déployez une instance LVS fraîche avec vss-deploy-profile. Sur les systèmes partagés, utilisez toujours un COMPOSE_PROJECT_NAME unique afin que vos conteneurs et volumes soient isolés des autres utilisateurs.

# Choisissez un nom de projet unique (ex. votre nom d'utilisateur)
export COMPOSE_PROJECT_NAME="lvs-bench-$(whoami)"

cd <repo>/deploy/docker

# REQUIS POUR BENCHMARKING : le benchmark télécharge les vidéos via la route LVS dev /files,
# qui est gâtée par VIA_DEV_API (false par défaut ; POST /files retourne 404 quand
# c'est désactivé). Le conteneur lvs-server charge son environnement depuis
# services/video-summarization/.env (le compose `env_file:`), donc VIA_DEV_API doit
# être défini LA — le mettre dans tout autre fichier env n'atteindra PAS le conteneur.
# Définissez-le avant de déployer :
grep -q '^VIA_DEV_API=' services/video-summarization/.env \
  && sed -i 's/^VIA_DEV_API=.*/VIA_DEV_API=true/' services/video-summarization/.env \
  || echo 'VIA_DEV_API=true' >> services/video-summarization/.env

# Déployez LVS sur vos GPUs désignées
./scripts/dev-profile.sh up \
  --profile lvs \
  --hardware-profile RTXPRO6000BW \
  --llm-device-id <LLM_GPU> \
  --vlm-device-id <VLM_GPU>

# Si LVS était déjà en cours d'exécution, réexécutez la commande de déploiement
# ci-dessus pour que compose recréé le conteneur avec le nouvel env (un simple
# `docker restart` ne relit PAS les modifications env_file).

Notez l'endpoint LVS (http://<HOST_IP>:38111) et le nom du conteneur : le fichier compose le définit statiquement à vss-lvs (vérifiez avec docker ps --filter name=lvs). Définissez-les avant de continuer :

export LVS_BACKEND=http://localhost:38111
export LVS_CONTAINER_NAME=vss-lvs
export VLM_GPUS=<VLM_GPU>
export LLM_GPUS=<LLM_GPU>

Téléchargements de modèles : Le premier déploiement télécharge les poids de modèle LLM (~20 GB) et VLM (~17 GB). Cela prend 20–40 minutes selon la vitesse du réseau. Les déploiements ultérieurs réutilisent les volumes créés sous votre COMPOSE_PROJECT_NAME et démarrent en quelques minutes.

Step 0: Pre-flight Check

Sur les systèmes partagés, un autre locataire peut tenir le port 38111 — donc le benchmark doit vérifier qu'il frappe VOTRE instance et VOS GPUs, pas ceux de quelqu'un d'autre. preflight.sh le fait (et échoue rapidement si ce n'est pas le cas).

Définissez les valeurs de votre déploiement, puis exécutez la vérification préalable :

export LVS_BACKEND=http://localhost:38111                          # VOTRE endpoint LVS /summarize
export LVS_CONTAINER_NAME=vss-lvs                                   # VOTRE conteneur LVS (voir l'étape deploy)
export VLM_GPUS=<VLM_GPU>                                           # GPU(s) que votre VLM utilise
export LLM_GPUS=<LLM_GPU>                                           # GPU(s) que votre LLM utilise

./scripts/preflight.sh

preflight.sh s'arrête avec un code non-zéro sauf si TOUS les éléments suivants sont vrais :

• la config se parse et vlm_gpus/llm_gpus sont des IDs GPU valides dans la plage GPU de l'hôte ;
• LVS_BACKEND est atteignable (/v1/ready → 200) et la route dev /files est activée (pas 404) ;
• votre LVS_CONTAINER_NAME possède réellement le port backend — son serveur s'est lié avec succès (pas de address already in use dans ses logs) et aucun autre conteneur ne publie ce port ;
• les VLM_GPUS/LLM_GPUS configurés sont réservés par vos conteneurs VLM/LLM de LVS — pour ne pas silencieusement benchmarker des GPUs inactives ou l'instance d'un autre locataire (l'exacte défaillance que ceci garde contre).

run_benchmark.sh exécute preflight.sh automatiquement avant chaque exécution ; vous pouvez aussi l'exécuter en standalone (ci-dessus) à tout moment.

Si /files retourne 404, la route dev est éteinte — activez VIA_DEV_API=true sur votre LVS (voir l'étape deploy) avant de continuer.

Step 1: Download Test Videos

Le benchmark utilise des vidéos de surveillance d'entrepôt du dataset d'exemple VSS, hébergé dans NGC. scripts/fetch-videos.sh télécharge le package et place un ensemble choisi — warehouse_4min.mp4, warehouse_5min.mp4, warehouse_10min.mp4 — dans <VSS_BENCHMARK_DATA_DIR>/videos/, les noms de fichiers exacts que le scripts/config.yaml par défaut référence. Cela nécessite la CLI ngc et une clé API NGC, et imprime les instructions d'installation/auth si l'une ou l'autre est absente.

export VSS_BENCHMARK_DATA_DIR=${VSS_BENCHMARK_DATA_DIR:-$HOME/vss-benchmark-data}

# Idempotent ; ajoutez FORCE=1 pour re-télécharger, ou passez une version de package (default 3.2.0)
./scripts/fetch-videos.sh

# Sondigez les durées des vidéos pour vérifier ce qui a été téléchargé
find "${VSS_BENCHMARK_DATA_DIR}/videos" -name "*.mp4" | while read f; do
  dur=$(ffprobe -v quiet -show_entries format=duration -of csv=p=0 "$f" 2>/dev/null | cut -d. -f1)
  echo "$(basename $f): ${dur}s"
done

Step 2: Generate Test Clips (if needed)

Normalement l'étape 1 fournit des clips réels de 5 et 10 minutes et cette étape peut être ignorée. Utilisez-la seulement si un clip choisi est manquant (ex. le layout du package NGC a changé) ou vous avez besoin de durées personnalisées : boucllez une vidéo source disponible dans les noms de fichiers que le scripts/config.yaml par défaut référence — warehouse_5min.mp4 (300s) et warehouse_10min.mp4 (600s).

# Trouvez une vidéo source à boucler depuis
SOURCE=$(find "${VSS_BENCHMARK_DATA_DIR}" -name "*.mp4" | head -1)
echo "Using source: ${SOURCE}"

# Créez un sous-répertoire videos/ où le serveur media attend les fichiers
mkdir -p "${VSS_BENCHMARK_DATA_DIR}/videos"

for spec in warehouse_5min:300 warehouse_10min:600; do
  NAME="${spec%%:*}"; DURATION="${spec##*:}"
  OUT="${VSS_BENCHMARK_DATA_DIR}/videos/${NAME}.mp4"
  [ -f "$OUT" ] && echo "Already exists: ${OUT}" && continue
  ffmpeg -stream_loop -1 -i "${SOURCE}" -t ${DURATION} -c copy "${OUT}" -y -loglevel error
  echo "Created: ${OUT}"
done

# Vérifiez les clips
find "${VSS_BENCHMARK_DATA_DIR}/videos" -name "*.mp4" | while read f; do
  dur=$(ffprobe -v quiet -show_entries format=duration -of csv=p=0 "$f" 2>/dev/null | cut -d. -f1)
  echo "$(basename $f): ${dur}s"
done

Step 3: Start Media Server

Le serveur media sert les vidéos de test sur HTTP afin que l'endpoint LVS /files puisse les télécharger par URL.

SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

# Démarrez le serveur media (nginx:alpine)
cd "${SKILL_DIR}"
docker compose -f scripts/media-server.yaml up -d
sleep 2

# Vérifiez la santé
curl -sf "http://localhost:8888/health" && echo "Media server ready" || echo "Media server not ready"

# Listez les vidéos disponibles (listing de répertoire JSON)
curl -s "http://localhost:8888/videos/" | python3 -m json.tool 2>/dev/null || \
  find "${VSS_BENCHMARK_DATA_DIR}/videos" -name "*.mp4" -exec basename {} \; | sed 's|^|http://localhost:8888/videos/|'

Notez les noms de fichiers retournés — vous en aurez besoin dans l'étape suivante pour mettre à jour config.yaml.

Step 4: Configure

Modifiez scripts/config.yaml avec les noms de fichiers vidéo réels découverts à l'étape 3 :

1. Mettez à jour les URLs vidéo — Dans les sections single_file_test et file_burst_test, remplacez HOST_IP par l'IP LAN de votre hôte (hostname -I | awk '{print $1}' — PAS localhost ; LVS télécharge les vidéos depuis l'intérieur de son conteneur) et assurez-vous que les noms de fichiers correspondent à ceux servis par le serveur media (ex., http://<HOST_IP>:8888/videos/warehouse_5min.mp4).

2. Définissez les assignations GPU — Mettez à jour vlm_gpus et llm_gpus pour correspondre à votre déploiement LVS. Vérifiez VOTRE conteneur :

   docker inspect "${LVS_CONTAINER_NAME}" \
   --format '{{range .Config.Env}}{{println .}}{{end}}' | grep -E "VLM_GPUS|LLM_GPUS|CUDA_VISIBLE"

3. Ajustez les tailles de chunk — Le chunk_sizes: [10, 30] par défaut teste à la fois le chunking de 10 et 30 secondes. Les chunks plus grands réduisent la surcharge d'appel API mais augmentent la latence par chunk.

4. Ajustez les niveaux de concurrence — Le concurrency_levels: [1, 2, 4, 8] par défaut pour file_burst. Supprimez les niveaux qui dépassent la capacité mémoire de votre matériel.

Step 5: Run Benchmark

SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
cd "${SKILL_DIR}/scripts"

# Créez un environnement virtuel Python s'il n'existe pas
[ ! -d "vss-bench-env" ] && python3 -m venv vss-bench-env

# Activez venv et installez les requirements
source vss-bench-env/bin/activate
pip install -r requirements.txt -q

# LVS_BACKEND doit déjà être défini à l'endpoint de VOTRE déploiement
if [ -z "${LVS_BACKEND}" ]; then
  echo "ERROR: LVS_BACKEND is not set. Set it to your own LVS endpoint before running."
  exit 1
fi
export VIA_BACKEND="${LVS_BACKEND}"
export VIA_VLM_GPUS="${VLM_GPUS:?ERROR: VLM_GPUS must be set (e.g. export VLM_GPUS=6)}"
export VIA_LLM_GPUS="${LLM_GPUS:?ERROR: LLM_GPUS must be set (e.g. export LLM_GPUS=7)}"

# Exécutez le scénario single_file
python vss_perf_benchmark.py --config config.yaml --scenario single_file_test

# Exécutez le scénario file_burst (peut être exécuté séparément ou ensemble)
python vss_perf_benchmark.py --config config.yaml --scenario file_burst_test

Le benchmark crée un répertoire de sortie (default : vss-perf-report/) avec des sous-répertoires par scénario. Chaque exécution de scénario génère un rapport XLSX et execution_summary.json.

Note : Le répertoire de sortie ne doit pas exister ou doit être vide avant chaque exécution. Déplacez ou renommez les résultats précédents avant de re-exécuter :

mv vss-perf-report vss-perf-report-$(date +%Y%m%d-%H%M%S)

Step 6: Analyze Results

SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
OUTPUT_DIR="${SKILL_DIR}/vss-perf-report"

# Affichage le résumé d'exécution de haut niveau pour single_file
echo "=== single_file_test execution summary ==="
cat "${OUTPUT_DIR}/single_file_test/execution_summary.json" | python3 -m json.tool

# Affichez les résumés par cas de test
find "${OUTPUT_DIR}" -name "test_case_summary.json" | while read f; do
  echo ""
  echo "=== $(dirname $f | xargs basename) ==="
  cat "$f" | python3 -m json.tool
done

# Listez les rapports XLSX générés
find "${OUTPUT_DIR}" -name "*.xlsx" | while read f; do
  echo "Report: $f"
done

Lisez les fichiers de résultats JSON et extrayez les métriques clés suivantes pour l'analyse :

• E2E latency (e2e_latency en secondes) : temps total de la demande à la réponse
• VLM pipeline latency (vlm_pipeline_latency) : temps passé dans le pipeline du modèle vision
• VLM pipeline % : vlm_pipeline_latency / e2e_latency * 100
• CA-RAG latency (ca_rag_latency) : temps d'inférence CA-RAG
• VLM GPU utilization mean (vlm_gpu_usage_mean) : utilisation de calcul GPU % pour VLM
• LLM GPU utilization mean (llm_gpu_usage_mean) : utilisation de calcul GPU % pour LLM
• GPU memory mean (vlm_gpu_memory_mean, llm_gpu_memory_mean) : pression mémoire %
• File burst throughput (throughput_files_per_second) : fichiers concurrents traités par seconde
• Optimal concurrency (optimal_target_concurrency.estimated_concurrency) : le niveau de concurrence qui satisfait target_latency_seconds

Step 7: Suggest Improvements

Après avoir analysé les résultats, présentez un tableau de résultats et des recommandations en fonction des règles suivantes :

Repeat Runs

Une fois le setup complet (Steps 1–4), utilisez run_benchmark.sh pour les exécutions ultérieures :

SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
cd "${SKILL_DIR}"

# Exécutez le scénario single_file
./scripts/run_benchmark.sh --scenario single_file_test

# Exécutez le scénario file_burst
./scripts/run_benchmark.sh --scenario file_burst_test

# Exécutez avec un répertoire de sortie versionné
./scripts/run_benchmark.sh --scenario single_file_test --output-dir vss-perf-report-v2

# Exécutez tous les scénarios dans config.yaml
./scripts/run_benchmark.sh

# Mode debug (payloads API verbeux)
./scripts/run_benchmark.sh --scenario single_file_test --debug

run_benchmark.sh vérifie la disponibilité de LVS, démarre le serveur media si besoin, crée/réutilise le venv Python, et passe tous les arguments supplémentaires directement à vss_perf_benchmark.py.

Troubleshooting

Cross-reference

• vss-deploy-profile — déployez LVS avec le profil lvs avant le benchmarking
• vss-summarize-video — utilisation opérationnelle de LVS pour la synthèse vidéo (pas le benchmarking)
• Benchmark modes reference — references/benchmark-modes.md
• Analyzing results reference — references/analyzing-results.md

bump:3