Trabalhar com embeddings vetoriais

Nesta página, mostramos como usar o Cloud SQL para PostgreSQL para realizar as seguintes ações:

  • Gerar e armazenar embeddings vetoriais com base em um modelo.

  • Indexe e consulte embeddings usando a extensão pgvector.

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. Isso permite 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 residir em uma região em que generative AI foundational models are supported. 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 os embeddings, 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 poder gerar embeddings de uma instância do Cloud SQL, configure o Cloud SQL para funcionar com um modelo de embedding de texto.

Para trabalhar com o modelo de text-embedding ou textembedding-geckobaseado na nuvem, você precisa 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. Esses 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.

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

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. Esses 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 do 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

pgvector oferece suporte à pesquisa de vizinho mais próximo por meio da indexação.

Para criar um índice baseado em pgvector com hnsw como método de índice, use o 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 porque 16 é o valor padrão de pgvector.

  • 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. Esses 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 Google 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 também é 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 versões de modelo nas chamadas para embedding(), uma nova versão de modelo publicada poderá alterar abruptamente o vetor retornado para uma determinada entrada. Isso pode causar erros ou outro comportamento inesperado nos aplicativos.

Para evitar esses problemas, sempre especifique a versão do modelo.

A seguir