Elasticsearch

Este componente, Elasticsearch, te permite conectar tu sistema Nappai con una base de datos de Elasticsearch para almacenar, organizar y buscar documentos de manera inteligente. Actúa como una “memoria” vectorial, lo que significa que no solo busca palabras clave exactas, sino que entiende el significado y la intención detrás de tus preguntas (búsqueda semántica).

Es ideal si ya utilizas Elasticsearch para gestionar tus datos y quieres que tus asistentes de IA puedan leer, responder y trabajar con esa información de forma rápida y precisa.

¿Cómo funciona?

Internamente, este componente prepara a Elasticsearch para trabajar con “vectores” (representaciones numéricas de texto). El proceso sigue estos pasos sencillos:

Conexión: El nodo se conecta a tu servidor de Elasticsearch usando la dirección URL o el ID de nube que proporciones.
Preparación: Asegura que el “índice” (el lugar donde se guardan los datos) exista y esté configurado para aceptar datos vectoriales. Si la configuración no existe, puede crearla automáticamente.
Almacenamiento (Ingesta): Si le envías documentos nuevos, los convierte en un formato que Elasticsearch puede leer y los guarda en tu índice.
Búsqueda Inteligente: Cuando haces una pregunta, el componente convierte tu texto en un vector utilizando un modelo de inteligencia artificial (Embedding) y busca los documentos más similares en tu base de datos.
Filtrado Avanzado: Además de buscar por similitud, puedes aplicar filtros estrictos (por ejemplo: “solo buscar en documentos de la categoría ‘Finanzas’ del año 2023”) para refinar los resultados.

Conexión y Credenciales

Este componente requiere configurar previamente una credencial en el panel de Nappai para poder interactuar con tu servicio Elasticsearch:

Dirígete a la sección de Credenciales en tu panel de Nappai.
Crea una nueva credencial del tipo Elasticsearch y guarda los campos requeridos (como la URL base, nombre de usuario, contraseña o Clave API).
En tu flujo de trabajo, selecciona la credencial guardada en el campo de entrada Credential de este nodo.

Operaciones

Este componente ofrece varias operaciones que puedes seleccionar según lo que necesites hacer. Solo puedes usar una operación a la vez:

Add: Permite introducir nuevos documentos o información en tu índice de Elasticsearch.
Search: Busca documentos en Elasticsearch basándose en una pregunta o consulta de texto.
Retriever: Configura el nodo como un dispositivo de recuperación de información para que otros componentes (como un chatbot) puedan acceder a tus datos automáticamente.

Para usar el componente, primero selecciona la operación que necesitas en el campo “Operation” (Operación).

Entradas

Este componente cuenta con un modo especial llamado “Mapping Mode” (Modo de Mapeo). Cuando activas este modo mediante el interruptor, se habilita una entrada adicional llamada “Mapping Data” y cada campo de entrada te ofrece tres formas diferentes de proporcionar datos:

Fixed (Fijo): Escribes el valor directamente en el campo.
Mapped (Mapeado): Conectas la salida de otro componente para usar su resultado como valor.
Javascript: Escribes código Javascript para calcular el valor dinámicamente.

Esta flexibilidad te permite crear flujos de trabajo más dinámicos y conectados.

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente. Cada campo puede estar visible en diferentes operaciones:

Operation: Selección de la acción que realizará el nodo.
- Visible en: Add, Search, Retriever
Embedding: El modelo de inteligencia artificial encargado de entender el lenguaje para crear las comparaciones vectoriales.
- Visible en: Add, Search, Retriever
Ingest Data: Los documentos o texto que deseas guardar en Elasticsearch.
- Visible en: Add
Elastic Cloud ID: Identificador único para conexiones en la nube de Elastic (usa esto en lugar de la URL si estás en la nube).
- Visible en: Add, Search, Retriever
Index Name: El nombre del “archivo” o índice donde se guardarán y buscarán tus datos en Elasticsearch.
- Visible en: Add, Search, Retriever
Number of Results: Cuántos documentos como máximo deseas obtener al buscar.
- Visible en: Add, Search, Retriever
Search Query: El texto o pregunta específica que deseas buscar.
- Visible en: Search
Search Score Threshold: El nivel mínimo de precisión requerido para considerar un resultado válido.
- Visible en: Add, Search, Retriever
Search Type: El método que se usará para encontrar los resultados más relevantes (Similitud básica, Umbral de puntuación o MMR para mayor diversidad).
- Visible en: Add, Search, Retriever

Salidas

El componente devuelve resultados dependiendo de la operación seleccionada, permitiéndote continuar con el flujo de trabajo:

Retriever: Un objeto preparado para servir datos a otros componentes (útil para Chatbots).
Results: La lista de documentos encontrados y su puntuación de relevancia al realizar una búsqueda.
Vector Store: El estado de la conexión con el almacenamiento vectorial.

Ejemplo de Respuesta JSON

Al realizar una operación Search, recibirás un resultado similar a este: json [ { “page_content”: “El informe financiero del 2023 muestra un crecimiento del 15%.”, “metadata”: { “year”: 2023, “department”: “Finanzas” }, “score”: 0.85 }, { “page_content”: “Resumen anual de ventas: Incremento significativo en el sector tech.”, “metadata”: { “year”: 2023, “department”: “Ventas” }, “score”: 0.78 } ]

Conectividad

Este componente se integra naturalmente con flujos de gestión de conocimiento:

Entradas: Suele recibir documentos de nodos como File Loader, Text Splitter o Chat Messages que necesitan ser almacenados para su posterior análisis.
Salidas: Conecta frecuentemente con nodos de LLM (Modelos de Lenguaje) para proporcionar contexto a un chatbot, o con nodos de Output para mostrar los resultados de la búsqueda al usuario final.

Ejemplo de Uso

Escenario: Crear un asistente para responder preguntas sobre manuales técnicos.

Operación Add: Conecta un archivo PDF o texto al nodo Elasticsearch con la operación Add para “enseñarle” al sistema los manuales.
Operación Search: En otro flujo, cuando un usuario hace una pregunta (ej. “¿Cómo reinicio el sistema?”), envía esa pregunta al nodo con la operación Search.
Resultado: El nodo busca las secciones más similares en los manuales guardados y devuelve el texto relevante, que luego puedes enviar a un Chatbot para que responda al usuario.

Notas Importantes

🔒 Security 🟡 Secure Credential Storage: Guarda las credenciales (usuario, password, API Key) en las opciones seguras de Nappai. Nunca las escribas directamente en el código o en el flujo si puedes evitarlo. 🟢 Avoid Hard‑coding Secrets: No incluyas contraseñas directamente en el componente; usa siempre la sección de Credenciales.

⚠️ Limitation 🔴 Development‑Stage Component: Este nodo está en etapa de desarrollo. Puede tener errores menores o funciones no probadas. Úsalo con precaución en entornos de producción crítica. 🟡 Cloud ID and URL Conflict: No uses la ID de la nube (Cloud ID) y una URL local al mismo tiempo. Elige solo uno. 🟡 Score Threshold Filtering: Si pones el umbral de puntuación muy alto, es posible que el sistema no devuelva ningún resultado. Empieza bajo e sube si es necesario. 🟡 All-Docs Retrieval Cost: Recuperar todos los documentos sin una búsqueda específica puede ser lento y consumir muchos recursos. Siempre intenta usar una consulta. 🟢 Default Index Name Collision: El nombre por defecto es “langflow”. Si ya tienes un índice con ese nombre, podrías confundir tus datos. Usa nombres únicos. 🟢 Input Data Type Requirement: Solo acepta objetos de datos (Data) para guardarlos. Si intentas enviar otros tipos, dará error.

📋 Requirement 🔴 Elasticsearch Cluster Availability: Tu servidor Elasticsearch debe estar encendido y accesible por la red. 🟡 Valid Embedding Provider: Necesitas conectar un modelo de “Embeddings” (como OpenAI o similar) para que el componente funcione; de lo contrario, no podrá buscar. 🟡 Vector Field Configuration: Asegúrate de que tu índice en Elasticsearch tenga configurado un campo vectorial correctamente antes de intentar guardar datos.

💡 Best Practice 🟢 Use API Key for Elastic Cloud: Si usas la nube de Elastic, es mejor y más seguro usar la Clave API que usuario/contraseña. 🟡 Align Embeddings with Index Mapping: Asegúrate de que las herramientas de embedding que usas coincidan con la configuración de tu índice para obtener mejores resultados. 🟡 Choose Search Type Wisely: Usa “Similarity” para búsquedas estándar. Usa “MMR” si quieres resultados variados y no repetitivos. 🟡 Limit Number of Results: Mantén un número razonable de resultados (por defecto 4) para evitar respuestas largas y lentas. 🟡 Adjust Score Threshold Carefully: Comienza con un umbral bajo para asegurar que encuentres algo, y ábrelo gradualmente si necesitas más precisión.

⚙️ Configuration 🟡 Elastic Cloud Connection: Si usas la nube, solo usa el Cloud ID y la API Key. 🟡 Local Cluster Connection: Si es local, usa la URL (http://localhost...) y credenciales estándar. 🟡 Network Connectivity: Verifica que tu red permita salir hacia la dirección de Elasticsearch.

ℹ️ Behavior 🟢 Document Ingestion Timing: Los documentos se guardan al “construir” el flujo. Si cambias los datos después, tendrás que reconstruir el nodo para que se actualice. 🟡 Search Result Structure: Los resultados incluyen el texto, metadatos y una puntuación de similitud. 🟡 Error Handling: Si el servidor no responde o no encuentra nada, el nodo te mostrará un mensaje de error descriptivo.

Consejos y Mejores Prácticas

Si estás usando Elastic Cloud, asegúrate de omitir la URL local y solo usar el Elastic Cloud ID y la API Key de tus credenciales.
Utiliza un Index Name único por proyecto para evitar que los datos de diferentes herramientas se mezclen.
Si los resultados de búsqueda son irrelevantes, ajusta el Search Score Threshold o elige un modelo de Embedding diferente.
Para flujos de agentes, la operación Retriever es especialmente útil para dar contexto al modelo antes de generar una respuesta.

Consideraciones de Seguridad

Nunca expongas tus claves API en las salidas del nodo.
Asegúrate de que tu servidor Elasticsearch tenga reglas de firewall adecuadas para que solo Nappai pueda acceder a él.
Usa verify_certs (SSL) en entornos de producción para asegurar que la conexión sea cifrada y segura.