Objetivo

Poner en marcha de forma independiente el microservicio RT-VLM de subtitulado denso y probar todos los puntos finales que expone (subida de archivos, generate_captions, añadir/eliminar flujos, autocompletado de chat, temas de Kafka).

Requisitos previos

Para la implementación autónoma de RT-VLM:

• Docker, Docker Compose, NVIDIA Container Toolkit y una GPU visible.
• Credenciales del registro NGC en $NGC_CLI_API_KEY para el inicio de sesión en Docker en nvcr.io, la obtención de imágenes y las descargas locales de modelos y artefactos de NGC.
• curl, jq y cualquier directorio de trabajo en el que se pueda escribir para la copia independiente de Compose.

Para llamadas a la API a un servicio existente:

• Servicio RT-VLM en ejecución accesible en $BASE_URL.
• Token «Bearer» en $RTVI_VLM_API_KEY o $NGC_CLI_API_KEY, dependiendo de cómo se haya configurado el servicio.

Para el despliegue completo del perfil VSS:

• Utiliza ../vss-deploy-profile/SKILL.md; esta skill no implementa perfiles VSS completos.

Instrucciones

Sigue las tablas de enrutamiento y los flujos de trabajo paso a paso que se indican a continuación. Cada sección que termine en «workflow», «quick start» o «flow» debe ejecutarse de arriba abajo. El material de referencia detallado se encuentra en references/; ejecuta directamente los flujos de trabajo documentados, a menos que una revisión futura indique una herramienta de ayuda concreta.

Ejemplos

Los ejemplos completos y funcionales se encuentran en la carpeta «evals/» (cada manifiesto *.json contiene un escenario ejecutable) y, además, se incluyen directamente en los bloques «curl» de cada flujo de trabajo que se muestran a continuación. Ejecuta una evaluación de Nivel 3 con «nv-base validate --agent-eval» para reproducirlos.

Limitaciones

• Requiere un servicio RT-VLM independiente implementado a través de esta habilidad o un servicio RT-VLM existente al que pueda acceder el solicitante.
• Los modelos alojados en NGC y los NIM pueden estar sujetos a límites de tasa, requisitos de memoria de GPU y restricciones de licencia.
• Los límites de concurrencia, memoria de GPU y almacenamiento dependen del hardware del host y del archivo de composición del perfil.
• Mantén los archivos NGC_CLI_API_KEY, RTVI_VLM_API_KEY y .env fuera de Git y de los registros; no muestres los valores de las credenciales ni los incluyas en las respuestas finales.
• El acceso al grupo Docker y el comando «sudo» son, en la práctica, privilegios de nivel root. Utiliza el comando «sudo -n» no interactivo en la referencia de implementación y detén la acción del propietario del host cuando no esté disponible el «sudo» sin contraseña.

Solución de problemas

• Error: la llamada REST devuelve «conexión rechazada». Causa: el microservicio de destino no se está ejecutando. Solución: comprueba /docs o /health; vuelve a implementar mediante vss-deploy-profile o la habilidad vss-deploy-* correspondiente.
• Error: código HTTP 401/403 en las consultas a NGC. Causa: falta la clave NGC_CLI_API_KEY o ha caducado. Solución: inicia sesión en Docker en nvcr.io y vuelve a exportar la clave antes de volver a intentarlo.
• Error: el contenedor está sin memoria (OOM) o el modelo no se carga. Causa: memoria de la GPU insuficiente para el perfil seleccionado. Solución: cambiar a una variante más pequeña o liberar GPU mediante «docker compose down».

Implementación y uso de RT-VLM Dense Captioning (VSS 3.2)

RT-VLM es el microservicio de visión-lenguaje en tiempo real de NVIDIA: decodifica vídeo (archivo o RTSP), lo segmenta en fragmentos, ejecuta un VLM (cosmos-reason1, cosmos-reason2 o cualquier modelo compatible con OpenAI), transmite subtítulos densos a través de SSE/HTTP y publica subtítulos, alertas de incidentes y errores en Kafka. Utiliza esta habilidad para implementar el servicio RT-VLM independiente cuando aún no se esté ejecutando un perfil VSS completo y, a continuación, llama a su API /v1/... para la generación de subtítulos, la subida de archivos, la gestión de la transmisión en directo, las comprobaciones de estado, las sugerencias de chat compatibles con NIM o las métricas de Prometheus. Referencia de la API: https://docs.nvidia.com/vss/latest/real-time-vlm-api.html.

Enrutamiento de la implementación

Si el usuario solicita implementar un perfil VSS completo, utiliza ../vss-deploy-profile/SKILL.md. Esa habilidad se encarga del enrutamiento del perfil, del archivo generated.env, del resolved.yml, del dimensionamiento multiservicio y de la implementación y desmontaje de la pila completa.

Si el usuario solicita subtitulado denso con RT-VLM independiente, o si no hay ningún perfil VSS ya en ejecución, utiliza el flujo de RT-VLM independiente en references/deploy-rt-vlm-service.md antes de llamar a la API. Esto sigue el mismo patrón centrado en Compose que vss-deploy-profile: recopilar el contexto, ejecutar comprobaciones previas, trabajar a partir de una copia local, realizar una simulación con la configuración de Docker Compose, revisar, implementar y, a continuación, esperar a que se compruebe el estado.

Flujo de implementación independiente

Sigue siempre esta secuencia. Nunca te saltes la simulación.

# 1. Copia deploy/docker/services/rtvi/rtvi-vlm/rtvi-vlm-docker-compose.yml
#    en cualquier directorio de trabajo independiente en el que se pueda escribir.
# 2. Obtén RTVI_VLM_IMAGE_TAG a partir de esa copia de Compose.
# 3. Elimina de la copia el bloque «depends_on» sobrante, exclusivo de la versión independiente.
# 4. Crea un archivo .env ignorado por Git con los valores RT-VLM necesarios.
# 5. Prepara las rutas de enlace del host, como $VSS_DATA_DIR/data_log/vst/clip_storage.
#    Utiliza `sudo -n` para corregir los permisos de propiedad; si no dispones de sudo sin contraseña,
#    detente y pide al propietario del host que ejecute manualmente el comando mostrado.
# 6. docker compose --env-file .env -f rtvi-vlm-docker-compose.yml config --quiet
# 7. Descarga con `docker pull` la etiqueta exacta de la imagen RT-VLM.
# 8. Ejecuta `docker compose ... up -d rtvi-vlm`, espera a que esté listo y, a continuación, realiza una prueba de funcionamiento.

Ejecuta las comprobaciones previas antes de cualquier «pull» o «up»; detén el proceso y corrige los errores aquí antes de depurar el propio RT-VLM:

nvidia-smi --query-gpu=index,name --format=csv,noheader
nvidia-container-cli info
docker compose version
docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

Para implementaciones independientes de un solo archivo, no ejecutes directamente el archivo deploy/docker/services/rtvi/rtvi-vlm/rtvi-vlm-docker-compose.yml: contiene referencias «depends_on» a servicios VLM/NIM hermanos que solo están están definidas en el proyecto completo de Compose de VSS/met-blueprints. La referencia independiente muestra cómo copiar el archivo de Compose, derivar de él la etiqueta de la imagen actual, eliminar el bloque «depends_on» y validar el resultado antes de la ejecución.

Para la validación basada en agentes, nunca permitas que el indicador de sudo sea interactivo. Antes de cualquier operación con privilegios o de Docker, utiliza la protección no interactiva de references/deploy-rt-vlm-service.md: prefiere «plain docker»; de lo contrario, utiliza «sudo -n docker»; si «sudo -n» falla, detén el proceso con el comando manual exacto para el propietario del host, en lugar de volver a intentarlo con «sudo» interactivo o debilitar los permisos.

Si «docker pull» falla con un error de «snapshotter/unpack» de containerd en Docker 28 o superior, aplica la corrección «containerd-snapshotter=false» en /etc/docker/daemon.json, tal y como se indica en la referencia de modo autónomo, antes de volver a intentarlo.

Valores mínimos de .env para la configuración independiente:

Configuración

export BASE_URL="http://localhost:${RTVI_VLM_PORT:-8018}"  # puerto RT-VLM del lado del host
export API_KEY="${NGC_CLI_API_KEY:-${RTVI_VLM_API_KEY:-}}" # token de portador utilizado por los comandos `curl` del lado del host
: "${API_KEY:?Establece NGC_CLI_API_KEY o RTVI_VLM_API_KEY antes de llamar a los puntos finales autenticados}"

Todas las solicitudes que aparecen a continuación utilizan «Authorization: Bearer $API_KEY». Los puntos finales de estado (/v1/health/*, /v1/ready, /v1/live, /v1/startup) suelen funcionar sin autenticación.

Prueba de funcionamiento antes de su uso:

curl -fsS "$BASE_URL/v1/health/ready"
MODEL_ID="$(curl -fsS "$BASE_URL/v1/models" -H "Authorization: Bearer $API_KEY" | jq -r '.data[0].id // .id')"
curl -fsS "$BASE_URL/openapi.json" | jq -r '.paths | keys[]' | sort

RTSP Sample Stream Guard

Cuando una tarea o evaluación mencione RTSP_SAMPLE_URL, considere esa variable de entorno exacta como una entrada obligatoria. Comprueba que esté definida y que no esté vacía antes de sondear o registrar cualquier flujo; si falta, detén el proceso con un mensaje de error claro. No derives un sustituto de NvStreamer, VIOS, paquetes de datos de muestra ni de ningún otro sistema de respaldo, ya que eso validaría un flujo diferente al solicitado por el llamante.

: "${RTSP_SAMPLE_URL:?Establece RTSP_SAMPLE_URL en una transmisión de muestra RTSP accesible antes de la validación RTSP}"
case "$RTSP_SAMPLE_URL" in
  rtsp://*) ;;
  *) echo "RTSP_SAMPLE_URL debe ser una URL rtsp://, se ha obtenido: $RTSP_SAMPLE_URL" >&2; exit 1 ;;
esac

if command -v ffprobe >/dev/null 2>&1; then
  ffprobe -v error -rtsp_transport tcp \
    -select_streams v:0 -show_entries stream=codec_type \
    -of csv=p=0 "$RTSP_SAMPLE_URL" | grep -qx video
elif command -v gst-discoverer-1.0 >/dev/null 2>&1; then
  gst-discoverer-1.0 "$RTSP_SAMPLE_URL" | grep -qi 'video'
else
  echo "Instala ffprobe o gst-discoverer-1.0 antes de la validación RTSP." >&2
  exit 1
fi

Inicio rápido: subtítulos densos a partir de un vídeo local

# 1. Sube el vídeo y captura su ID de archivo
FILE_ID=$(curl -fsS -X POST "$BASE_URL/v1/files" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@/path/to/warehouse.mp4" \
  -F "purpose=vision" \
  -F "media_type=video" | jq -r '.id')

# 2. Generar subtítulos y alertas (flujo SSE de respuestas fragmentadas)
curl -N -X POST "$BASE_URL/v1/generate_captions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"id\": \"$FILE_ID\",
    \"prompt\": \"Escribe un subtítulo conciso y conciso para cada segmento de 10 segundos de este vídeo del almacén.\",
    \"model\": \"$MODEL_ID\",
    \"chunk_duration\": 10,
    \"stream\": true
  }"

Superficie de la API

Utiliza la OpenAPI en tiempo real como fuente de referencia antes de llamar a los puntos finales opcionales:

curl -fsS "$BASE_URL/openapi.json" | jq -r '.paths | keys[]' | sort

Las rutas principales para VSS 3.2 son:

• POST /v1/files para la subida de archivos multimedia en varias partes; pasa el identificador del archivo devuelto a la generación de subtítulos y elimina el archivo cuando hayas terminado.
• POST /v1/generate_captions para la generación de subtítulos de archivos o transmisiones. Utilice el ID de modelo exacto devuelto por GET /v1/models; los alias como cosmos-reason2 son selectores del backend, no ID de modelo de solicitud.
• POST /v1/streams/add, GET /v1/streams/get-stream-info y DELETE /v1/streams/delete/{stream_id} para el ciclo de vida de RTSP. Analiza los identificadores de transmisión a partir de results[0].id.
• POST /v1/chat/completions para llamadas de texto y multimodales compatibles con OpenAI. Las compilaciones actuales de la versión 26.05 devuelven un código HTTP 400 para /v1/completions de solo texto; tenlo en cuenta como algo esperado al validar el comportamiento heredado.
• GET /v1/health/ready, /v1/models, /v1/assets/stats y /v1/metrics para pruebas de servicio. No des por sentado que existe /v1/license a menos que OpenAPI lo incluya en la lista.

Los esquemas detallados de los puntos finales, los formatos de respuesta, los puntos finales de flujo único al estilo CV y las notas de compatibilidad con la versión 26.05 se encuentran en references/api-surface-26.05.md.

Flujos de trabajo habituales

• Subtítulos de archivos almacenados: sube el archivo con POST /v1/files, llama a /v1/generate_captions con el ID del archivo devuelto, utiliza stream=true para SSE, y, a continuación, elimina el archivo para liberar espacio de almacenamiento.
• Subtitulado en directo por RTSP: cuando el solicitante proporcione RTSP_SAMPLE_URL, utiliza esa URL exacta y ejecuta el RTSP Sample Stream Guard antes del registro. No derives una transmisión de sustitución de NvStreamer o VIOS cuando RTSP_SAMPLE_URL esté vacío; en su lugar, da un error rápido. Exige una entrada real de transmisión de vídeo/subtítulos antes del registro; añade la transmisión, subtítula y, a continuación, da de baja el registro.
• Mensajes de alerta: incluye una línea determinista «Anomalía detectada: Sí/No ». La publicación en Kafka es una configuración del lado del servidor, adicional a las respuestas HTTP, y está documentada en references/kafka-workflows.md.
• Validación de Kafka: confía en el entorno vss-rtvi-vlm en producción para los nombres de los temas. En un perfil completo de alertas VSS en tiempo real, utiliza el contenedor VSS Kafka existente mdx-kafka para las comprobaciones de la CLI y los comandos finales del consumidor de incidentes. Para la validación independiente, utiliza un broker que anuncie ${HOST_IP}:9092; nunca detengas ni sustituyas un broker preexistente sin la confirmación del usuario.

Referencia de errores

Causas comunes: 400 por formato de solicitud o ID de modelo no válido, 401/403 por falta o error en el token de portador, 404 por archivos o flujos eliminados o puntos finales no compatibles, 413 por cargas de gran tamaño, 422 por validación de esquema, 429 por exceso de concurrencia, 500 por fallos de inferencia o de tiempo de ejecución, y 503 mientras el inicio aún está en curso. Revisa los registros de Docker «vss-rtvi-vlm» para detectar fallos del lado del servicio.