Documentación: Nodo Búsqueda Natural de Eventos (Events Natural Search)¶
Descripción General¶
El Nodo Búsqueda Natural de Eventos (Events Natural Search) es un nodo de la familia de AI Models que permite consultar el registro de eventos de la plataforma usando lenguaje natural. Internamente, un modelo de lenguaje (LLM) traduce tu pregunta en lenguaje cotidiano (por ejemplo, "motion events in the north perimeter camera this week") a una búsqueda estructurada sobre el log de eventos, y devuelve los eventos que coinciden.
En entornos IoT y de seguridad, simplifica enormemente el acceso a la información: en lugar de construir filtros complejos, basta describir lo que se busca, lo que habilita asistentes y automatizaciones que razonan sobre el histórico de eventos.
¿Cuándo usar este nodo?¶
Utiliza este nodo cuando necesites:
- Buscar eventos del histórico describiendo lo que quieres en lenguaje natural.
- Alimentar un Agente o un reporte con eventos relevantes sin construir filtros manualmente.
- Recuperar eventos por criterios complejos (tipo, cámara, fechas relativas) de forma sencilla.
Configuración del Nodo¶
El formulario se organiza en tres secciones seleccionables: Query, LLM Configuration y Advanced. Además, dispone de la pestaña JSON Editor.
Sección: Query (Consulta)¶
1. Consulta (Query) *Requerido¶
La descripción en lenguaje natural de los eventos a recuperar. Soporta expresiones de plantilla ({{trigger.message}}, {{node_key.output}}). Por ejemplo: "motion events in the north perimeter camera this week".
2. Límite (Limit)¶
Número máximo de eventos a devolver en esta ejecución (sobrescribe el Default Limit).
3. Zona Horaria (Timezone)¶
Nombre IANA de la zona horaria (por ejemplo, America/Mexico_City). Se usa para interpretar fechas relativas como "esta semana" o "ayer".
Sección: LLM Configuration (Configuración del Modelo)¶
Define el modelo de lenguaje que interpreta la consulta:
- LLM Provider (Proveedor): OpenAI, Anthropic, Google AI (Gemini), Grok (xAI), DeepSeek, Ollama, AWS Bedrock o Hugging Face.
- Model ID: El identificador del modelo (por ejemplo,
gpt-4o-mini,claude-3-5-sonnet-latest,gemini-1.5-flash). - API Key: La credencial del proveedor seleccionado (gestionada de forma segura). Para Ollama y Bedrock cambian los campos (Base URL, región/credenciales de AWS).
Sección: Advanced (Avanzado)¶
Parámetros finos del proceso de búsqueda/contexto:
- Default Limit / Max Limit: Límites por defecto y máximo de eventos.
- Top Event Types: Cantidad de tipos de evento más frecuentes a considerar como contexto.
- Top Metadata Keys: Cantidad de claves de metadatos más relevantes a considerar.
- Samples per Key: Número de muestras por clave de metadato.
Vista Editor de JSON¶
Estructura JSON (Parámetros de entrada)¶
{
"query": "motion events in the north perimeter camera this week",
"provider": "openai",
"model_id": "gpt-4o-mini",
"api_key": "",
"timezone": "America/Mexico_City"
}
Campos del JSON¶
| Campo | Tipo | Descripción |
|---|---|---|
query |
string | Descripción en lenguaje natural de los eventos a buscar. |
provider |
string | Proveedor del LLM (openai, anthropic, google, grok, deepseek, ollama, bedrock, huggingface). |
model_id |
string | ID del modelo (ej. gpt-4o-mini). |
api_key |
string | Referencia a la credencial del proveedor (gestionada de forma segura). |
limit |
number | (Opcional) Máximo de eventos a devolver en esta ejecución. |
timezone |
string | (Opcional) Zona horaria IANA para fechas relativas. |
default_limit / max_limit |
number | (Avanzado) Límites por defecto y máximo. |
top_event_types / top_metadata_keys / samples_per_key |
number | (Avanzado) Parámetros de contexto para la búsqueda. |
Output: Dónde viene la data del nodo¶
El nodo devuelve en su Output (Salida) la lista de eventos que coinciden con la consulta. Esta salida puede usarse en nodos posteriores con {{node_key}} (por ejemplo, para iterarlos, resumirlos o notificarlos).
Ejemplos de uso¶
Ejemplo 1: Buscar eventos de movimiento de la semana¶
Caso de uso: Recuperar los eventos de movimiento de una cámara específica de la última semana para incluirlos en un reporte.
- Query:
motion events in the north perimeter camera this week - Provider:
openai| Model ID:gpt-4o-mini - Timezone:
America/Mexico_City
(ver estructura JSON anterior)
Ejemplo 2: Alimentar un Agente con eventos relevantes¶
Caso de uso: Un Agente que responde preguntas sobre seguridad usa este nodo (o su herramienta equivalente) para recuperar los eventos pertinentes antes de razonar.
Validación y errores¶
| Condición | Causa / Solución habitual |
|---|---|
| Resultado vacío | Reformula la consulta o amplía el rango temporal; revisa que existan eventos que coincidan. |
| Error de autenticación | La credencial/API Key del proveedor es inválida o sin saldo. |
| Fechas mal interpretadas | Configura correctamente la Timezone para que las fechas relativas se calculen bien. |
Buenas prácticas¶
- Consultas claras: Describe con precisión qué eventos buscas (tipo, ubicación, periodo).
- Configurar la zona horaria: Esencial para interpretar correctamente "hoy", "esta semana", etc.
- Usar credenciales centralizadas: Selecciona una credencial del proveedor gestionada de forma segura.
- Encadenar con Iterar/Notificar: Combina la salida con Iterar elementos, reportes o notificaciones para dar utilidad a los eventos recuperados.