Neo4j CypherQAChain

El componente Neo4j CypherQAChain es una herramienta inteligente dentro del sistema de automatización Nappai que actúa como un puente entre tú y tu base de datos de Neo4j. En lugar de tener que escribir consultas complejas en lenguaje técnico (Cypher), puedes hacer preguntas en un idioma natural (como español o inglés) y el componente utilizará un Modelo de Lenguaje (IA) para entender tu solicitud, traducirla a instrucciones que la base de datos comprenda y devolverte la información deseada.

Es ideal para explorar datos, realizar análisis rápidos o crear interfaces conversacionales donde los usuarios pueden preguntar sobre la información almacenada en tus nodos y conexiones.

¿Cómo funciona?

Este componente utiliza inteligencia artificial para facilitar la lectura de datos. El proceso sigue estos pasos simplificados:

Conexión: Se conecta a tu servidor de base de datos Neo4j usando las credenciales y la configuración que proporciones.
Entendimiento: Cuando escribes una pregunta en el campo de entrada, el componente utiliza un Modelo de Lenguaje (LLM) para analizar el significado de tu pregunta.
Traducción: La IA traduce tu pregunta en lenguaje natural a un código de consulta (Cypher) válido para Neo4j.
Ejecución y Respuesta: Ejecuta la consulta en la base de datos. Dependiendo de cómo lo configures, puede devolver los datos brutos para su procesamiento o generar una respuesta de texto natural y fácil de leer basada en los resultados obtenidos.

Para que esto funcione correctamente, es fundamental que tengas acceso válido a tu base de datos y que el “modelo de inteligencia” (LLM) esté correctamente configurado.

Conexión y Credenciales

Este componente requiere configurar previamente una credencial en el panel de Nappai para poder interactuar con la base de datos Neo4j:

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

Nota de seguridad: Asegúrate de almacenar tus contraseñas y claves de API de forma segura. Nunca compartas archivos de configuración que contengan credenciales en texto plano.

Entradas

Los siguientes campos están disponibles para configurar este componente. Asegúrate de completar todos los campos marcados como requeridos.

Model [REQUERIDO]: Selecciona aquí el componente de Modelo de Lenguaje (LLM) que deseas utilizar para interpretar tus preguntas y generar las consultas. Sin un modelo conectado, el componente no puede funcionar.
Neo4j Database [REQUERIDO]: Especifica el nombre de la base de datos específica dentro de tu entorno Neo4j a la que quieres acceder.
Query [REQUERIDO]: Escribe aquí tu pregunta o instrucción en lenguaje natural. Por ejemplo: “¿Cuáles son los usuarios activos en el último mes?”.
Limit the number of results: Define cuántos resultados máximo deseas obtener. El valor predeterminado es 10. Ajusta este número según la cantidad de datos que necesites; un número muy alto puede ralentizar la respuesta.

Salidas

Este componente te ofrece principalmente una salida de texto procesada para facilitar la lectura de la información.

Text: Devuelve una respuesta en formato de texto plano generada por la IA basada en los datos encontrados. Es ideal para mostrar respuestas conversacionales en un chat o visualización simple.

Ejemplo de Respuesta JSON

A continuación, se muestra un ejemplo de cómo se ve la salida de datos crudos (estructura interna) que puede ser utilizada por otros componentes en flujos avanzados. Cuando se usa la salida “Text”, el sistema convierte esto en una respuesta legible. json [ { “id”: “node_1”, “label”: “User”, “properties”: { “name”: “Ana García”, “status”: “Active”, “last_login”: “2023-10-25” } }, { “id”: “node_2”, “label”: “User”, “properties”: { “name”: “Carlos Ruiz”, “status”: “Active”, “last_login”: “2023-10-26” } } ]

Conectividad

Este componente es versátil y puede conectarse a diversos elementos de tu flujo de trabajo:

Hacia Visualizaciones de Datos: Puedes conectar su salida (especialmente si usas la estructura de datos interna) a componentes de gráficos o tablas para visualizar las relaciones encontradas en Neo4j.
Hacia Generadores de Texto: La salida “Text” puede conectarse a componentes que redacten reportes finales o envíen resúmenes por correo electrónico.
Desde Entradas de Usuario: Es común recibir la pregunta (“Query”) directamente de la salida de un componente de tipo “Input” o “Chatbot”, permitiendo que el usuario interactúe directamente con la base de datos.

Ejemplo de Uso

Imagina que tienes una base de datos de empleados en Neo4j y quieres saber quién trabajó en el proyecto “Alpha”.

Conecta un componente Model (como GPT-4) al campo Model.
Configura la credencial de Neo4j y selecciona la base de datos correcta.
En el campo Query, escribe: "Find all employees who worked on the project 'Alpha'."
Ejecuta el flujo.
El componente generará una consulta Cypher automáticamente, buscará en la base de datos y devolverá una respuesta de texto como: “Los empleados que trabajaron en el proyecto Alpha son: Maria Lopez y John Doe.”

Notas Importantes

🔒 Security Provide Neo4j Connection Details 🟢 High Debes proporcionar una URL, nombre de usuario, contraseña y nombre de base de datos de Neo4j válidos para que el componente pueda conectarse.

🔒 Security Handle Credentials Safely 🟢 High Nunca hardcodees las credenciales de Neo4j en repositorios públicos. Almacénalas en variables de entorno seguras o en el gestor de secretos de Nappai.

📋 Requirement Attach a Language Model 🟢 High Se requiere un Modelo de Lenguaje (LLM) para procesar las consultas. Asegúrate de conectar un modelo compatible antes de ejecutar.

⚠️ Limitation No Automatic Error Recovery 🟡 Medium Las fallas de conexión o errores de sintaxis en la consulta resultarán en excepciones no controladas. Implementa manejo de errores externo si necesitas respuestas alternativas.

🟡 Behavior Direct vs. Text Output Differences 🟡 Medium Ten en cuenta que el componente ofrece dos formas de salida. ‘Data’ devuelve resultados brutos, mientras que ‘Text’ devuelve solo resultados en cadena de texto. Si la consulta produce datos no textuales, la salida de texto estará vacía.

💡 Best Practice Use Specific, Valid Cypher Queries 🟡 Medium Aunque la IA genera la consulta, es mejor escribir preguntas claras y concisas. Consultas demasiado amplias pueden devolver muchos resultados y ralentizar el rendimiento.

💡 Best Practice Set an Appropriate Result Limit 🟢 Low Ajusta el límite de resultados (top_k) para controlar la cantidad de registros. Un número menor reduce el uso de memoria y acelera la respuesta.

⚙️ Configuration Verbose Logging Can Be Verbose 🟢 Low El modo detallado está activado por defecto, lo que genera logs extensos. Desactívalo en producción para mantener los logs limpios.

Consejos y Mejores Prácticas

Asegúrate de que tu modelo de lenguaje (LLM) esté calibrado para entender contextos técnicos si estás haciendo preguntas sobre estructuras de datos complejas.
Utiliza el campo “Limit the number of results” para evitar sobrecargar la memoria si esperas devolver miles de registros.
Revisa siempre las respuestas generadas, especialmente si la base de datos es grande, para asegurar que la IA no ha malinterpretado la pregunta inicial.
Mantén tus credenciales actualizadas si cambias la contraseña de acceso a Neo4j.

Consideraciones de Seguridad

Este componente maneja datos sensibles al interactuar directamente con tu base de datos Neo4j.

Validación de Seguridad: El sistema valida automáticamente la sintaxis de las consultas Cypher para reducir el riesgo de inyección maliciosa. Se recomienda mantener esta validación activada.
Gestión de Credenciales: Las credenciales (URL, Usuario, Contraseña) deben ser gestionadas a través del panel de Credenciales de Nappai. Nunca expongas estas claves en el código visible del flujo de trabajo o en capturas de pantalla compartidas públicamente.
Acceso Restringido: Asegúrate de que el usuario de Neo4j que utilices tenga permisos mínimos necesarios (solo lectura si es posible) para realizar las consultas que necesitas, minimizando el riesgo de modificación accidental de datos.