Saltearse al contenido
Nappai Documentation

FastEmbed Embeddings (Local)

Este componente está diseñado para convertir textos en representaciones numéricas (vectores) que las máquinas pueden entender y procesar. Funciona completamente en tu computadora o servidor local, lo que significa que no necesitas conexión a internet, ni pagar por servicios externos ni preocuparte por enviar tus datos a la nube. Es ideal si priorizas la privacidad, tienes una conexión limitada o trabajas en entornos offline. En el sistema Nappai, este componente se encarga de la “traducción” inicial del texto a un formato que otros elementos del dashboard podrán usar para buscar, clasificar o responder sobre tu información de gestión.

¿Cómo funciona?

Internamente, el componente utiliza un motor de inteligencia artificial ligero y eficiente. Cuando le proporcionas un texto, lo analiza y genera un conjunto de números que capturan su significado y contexto. Este proceso se ejecuta de forma local, descargando automáticamente el modelo de IA elegido a una carpeta de caché en tu dispositivo. El sistema ajusta automáticamente la cantidad de información que procesa y la velocidad de cálculo según la configuración que selecciones. Al final, entrega un objeto listo para ser conectado a otros nodos que necesiten trabajar con datos textuales, manteniendo siempre la privacidad de la información.

Conexión y Credenciales

Este componente NO requiere credenciales, claves API ni tokens de acceso. Al ser una herramienta 100% local, no necesitas registrarte en servicios externos ni configurar permisos en el panel de Nappai. Simplemente selecciona las opciones que prefieras y conéctalo directamente a los siguientes nodos de tu flujo.

Entradas

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente:

  • Model: Selecciona el modelo de inteligencia artificial que convertirá el texto en vectores. Cada opción tiene un tamaño, velocidad y soporte de idiomas diferente (ej. uno muy ligero y rápido, otro optimizado para español e inglés, o modelos de mayor precisión).
  • Document Embed Type: Define cómo se procesarán los documentos. Si usas el modelo “multilingual-e5-large”, seleccionar “passage” agrega automáticamente un prefijo interno para mejorar la precisión. Las consultas de búsqueda ya reciben su prefijo automáticamente.
  • Model Cache Directory: Especifica la carpeta donde se guardarán los modelos descargados. Si lo dejas vacío, el sistema usará la ubicación predeterminada de tu dispositivo o del entorno Docker.
  • Max Sequence Length: Establece el número máximo de palabras o tokens que el modelo analizará en cada texto. Si un texto es muy largo, se recortará automáticamente para ajustarse a este límite.
  • Batch Size: Indica cuántos textos se procesarán al mismo tiempo. Un valor más alto acelera el trabajo pero consume más memoria RAM; uno más bajo es más suave para el equipo.
  • ONNX Runtime Threads: Controla cuántos núcleos de la CPU se usarán para calcular los vectores. Si lo dejas en “0”, el sistema detectará automáticamente la mejor cantidad según tu hardware disponible.

Salidas

  • Embeddings Object: Es el resultado principal del componente. No es un texto simple, sino un objeto listo para ser conectado a nodos que almacenan datos en bases de vectores (como bases de datos locales o en la nube), sistemas de búsqueda (RAG) o flujos de automatización. Este objeto contiene toda la configuración aplicada y permite que el resto del flujo transforme tu texto en datos matemáticos para análisis, búsqueda o respuestas inteligentes.

Ejemplo de Respuesta JSON

{ “status”: “success”, “component_name”: “FastEmbed Embeddings (Local)”, “model_config”: { “model_name”: “jinaai/jina-embeddings-v2-base-es”, “batch_size”: 256, “max_length”: 512, “threads”: 0, “cache_dir”: ”~/.cache/fastembed” }, “output_preview”: { “input_sample”: “Automatiza la gestión de datos en Nappai”, “vector_dimensions”: 768, “representative_values”: [0.12, -0.34, 0.89, 0.05, -0.21], “note”: “El objeto real contiene miles de valores numéricos. Este JSON es una representación esquemática para fines de documentación y depuración en el dashboard.” } }

Conectividad

Este componente está diseñado para conectar su salida directamente con nodos que requieran datos vectoriales. Es común conectarlo a:

  • Bases de datos vectoriales (Vector Stores): Para almacenar los vectores y permitir búsquedas rápidas por significado semántico.
  • Nodos de RAG (Búsqueda Augmentada por Generación): Para preparar el texto que un asistente de IA usará como conocimiento base antes de responder preguntas.
  • Cadenas de procesamiento (Chains) o clasificadores: Para alimentar flujos de resumen, análisis de sentimiento o extracción de información.

La conexión tiene sentido lógico porque, una vez que el texto se convierte en vectores, los siguientes nodos necesitan ese formato numérico para comparar similitudes, almacenar información de forma eficiente o generar respuestas inteligentes sin perder contexto.

Ejemplo de Uso

Imagina que quieres que el asistente de Nappai analice automáticamente tus contratos legales o reportes de RRHH. Conectas un nodo que extrae el texto de los documentos a la entrada de este componente. Al configurarlo con el modelo jina-embeddings-v2-base-es y el tipo passage, Nappai transforma cada cláusula en un vector local. Luego, conectas la salida a un nodo de base de datos vectorial para guardarlos, y finalmente a un nodo de RAG para que, cuando un usuario pregunte “¿Cuál es la penalización por cancelación?”, el sistema encuentre la respuesta exacta en los documentos de forma instantánea, sin enviar nunca el texto original a servidores externos.

Consejos y Mejores Prácticas

  • Empieza con el modelo ligero (paraphrase-multilingual-MiniLM-L12-v2) si tu equipo tiene recursos limitados o priorizas velocidad de respuesta.
  • Usa jina-embeddings-v2-base-es cuando trabajes principalmente con texto en español e inglés para obtener el mejor equilibrio entre precisión y rendimiento.
  • Ajusta el Batch Size según la memoria RAM de tu servidor: valores altos (256+) son ideales para servidores dedicados, mientras que valores bajos (16-32) evitan bloqueos en equipos personales.
  • Deja el campo ONNX Runtime Threads en “0” para que el sistema optimice automáticamente el uso de la CPU según tu hardware.
  • Verifica que la carpeta de caché (Model Cache Directory) tenga permisos de lectura/escritura para evitar errores de ejecución en entornos compartidos o Docker.
  • Si trabajas con textos muy extensos, reduce el Max Sequence Length para evitar que el sistema los corte o tarde demasiado en procesarlos.

Consideraciones de Seguridad

Al funcionar 100% en local, este componente garantiza que tu texto nunca sale de tu infraestructura, eliminando riesgos de exposición en tránsito o almacenamiento en servidores de terceros. Para mantener un entorno seguro en Nappai:

  • Descarga y utiliza únicamente modelos oficiales y verificados.
  • Revisa los permisos del directorio de caché para evitar conflictos de archivos o accesos no autorizados.
  • En entornos corporativos, mantén actualizado el paquete de dependencias locales y considera restringir el acceso a la carpeta de caché solo a usuarios con privilegios de administración.
  • Aunque no hay transmisión de datos a la nube, asegúrate de que tu servidor local cuente con copias de respaldo y control de versiones para proteger los vectores generados.