Saltearse al contenido
Nappai Documentation

RestApi Retriever

⚠️ ADVERTENCIA DE DEPRECACIÓN

Este componente está deprecado y será eliminado en una versión futura de Nappai. Por favor, migra a los componentes alternativos recomendados.

RestApi Retriever

Este componente actúa como un puente inteligente entre tu dashboard de Nappai y bases de datos o servicios externos. Su función principal es tomar una pregunta o palabra clave que tú le indiques, buscar esa información en un servidor remoto a través de una dirección web (API) y devolverte los resultados organizados para que puedas usarlos en tus procesos de automatización o en respuestas generadas por IA.

¿Cómo funciona?

Imagina que este componente es un bibliotecario especializado. Tú le entregas una búsqueda (por ejemplo, un texto o pregunta), le indicas cuál es la dirección del servidor donde se encuentra la información y cuántos resultados te gustaría recibir. El componente envía la solicitud al servidor, espera de forma automática y sin detener el resto de tu flujo la respuesta, y luego te entrega los documentos encontrados listos para usarse. Todo el proceso ocurre en segundo plano, lo que mantiene tu dashboard ágil y fluido.

Entradas

Campos de Entrada

  • URL: Dirección web del servicio externo al que se conectarán las solicitudes de búsqueda.
    • Nota: Este campo debe apuntar al endpoint correcto de tu API. El valor por defecto está configurado localmente.
  • Search Query: Texto o pregunta que se enviará al servicio externo para recuperar la información deseada.
    • Nota: Puedes dejarlo vacío, pero ten en cuenta que el servicio podría devolver todos los documentos disponibles o ninguno, dependiendo de cómo esté configurado el servidor.
  • Number of Results: Cantidad máxima de documentos o elementos que deseas recibir como respuesta.
    • Nota: El valor por defecto es 10. Aumentarlo demasiado puede ralentizar la respuesta o consumir más recursos.

Salidas

Al ejecutar este componente, el sistema generará dos tipos de resultados:

  • Retriever: Una instancia lista para usar dentro de tu flujo. Este objeto puede reutilizarse para realizar filtros adicionales o para conectar con otras herramientas de IA que necesiten acceder directamente a la fuente de datos.
  • Search Results: Una lista estructurada con los documentos recuperados. Esta salida está lista para ser consumida por otros nodos, visualizada directamente en tu dashboard o utilizada para enriquecer respuestas de asistentes de IA.

Ejemplo de Respuesta JSON

Cuando el componente encuentra información, devuelve un formato estructurado similar al siguiente:json { “docs”: [ { “id”: “doc_001”, “content”: “La política de vacaciones indica que los empleados tienen derecho a 20 días al año.”, “metadata”: { “source”: “https://ejemplo.com/politicas”, “category”: “rrhh”, “relevance_score”: 0.95 } }, { “id”: “doc_002”, “content”: “Los días no utilizados pueden acumularse hasta un máximo de 5 días al finalizar el año fiscal.”, “metadata”: { “source”: “https://ejemplo.com/politicas”, “category”: “rrhh”, “relevance_score”: 0.88 } } ], “status”: “success” } Puedes usar los campos dentro de docs para mapear datos en los siguientes pasos de tu automatización.

Conectividad

Este nodo suele conectarse como eslabón intermedio en flujos de automatización. Normalmente, recibe los datos de entrada de otros componentes que recopilan información o del mismo usuario (a través de campos como Search Query), y envía sus salidas hacia:

  • Nodos de LLM o Chat: Para alimentar al asistente de IA con la información recuperada y generar respuestas contextuales.
  • Transformadores de Datos o Plantillas: Para estructurar o maquetar los resultados antes de mostrarlos en una interfaz.
  • Vectores o Bases de Conocimiento: Aunque este componente no crea almacenes vectoriales, el objeto Retriever puede pasarse a nodos que ya gestionen índices para realizar búsquedas más rápidas.

Ejemplo de Uso

Escenario: Automatización de atención al cliente en Nappai.

  1. Arrastras el componente RestApi Retriever a tu flujo y pegas la URL de tu base de conocimientos de productos en el campo URL.
  2. Conectas una salida previa que contiene el mensaje del cliente (por ejemplo: “¿Cómo solicito un reembolso?”) al campo Search Query.
  3. Ejecutas el flujo. El componente busca esa pregunta en tu API externa y devuelve los artículos relevantes en Search Results.
  4. Enlances esa salida a un nodo de Generación de Respuesta, el cual usará la información recuperada para redactar una respuesta precisa y personalizada para el cliente.

Notas Importantes

🔒 Use HTTPS for Sensitive Data 🔴 Si el componente enviaría o recibiría información confidencial o sensible, asegúrate de configurar el campo URL para que utilice https:// en lugar de http://. Esto cifrará la comunicación y protegerá los datos contra accesos no autorizados.

🔒 Authentication Not Handled 🔴 El componente no incluye automáticamente credenciales de acceso (como tokens o claves de API). Es responsabilidad del usuario configurar la seguridad en el servidor externo o añadir los encabezados de autenticación necesarios fuera de este nodo.

⚠️ Requires a Working API Endpoint 🟡 El componente depende completamente de que la dirección URL proporcionada esté activa y sea accesible. Si el servidor externo está caído, no responde o cambia su estructura, la búsqueda no devolverá resultados o podría fallar.

⚠️ No Vector Store Output 🟡 Este nodo solo está diseñado para recuperar documentos y devolver un objeto recuperador y los resultados de búsqueda. No genera ni exporta almacenes vectoriales, por lo que no podrá reemplazar nodos específicos diseñados para indexación o almacenamiento masivo de datos.

⚠️ Development‑Stage Component 🔴 Actualmente, este componente se encuentra en una etapa de desarrollo. Su lógica interna puede sufrir modificaciones, presentar comportamientos inesperados o carecer de características completas. Se recomienda probarlo en entornos de prueba antes de integrarlo en procesos críticos de producción.

⚙️ Default URL Points to Localhost 🟢 La configuración inicial apunta a localhost:59958, lo que solo funciona si tienes el servicio externo corriendo en tu propia computadora. Asegúrate de cambiarlo por la dirección real de tu servidor remoto antes de ejecutar el flujo.

⚙️ Search Query Can Be Empty 🟡 Si dejas el campo de búsqueda vacío, el comportamiento dependerá de cómo esté programado el servidor externo. En algunos casos devolverá todos los documentos; en otros, retornará vacío. Para obtener resultados controlados y relevantes, siempre es recomendable ingresar un texto de búsqueda específico.

💡 Set the Correct API URL 🟢 Verifica que la URL que pegas en el campo URL corresponda exactamente al punto de entrada (endpoint) de tu API de búsqueda. Un error en la ruta o en el protocolo hará que la conexión falle.

💡 Provide Specific Search Queries 🟢 Cuanto más detallado y preciso sea el texto en el campo Search Query, más relevantes serán los documentos recuperados. Evita consultas genéricas para reducir el ruido y mejorar la calidad de la información entregada.

💡 Adjust Number of Results 🟢 Configura el campo Number of Results con un valor equilibrado. Solicitar demasiados documentos puede sobrecargar la API y ralentizar el flujo de trabajo. Un rango entre 5 y 20 suele ser óptimo para la mayoría de los casos.

Consejos y Mejores Prácticas

  • Siempre prueba la conexión con el endpoint externo en una pestaña de navegador o en una herramienta de pruebas como Postman antes de integrarlo en Nappai.
  • Si tu flujo involucra datos sensibles, utiliza siempre HTTPS y verifica que el servidor externo cumpla con normativas de privacidad.
  • Monitorea el campo Search Query para evitar enviar vacíos que puedan devolver grandes volúmenes de datos no deseados.
  • Dado que se encuentra en fase de desarrollo, guarda copias de respaldo de tus flujos antes de realizar cambios mayores en la configuración del nodo.
  • Reutiliza la salida Retriever si necesitas encadenar múltiples búsquedas o aplicar filtros adicionales sin volver a consultar la API desde cero.

Consideraciones de Seguridad

La seguridad de este componente depende directamente de cómo configures el servicio externo. Al no gestionar autenticación ni cifrado por defecto, es fundamental que:

  • Utilices exclusivamente endpoints con certificado HTTPS válido en entornos de producción.
  • Validar que el servidor externo no exponga información sensible sin autorización.
  • Evites introducir credenciales de acceso directamente en los campos de texto de este nodo. Si tu API requiere claves, configúralas a nivel del servidor o utiliza componentes de Nappai específicos para el manejo de credenciales seguras.
  • Ten en cuenta que, al estar marcado como componente en fase de desarrollo, las actualizaciones futuras podrían modificar el manejo interno de datos o las reglas de validación de entradas. Mantén tu versión de Nappai actualizada y revisa la documentación oficial para conocer las alternativas de reemplazo recomendadas.