Saltearse al contenido
Nappai Documentation

HuggingFace Embeddings

El componente HuggingFace Embeddings permite convertir textos en vectores numéricos (embeddings) utilizando modelos alojados en la plataforma Hugging Face. Estos vectores son útiles para tareas de búsqueda semántica, clasificación, clustering y otras aplicaciones de inteligencia artificial que requieren comparar textos en un espacio vectorial.

¿Cómo funciona?

Cuando activas el componente, Nappai envía el texto que le proporciones a la API de inferencia de Hugging Face. La API procesa el texto con el modelo especificado (por defecto BAAI/bge-large-en-v1.5) y devuelve un vector de números que representa el contenido semántico del texto. El componente simplemente pasa ese vector a la siguiente etapa de tu flujo de trabajo.

Entradas

Modo de Mapeo (Mapping Mode)

Este componente cuenta con un modo especial llamado “Mapping Mode” (Modo de Mapeo). Cuando activas este modo mediante el interruptor, se habilita una entrada adicional llamada “Mapping Data” y cada campo de entrada te ofrece tres formas diferentes de proporcionar datos:

  • Fixed (Fijo): Escribes el valor directamente en el campo.
  • Mapped (Mapeado): Conectas la salida de otro componente para usar su resultado como valor.
  • Javascript: Escribes código Javascript para calcular el valor dinámicamente.

Esta flexibilidad te permite crear flujos de trabajo más dinámicos y conectados.

Campos de Entrada

  • API URL: La dirección del servidor que expone la API de inferencia de Hugging Face. Si usas el servidor local, el valor por defecto es http://localhost:8080.
  • Mapping Mode: Interruptor que habilita el modo de mapeo para procesar múltiples registros en lote.
  • Model Name: El nombre del modelo Hugging Face que se utilizará para generar los embeddings. Puedes usar el valor por defecto BAAI/bge-large-en-v1.5 o especificar otro modelo disponible en Hugging Face.

Nota importante: Este componente necesita una credencial de tipo HuggingFace API.

  1. Configura primero la credencial en la sección de credenciales de Nappai.
  2. Luego selecciona esa credencial en el campo Credential del componente.

Salidas

  • Embeddings: Un vector numérico que representa el texto de entrada. Este vector puede ser usado como entrada para otros componentes, como búsqueda por similitud, clasificación o clustering.

Ejemplo de Uso

  1. Configura la credencial: Ve a la sección de credenciales de Nappai y añade una nueva credencial de tipo HuggingFace API, ingresando tu HuggingFace Api Key.
  2. Añade el componente: Arrastra el componente HuggingFace Embeddings al flujo.
  3. Selecciona la credencial: En el campo Credential, elige la credencial que acabas de crear.
  4. Configura los parámetros (opcional):
    • API URL: http://localhost:8080 (o la URL de tu servidor).
    • Model Name: BAAI/bge-large-en-v1.5 (o cualquier otro modelo).
  5. Conecta la entrada de texto: Conecta la salida de un componente que genere texto (por ejemplo, un nodo de entrada de usuario).
  6. Ejecuta el flujo: El componente enviará el texto a Hugging Face y devolverá el vector de embeddings.
  7. Usa el resultado: Conecta la salida Embeddings a otro componente, como un buscador semántico o un clasificador.

Componentes Relacionados

  • OpenAI Embeddings – Genera embeddings usando la API de OpenAI.
  • SentenceTransformer Embeddings – Utiliza modelos de Sentence Transformers para embeddings locales.
  • Custom Embeddings – Permite cargar modelos personalizados entrenados en tu propio entorno.

Consejos y Mejores Prácticas

  • Elige el modelo correcto: Los modelos más grandes suelen ofrecer mayor precisión, pero consumen más recursos y tiempo de respuesta.
  • Usa batch processing: Si necesitas procesar muchos textos, activa el Mapping Mode para enviar varios registros en una sola llamada.
  • Controla el tamaño de los vectores: Algunos modelos generan embeddings de 768 dimensiones, otros de 1024. Asegúrate de que el resto de tu flujo pueda manejar el tamaño que elijas.
  • Mantén tu API Key segura: Nunca la expongas en el código ni la compartas públicamente. Usa la gestión de credenciales de Nappai.
  • Prueba con textos de muestra: Antes de ejecutar flujos en producción, prueba el componente con textos representativos para verificar la calidad de los embeddings.

Consideraciones de Seguridad

  • La API Key de Hugging Face debe almacenarse en la sección de credenciales de Nappai y no debe mostrarse en la interfaz de usuario.
  • Si usas un servidor local (http://localhost:8080), asegúrate de que esté protegido y no expuesto a redes no confiables.
  • Revisa los límites de uso de tu cuenta Hugging Face para evitar bloqueos inesperados.