Gerar e gerenciar embeddings vetoriais,Gerar e gerenciar embeddings vetoriais,Gerar e gerenciar embeddings vetoriais,Gerar e gerenciar embeddings vetoriais

Esta página descreve como gerar e armazenar embeddings vetoriais com base em um modelo.

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

O Cloud SQL permite que você use um modelo de incorporação hospedado pela Vertex AI para traduzir uma sequência de texto em uma incorporação , 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 . Você pode usar embeddings gerados como entradas para funções de extensão pgvector .

Antes de começar

Alguns requisitos variam dependendo se você deseja usar o Cloud SQL para gerar embeddings ou se precisa trabalhar apenas com embeddings armazenados no seu banco de dados de outra fonte.

Restrições regionais

Para gerar embeddings do Vertex AI com o Cloud SQL, sua instância deve residir em uma região com suporte para modelos fundamentais de IA generativa . Os modelos do 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 do Vertex AI, instale a versão 1.2 ou posterior. Para modelos de terceiros ou personalizados, instale a versão 1.4.2 ou posterior.

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

O Cloud SQL possui ambas as extensões. Você pode instalá-las em qualquer banco de dados da sua instância. Para obter mais informações, consulte Configurar extensões do PostgreSQL .

Configurar acesso ao modelo

Antes de gerar embeddings de uma instância do Cloud SQL, você deve configurar o Cloud SQL para funcionar com um modelo de incorporação de texto.

Para trabalhar com o modelo de text-embedding baseado em nuvem ou textembedding-gecko , você precisa integrar o Cloud SQL com o Vertex AI .

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

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

  1. Conecte um cliente psql à instância primária, 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 o seguinte:

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

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

Gerar embeddings

O Cloud SQL oferece uma função que permite traduzir texto em um embedding vetorial. Você pode então armazenar esse embedding no seu banco de dados como dados vetoriais e, opcionalmente, usar funções pgvector para executar consultas nele.

Gerar uma incorporação

Para gerar uma incorporação usando 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 Vertex AI Model Garden , especifique text-embedding-004 ou
    text-multilingual-embedding-002 . Estes são os modelos baseados em nuvem que o Cloud SQL pode usar para incorporações de texto. Para obter mais informações, consulte Incorporações de texto .

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

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

  • TEXT : o texto a ser traduzido para uma incorporação vetorial.

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

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

Armazene uma incorporação gerada

O valor de retorno da função embedding() é um array 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 incorporação

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

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

Opcionalmente, se você tiver instalado a extensão pgvector , poderá armazenar embeddings como valores vector :

ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN vector(DIMENSIONS);

Depois de criar uma coluna para armazenar embeddings, você pode 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 incorporação.

  • MODEL_ID : o ID do modelo a ser consultado.

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

  • VERSION_TAG (Opcional): a tag de versão do modelo a ser consultado. Para versões de 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 o Vertex AI, especifique uma das tags de versão listadas em Versões do modelo .

  • SOURCE_TEXT_COLUMN : o nome da coluna que armazena o texto. Você traduz esse texto para embeddings.

O comando anterior funciona tanto para colunas de incorporação real[] quanto para colunas de incorporação 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íficas de vetores ao armazenar, indexar e consultar embeddings de texto no seu banco de dados. O Cloud SQL possui suas próprias otimizações para trabalhar com pgvector , permitindo criar índices que podem acelerar consultas que envolvem embeddings.

Crie um índice de vizinho mais próximo

pgvector suporta pesquisas aproximadas de vizinho mais próximo (ANN) por meio de 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 à qual você está adicionando o índice.

  • EMBEDDING_COLUMN : uma coluna que armazena dados vector .

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

    • Distância 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 grafo ao construir o índice. Valores mais altos levam o algoritmo a considerar mais candidatos, permitindo a criação de um índice melhor. O tamanho padrão é 64.

Para criar esse índice em uma coluna de incorporação 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 incorporação.

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

Faça uma consulta de vizinho mais próximo com o texto fornecido

Depois de armazenar e indexar os embeddings no seu banco de dados, toda a funcionalidade da consulta pgvector estará disponível para você.

Para encontrar os vizinhos semânticos mais próximos de um trecho de texto, use a função embedding() para traduzir 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 semanticamente mais semelhantes.

Como embedding() retorna um array real , você deve converter 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 a incorporação à qual 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 Vertex AI Model Garden , especifique text-embedding-004 ou
    text-embedding-multilingual-002 . Estes são os modelos baseados em nuvem que o Cloud SQL pode usar para incorporações de texto. Para mais informações, consulte Incorporações de texto .

  • VERSION_TAG (Opcional): a tag de versão do modelo a ser consultado. Adicione @ antes da tag.

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

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

  • ROW_COUNT : o número de linhas a serem retornadas. Se desejar apenas a melhor correspondência, especifique 1 como valor para este parâmetro.

Para executar esta consulta com uma coluna de incorporação 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

Use tags de versão do modelo para evitar erros

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

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

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

Uma determinada versão do modelo Vertex AI sempre retorna a mesma resposta embedding() para uma determinada entrada de texto. Se você não especificar a versão do modelo em suas chamadas de incorporação, é possível que uma versão de modelo recém-publicada altere abruptamente o vetor retornado para uma determinada entrada. Isso pode causar erros ou outros comportamentos inesperados em seus aplicativos.

O que vem a seguir