Gerar e gerenciar embeddings de vetor

Nesta página, descrevemos como gerar e armazenar embeddings vetoriais com base em um modelo.

Para mais informações, consulte Criar aplicativos de IA generativa usando o Cloud SQL.

Com o Cloud SQL, é possível usar um modelo de embedding hospedado pela Vertex AI para traduzir uma string de texto em uma embedding, que é a representação do modelo do significado semântico do texto fornecido como um vetor numérico.

O Cloud SQL implementa embeddings como matrizes de valores real. É possível usar embeddings gerados como entradas para funções de extensão pgvector.

Antes de começar

Alguns requisitos são diferentes se você quer usar o Cloud SQL para gerar embeddings ou se só precisa trabalhar com embeddings armazenados no seu banco de dados de outra fonte.

Restrições regionais

Para gerar embeddings da Vertex AI com o Cloud SQL, sua instância precisa estar em uma região em que os modelos de fundação de IA generativa são compatíveis. Os modelos da Vertex AI que o Cloud SQL pode usar para embeddings, text-embedding e textembedding-gecko, estão localizados nessa região.

Extensões de banco de dados necessárias

Para trabalhar com embeddings, instale a extensão google_ml_integration na sua instância do Cloud SQL. Para modelos da Vertex AI, instale a versão 1.2 ou mais recente. Para modelos personalizados ou de terceiros, instale a versão 1.4.2 ou mais recente.

Opcionalmente, se você quiser armazenar esses embeddings e usar funções e operadores vetoriais com eles, também precisará da extensão pgvector.

O Cloud SQL tem as duas extensões. Você pode instalá-los em qualquer banco de dados na sua instância. Para mais informações, consulte Configurar extensões do PostgreSQL.

Configurar o acesso ao modelo

Antes de gerar embeddings de uma instância do Cloud SQL, configure o Cloud SQL para trabalhar com um modelo de embedding de texto.

Para trabalhar com o modelo de text-embedding ou textembedding-gecko baseado na nuvem, é necessário integrar o Cloud SQL à Vertex AI.

Conceder acesso aos usuários do banco de dados para gerar embeddings

Conceda permissão aos usuários do banco de dados para usar a função embedding para executar previsões:

  1. Conecte um cliente psql à instância principal, conforme descrito em Conectar usando um cliente psql.

  2. No prompt de comando psql, conecte-se ao banco de dados e conceda permissões:

    \c DB_NAME

GRANT EXECUTE ON FUNCTION embedding TO USER_NAME;

    Substitua:

    • DB_NAME: o nome do banco de dados para o qual você está concedendo permissões

    • USER_NAME: o nome do usuário para quem você está concedendo permissões

Gerar embeddings

O Cloud SQL fornece uma função que permite traduzir texto em um embedding de vetor. Em seguida, é possível armazenar esse embedding em seu banco de dados como dados vetoriais e, opcionalmente, usar funções pgvector para executar consultas nele.

Gerar um embedding

Para gerar um embedding com o Cloud SQL, use a função embedding fornecida pela extensão google_ml_integration:

SELECT embedding( 'MODEL_IDVERSION_TAG', 'TEXT');

Faça as seguintes substituições:

  • MODEL_ID: o ID do modelo a ser consultado.

    Se você estiver usando o Model Garden da Vertex AI, especifique text-embedding-004 ou
    text-multilingual-embedding-002. Estes são os modelos baseados na nuvem que o Cloud SQL pode usar para embeddings de texto. Para mais informações, consulte Embeddings de texto.

  • VERSION_TAG (opcional): a tag da versão do modelo a ser consultada. Para versões do textembedding-gecko anteriores a text-embedding-004 ou text-multilingual-embedding-002, adicione @ ao início da tag.

    Se você estiver usando um dos modelos textembedding-gecko com a Vertex AI, especifique uma das tags de versão listadas em Versões de modelo.

  • TEXT: o texto a ser traduzido em um embedding de vetor.

O exemplo a seguir usa o modelo text-embedding-004 para gerar um embedding com base em uma string literal fornecida:

SELECT embedding( 'text-embedding-004', 'Cloud SQL is a managed, cloud-hosted SQL database service.');

Armazenar um embedding gerado

O valor de retorno da função embedding() é uma matriz de valores real. Para armazenar esse valor em uma tabela, adicione uma coluna real[]:

ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN real[DIMENSIONS];

Faça as seguintes substituições:

  • TABLE: o nome da tabela

  • EMBEDDING_COLUMN: o nome da nova coluna de embedding

  • DIMENSIONS: o número de dimensões que o modelo aceita.

    Se você estiver usando um dos modelos text-embedding ou textembedding-gecko com a Vertex AI, especifique 768.

Opcionalmente, se você instalou a extensão pgvector, é possível armazenar embeddings como valores vector:

ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN vector(DIMENSIONS);

Depois de criar uma coluna para armazenar embeddings, é possível preenchê-la com base nos valores já armazenados em outra coluna na mesma tabela:

UPDATE TABLE SET EMBEDDING_COLUMN = embedding('MODEL_IDVERSION_TAG', SOURCE_TEXT_COLUMN);

Faça as seguintes substituições:

  • TABLE: o nome da tabela.

  • EMBEDDING_COLUMN: o nome da coluna de embedding.

  • MODEL_ID: o ID do modelo a ser consultado.

    Se você estiver usando o Model Garden da Vertex AI, especifique text-embedding-004 ou
    text-multilingual-embedding-002. Estes são os modelos baseados na nuvem que o Cloud SQL pode usar para embeddings de texto. Para mais informações, consulte Embeddings de texto.

  • VERSION_TAG (opcional): a tag da versão do modelo a ser consultada. Para versões do textembedding-gecko anteriores a text-embedding-004 ou text-multilingual-embedding-002,Prepend the tag with@`.

    Se você estiver usando um dos modelos textembedding-gecko com a Vertex AI, especifique uma das tags de versão listadas em Versões de modelo.

  • SOURCE_TEXT_COLUMN: o nome da coluna que está armazenando o texto. Você traduz esse texto em embeddings.

O comando anterior funciona para as colunas de incorporação real[] e vector. Se a coluna de incorporação for do tipo vector, o Cloud SQL converterá o valor de retorno de embedding() de uma matriz real para um valor vector implicitamente.

O exemplo a seguir usa o modelo text-embedding-004 para preencher a coluna messages.message_vector com embeddings baseados no conteúdo da coluna messages.message:

UPDATE messages SET message_vector = embedding( 'text-embedding-004', message);

Consultar e indexar embeddings usando pgvector

A extensão pgvector do PostgreSQL permite usar operadores e funções específicos de vetor ao armazenar, indexar e consultar embeddings de texto no banco de dados. O Cloud SQL tem as próprias otimizações para trabalhar com pgvector, permitindo que você crie índices que podem acelerar consultas que envolvem embeddings.

Criar um índice de vizinho mais próximo

O pgvector oferece suporte a pesquisas de vizinho mais próximo aproximado (ANN) por meio da indexação.

Para criar um índice HNSW, use a função hnsw, conforme mostrado no exemplo a seguir:

CREATE INDEX ON TABLE
  USING hnsw (EMBEDDING_COLUMN DISTANCE_FUNCTION)
  WITH (m = M, ef_construction = EF_CONSTRUCTION);

Faça as seguintes substituições:

  • TABLE: a tabela a que você está adicionando o índice.

  • EMBEDDING_COLUMN: uma coluna que armazena dados de vector.

  • DISTANCE_FUNCTION: a função de distância a ser usada com esse índice. Escolha uma destas opções:

    • Distância de L2: vector_l2_ops

    • Produto interno: vector_ip_ops

    • Distância do cosseno: vector_cosine_ops

  • M (opcional): o número máximo de conexões com pontos de dados vizinhos em um gráfico. Recomendamos um intervalo de 5 a 48. O padrão é 16.

  • EF_CONSTRUCTION (opcional): o tamanho da lista que contém os candidatos mais próximos durante a travessia do gráfico ao criar o índice. Valores mais altos fazem com que o algoritmo considere mais candidatos, permitindo a criação de um índice melhor. O tamanho padrão é 64.

Para criar esse índice em uma coluna incorporada que usa o tipo de dados real[] em vez de vector, converta a coluna no tipo de dados vector:

CREATE INDEX ON TABLE
  USING hnsw ((CAST(EMBEDDING_COLUMN AS vector(DIMENSIONS))) DISTANCE_FUNCTION)
  WITH (m = M, ef_construction = EF_CONSTRUCTION);

Substitua DIMENSIONS pela largura dimensional da coluna de embedding.

A próxima seção demonstra um exemplo desse tipo de índice.

Fazer uma consulta vizinha mais próxima com um texto fornecido

Depois de armazenar e indexar embeddings no banco de dados, a variedade completa da funcionalidade de consulta pgvector está disponível para você.

Para encontrar os vizinhos semânticos mais próximos de um texto, use a função embedding() para converter o texto em um vetor. Na mesma consulta, aplique esse vetor ao operador vizinho mais próximo pgvector, <->, para encontrar as linhas do banco de dados com os embeddings mais semanticamente semelhantes.

Como embedding() retorna uma matriz real, é necessário transmitir a chamada embedding() para vector para usar esses valores com operadores pgvector.

  SELECT RESULT_COLUMNS FROM TABLE
    ORDER BY EMBEDDING_COLUMN
    <-> embedding('MODEL_IDVERSION_TAG', 'TEXT')::vector
    LIMIT ROW_COUNT

Faça as seguintes substituições:

  • RESULT_COLUMNS: as colunas a serem exibidas de linhas semanticamente semelhantes.

  • TABLE: a tabela que contém o embedding a que você compara o texto.

  • EMBEDDING_COLUMN: a coluna que contém os embeddings armazenados.

  • MODEL_ID: o ID do modelo a ser consultado.

    Se você estiver usando o Model Garden da Vertex AI, especifique text-embedding-004 ou
    text-embedding-multilingual-002. Estes são os modelos baseados na nuvem que o Cloud SQL pode usar para embeddings de texto. Para mais informações, consulte Embeddings de texto.

  • VERSION_TAG (opcional): a tag da versão do modelo a ser consultada. Adicione @ ao início da tag.

    Se você estiver usando um dos modelos textembedding-gecko com a Vertex AI, especifique uma das tags de versão listadas em Versões de modelo.

  • TEXT: o texto que você quer para encontrar os vizinhos semânticos armazenados mais próximos.

  • ROW_COUNT: o número de linhas que serão retornadas. Se você quiser apenas a melhor correspondência, especifique 1 como o valor desse parâmetro.

Para executar esta consulta com uma coluna de embedding armazenada que usa o tipo de dados real[] em vez de vector, converta a coluna no tipo de dados vector:

  SELECT RESULT_COLUMNS FROM TABLE
    ORDER BY EMBEDDING_COLUMN::vector
    <-> embedding('MODEL_IDVERSION_TAG', 'TEXT')::vector
    LIMIT ROW_COUNT

Usar tags de versão do modelo para evitar erros

O Cloud SQL recomenda que você sempre use uma versão estável do modelo de embeddings escolhido. Na maioria dos modelos, isso significa definir explicitamente uma tag de versão.

Chamar a função embedding() sem especificar a tag de versão do modelo é sintaticamente válido, mas pode ser propenso a erros.

Se você omitir a tag de versão ao usar um modelo no Model Garden da Vertex AI, a Vertex AI usará a versão mais recente do modelo. Esta pode não ser a versão estável mais recente. Para mais informações sobre as versões de modelo da Vertex AI disponíveis, consulte Versões de modelo.

Uma determinada versão de modelo da Vertex AI sempre retorna a mesma resposta embedding() para uma determinada entrada de texto. Se você não especificar a versão do modelo nas chamadas de incorporação, é possível que uma versão recém-publicada mude abruptamente o vetor retornado para uma determinada entrada. Isso pode causar erros ou outro comportamento inesperado nos aplicativos.

A seguir