Informe

Genera un informe de análisis de vídeo redirigiéndolo a uno de los dos backends; nunca a través de POST /generate en el agente VSS.

Si la solicitud es ambigua (p. ej., «informe sobre » sin intervalo de tiempo ni descripción del incidente), se utilizará por defecto el Modo A. Pregunta solo si el usuario menciona tanto un sensor como un intervalo de tiempo. Consulta los ejemplos a continuación para ver las formulaciones de las solicitudes que se dirigen a cada modo.

Instrucciones

1. Elige el modo: el modo A para un único clip grabado o vídeo de un sensor; el modo B cuando la solicitud especifique un intervalo de tiempo o incidentes/alertas (compáralo con los ejemplos).
2. Verifica el perfil de implementación para ese modo en «Requisitos previos de implementación»; transfiere la tarea a /vss-deploy-profile si su prueba falla.
3. Ejecuta los pasos numerados de ese modo: el modo A o el modo B que se indican a continuación.
4. Reescribe todas las URL de clips destinadas a los usuarios con la cadena de una sola línea $VSS_PUBLIC_HOST:$VSS_PUBLIC_PORT (URL de clip reproducible en el navegador) antes de incrustarlas en el informe.
5. Devuelve al usuarioel informe renderizado en formato Markdown.

Especificaciones del contrato para los evaluadores:

• El título principal del Modo A DEBE ser exactamente # Informe de análisis de vídeo.
• El título principal del Modo B DEBE ser exactamente # Informe de rango de incidentes (nunca # Informe de incidentes ni variantes con el nombre del sensor).
• El modo B DEBE incluir ## Información básica con las filas exactas requeridas de la plantilla (Identificador del informe, Rango, Alcance, Total de incidentes, Confirmados / Rechazados / No verificados).

Ejemplos

• «Generar un informe para este vídeo» / «informe sobre » → Modo A
• «Analizar warehouse_01.mp4» / «crear un informe de análisis sobre el vídeo subido» → Modo A
• «Informe sobre los incidentes desde las 12:31Z hasta las 12:32Z» → Modo B
• «Informe sobre las alertas de hoy» / «¿Qué incidentes han ocurrido en última hora» → Modo B
• «Resumen de alertas de entre y » → Modo B

Desencadenantes negativos

No utilices esta habilidad cuando la solicitud sea una de las siguientes:

• Preguntas y respuestas visuales puntuales sobre un clip en las que no se solicite explícitamente un informe («¿de qué color es el camión?», «¿qué ocurre en el minuto 00:12?») → utiliza /vss-ask-video.
• Búsqueda en el archivo o por similitud semántica («buscar carretillas elevadoras», «buscar en todos los vídeos casos de conducción demasiado cerca del vehículo de delante») → utiliza /vss-search-archive.
• Consulta de incidentes o métricas en modo de solo lectura sin necesidad de generar un informe → utiliza /vss-query-analytics.
• Implementación, desactivación o cambios de perfil («implementar alertas», «cambiar de perfil», «activar la configuración básica») → utiliza /vss-deploy-profile.
• Solicitudes de gestión de alertas o reglas en tiempo real → utiliza /vss-manage-alerts.

Nunca envíe informes a través de VSS-agent POST /generate.

Requisitos previos para la implementación

El modo A requiere el perfil base de VSS (VST + VLM NIM). El modo B requiere el perfil de alertas de VSS (VA-MCP + Elasticsearch).

Prueba:

# Modo A — Accesibilidad de VST + VLM
curl -sf --max-time 5 "http://${HOST_IP}:30888/vst/api/v1/sensor/version" >/dev/null

# Modo B — VA-MCP
curl -sf --max-time 5 "http://${HOST_IP}:9901/" >/dev/null

Si la prueba falla, pasa el control a /vss-deploy-profile con -p base (modo A) o -p alerts (modo B). Confirma siempre primero la implementación con el usuario.

URL de clips: entrada de VLM frente al enlace del informe del navegador

VST devuelve las URL de recorte utilizando el host:puerto interno del agente ${HOST_IP}:30888. Conserva esa URL original como VIDEO_URL para la obtención de fotogramas de VLM locales o dentro del clúster. No reescribas la URL de entrada de VLM solo para que se pueda reproducir en el navegador.

Crea BROWSER_CLIP_URL únicamente para las URL que aparecen en el informe generado. La capa de implementación exporta el host:puerto visible para el navegador como $VSS_PUBLIC_HOST / $VSS_PUBLIC_PORT (y el esquema como $VSS_PUBLIC_HTTP_PROTOCOL) en cada archivo .env de perfil —ya sea Brev o bare-metal—, por lo que la reescritura del enlace del informe es:

: "${VSS_PUBLIC_HOST:?Establece VSS_PUBLIC_HOST antes de reescribir las URL de los clips}"
: "${VSS_PUBLIC_PORT:?Establece VSS_PUBLIC_PORT antes de reescribir las URL de los clips}"
VSS_PUBLIC_HTTP_PROTOCOL="${VSS_PUBLIC_HTTP_PROTOCOL:-http}"
BROWSER_CLIP_URL=$(echo "$RAW_URL" | sed -E "s|^https?://[^/]+|${VSS_PUBLIC_HTTP_PROTOCOL}://${VSS_PUBLIC_HOST}:${VSS_PUBLIC_PORT}|")

Si falta alguno de los valores de host público requeridos, omite el enlace del clip destinado al informe e indica que no se ha podido generar una URL reproducible en el navegador; no bloquees la ruta de análisis local de VLM. Aplica la reescritura a todas las URL de fragmentos que aparezcan en el informe generado (Modo A, paso 4, fila «URL del fragmento»; Modo B, subpunto de fragmentos por incidente). Deja el bloque de contenido video_url del VLM en el Modo A, paso 3, con la URL interna original cuando el VLM sea local o esté dentro del clúster.

Modo A — Informe sobre un clip de vídeo grabado

Si se ha implementado el perfil VSS lvs — curl -sf --max-time 5 "http://${HOST_IP}:38111/v1/ready" devuelve un código HTTP 200 — ejecute /vss-summarize-video para generar el resumen, a continuación, pega el resultado en la plantilla de informe del paso 4 y omite los pasos 1 a 3 (la ruta directa al VLM). Ejecuta los pasos 1 a 3 solo cuando /v1/ready no devuelva un código 200.

Paso 1: resolver la URL del clip

Pase el control a /vss-manage-video-io-storage para:

1. enumerar los sensores y confirmar que el sensor existe (si no es así, subirlo primero).

2. Obtener /storage//timelines para el intervalo grabado cuando el usuario no haya proporcionado startTime ni endTime.

3. Solicitar una URL del clip:

   curl -s "http://${HOST_IP}:30888/vst/api/v1/storage/file//url?startTime=&endTime=&container=mp4&disableAudio=true" | jq -r .videoUrl
   

   Esto proporciona una URL mp4 directa de la que el VLM local o dentro del clúster puede extraer fotogramas. Asigna esta URL a VIDEO_URL (utilizada por el VLM en el paso 3) y establece RAW_URL="$VIDEO_URL" antes de aplicar la reescritura del enlace del informe para generar BROWSER_CLIP_URL para el paso 4; el navegador del usuario no puede acceder directamente a $VIDEO_URL. El modo A requiere que el punto final VLM seleccionado pueda recuperar VIDEO_URL. Las implementaciones locales de NIM/RT-VLM normalmente pueden hacerlo; los puntos finales remotos, por lo general, no pueden recuperar localhost, HOST_IP privada ni URL internas de VST. Si el VLM_ENDPOINT en directo es remoto, muestra ese requisito de accesibilidad en lugar de realizar una solicitud de chat que fallará después de que /v1/models tenga éxito.

Paso 2 — Resolver el punto final VLM y el modelo

La implementación puede servir el VLM a través de cualquiera de las dos pilas. Ambas exponen una API de chat/autocompletado compatible con OpenAI; elige la que esté activa:

Lee los valores en tiempo real del contenedor del agente en ejecución — no hagas suposiciones:

docker exec vss-agent sh -lc '
for k in HOST_IP VLM_MODE VLM_MODEL_TYPE VLM_BASE_URL VLM_NAME RTVI_VLM_BASE_URL RTVI_VLM_MODEL_TO_USE; do
  v="$(printenv "$k")"
  [ -n "$v" ] && printf "%s=%s\n" "$k" "$v"
done
'

No es necesario que RTVI_VLM_ENDPOINT esté presente en el entorno de vss-agent; hay varios perfiles que no lo incluyen.

Regla de selección:

if [ "${VLM_MODEL_TYPE:-}" = "rtvi" ]; then
  VLM_BACKEND="rtvlm"
  VLM_ENDPOINT="${RTVI_VLM_BASE_URL:+${RTVI_VLM_BASE_URL%/}/v1}"
  [ -z "${VLM_ENDPOINT}" ] && VLM_ENDPOINT="http://${HOST_IP}:8018/v1"   # alertas por defecto
  VLM_MODEL="${RTVI_VLM_MODEL_TO_USE}"
elif [ -n "${VLM_BASE_URL}" ] && [ "${VLM_MODE}" != "none" ]; then
  VLM_BACKEND="nim_cosmos"
  VLM_ENDPOINT="${VLM_BASE_URL%/}/v1"
  VLM_MODEL="${VLM_NAME}"
else
  VLM_BACKEND="rtvlm"
  VLM_ENDPOINT="${RTVI_VLM_BASE_URL:+${RTVI_VLM_BASE_URL%/}/v1}"
  [ -z "${VLM_ENDPOINT}" ] && VLM_ENDPOINT="http://${HOST_IP}:30082/v1"  # valor predeterminado
  VLM_MODEL="${RTVI_VLM_MODEL_TO_USE}"
fi

Comprueba /v1/models antes de enviar una solicitud de chat para confirmar que el punto final elegido está activo y que el modelo se ha cargado:

curl -sf --max-time 5 "${VLM_ENDPOINT}/models" | jq -r '.data[].id'

Si la comprobación falla o los ID mostrados no incluyen ${VLM_MODEL}, recurre al otro backend (o muestra el error; nunca elijas en silencio un modelo que no esté en el servidor).

Paso 3 — Llamar directamente al VLM

Utiliza el punto final de chat/completaciones compatible con OpenAI con un bloque de contenido video_url: la misma estructura de carga útil y los mismos ajustes multimodales que video_understanding genera en src/vss_agents/tools/video_understanding.py (_build_vlm_messages + la llamada base_vlm.bind(...) de Cosmos).

El muestreo de fotogramas y el presupuesto de tokens visuales (píxeles) deben coincidir con la configuración de video_understanding en tiempo real para el perfil activo. Envía mm_processor_kwargs y media_io_kwargs para que la llamada directa utilice el mismo muestreo de fotogramas y el mismo presupuesto de píxeles que la herramienta video_understanding integrada en el agente; si se omiten, el VLM aplicará sus propios valores predeterminados, por lo que la salida se desviará de la ruta del agente.

PROMPT='Describe con detalle lo que ocurre en el vídeo, con marcas de tiempo (inicio-fin en segundos desde el inicio del clip) para cada segmento o evento. Incluye escenas, objetos, personas, vehículos y acciones destacadas.'

# El razonamiento está desactivado por defecto — coincide con la configuración de video_understanding del perfil base (`reasoning: false`).
# video_understanding.py utiliza config.reasoning a menos que quien lo invoque lo anule, por lo que por defecto no se aplica el razonamiento.
# Añade el sufijo de razonamiento «Cosmos Reason 2» ÚNICAMENTE cuando el usuario solicite explícitamente el razonamiento
# (omítelo para los VLM que no sean «cosmos-reason2»). Con el razonamiento desactivado, la respuesta no incluye  el bloque .
if [ "${REASONING:-false}" = "true" ]; then
PROMPT="${PROMPT}

Responde a la pregunta utilizando el siguiente formato:


Tu razonamiento.


Escribe tu respuesta final inmediatamente después de la etiqueta ."
fi

# Si el Paso 3 se ejecuta de forma independiente, deduce el backend que falte a partir del entorno/modelo actual.
[ -z "${VLM_BACKEND:-}" ] && {
  if [ "${VLM_BACKEND:-}" = "rtvi" ]; then
    VLM_BACKEND="rtvlm"
  elif [[ "${VLM_MODEL:-}" == nvidia/cosmos* ]]; then
    VLM_BACKEND="nim_cosmos"
  else
    VLM_BACKEND="rtvlm"
  fi
}

# Configuración multimodal: se determina a partir de la ruta del archivo de configuración del agente en tiempo real, no a partir de opciones fijas.
CFG_JSON=$(
docker exec vss-agent python3 -c '
import json, os, yaml
p = os.getenv("VSS_AGENT_CONFIG_FILE")
if not p:
    raise SystemExit("VSS_AGENT_CONFIG_FILE no está definido en vss-agent")
if not os.path.isabs(p):
    p = os.path.join("/vss-agent", p.lstrip("./"))
with open(p, encoding="utf-8") as f:
    cfg = yaml.safe_load(f) or {}
vu = (cfg.get("functions", {}) or {}).get("video_understanding", {}) or {}
print(json.dumps({
    "max_fps": int(vu.get("max_fps", 2)),
    "max_frames": int(vu.get("max_frames", 30)),
    "min_pixels": int(vu.get("min_pixels", 3136)),
    "max_pixels": int(vu.get("max_pixels", 8388608)),
}))
')
)
[ -n "${CFG_JSON}" ] || { echo "Error al leer la configuración de video_understanding desde vss-agent"; exit 1; }
jq -e . >/dev/null <<< "${CFG_JSON}" || { echo "Configuración JSON no válida de vss-agent"; exit 1; }
MAX_FPS="$(jq -r '.max_fps' <<< "${CFG_JSON}")"
MAX_FRAMES="$(jq -r '.max_frames' <<< "${CFG_JSON}")"
MIN_PIXELS="$(jq -r '.min_pixels' <<< "${CFG_JSON}")"
MAX_PIXELS="$(jq -r '.max_pixels' <<< "${CFG_JSON}")"

# num_frames = min(int(clip_seconds) * max_fps, max_frames), mínimo 1 — coincide con video_understanding.py.
# clip_seconds (Step 1 endTime-startTime) puede ser un valor fraccionario; se redondea a segundos enteros — bash $((...))
# solo admite números enteros y da error con «15.0»/«1.5». Por defecto, 15 s -> se limita a MAX_FRAMES.
CLIP_SECONDS=$(awk -v s="${CLIP_SECONDS:-15}" 'BEGIN{printf "%d", s}')
NUM_FRAMES=$(( CLIP_SECONDS * MAX_FPS ))
[ "$NUM_FRAMES" -gt "$MAX_FRAMES" ] && NUM_FRAMES=$MAX_FRAMES
[ "$NUM_FRAMES" -lt 1 ] && NUM_FRAMES=1

# Aplicar los argumentos de línea de comandos de Cosmos mm/media únicamente en la ruta NIM de Cosmos.
# El modo RT-VLM utiliza su propio preprocesamiento del lado del servidor y no debe recibir estos argumentos de línea de comandos.
MM_KWARGS=""
if [ "${VLM_BACKEND}" = "nim_cosmos" ]; then
  case "$VLM_MODEL" in
    *cosmos-reason2*) MM_KWARGS=", \"mm_processor_kwargs\": {\"size\": {\"shortest_edge\": ${MIN_PIXELS}, \"longest_edge\": ${MAX_PIXELS}}}, \"media_io_kwargs\": {\"video\": {\"num_frames\": ${NUM_FRAMES}}}" ;;
    *cosmos*)         MM_KWARGS=", \"mm_processor_kwargs\": {\"videos_kwargs\": {\"min_pixels\": ${MIN_PIXELS}, \"max_pixels\": ${MAX_PIXELS}}}, \"media_io_kwargs\": {\"video\": {\"num_frames\": ${NUM_FRAMES}}}" ;;
    *)                      MM_KWARGS="" ;;
  esac
fi

curl -s --connect-timeout 5 --max-time 120 -X POST "${VLM_ENDPOINT}/chat/completions" \
  -H "Content-Type: application/json" \
  -d @- <<EOF | jq -r '.choices[0].message.content'
{
  "model": $(jq -Rs . <<< "${VLM_MODEL}"),
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": $(jq -Rs . <<< "${PROMPT}")},
        {"type": "video_url", "video_url": {"url": $(jq -Rs . <<< "${VIDEO_URL}")}}
      ]
    }
  ],
  "max_tokens": 1024,
  "temperature": 0.0${MM_KWARGS}
}
EOF

El bloque kwargs se adapta al backend: en nim_cosmos, las variantes de Reason2 (nvidia/cosmos-reason2*) utilizan mm_processor_kwargs.size{shortest_edge,longest_edge}, mientras que otras variantes de NIM Cosmos (nvidia/cosmos*) utilizan mm_processor_kwargs.videos_kwargs{min_pixels,max_pixels}; ambos envían también media_io_kwargs.video.num_frames. En rtvlm, no se envían kwargs de Cosmos.

Si el VLM devuelve un … (modo de razonamiento Cosmos Reason), conserva solo el texto que aparece después de como cuerpo del informe.

Paso 4 — Rellena la plantilla del informe de análisis de vídeo

Copia el archivo assets/video-analysis-report.md, rellena todos los marcadores de posición y devuelve el código Markdown generado al usuario. Mantén el archivo original sin cambios. Antes de generar el código, comprueba que BROWSER_CLIP_URL esté definido y no esté vacío; a continuación, sustituye por ese valor exacto en la fila «URL del clip ». Nunca dejes el marcador de posición en la salida, nunca incluyas instrucciones de la plantilla en una celda rellenada y nunca utilices la URL sin procesar HOST_IP:30888.

Modo B — Informe sobre incidentes en un intervalo de tiempo

Paso 1 — Resolver el intervalo de tiempo y (opcionalmente) el sensor

• start_time / end_time deben estar en formato ISO 8601 UTC (AAAA-MM-DDTHH:MM:SS.sssZ). Resuelve las expresiones relativas («última hora», «hoy») en función del reloj actual del host.
• Si el usuario especifica un sensor, regístralo como source + source_type=sensor. De lo contrario, deja ambos campos sin definir para realizar una consulta que abarque todos los sensores.

Paso 2 — Obtener incidentes mediante /vss-query-analytics

Pasa el control a /vss-query-analytics (inicializar → tools/call) con:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "video_analytics__get_incidents",
    "arguments": {
      "source": "",
      "source_type": "sensor",
      "start_time": "",
      "end_time": "",
      "max_count": 100,
      "includes": ["objectIds", "info"]
    }
  },
  "id": 1
}

Límite de solo lectura (obligatorio):

• El modo B consiste exclusivamente en la recuperación de datos analíticos de solo lectura. Nunca se deben escribir, inicializar, rellenar ni modificar datos de Elasticsearch/VA.
• Ejemplos prohibidos: indexar incidentes sintéticos, reproducir cargas útiles de pruebas en ES, llamar a las API de escritura/actualización/eliminación para «poner los datos a disposición» del informe.
• Si no existen incidentes para el rango o ámbito solicitado, trátalos como resultados vacíos (véase más abajo); no inventes datos.

Para cada incidente, conserva: id, sensorId, timestamp, end, category, place.name, info.verdict, info.reasoning, objectIds y la URL del clip (normalmente info.clip_url, clip_url o cualquier campo de puntero de clip que contenga la respuesta). Aplica la reescritura $VSS_PUBLIC_HOST:$VSS_PUBLIC_PORT (véase «URL de clip reproducible en el navegador» más arriba) a cada URL de clip antes de pegarla en el informe; el valor sin procesar es una URL HOST_IP:30888 a la que el navegador del usuario no puede acceder.

Paso 3 — Rellenar la plantilla del informe de rango de incidentes

Copia el archivo assets/incident-range-report.md; a continuación, agrupa por sensor (o por categoría si no hay un ámbito de sensor), contabiliza los veredictos y enumera cada incidente con la marca de tiempo, la categoría, el veredicto y el razonamiento. Mantén el archivo original sin cambios. Cada valor de clip de incidente debe ser una URL reescrita que se pueda reproducir en el navegador; omite la línea del clip cuando el incidente no contenga ninguna URL de clip. Nunca incluyas instrucciones de la plantilla en una celda rellenada.

Si get_incidents devuelve cero resultados, DETENTE y devuelve exactamente una declaración de rango vacío de una sola línea en la que se indique el rango y el ámbito solicitados. No generes la plantilla completa de «Incident Range», no inventes incidentes, no introduzcas datos de prueba y no recurras al Modo A.

Gestión de errores

• Si falla una sonda, una llamada curl, una llamada VLM o una solicitud /vss-query-analytics, detén el flujo de trabajo e informa del punto final que ha fallado, del estado HTTP o del error de comando, así como del siguiente paso útil para la recuperación. No elabores un informe a partir de datos parciales o incompletos.
• Si la respuesta de VLM está vacía, tiene un formato incorrecto o solo contiene un bloque de razonamiento, señala ese problema en la respuesta y sugiere comprobar la disponibilidad del modelo o los registros antes de volver a intentarlo.
• Si no es posible reescribir la URL de un clip para que apunte al host o puerto público, omítela del informe generado e indica que no se ha podido generar la URL reproducible en el navegador.
• Para el Modo B, trata los campos opcionales del incidente que falten (info.reasoning, objectIds, URL del clip) como omisiones en el informe, pero trata la falta de ID, marca de tiempo o categoría como un error de calidad de los datos que debe notificarse.

Referencia cruzada

• /vss-manage-video-io-storage: lista de sensores, líneas de tiempo y URL de clips para el paso 1 del modo A.
• /vss-query-analytics — recuperación de incidentes (y enriquecimiento del veredicto y el razonamiento) para el paso 2 del Modo B.
• /vss-ask-video — Preguntas y respuestas ad hoc de VLM sobre un único clip (no es un informe estructurado).
• /vss-summarize-video — utilizado por el Modo A para generar el cuerpo del resumen cuando se implementa el perfil lvs; la plantilla del informe (Paso 4) se sigue rellenando aquí.