Saltearse al contenido
Nappai Documentation

VertexAI Embeddings

VertexAI Embeddings es un componente de Nappai que convierte textos en vectores numéricos (embeddings) usando los modelos de Google Cloud VertexAI. Estos vectores pueden ser usados para búsquedas semánticas, clustering, clasificación y otras tareas de inteligencia artificial que requieren una representación numérica de los datos de texto.

¿Cómo funciona?

Cuando activas el componente, Nappai envía el texto que le entregues a la API de VertexAI. La API procesa el texto con el modelo especificado (por defecto textembedding-gecko) y devuelve un vector de números que representa el contenido semántico del texto. El componente también permite configurar parámetros como la temperatura, el número de resultados (N), la paralelización de peticiones y la gestión de errores (Max Retries). Si proporcionas un archivo de credenciales JSON, Nappai lo usará para autenticarse; de lo contrario, intentará usar las variables de entorno o la configuración de la CLI de Google Cloud.

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

  • Credentials: Archivo JSON con las credenciales de Google Cloud. Si lo dejas vacío, Nappai intentará usar las variables de entorno o la configuración de la CLI de Google Cloud.
  • Location: Región donde se ejecuta el modelo de VertexAI (ejemplo: us-central1).
  • Mapping Mode: Interruptor que habilita el modo de mapeo para procesar múltiples registros en lote.
  • Max Output Tokens: Máximo número de tokens que el modelo puede devolver.
  • Max Retries: Número máximo de intentos que se harán en caso de error de la API.
  • Model Name: Nombre del modelo de embeddings que se usará (por defecto textembedding-gecko).
  • N: Cantidad de embeddings que se generarán por cada entrada de texto.
  • Project: ID del proyecto de Google Cloud que contiene el modelo.
  • Request Parallelism: Número de peticiones que se enviarán en paralelo a la API.
  • Stop: Secuencias que, si aparecen en el texto, harán que el modelo deje de generar más tokens.
  • Streaming: Si está activado, la respuesta se enviará en tiempo real a medida que se genera.
  • Temperature: Controla la aleatoriedad de la generación (0.0 = determinista).
  • Top K: Número de tokens más probables que se considerarán en cada paso.
  • Top P: Umbral de probabilidad acumulativa para la selección de tokens.

Salidas

  • Embeddings: Un vector numérico (o una lista de vectores si N > 1) que representa el contenido semántico del texto de entrada. Este vector puede ser usado como entrada para otros componentes de búsqueda, clasificación o clustering dentro de Nappai.

Ejemplo de Uso

  1. Arrastra el componente VertexAI Embeddings al lienzo.
  2. Conecta la salida de un componente que genere texto (por ejemplo, un Text Splitter) a la entrada de texto de este componente.
  3. Si ya tienes un archivo de credenciales JSON, arrástralo a la entrada Credentials; de lo contrario, deja el campo vacío y asegúrate de que las variables de entorno de Google Cloud estén configuradas.
  4. Ajusta Model Name a textembedding-gecko y N a 1 para obtener un único embedding por texto.
  5. Conecta la salida Embeddings a un componente de Vector Store para indexar los resultados y poder hacer búsquedas semánticas más adelante.

Componentes Relacionados

  • Text Splitter – Divide textos largos en fragmentos manejables antes de generar embeddings.
  • Vector Store – Almacena y consulta embeddings para búsquedas y análisis.
  • VertexAI Text Generation – Genera texto a partir de prompts; puede usar los embeddings como contexto.

Consejos y Mejores Prácticas

  • Usa credenciales seguras: Guarda el archivo JSON en un lugar protegido y no lo compartas públicamente.
  • Controla el número de peticiones: Ajusta Request Parallelism según la capacidad de tu cuenta de VertexAI para evitar sobrecargas.
  • Limita la longitud del texto: Los modelos de embeddings tienen un límite de tokens; corta textos muy largos antes de enviarlos.
  • Revisa los costos: Cada llamada a VertexAI genera cargos; monitorea tu uso en la consola de Google Cloud.
  • Prueba con Temperature = 0.0: Para embeddings, la determinación es preferible; evita la aleatoriedad.

Consideraciones de Seguridad

  • Credenciales: El archivo JSON contiene claves de acceso a tu proyecto de Google Cloud. Manténlo en un entorno seguro y evita exponerlo en repositorios públicos.
  • Variables de Entorno: Si dependes de variables de entorno (GOOGLE_APPLICATION_CREDENTIALS), asegúrate de que solo los usuarios autorizados tengan acceso a ellas.
  • Datos Sensibles: Los textos que envías a VertexAI pueden ser procesados por Google. Si contienen información confidencial, revisa la política de privacidad de Google Cloud y considera anonimizar los datos antes de enviarlos.