Embedding

1. Visão Geral

O componente Embedding (embedding) transforma um texto em um vetor numérico (embedding), usado para busca semântica, comparação de similaridade e alimentação de bancos vetoriais (como o Qdrant). Suporta os provedores OpenAI, Google Gemini e Hugging Face.

Use quando o fluxo precisa gerar representações vetoriais de texto — por exemplo, antes de gravar um documento em um banco vetorial, ou para comparar a similaridade entre dois textos. Só funciona como ação de saída.

2. Pré-requisitos

• Uma chave de API válida do provedor escolhido (OpenAI, Gemini ou Hugging Face).
• Se for usado um provedor customizado/compatível, a URL base desse serviço.

3. Autenticação e Conexão

Campo	Obrigatório	Tipo	Descrição	Exemplo
apiKey	Sim	Texto	Chave de autenticação do provedor escolhido.	Uma expressão que busca a chave em uma variável segura
provider	Não	Texto: openai, gemini ou huggingface	Provedor de embeddings a ser usado. Valor padrão: "openai".	"gemini"
baseUrl	Não	Texto	URL base customizada do provedor (para endpoints compatíveis ou auto-hospedados). Se não informado, usa a URL padrão do provedor escolhido.	"https://meu-proxy.exemplo.com/v1"

4. Configuração / Operações Suportadas

O componente tem uma única operação: gerar o embedding de um texto.

Campo	Obrigatório	Tipo	Descrição	Exemplo
text	Sim	Texto	Texto a ser transformado em vetor.	"Descrição do produto..."
model	Não	Texto	Identificador do modelo de embedding. Cada provedor tem um valor padrão próprio (ex.: OpenAI usa text-embedding-ada-002).	"text-embedding-3-small"
maxChunkSize	Não	Número	Tamanho máximo de texto (em caracteres) antes de dividir automaticamente em pedaços (chunks). Valor padrão: 8000.	4000
chunkSize	Não	Número	Tamanho de cada pedaço, quando o texto é dividido. Valor padrão: 1000.	800
chunkOverlap	Não	Número	Sobreposição entre pedaços consecutivos. Valor padrão: 200.	100

Se o texto for menor ou igual a maxChunkSize, é gerado um único embedding. Se for maior, o texto é dividido em pedaços e um embedding é gerado para cada um.

5. Exemplos Práticos

Exemplo simples: gerar o embedding de uma descrição curta de produto, usando OpenAI.

Entrada:

{
  "produto": { "descricao": "Tênis esportivo para corrida, solado com amortecimento" }
}

Configuração do componente:

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

Resposta:

{
  "provider": "openai:text-embedding-ada-002",
  "textLength": 60,
  "chunked": false,
  "originalText": "Tênis esportivo para corrida, solado com amortecimento",
  "embedding": [0.0123, -0.0456, 0.0789],
  "dimensions": 1536
}

Exemplo avançado: gerar embeddings de um documento longo, dividido automaticamente em pedaços.

Entrada:

{
  "documento": "<texto longo de várias páginas>"
}

Configuração do componente:

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

Resposta (documento dividido em pedaços):

{
  "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. Erros Comuns e Troubleshooting

Erro / Sintoma	Causa provável	Como resolver
"API Key is required but has not been configured."	O campo apiKey não foi preenchido.	Preencher apiKey com uma chave válida do provedor.
"Text is required but has not been configured."	O campo text não foi preenchido.	Preencher text com o conteúdo a ser transformado em embedding.
"Unsupported embedding provider: ..."	O valor de provider não é reconhecido.	Usar openai, gemini ou huggingface.
"OpenAI API error: ..." / "Gemini API error: ..." / "HuggingFace API error: ..."	O provedor retornou um erro (chave inválida, limite excedido, modelo inexistente).	Revisar a chave de API e o nome do modelo configurado.
"Embedding operation failed: ..."	Falha geral na chamada ao provedor.	Verificar conectividade e revisar a configuração do provedor.