Neo4j

El componente Neo4j actúa como un puente inteligente entre tu sistema de automatización Nappai y una base de datos de grafos Neo4j. Su propósito principal es permitirte gestionar tu conocimiento almacenado: puedes guardar (ingresar) nuevos documentos para que la IA los recuerde o buscar información específica basada en el significado de tus preguntas, no solo en palabras clave exactas.

Es una herramienta poderosa que combina la estructura de una base de datos tradicional con la capacidad de la inteligencia artificial para entender contexto y similitudes.

¿Cómo funciona?

Imagina que este componente es un bibliotecario especializado. Tiene dos formas principales de ayudarte:

1. Guardar Información (Ingestión): Cuando le entregas documentos, el componente los analiza, los convierte en un formato que la computadora puede entender (vectores) y los guarda en tu base de datos Neo4j. De esta manera, la base de datos “aprende” el contenido.
2. Encontrar Información (Búsqueda/Retrieval): Cuando haces una pregunta, el componente busca en la base de datos las respuestas que sean más parecidas en significado a tu pregunta. Utiliza un modelo de “embedding” (una forma de traducir texto a números matemáticos) para hacer esta comparación inteligente.

El componente es flexible: puede simplemente leer de una base de datos existente o puede crear y actualizar esa base de datos con nueva información, dependiendo de cómo lo configures.

Conexión y Credenciales

Este componente requiere configurar previamente una credencial en el panel de Nappai para poder interactuar con tu servidor de Neo4j.

1. Dirígete a la sección de Credenciales en tu panel de Nappai.
2. Crea una nueva credencial del tipo Neo4j API y guarda los campos requeridos (Neo4j URL, Username y Password).
3. 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: Esta opción se utiliza para guardar o ingresar nuevos documentos en tu base de datos Neo4j. Es útil cuando quieres que el sistema “aprenda” nueva información.
• Search: Esta opción sirve para buscar información específica dentro de la base de datos basada en una consulta de texto. Es ideal para responder preguntas usando la información almacenada.
• Retriever: Esta opción actúa como un enlace directo para recuperar documentos relevantes. Es especialmente útil cuando quieres conectar este componente directamente con otros que necesitan leer datos, como un modelo de lenguaje para generar respuestas.

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

Entradas

Campos de Entrada

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

• Embedding: Es el “cerebro” que traduce el texto en números matemáticos para que la base de datos pueda entenderlo y compararlo. Necesitas proporcionar un modelo de incrustación (embedding) para que la búsqueda o el guardado funcionen correctamente.
  • Visible in: Add, Search, Retriever
• Ingest Data: Son los documentos o textos que quieres guardar en la base de datos. Solo es necesario si vas a guardar nueva información.
  • Visible in: Add
• Operation: Permite elegir qué acción quieres realizar con el componente (Guardar, Buscar o Recuperar).
  • Visible in: Add, Search, Retriever
• Embedding Node Property: Es el nombre de la propiedad en la base de datos donde se guardan los “vectores” (las representaciones numéricas del texto). Debe coincidir con cómo están organizados tus datos en Neo4j.
  • Visible in: Add, Search, Retriever
• Node Label: Es la etiqueta que identifica qué tipo de nodos (elementos) en la base de datos contienen el texto que quieres buscar o guardar. Ayuda a enfocar la búsqueda en el tipo correcto de datos.
  • Visible in: Add, Search, Retriever
• Search Query: Es la pregunta o frase que quieres buscar. El componente encontrará los documentos más similares a esta frase.
  • Visible in: Search
• Text Node Properties: Son las propiedades específicas de los nodos donde está escrito el texto que quieres recuperar. Ayuda al componente a saber exactamente dónde leer el contenido dentro de los nodos de la base de datos.
  • Visible in: Add, Search, Retriever

Salidas

El componente produce resultados que puedes utilizar en el resto de tu flujo de trabajo:

• Retriever: Un objeto que puede ser conectado a otros componentes para proporcionarles acceso a la información recuperada de Neo4j.
• Results: La lista de documentos encontrados que coinciden con tu búsqueda. Estos son los datos reales que la IA encontró.
• Vector Store: La conexión activa a la base de datos, que puede usarse internamente para mantener el estado de la búsqueda o ingesta.

Ejemplo de Respuesta JSON

Cuando utilizas la operación Search y encuentras documentos, la salida Results tendría una estructura similar a esta (simplificada para ilustración): json [ { “page_content”: “Nappai es un sistema de automatización de IA que ayuda a gestionar datos.”, “metadata”: { “source”: “docs/nappai_overview.txt”, “score”: 0.95 } }, { “page_content”: “La automatización de procesos mejora la eficiencia en el manejo de información.”, “metadata”: { “source”: “docs/automation_benefits.txt”, “score”: 0.88 } } ]

En este ejemplo, los resultados muestran el contenido del texto encontrado (page_content) y metadatos sobre de dónde vino y qué tan relevante es (score).

Conectividad

Este componente es versátil y se conecta lógicamente con diferentes partes de tu flujo:

1. Hacia Componentes de IA (LLMs): Una vez que buscas información, es común enviar los resultados (Results) a un modelo de lenguaje para que genere una respuesta basada en esos datos.
2. Desde Componentes de Carga de Datos: Si usas la operación Add, este componente suele recibir documentos desde nodos anteriores que cargan archivos PDF, sitios web o bases de datos.
3. Hacia Componentes de Recuperación: La salida Retriever se conecta frecuentemente a componentes que necesitan “leer” datos en tiempo real, como asistentes de chat o analizadores de documentos.

Ejemplo de Uso

Escenario: Crear un Asistente de Preguntas y Respuestas (QA) sobre Manuales

1. Fase de Carga (Add):

   • Conectas un componente que lee manuales de usuario.
   • Conectas la salida a este componente Neo4j.
   • Seleccionas la operación Add.
   • Asegúrate de configurar la Embedding y las propiedades de nodo correctamente.
   • Resultado: Los manuales se guardan en Neo4j.

2. Fase de Consulta (Search):

   • Conectas una caja de texto donde el usuario escribe su pregunta (ej: “¿Cómo reinicio el sistema?”).
   • Conectas esa caja a este componente Neo4j en el campo Search Query.
   • Seleccionas la operación Search.
   • El componente busca las respuestas más similares en los manuales guardados.
   • Conectas la salida Results a un componente de LLM para que lea esos resultados y genere una respuesta final para el usuario.

Notas Importantes

🔒 Security Ensure Embedding Property Matches Graph The embedding_node_property input must correspond to the property name that stores the embedding vectors in your Neo4j nodes. If it is incorrect, similarity searches will not find matching documents. (Medium)

⚠️ Limitation Default Index Name May Conflict If you do not provide an index name, the component uses the default ‘nappai_neo4j_index’. Using this name on a database that already contains an index with the same name could overwrite existing data or produce unexpected results. (Medium)

⚠️ Limitation Node Properties Must Match Graph Schema For graph‑based retrieval, the node_label and comma‑separated text_node_properties must exactly match the labels and properties in your Neo4j graph. Mismatched names will prevent the component from locating documents. (Medium)

📋 Requirement Neo4j Server Must Be Accessible The component connects to a running Neo4j instance via the provided URL, username, and password. Ensure the server is online and reachable from your network before using the component. (High)

📋 Requirement Embedding Model Required An embedding model must be supplied to the component. The embeddings must match the dimensionality expected by Neo4j’s vector index; otherwise, indexing or search will fail. (High)

📋 Requirement Index Existence for Retrieval When using the component in only‑retriever mode, the specified Neo4j vector index must already exist. If it does not, the component will fall back to a default index or fail to retrieve results. (Medium)

💡 Best Practice Specify Node Label and Properties for Efficient Retrieval When using only_retriever, providing node_label and text_node_properties limits the search to relevant nodes, improving performance and reducing memory usage. (Low)

💡 Best Practice Use Secure Storage for Credentials Never hard‑code Neo4j credentials in source files. Store them in environment variables or a secrets manager and reference them securely to protect against accidental exposure. (High)

ℹ️ Behavior Empty Query Returns No Results If the search_query input is empty or not a non‑blank string, the component will return an empty list instead of performing a search. Always provide a valid query string to retrieve documents. (Low)

Consejos y Mejores Prácticas

• Verifica tu Conexión: Antes de construir flujos complejos, asegúrate de que tu servidor Neo4j esté accesible y que las credenciales sean correctas.
• Sé Preciso con las Etiquetas: Si usas nodos personalizados en tu base de datos Neo4j, asegúrate de que los nombres de las etiquetas (Node Labels) y propiedades coincidan exactamente con lo que hay en tu base de datos.
• Usa el Modo Adecuado: Si solo quieres buscar en datos existentes, usa el modo de recuperación (Retriever/Search). Si necesitas añadir nuevos datos, usa el modo Add. No mezcles innecesariamente ambas acciones en un solo paso a menos que sea necesario.
• Gestiona las Credenciales Seguramente: Utiliza siempre la sección de credenciales de Nappai en lugar de escribir las contraseñas directamente en el flujo de trabajo.

Consideraciones de Seguridad

Asegúrate de nunca exponer tus contraseñas de Neo4j en el código visible del flujo. Utiliza siempre la integración de credenciales seguras de Nappai. Además, evita usar el nombre de índice por defecto (nappai_neo4j_index) si ya existe un índice crítico con ese nombre en tu base de datos para prevenir la sobrescritura accidental de datos.