Saltearse al contenido
Nappai Documentation

Knowledge Graph Builder

Bienvenido al Knowledge Graph Builder de Nappai. Este componente es una herramienta poderosa diseñada para transformar documentos de texto (como informes, artículos o bases de datos) en una red visual estructurada de información.

Utilizando inteligencia artificial avanzada, este componente analiza tus textos para identificar personas, lugares, organizaciones o conceptos (entidades) y comprende cómo se conectan entre sí (relaciones). El resultado es un “Grafo de Conocimiento” que te permite navegar, buscar y entender los datos de una manera más inteligente y conectada.

¿Cómo funciona?

Imagina que tienes una gran cantidad de informes legales o manuales técnicos. Leerlos todos es tedioso y a menudo pierdes las conexiones entre diferentes partes del texto.

El Knowledge Graph Builder actúa como un asistente inteligente que lee estos documentos y crea un mapa mental.

  1. Entrada: Tú le proporcionas los documentos (archivos PDF, texto, URL, etc.) y conectas tu base de datos y tu modelo de IA.
  2. Procesamiento: La inteligencia artificial (llamada LLM) analiza el contenido. Detecta, por ejemplo, que “Empresa A” trabaja con “Persona B” y que ambos están relacionados con “Norma X”.
  3. Salida: Genera una estructura de datos (el grafo) que puedes visualizar o utilizar para responder preguntas complejas sobre la información contenida en tus documentos.

Este componente está diseñado para integrarse en tu panel de Nappai, permitiendo que tus flujos de automatización no solo lean datos, sino que entiendan el contexto entre ellos.

Operaciones

Este componente es versátil y ofrece varias operaciones según lo que necesites hacer. Solo puedes usar una operación a la vez:

  • Add Document: Ingesta y extrae entidades del texto. Ideal para cargar nuevos documentos y construir o actualizar tu grafo.
  • Resolve Entities: Deduplica entidades. Útil para unificar nombres diferentes que se refieren a la misma cosa (ej. “Juan Pérez” y “J. Pérez”).
  • Search: Consulta el grafo utilizando una búsqueda agénica estándar. Útil para encontrar respuestas rápidas basadas en tus documentos.
  • Deep Search: Realiza una investigación autónoma de múltiples pasos con un rol y formato personalizables. Ideal para análisis profundos.
  • Retriever: Obtén un recuperador para cadenas RAG (Generación Aumentada con Recuperación). Perfecto si necesitas integrar este componente con otras herramientas de IA.

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

Entradas

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente. Algunos campos pueden variar su visibilidad dependiendo de la Operación seleccionada.

Campos Comunes y de Configuración:

  • Operation: Selecciona la acción principal que deseas realizar (ej. Add Document, Search, Deep Search).
    • Visible en: Todas las operaciones.
  • Documents: Document(s) to process. Accepts Binary data from file uploads, URLs, or other sources.
    • Visible en: Add Document, Search, Deep Search.
  • Database: Database connection info. Connect a PostgreSQL, MySQL, or other database component configured with ‘DatabaseInfo’ operation.
    • Visible en: Todas las operaciones.
  • Llm: Language model for entity and relationship extraction.
    • Visible en: Todas las operaciones.
  • Embeddings: Embedding model for generating vectors. Embeddings will be stored directly in the database for native vector search.
    • Visible en: Todas las operaciones.

Campos para Búsqueda y Consultas:

  • Search Query: Query text to search in the knowledge graph.
    • Visible en: Search, Deep Search.
  • Search Metadata: Metadata to search in the knowledge graph.
    • Visible en: Search, Deep Search.
  • Agent Role: Persona and backstory for the Deep Agent (e.g. ‘You are an expert Auditor…’). Default: ‘You are an expert Research Assistant powered by a Knowledge Graph.’.
    • Visible en: Deep Search.
  • Output Format Instructions: Specific instructions for the final output format (e.g. ‘Report with Executive Summary’, ‘Legal Brief’).
    • Visible en: Deep Search.

Campos de Avanzado y Personalización:

  • Citation Metadata Fields: Comma-separated list of metadata fields to include in citations (e.g. ‘title, date, url’).
    • Visible en: Search, Deep Search, Retriever.
  • Fast Mode: Use fast embedding-only entity detection (21% faster, same quality).
    • Visible en: Add Document.
  • Section-Aware Chunking: Split markdown documents by section headers (## Header) to preserve semantic boundaries. Improves retrieval quality.
    • Visible en: Add Document.
  • Semantic Hierarchy: Comma-separated hierarchy patterns for section-aware chunking (e.g. ‘TÍTULO,CAPÍTULO,Sección,Artículo’).
    • Visible en: Add Document.
  • Generate Graph Image: Generate a visual image of the knowledge graph.
    • Visible en: Add Document.
  • Domain: Domain label for multi-graph support (e.g., ‘legal_documents’, ‘technical_docs’).
    • Visible en: Add Document, Search.
  • Domain Description: Description of the knowledge domain for context injection (e.g. ‘Spanish Auditing Standards’, ‘Technical Documentation’).
    • Visible en: Add Document, Search.

Notas Importantes sobre Configuración:

  • Database y Llm son campos requeridos para la mayoría de las operaciones. Asegúrate de haber configurado previamente estas conexiones en tu panel de Nappai.
  • Campos como Agent Role y Output Format Instructions son especialmente útiles si seleccionas la operación Deep Search para obtener resultados más personalizados.

Salidas

Al ejecutar el Knowledge Graph Builder, recibirás como salida el grafo de conocimiento construido o los resultados de la búsqueda. Este grafo puede ser mapeado en nodos posteriores para realizar análisis, generar reportes o alimentar otras herramientas de IA.

Ejemplo de Respuesta JSON

El componente devuelve una estructura que refleja las entidades y sus conexiones. Dependiendo de la operación, la salida puede ser un grafo completo o una lista de documentos relevantes.

Ejemplo de salida para una búsqueda o grafo estructurado: json { “nodes”: [ { “id”: “entity_1”, “label”: “Empresa A”, “type”: “Organization”, “properties”: { “description”: “Principal empresa contratante.”, “location”: “Madrid, Spain” } }, { “id”: “entity_2”, “label”: “Juan Pérez”, “type”: “Person”, “properties”: { “role”: “Auditor”, “certification”: “CPA” } } ], “edges”: [ { “source”: “entity_1”, “target”: “entity_2”, “label”: “contracts_with”, “properties”: { “date”: “2023-01-01”, “context”: “Contrato de auditoría anual.” } } ], “metadata”: { “total_entities”: 2, “total_relationships”: 1, “source_documents”: [“doc_1.pdf”] } }

Este JSON te permite entender que la “Empresa A” está conectada a “Juan Pérez” mediante la relación “contracts_with”, lo cual es crucial para el análisis de datos.

Conectividad

Este componente se conecta lógicamente de la siguiente manera en un flujo de trabajo de Nappai:

  1. Entrada (Inputs):

    • Documentos: Se conecta típicamente a componentes que generan o almacenan texto, como “File Reader”, “Web Scraper” o “SQL Query” (para extraer texto de bases de datos).
    • Database: Requiere una conexión a un componente de base de datos (como PostgreSQL o MySQL) que almacene los grafos generados.
    • Llm: Se conecta a un componente de modelo de lenguaje previamente configurado (como OpenAI, Anthropic, etc.).

  2. Salida (Outputs):

    • Grafo de Conocimiento: Puede alimentar componentes de visualización (para ver el grafo), componentes de búsqueda (para hacer preguntas sobre los datos) o otros agentes de IA que necesiten contexto relacional.
    • Resultados de Búsqueda: Se conecta a componentes que redactan respuestas, generan informes o toman decisiones basadas en la información recuperada.

Ejemplo de Uso

Escenario: Análisis de Contratos Legales

Imagina que eres un abogado automatizado que necesita revisar cientos de contratos para identificar partes involucradas y fechas clave.

  1. Carga de Documentos: Usas la operación “Add Document”. Conectas tus archivos PDF de contratos al campo Documents. Configuras Domain como “legal_documents”.
  2. Extracción: El componente extrae “Contratante”, “Proveedor” y “Fecha de Vencimiento” como entidades y crea las relaciones entre ellos.
  3. Búsqueda: Usas la operación “Search”. En el campo Search Query, escribes: “¿Quiénes son los proveedores de la Empresa A en 2023?”.
  4. Resultado: El componente busca en el grafo construido y te devuelve una lista de proveedores y fechas relevantes, con sus fuentes citadas.

Escenario: Investigación Profunda

  1. Operación Deep Search: Para una pregunta compleja como “Analiza los riesgos financieros de las empresas asociadas con la entidad X”, usas Deep Search.
  2. Personalización: En Agent Role, defines: “Eres un analista financiero experto en riesgos”. En Output Format Instructions, solicitas: “Entrega un reporte con tabla de riesgos”.
  3. Resultado: El sistema realiza múltiples pasos de búsqueda y razonamiento, devolviendo un informe estructurado basado en el conocimiento del grafo.

Consejos y Mejores Prácticas

  • Claridad en los Documentos: El grafo resultante depende de la calidad del texto de entrada. Asegúrate de que los documentos sean legibles y estén bien estructurados.
  • Uso de Fast Mode: Si estás cargando grandes volúmenes de documentos y la velocidad es prioritaria sobre la extracción de relaciones complejas, activa Fast Mode para una extracción 21% más rápida.
  • Segmentación (Chunking): Para documentos largos con estructura clara (como libros o manuales), activa Section-Aware Chunking para preservar el contexto de las secciones.
  • Dominios Específicos: Define el campo Domain y Domain Description para ayudar a la IA a entender el contexto específico (ej. “médico”, “legal”), mejorando la precisión de la extracción.
  • Gestión de Entidades: Si identificas duplicados en tus datos (ej. “IBM” y “International Business Machines”), usa la operación Resolve Entities para unificarlos y limpiar tu grafo.

Consideraciones de Seguridad

  • Protección de Datos: Al procesar documentos, asegúrate de no cargar información sensible o confidencial sin la debida anonimización, ya que los LLMs pueden procesar estos datos en la nube.
  • Control de Acceso: Utiliza las credenciales de base de datos y LLM configuradas con permisos mínimos necesarios para evitar accesos no autorizados.
  • Validación de Salidas: Aunque el grafo extraído es muy útil, valida las relaciones críticas antes de usarlas para decisiones automatizadas importantes.

Nota sobre el Estado de Desarrollo: Este componente está actualmente en fase de desarrollo (is_development = True). Esto significa que su comportamiento o interfaz puede cambiar en futuras actualizaciones. Te recomendamos revisar las notas de lanzamiento de Nappai para estar al tanto de nuevas funciones o cambios.