VSS Resumir Video

¿Qué hace VSS Resumir Video?

Ejecuta el pipeline de resumen a través del Pipeline Manager. Llama a la API documentada tú mismo e informa solo las respuestas observadas. Los endpoints usan el prefijo nginx /manager. Cuando las herramientas MCP vss_* están conectadas, vss_summarize_video cubre el mismo trabajo; esta habilidad es la ruta REST.

Establece HOST=http://${HOST_IP:-localhost}:${APP_HOST_PORT:-12345}.

Contrato de respuesta cuando VSS no está accesible

El usuario puede estar fuera del despliegue, $HOST puede rechazar conexiones, o una precondición en vivo puede fallar (por ejemplo, el modo de resumen está deshabilitado o el video nombrado no existe). En cualquiera de esos casos no te detengas ni inventes respuestas. Informa el bloqueador observado, luego responde con la secuencia de llamada completa exacta que el usuario puede ejecutar después de solucionarlo: rutas completas de endpoints, cuerpos de solicitud / campos de formulario, el campo que cada paso arrastra de la respuesta anterior, y la condición que indica que un paso está terminado. No abreviar ni omitir el flujo de resumen solicitado simplemente porque no se pudo ejecutar. Indica claramente qué comandos no se ejecutaron. Nunca termines la respuesta preguntando si se deben ejecutar.

Configuración del entorno (ejecutar primero)

Esta habilidad maneja la aplicación Video Search & Summarization a través de sus archivos fuente reales, por lo que la aplicación VSS debe estar presente y debes ejecutar comandos desde su raíz de la aplicación. Haz esto antes de cualquier otra cosa, y funciona tanto si el código fuente de VSS ya está en tu espacio de trabajo.

Ejecuta el bootstrap incluido. Resuelve la raíz de la aplicación en este orden y la imprime como la única línea en stdout:

1. Subir desde el directorio actual buscando una raíz de la aplicación VSS: un directorio que tenga los tres marcadores setup.sh, docker/, y pipeline-manager/.
2. Preguntar a git por el repositorio contenedor (git rev-parse --show-toplevel) y verificar si contiene sample-applications/video-search-and-summarization, o si es en sí mismo una raíz de la aplicación VSS. Esto hace que tu propio clon - o un fork - funcione sin cambios.
3. Reutilizar un checkout que un bootstrap anterior ya haya colocado en ${XDG_CACHE_HOME:-$HOME/.cache}/vss-src/edge-ai-libraries.

Si alguno de estos acierta, ese checkout se reutiliza y NO se realiza ningún clon. Solo cuando los tres fallan se clona - y entonces solo es un checkout superficial (--depth 1), de una sola rama, disperso (sparse) de solo sample-applications/video-search-and-summarization desde main:

# SKILL_DIR es el directorio de ESTA habilidad (se te muestra cuando la habilidad se carga);
# en el repositorio es .github/skills/vss-summarize-video. Funciona igual si la habilidad está instalada de forma independiente.
SKILL_DIR=".github/skills/vss-summarize-video"
APP_ROOT="$(bash "$SKILL_DIR/scripts/vss-bootstrap.sh")"
cd "$APP_ROOT"

Cada comando a continuación asume que el directorio de trabajo es esta APP_ROOT. Para obtener un fork/rama o reutilizar un directorio de checkout específico, anula VSS_REPO_URL, VSS_REPO_BRANCH, o VSS_CLONE_DIR antes de ejecutarlo. El bootstrap se niega a sobrescribir un destino de clon existente que no sea VSS.

Precondiciones

1. Backend saludable y resumen habilitado - probar primero; si no, usa la habilidad vss-troubleshoot o vss-deploy instalada por nombre:

   curl -sf "$HOST/manager/health" >/dev/null && \
   curl -s "$HOST/manager/app/features" | jq -e '(.summary // .) == "FEATURE_ON"'
   

2. Un videoId para resumir - sube uno con POST /manager/videos (multipart, campo video), que devuelve { "videoId": "…" }. O lista los existentes - nota que la respuesta es un objeto { "videos": [...] }, no un arreglo simple, y name es un hash generado (el nombre real del archivo está en url / dataStore.fileName):

   curl -s -X POST "$HOST/manager/videos" -F "video=@/ruta/al/clip.mp4" | jq .
   curl -s "$HOST/manager/videos" | jq '.videos[] | {videoId, file: .dataStore.fileName}'
   

1. Iniciar el pipeline de resumen

POST /manager/summary. El cuerpo tiene campos requeridos; si falta alguno de title, sampling.*, o evam.evamPipeline devuelve 400. Consulta references/summary-request.md para el esquema completo, anulaciones de prompt y opciones de audio.

Solicitud mínima válida:

curl -s -X POST "$HOST/manager/summary" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Revisión del muelle de carga",
    "videoId": "<VIDEO_ID>",
    "sampling": { "chunkDuration": 20, "samplingFrame": 5, "frameOverlap": 0, "multiFrame": 5 },
    "evam": { "evamPipeline": "object_detection" },
    "produceFinalSummary": true
  }' | jq .
# → { "summaryPipelineId": "<STATE_ID>" }

Restricción de muestreo: el Pipeline Manager exige multiFrame == frameOverlap + samplingFrame. Con frameOverlap: 0, establece multiFrame == samplingFrame. Desajuste → 400 "Multi frame mismatch". evamPipeline es uno de object_detection | video_ingestion.

Para resumir solo una parte de un clip, agrega los opcionales sampling.videoStart y sampling.videoEnd (segundos) - por ejemplo, los primeros diez minutos son "videoStart": 0, "videoEnd": 600.

2. Sonde hasta completar

El summaryPipelineId devuelto es el stateId. GET /manager/summary/{stateId} no tiene un campo status/progress de nivel superior (solo /raw lo tiene) - el progreso está en campos por etapa:

STATE_ID=<STATE_ID>
curl -s "$HOST/manager/summary/$STATE_ID" | jq '{
  chunking: .chunkingStatus,         # string, "complete" cuando está fragmentado
  frames:   .frameSummaryStatus,     # objeto COUNTS: {complete, inProgress, na, ready}
  video:    .videoSummaryStatus,     # string: "na" → "inProgress" → "complete"  ← señal real de finalización
  audio:    .audioTranscriptSummaryStatus,
  summary_len: (.summary | length)
}'

⚠️ La finalización es videoSummaryStatus == "complete", NO que summary esté no vacío. El texto del resumen final se transmite incrementalmente mientras videoSummaryStatus aún está "inProgress", por lo que sondear en "longitud del resumen > 0" devuelve un resultado truncado, a mitad de frase. Siempre espera a videoSummaryStatus. Con produceFinalSummary: false no hay etapa final - espera a frameSummaryStatus.inProgress == 0 en su lugar.

until curl -s "$HOST/manager/summary/$STATE_ID" \
       | jq -e '.videoSummaryStatus == "complete"' >/dev/null; do sleep 10; done

La resumización es lenta (VLM por fragmento + LLM map-reduce) - minutos, no segundos.

3. Recuperar el resumen

curl -s "$HOST/manager/summary/$STATE_ID" | jq -r '.summary'   # resumen final map-reduce
# Los subtítulos por fragmento están en .frameSummaries[] (cada uno: frameKey, status, summary).
# NO en .chunks[] - esos solo llevan {chunkId, duration, audioTranscripts}:
curl -s "$HOST/manager/summary/$STATE_ID" | jq -r '.frameSummaries[] | "[\(.frameKey)] \(.summary)"'
curl -s "$HOST/manager/summary/$STATE_ID/raw" | jq .   # todo (audio, frames, status, …)

Presenta el texto del resumen final; ofrece el detalle por fragmento si es útil. El audio sin voz produce un audioTranscriptSummary que lo indica - no es un error.

Registro de auditoría de la respuesta final

Los argumentos de la herramienta pueden no ser visibles para el usuario o el evaluador. La respuesta final debe, por lo tanto, informar el resultado del bootstrap: el APP_ROOT resuelto, si se reutilizó un checkout existente sin clonar, y que los comandos se ejecutaron después de cambiar a esa raíz de la aplicación. También indica que un fallo total del bootstrap recurre a un checkout superficial (--depth 1), de una sola rama, disperso solo de la aplicación VSS desde main. Reporta los valores observados de /manager/health y de la característica de resumen.

Para el flujo de trabajo de resumen, nombra cada operación pública del Manager utilizada (método y ruta /manager/...), los campos de solicitud importantes, la respuesta observada, y el arrastre de summaryPipelineId a STATE_ID. Cuando una precondición bloquea la ejecución, separa claramente las pruebas observadas de los comandos no ejecutados y aún así muestra la solicitud válida exacta, la condición de finalización y el paso de recuperación sin inventar ids ni contenido del resumen.

Gestión

curl -s "$HOST/manager/summary" | jq '.[] | {stateId, title}'   # listar todos
curl -s -X DELETE "$HOST/manager/summary/$STATE_ID"             # eliminar uno