Embedding

1. Visión General

El componente Embedding (embedding) transforma un texto en un vector numérico (embedding), usado para búsqueda semántica, comparación de similitud y alimentación de bases vectoriales (como Qdrant). Soporta los proveedores OpenAI, Google Gemini y Hugging Face.

Úsalo cuando el flujo necesita generar representaciones vectoriales de texto — por ejemplo, antes de grabar un documento en una base vectorial, o para comparar la similitud entre dos textos. Solo funciona como acción de salida.

2. Prerrequisitos

• Una clave de API válida del proveedor elegido (OpenAI, Gemini o Hugging Face).
• Si se usa un proveedor personalizado/compatible, la URL base de ese servicio.

3. Autenticación y Conexión

Campo	Obligatorio	Tipo	Descripción	Ejemplo
apiKey	Sí	Texto	Clave de autenticación del proveedor elegido.	Una expresión que busca la clave en una variable segura
provider	No	Texto: openai, gemini o huggingface	Proveedor de embeddings a usar. Valor por defecto: "openai".	"gemini"
baseUrl	No	Texto	URL base personalizada del proveedor (para endpoints compatibles o autoalojados). Si no se informa, usa la URL por defecto del proveedor elegido.	"https://mi-proxy.ejemplo.com/v1"

4. Configuración / Operaciones Soportadas

El componente tiene una única operación: generar el embedding de un texto.

Campo	Obligatorio	Tipo	Descripción	Ejemplo
text	Sí	Texto	Texto a transformar en vector.	"Descripción del producto..."
model	No	Texto	Identificador del modelo de embedding. Cada proveedor tiene un valor por defecto propio (ej.: OpenAI usa text-embedding-ada-002).	"text-embedding-3-small"
maxChunkSize	No	Número	Tamaño máximo de texto (en caracteres) antes de dividirlo automáticamente en fragmentos (chunks). Valor por defecto: 8000.	4000
chunkSize	No	Número	Tamaño de cada fragmento, cuando el texto se divide. Valor por defecto: 1000.	800
chunkOverlap	No	Número	Superposición entre fragmentos consecutivos. Valor por defecto: 200.	100

Si el texto es menor o igual a maxChunkSize, se genera un único embedding. Si es mayor, el texto se divide en fragmentos y se genera un embedding para cada uno.

5. Ejemplos Prácticos

Ejemplo simple: generar el embedding de una descripción corta de producto, usando OpenAI.

Entrada:

{
  "produto": { "descricao": "Zapatillas deportivas para correr, suela con amortiguación" }
}

Configuración del componente:

{
  "componentName": "embedding",
  "configurations": {
    "provider": "openai",
    "apiKey": "{$.secrets.openaiApiKey}",
    "text": "{$.body.produto.descricao}"
  }
}

Respuesta:

{
  "provider": "openai:text-embedding-ada-002",
  "textLength": 60,
  "chunked": false,
  "originalText": "Zapatillas deportivas para correr, suela con amortiguación",
  "embedding": [0.0123, -0.0456, 0.0789],
  "dimensions": 1536
}

Ejemplo avanzado: generar embeddings de un documento largo, dividido automáticamente en fragmentos.

Entrada:

{
  "documento": "<texto largo de varias páginas>"
}

Configuración del componente:

{
  "componentName": "embedding",
  "configurations": {
    "provider": "gemini",
    "apiKey": "{$.secrets.geminiApiKey}",
    "text": "{$.body.documento}",
    "maxChunkSize": "4000",
    "chunkSize": "800",
    "chunkOverlap": "100"
  }
}

Respuesta (documento dividido en fragmentos):

{
  "provider": "gemini:gemini-embedding-001",
  "totalChunks": 3,
  "chunkSize": 800,
  "chunkOverlap": 100,
  "originalTextLength": 9500,
  "chunked": true,
  "chunks": [
    { "index": 0, "text": "...", "length": 800, "embedding": [0.01, 0.02], "dimensions": 768 },
    { "index": 1, "text": "...", "length": 800, "embedding": [0.03, 0.04], "dimensions": 768 }
  ]
}

6. Errores Comunes y Troubleshooting

Error / Síntoma	Causa probable	Cómo resolverlo
"API Key is required but has not been configured."	El campo apiKey no fue completado.	Completar apiKey con una clave válida del proveedor.
"Text is required but has not been configured."	El campo text no fue completado.	Completar text con el contenido a transformar en embedding.
"Unsupported embedding provider: ..."	El valor de provider no es reconocido.	Usar openai, gemini o huggingface.
"OpenAI API error: ..." / "Gemini API error: ..." / "HuggingFace API error: ..."	El proveedor devolvió un error (clave inválida, límite excedido, modelo inexistente).	Revisar la clave de API y el nombre del modelo configurado.
"Embedding operation failed: ..."	Falla general en la llamada al proveedor.	Verificar conectividad y revisar la configuración del proveedor.