Pular para o conteúdo principal

VillageSQL is a drop-in replacement for MySQL with extensions.

All examples on this page work on VillageSQL. Install Now →
Embeddings vetoriais representam texto como arrays de números que capturam o significado semântico. Dois trechos de texto sobre o mesmo assunto têm vetores semelhantes, mesmo que não compartilhem nenhuma palavra. O MySQL não tem uma forma interna de gerar embeddings. A extensão vsql_ai do VillageSQL adiciona a ai_embedding(), que chama um modelo de embedding e retorna o vetor como um array JSON que você pode armazenar e consultar.

Para Que Servem os Embeddings

Um modelo de embedding converte texto em um vetor de floats de comprimento fixo. A distância entre dois vetores reflete a similaridade semântica:
  • "dog" e "puppy" → vetores semelhantes
  • "dog" e "database index" → vetores distantes
Isso possibilita a busca semântica (encontrar linhas que significam o mesmo que uma consulta), o agrupamento e a recomendação — nenhum dos quais a busca por palavras-chave trata bem.

Com o VillageSQL: ai_embedding()

A ai_embedding(provider, model, api_key, text) chama um modelo de embedding e retorna uma string de array JSON.

A conversão de charset

No VillageSQL 0.0.6 e anteriores, a ai_embedding() retorna o charset binário, e o analisador de JSON do MySQL rejeita uma string binária — o resultado precisa passar por CONVERT(... USING utf8mb4) antes de chegar a uma coluna JSON ou a uma função JSON:
O VillageSQL 0.0.7 e posteriores retornam o charset correto diretamente, portanto o CONVERT não é mais necessário neles — mas é inofensivo mantê-lo, por isso todos os exemplos abaixo ainda o usam, para compatibilidade com o 0.0.6 e anteriores.

Armazenando embeddings

Armazene o array JSON em uma coluna JSON:

Preenchendo embeddings em linhas existentes

Escolhendo um Modelo

Use o mesmo modelo para todos os embeddings de uma tabela. Embeddings de modelos diferentes não são comparáveis — misturá-los produz pontuações de similaridade sem sentido. A Anthropic não fornece atualmente uma API de embedding. Nem o MySQL nem o VillageSQL fornecem uma função nativa de distância vetorial. A busca completa por similaridade — encontrar os vetores mais próximos em uma tabela grande — é executada no código da aplicação. A arquitetura típica: armazene os embeddings no MySQL, busque-os, calcule a similaridade de cosseno na sua aplicação e retorne as melhores correspondências.
Passe os resultados a uma biblioteca de similaridade vetorial (NumPy, scikit-learn, Faiss) para encontrar os vizinhos mais próximos. Para busca em escala de produção, considere um banco de dados vetorial dedicado ao lado do MySQL.

O Que Incluir no Embedding

A qualidade dos seus embeddings depende do que você inclui neles. Alguns padrões:
Mantenha o texto que você inclui no embedding abaixo de alguns milhares de tokens. Um texto mais longo é truncado pelo modelo de embedding.

Perguntas Frequentes

Posso comparar embeddings de modelos diferentes?

Não. Os embeddings de text-embedding-3-small e de gemini-embedding-001 vivem em espaços vetoriais diferentes — as suas pontuações de similaridade não têm sentido quando comparadas entre si. Padronize um modelo por coluna.

Quanto espaço os embeddings ocupam?

Um array JSON de 1536 floats ocupa cerca de 10–15 KB por linha como string de texto. Em tabelas grandes, isso se acumula. Avalie se você precisa armazenar todos os embeddings ou apenas aqueles contra os quais vai consultar.

A ai_embedding() aceita entrada em lote?

Não — cada chamada processa uma única entrada de texto. Para gerar embeddings em massa, percorra as linhas na sua aplicação e chame UPDATE em lotes.

O que acontece se o texto for longo demais?

O modelo de embedding trunca a entrada no seu limite de tokens (normalmente 8191 tokens para os modelos da OpenAI). O embedding é calculado sobre o texto truncado. Para documentos longos, inclua no embedding um resumo ou os primeiros parágrafos, em vez do texto completo.

Solução de Problemas

Veja também