Saltearse al contenido
Nappai Documentation

Entities extraction

Bienvenido al componente Entities extraction dentro del sistema de automatización Nappai. Este componente actúa como un “asistente de lectura inteligente” para tus datos. Su propósito principal es analizar un documento o conjunto de información (el Data) y devolver solo la información específica que tú le pidas, como nombres, fechas, montos o categorías, presentándola de una manera estructurada y fácil de usar para los siguientes pasos de tu automatización.

¿Cómo funciona?

Imagina que tienes un documento largo y necesitas encontrar rápidamente ciertos datos (por ejemplo, “extraer todos los nombres de clientes y sus direcciones”). En lugar de que un humano lea todo el texto, este componente envía el documento a un Modelo de Lenguaje (LLM), una inteligencia artificial especializada en comprender el lenguaje humano.

  1. Análisis: La IA recibe tu documento de datos y tus instrucciones sobre qué buscar (Extract keys).
  2. Procesamiento: Utiliza el modelo de lenguaje seleccionado para leer y entender el texto, buscando patrones que coincidan con lo que necesitas.
  3. Extracción: Devuelve una lista organizada con solo la información encontrada, eliminando el “ruido” del texto original.

Este proceso puede ocurrir de dos formas: directamente en tu flujo de trabajo como un paso de proceso de datos, o como una “herramienta” que puede ser usada por otros agentes de IA dentro de Nappai.

Conexión y Credenciales

Este componente no requiere credenciales directas en su configuración. Sin embargo, es fundamental entender que funciona conectándose a un Modelo de IA (Model).

Para que este componente funcione, debes conectarlo a otro nodo que haya configurado previamente un modelo de lenguaje (como OpenAI, HuggingFace, o un modelo local).

  1. Asegúrate de tener un nodo de Model configurado en tu flujo.
  2. Conecta la salida de ese nodo Model a la entrada Model de este componente Entities extraction.
  3. Sin esta conexión, el componente no tendrá “cerebro” para realizar la extracción.

Entradas

Los siguientes campos están disponibles para configurar este componente. Algunos son obligatorios, mientras que otros son opcionales y ayudan a refinar el resultado.

  • Data: [El objeto de datos principal que deseas analizar. Puede ser texto, documentos o estructuras de información. Es la materia prima que la IA leerá].

    • Visible en: Todas las operaciones

  • Model: [La conexión al modelo de inteligencia artificial que realizará el análisis. Debe ser un modelo compatible con LangChain].

    • Visible en: Todas las operaciones

  • Extract keys: [Una lista de las entidades o datos específicos que quieres extraer. Por ejemplo: “Name”, “Email”, “Amount”. Es la instrucción principal sobre qué buscar].

    • Visible en: Todas las operaciones

  • Additional instructions: [Instrucciones adicionales opcionales para guiar a la IA. Puedes usarlas para darle contexto, como “ignorar fechas pasadas” o “priorizar nombres comerciales”].

    • Visible en: Todas las operaciones

  • Output instructions: [Instrucciones específicas sobre el formato deseado para la salida. Por ejemplo, “devuelve solo en formato JSON” o “usa una lista separada por comas”].

    • Visible en: Todas las operaciones

  • chunk size: [Tamaño máximo (en caracteres) de cada fragmento de texto que se envía al modelo. Útil para textos muy largos. El valor predeterminado es 1500].

    • Visible en: Todas las operaciones

  • chunk overlap: [Número de caracteres que se repiten entre un fragmento y el siguiente para mantener el contexto. El valor predeterminado es 150].

    • Visible en: Todas las operaciones

Salidas

El componente produce dos tipos de salidas que puedes conectar a otros nodos:

  1. Extracted Data: Es la salida principal. Contiene una lista de datos estructurados con la información que extraiste (ej. una lista de clientes con sus nombres y emails). Esta salida es la que normalmente conectarás a otros nodos para guardar en una base de datos, enviar un correo o generar un reporte.
  2. Tool: Es una versión “empaquetada” de esta funcionalidad que puede ser usada como una herramienta por otros agentes de IA dentro de Nappai. Úsalo si estás creando un flujo donde un agente principal llama a esta función como un servicio.

Ejemplo de Respuesta JSON

El campo Extracted Data devolverá una lista de objetos. Aquí tienes un ejemplo de lo que podrías recibir después de extraer clientes de un texto: json [ { “name”: “Juan Pérez”, “email”: “juan.perez@ejemplo.com”, “company”: “Tech Solutions”, “status”: “Active” }, { “name”: “María López”, “email”: “maria.lopez@ejemplo.com”, “company”: “Design Studio”, “status”: “Pending” } ]

Conectividad

Este componente actúa como un puente entre datos crudos y procesos estructurados.

  • Conexión de Entrada (Input): Debes conectar obligatoriamente un Model (IA) y un objeto Data (texto/documento). Lógicamente, este componente suele colocarse después de nodos que recopilan texto (como lectura de correos, web scraping o subida de archivos) y antes de nodos que requieren datos limpios (como bases de datos o generadores de respuestas).
  • Conexión de Salida (Output):
    • Extracted Data: Conéctalo a nodos de Base de Datos, Email, o Conditional (para tomar decisiones basadas en los datos extraídos).
    • Tool: Conéctalo a nodos de tipo Agent o Tool Executor que necesiten realizar una tarea de extracción específica como parte de una acción más compleja.

Ejemplo de Uso

Escenario: Automatización de Facturas

  1. Tienes un flujo que recibe correos electrónicos de proveedores.
  2. Conectas el texto del correo al Data de Entities extraction.
  3. En Extract keys, escribes: ["Invoice Number", "Date", "Total Amount", "Vendor Name"].
  4. El componente analiza el correo y devuelve en Extracted Data solo esos 4 datos.
  5. Conectas Extracted Data a un nodo de Google Sheets para guardar esas facturas en una tabla.

Notas Importantes

🔒 Sensitive data is sent to the LLM [🔴 high] All extracted data is processed by the supplied language model. Ensure the model runs in a secure, privacy‑compliant environment if handling confidential information.

📋 Provide a LangChain-compatible LLM [🔴 high] The component requires a LanguageModel instance that implements the LangChain interface. Without a valid model, extraction will fail.

⚠️ Data size may affect performance [🟡 medium] Large Data objects are split into 1,500‑character chunks by default. Extremely large inputs can increase processing time and memory usage. Consider pre‑splitting or reducing size before use.

📋 Component is in development [🟡 medium] Marked as is_development=True, the component may have bugs or incomplete features. Use with caution in production workflows.

💡 Specify precise entity keys [🟢 low] List exact entity names you want extracted in filter_criteria. Vague or misspelled keys will result in missing data. Double‑check spelling and structure.

💡 Adjust chunk size for long texts [🟡 medium] The default chunk_size is 1,500 characters. For very long documents, increasing this value can reduce the number of LLM calls, improving speed. Too large a value may exceed model limits.

⚙️ Hidden advanced inputs may be overlooked [🟢 low] Inputs like additional_context, output_format, chunk_size, and chunk_overlap are hidden by default. They are still configurable but not shown in the basic UI. Enable advanced settings if you need fine‑tuning.

⚙️ Output format applies only to async extraction [🟢 low] When using the tool directly (run_tool), the output_format input is ignored. The async method (extracted_entities_data) supports custom output formatting. Use the appropriate method depending on your workflow.

Consejos y Mejores Prácticas

  • Sé específico en los Extract keys. En lugar de pedir “datos de cliente”, pide “Nombre Completo”, “Teléfono” y “Dirección”. La IA será más precisa con instrucciones claras.
  • Si el documento es muy largo, el componente lo dividirá en trozos (chunks). Si notas que falta información al final, intenta ajustar el chunk size y chunk overlap en la configuración avanzada.
  • Usa Additional instructions para corregir errores comunes. Por ejemplo, si la IA confunde fechas con números, añade una instrucción como: “Asegúrate de distinguir entre fechas y cantidades numéricas”.

Consideraciones de Seguridad

Dado que este componente envía tus datos al modelo de IA externo para su procesamiento, es crucial:

  1. Verificar que el modelo que conectes cumple con las políticas de privacidad de tu organización.
  2. Evitar enviar información sensible (como contraseñas, datos bancarios completos o información médica protegida) si no estás seguro de que el proveedor del modelo la almacene o utilice para entrenar sus modelos.
  3. Revisar los datos extraídos en el nodo siguiente para garantizar que no se hayan incluido datos sensibles no deseados.