Configuración

La sección Configuración (/configuration) es el centro de administración de Perceiver. Desde aquí puedes consultar el catálogo de modelos disponibles, crear flujos de análisis (paquetes de modelos), ajustar el orden y las opciones de cada modelo, revisar endpoints webhook asociados y controlar el seguimiento global de objetos.

Vista general de Configuración

Pantalla de Configuración: columna de modelos a la izquierda, tarjetas de flujos a la derecha y la tarjeta de seguimiento global al final.

¿Qué muestra la pantalla?

La página se divide en dos columnas principales:

• Columna izquierda — Modelos disponibles: catálogo de modelos locales instalados y modelos externos vía API, con un contador total y el botón Agregar modelo API.
• Columna derecha — Flujo: listado de paquetes de modelos creados, con sus modelos asignados, endpoints webhook y acciones de vista y eliminación. Se paginan de seis en seis.
• Parte inferior — Seguimiento global de objetos: interruptor y estado del sistema de Vision Tracking, que se actualiza cada 10 segundos.

Modelos disponibles

Cada tarjeta de modelo muestra:

Elemento	Qué indica
Nombre y tipo	Identificador del modelo y su familia (Object Detection, OCR, Segmentation, etc.)
Versión	Versión del modelo instalado (Badge junto al título)
Estado	OPERATIVO (verde), INSTALADO (amarillo) o NO INSTALADO (gris)
FPS mínimos	Rendimiento mínimo declarado del modelo
Instalado / Último uso	Fechas de instalación y de su última ejecución (solo modelos instalados)

Los modelos instalados y operativos muestran una barra lateral verde y un rayo. Las tarjetas de modelos locales son de solo consulta: esta pantalla no instala ni desinstala modelos, solo refleja el estado que reporta /api/models.

Catálogo de modelos

Modelos locales con su estado operativo junto a un modelo externo identificado por la barra azul.

Modelos externos vía API

Perceiver permite incorporar modelos alojados en plataformas externas (Replicate, HuggingFace y Fal.ai) mediante el botón Agregar modelo API.

Agregar un modelo externo

1. Haz clic en Agregar modelo API en la cabecera de la columna de modelos.
2. Pega la URL del modelo (por ejemplo, https://replicate.com/stability-ai/sdxl).
3. Haz clic en Descubrir. El backend consulta la plataforma y muestra una ficha con el nombre, la plataforma detectada, el tipo, la descripción y la variable de entorno de la clave API requerida.
4. Haz clic en Agregar modelo. El modelo queda registrado como activo con minFps = 1 por defecto.

Si el campo de URL está vacío o el descubrimiento falla, se muestra un aviso de error y no se guarda nada.

Acciones sobre cada modelo externo

Las tarjetas externas se distinguen por una barra lateral azul y un icono de enlace. Ofrecen cuatro acciones:

• Probar API: valida la clave API configurada en el servidor. Muestra una insignia OK o Error y, si falla, el mensaje devuelto por la plataforma.
• Probar con imagen: abre un diálogo para subir una imagen y, opcionalmente, un prompt. Ejecuta una inferencia de prueba y muestra el resultado devuelto por el modelo y la duración en milisegundos. Útil para comprobar modelos como LLaVA, que pueden requerir prompt.
• Configurar modelo (engranaje): abre el diálogo de edición con nombre, tipo, descripción, variable de entorno de la clave API, identificador del modelo, prompt predeterminado y un campo Configuración (JSON) que se valida en el cliente antes de guardar; si el JSON es inválido, aparece el aviso JSON inválido en el campo de configuración.
• Eliminar: abre un diálogo de confirmación antes de borrar el modelo.

Agregar modelo externo

Diálogo de descubrimiento: la URL del modelo arriba y la ficha detectada con plataforma, tipo y clave API.

Crear un flujo (paquete de modelos)

Un flow en esta pantalla es un paquete: un grupo ordenado de modelos que se ejecutan en cadena sobre cada imagen que llega por webhook.

1. Haz clic en Crear flujo (botón verde en la cabecera de la columna derecha).
2. Completa el diálogo Crear nuevo flujo:
   • Nombre del flujo (obligatorio): identificador visible, p. ej. Vigilancia de tienda.
   • Descripción (opcional): propósito breve del flujo.
   • Seleccionar modelos: lista de casillas con todos los modelos locales instalados y los modelos externos disponibles. Debes marcar al menos uno.
   • Guardar descripciones de LLaVA: si se activa, las descripciones de texto que genere LLaVA se indexan para la búsqueda semántica.
3. Haz clic en Crear flujo.

Al crearlo, el servidor genera además un pipeline asociado al paquete (Pipeline: <nombre>) con todos los modelos seleccionados en modo Sync y habilitados, en el orden elegido. Por eso el paquete aparece también en la pestaña Flow del panel y puede editarse como pipeline.

Si falta el nombre o no hay modelos seleccionados, se muestra el aviso Se requiere un nombre y al menos un modelo y no se crea nada.

Crear flujo

Diálogo Crear nuevo flujo: nombre, descripción, casillas de modelos y la opción de guardar descripciones LLaVA.

Tarjetas de flujos existentes

Cada paquete se muestra como una tarjeta con:

• Nombre, descripción y estado (ACTIVO / INACTIVO).
• Modelos asignados: insignias con el nombre de cada modelo. Las insignias externas llevan borde azul e icono de enlace; las operativas muestran una marca verde.
• Agregar modelo: menú desplegable con los modelos locales y externos que aún no están en el paquete. El modelo añadido entra al final de la cadena en modo Sync y habilitado.
• Eliminar modelo (×): visible al pasar el cursor sobre la insignia. Solo aparece cuando el paquete tiene más de un modelo; un paquete no puede quedar vacío.
• Reglas de detección (engranaje en yolo-v8-pose): permite activar las reglas Posición de Disparo y Brazos Arriba directamente desde la tarjeta.
• Endpoints webhook: si el paquete tiene endpoints, se listan con su ruta (/api/webhook/<ruta>) y un botón de eliminar que aparece al pasar el cursor —sin confirmación.
• Ver flujo: abre el panel lateral del paquete (ver siguiente sección).
• Eliminar: abre el diálogo de confirmación.

Cuando hay más de seis paquetes, aparece una paginación inferior con flechas y el indicador Página X de Y (6 por página).

Tarjetas de flujos

Tarjeta de paquete: insignias de modelos con reglas, menú Agregar modelo, endpoints y acciones Ver flujo/Eliminar.

Panel del paquete (Ver flujo)

El botón Ver flujo abre un panel lateral derecho con el nombre del paquete, su estado y tres pestañas.

Pestaña Flujo

Es el editor completo del pipeline del paquete:

• Orden de ejecución: los modelos se muestran como tarjetas numeradas conectadas por flechas hasta el bloque Resultado del Análisis. Puedes arrastrar y soltar una tarjeta para cambiar su posición; el nuevo orden se guarda automáticamente en el pipeline y es el orden en que se ejecutan los modelos sobre cada imagen.
• Habilitar/deshabilitar: el interruptor superior de cada tarjeta excluye el modelo de la cadena sin quitarlo del paquete.
• Modo de ejecución: cada modelo puede alternarse entre Sync (bloqueante, el resultado se encadena al siguiente modelo) y Async (se ejecuta en segundo plano sin bloquear la cadena).
• Expandir (cheurón): cada tarjeta se despliega para mostrar las opciones específicas del modelo:
  • Umbral de confianza: deslizador del 10 % al 100 % en pasos del 5 %.
  • Clases a detectar (solo yolo-world): selector de prompts de vocabulario abierto con clases predefinidas y gestor de paquetes de prompts (detalle abajo).
  • Detección de aglomeraciones (solo yolo-v8): activa el análisis de multitudes y define el umbral de personas.
• Guardar descripciones de LLaVA: interruptor que activa o desactiva la indexación de descripciones LLaVA para este paquete.
• Horario: editor de ventana de ejecución (días, hora de inicio/fin, frecuencia). La ventana valida cuándo se aceptan análisis entrantes; no dispara ejecuciones por sí sola. Detalles en Flujos.

Mientras se guardan cambios en el pipeline aparece un indicador Guardando cambios... bajo el encabezado.

Clases a detectar (yolo-world)

Al expandir yolo-world aparece el bloque Clases a Detectar, que define qué objetos busca el modelo de vocabulario abierto en cada imagen:

• Clases predefinidas: siete chips en español — Persona, Vehículo, Automóvil, Camión, Motocicleta, Bicicleta y Perro — que se activan o desactivan con un clic. Internamente se guardan en inglés (person, vehicle, car, truck, motorcycle, bicycle, dog), que es el idioma que espera el modelo.
• Prompts personalizados: los prompts activos que no pertenecen a los predefinidos (por ejemplo, los que llegan desde un paquete) se muestran como chips naranjas y se quitan individualmente con la ×.
• Prompts activos: línea inferior que lista el conjunto exacto que recibirá el modelo. Si no hay ninguna clase seleccionada se muestra el aviso Selecciona al menos una clase para que el modelo funcione.
• Paquete activo: cuando las clases seleccionadas coinciden exactamente con un paquete guardado, junto al título aparece una insignia con el nombre de ese paquete.

Paquetes de prompts

El botón Gestionar paquetes abre el diálogo Paquetes de Prompts, que permite crear conjuntos reutilizables de clases y asignarlos al modelo en un solo paso:

1. Nuevo paquete: despliega el formulario con Nombre (obligatorio), Descripción (opcional) y el campo Prompts (en inglés).
2. Agregar prompts: escribe la palabra y pulsa Enter o el botón +. Cada prompt se normaliza a minúsculas, se ignoran los duplicados y se muestra como chip con su × para quitarlo antes de guardar.
3. Guardar solo se habilita cuando el paquete tiene nombre y al menos un prompt; Cancelar cierra el formulario sin guardar.
4. La lista muestra cada paquete con su descripción y sus prompts, más tres acciones:
   • Seleccionar: reemplaza las clases del modelo por todos los prompts del paquete. Si el paquete ya está aplicado, el botón cambia a Deseleccionar y vacía la lista de clases.
   • Editar (lápiz): abre el mismo formulario con los datos cargados.
   • Eliminar (papelera): borra el paquete sin confirmación. No altera los prompts ya asignados a los modelos: la asignación copia los prompts en la configuración del modelo, no los vincula al paquete.

Los paquetes son globales (/api/prompt-packages): el mismo conjunto puede asignarse a yolo-world en cualquier paquete o pipeline. Ten en cuenta que Seleccionar sustituye las clases actuales del modelo — no las suma — y que quitar el paquete con Deseleccionar deja el modelo sin clases, por lo que habrá que elegir otras antes de guardar.

Paquetes de prompts

Pestaña Endpoints

Lista los endpoints webhook asociados al paquete, cada uno con:

• Insignia de estado (activo/inactivo).
• La ruta del endpoint y un botón para copiar la URL completa al portapapeles (dominio actual + ruta).
• La URL de callback configurada, si existe.
• Botón de eliminar sin confirmación.

Pestaña Estadísticas

Muestra cuatro métricas del paquete:

• Análisis totales, Tasa de éxito, Tiempo promedio (la API actualmente devuelve 0, por lo que la interfaz muestra N/A) y Último uso.
• Ficha con descripción, modelos incluidos, endpoints y fecha de creación.

Panel del paquete

Pestaña Flujo: cadena de modelos numerados con flechas de ejecución, interruptores y opciones expandidas.

Pestaña Endpoints: endpoints del paquete con estado, botón de copia de la URL y eliminación.

Pestaña Estadísticas: análisis totales, tasa de éxito, tiempo promedio y ficha informativa del paquete.

Eliminar un flujo

1. En la tarjeta del paquete, haz clic en Eliminar.
2. Confirma en el diálogo ¿Estás seguro?, que muestra el nombre del paquete.

Al confirmar, el servidor elimina el paquete junto con sus resultados de análisis, el pipeline asociado y los endpoints vinculados. Esta operación no se puede deshacer.

Los modelos externos usan el mismo diálogo de confirmación; los endpoints se borran directamente al hacer clic en el icono de papelera.

Seguimiento global de objetos

La tarjeta inferior Seguimiento global de objetos controla el sistema Vision Tracking de toda la instancia:

• Interruptor: activa o desactiva el seguimiento (POST /api/system/vision-tracking).
• Estado: punto verde Activo o gris Deshabilitado.
• Cámaras activas y Seguimientos activos: contadores en vivo.
• Modelo: nombre del modelo de seguimiento cargado actualmente.

El estado se actualiza automáticamente cada 10 segundos; mientras se consulta o se aplica el cambio, el interruptor queda deshabilitado.

Validaciones y mensajes frecuentes

Situación	Mensaje / comportamiento
Crear flujo sin nombre o sin modelos	Se requiere un nombre y al menos un modelo
Descubrir modelo externo sin URL	Introduce la URL de un modelo
JSON inválido en la edición del modelo externo	JSON inválido en el campo de configuración
Probar inferencia sin imagen	Selecciona una imagen
Fallo de la API del modelo externo	Insignia Error + mensaje devuelto por la plataforma
Paquete con un solo modelo	La insignia no muestra el botón de quitar
Endpoint sin callback	Solo se muestra la ruta; no hay URL de callback que copiar

Relación con otros módulos

• Flujos: la página /flows crea pipelines independientes (sin paquete). Aquí se administran los pipelines vinculados a paquetes, que además tienen endpoints, horario y estadísticas.
• Dashboard: los paquetes activos y endpoints creados aquí alimentan los indicadores y análisis recientes del Dashboard.
• Análisis: el orden de modelos y sus umbrales configurados aquí determinan los resultados que luego se revisan en Análisis.