Gere e faça a gestão de incorporações vetoriais

Esta página descreve como gerar e armazenar incorporações vetoriais com base num modelo.

Para mais informações, consulte o artigo Crie aplicações de IA generativa com o Cloud SQL.

O Cloud SQL permite-lhe usar um modelo de incorporação alojado pela Vertex AI para traduzir uma string de texto numa incorporação, que é a representação do modelo do significado semântico do texto fornecido como um vetor numérico.

O Cloud SQL implementa incorporações como matrizes de valores real. Pode usar incorporações geradas como entradas para funções de extensão da API pgvector.

Antes de começar

Alguns requisitos diferem consoante queira usar o Cloud SQL para gerar incorporações ou se só precisar de trabalhar com incorporações armazenadas na sua base de dados a partir de outra origem.

Restrições regionais

Para gerar incorporações da Vertex AI com o Cloud SQL, a sua instância tem de residir numa região onde os modelos fundamentais de IA generativa são suportados. Os modelos do Vertex AI que o Cloud SQL pode usar para incorporações, text-embedding e textembedding-gecko, estão localizados nessa região.

Extensões de base de dados necessárias

Para trabalhar com incorporações, 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 personalizados ou de terceiros, instale a versão 1.4.2 ou posterior.

Opcionalmente, se quiser armazenar estas incorporações e usar funções vetoriais e operadores com as incorporações, também precisa da extensão pgvector.

O Cloud SQL tem ambas as extensões. Pode instalá-los em qualquer base de dados na sua instância. Para mais informações, consulte o artigo Configure as extensões do PostgreSQL.

Configure o acesso ao modelo

Antes de poder gerar incorporações a partir de uma instância do Cloud SQL, tem de configurar o Cloud SQL para funcionar com um modelo de incorporação de texto.

Para trabalhar com o modelo text-embedding ou textembedding-gecko baseado na nuvem, tem de integrar o Cloud SQL com o Vertex AI.

Conceda aos utilizadores da base de dados acesso à geração de incorporações

Conceda autorização aos utilizadores da base de dados para usarem a função embedding para executar previsões:

  1. Associe um cliente psql à instância principal, conforme descrito em Associe através de um cliente psql.

  2. Na linha de comandos psql, estabeleça ligação à base de dados e conceda autorizações:

    \c DB_NAME

GRANT EXECUTE ON FUNCTION embedding TO USER_NAME;

    Substitua o seguinte:

    • DB_NAME: o nome da base de dados para a qual está a conceder autorizações

    • USER_NAME: o nome do utilizador ao qual está a conceder autorizações

Gere incorporações

O Cloud SQL oferece uma função que lhe permite traduzir texto numa incorporação de vetores. Em seguida, pode armazenar essa incorporação na sua base de dados como dados vetoriais e, opcionalmente, usar funções pgvector para executar consultas sobre a mesma.

Gere uma incorporação

Para gerar uma incorporação através do Cloud SQL, use a função que a extensão google_ml_integration fornece:embedding

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

Faça as seguintes substituições:

  • MODEL_ID: o ID do modelo a consultar.

    Se estiver a usar o Model Garden do 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 incorporações de texto. Para mais informações, consulte o artigo Incorporações de texto.

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

    Se estiver a usar um dos modelos textembedding-gecko com a Vertex AI, especifique uma das etiquetas de versão indicadas em Versões do modelo.

  • TEXT: o texto a traduzir numa incorporação vetorial.

O exemplo seguinte usa o modelo text-embedding-004 para gerar uma incorporação com base numa 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 devolvido da função embedding() é uma matriz de valores real. Para armazenar este valor numa 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 suportadas pelo modelo.

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

Opcionalmente, se tiver instalado a extensão pgvector, pode armazenar incorporações como valores vector:

ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN vector(DIMENSIONS);

Depois de criar uma coluna para armazenar incorporações, pode preenchê-la com base nos valores já armazenados noutra 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 consultar.

    Se estiver a usar o Model Garden do 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 incorporações de texto. Para mais informações, consulte o artigo Incorporações de texto.

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

    Se estiver a usar um dos modelos textembedding-gecko com a Vertex AI, especifique uma das etiquetas de versão indicadas em Versões do modelo.

  • SOURCE_TEXT_COLUMN: o nome da coluna que armazena o texto. Traduz este texto em incorporações.

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

O exemplo seguinte usa o modelo text-embedding-004 para preencher a coluna messages.message_vector com incorporações baseadas no conteúdo da coluna messages.message:

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

Consulte e indexe incorporações com pgvector

A extensão pgvector PostgreSQL permite-lhe usar operadores e funções específicos de vetores quando armazena, indexa e consulta incorporações de texto na sua base de dados. O Cloud SQL tem as suas próprias otimizações para trabalhar com pgvector, o que lhe permite criar índices que podem acelerar as consultas que envolvem incorporações.

Crie um índice de vizinhos mais próximos

pgvector suporta pesquisas de vizinhos mais próximos aproximados (ANN) através da indexação.

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

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 está a adicionar o índice.

  • EMBEDDING_COLUMN: uma coluna que armazena dados vector.

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

    • Distância L2: vector_l2_ops

    • Produto interno: vector_ip_ops

    • Distância de cosseno: vector_cosine_ops

  • M (opcional): o número máximo de associações com pontos de dados vizinhos num gráfico. Recomendamos um intervalo de 5 a 48. A predefinição é 16.

  • EF_CONSTRUCTION (opcional): o tamanho da lista que contém os candidatos mais próximos durante o percurso do gráfico quando o índice está a ser criado. Os valores mais elevados levam o algoritmo a considerar mais candidatos, o que permite criar um índice melhor. O tamanho predefinido é 64.

Para criar este índice numa 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 secção seguinte demonstra um exemplo deste tipo de índice.

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

Depois de armazenar e indexar as incorporações na sua base de dados, a gama completa de pgvector funcionalidades de consulta fica disponível.

Para encontrar os vizinhos semânticos mais próximos de um fragmento de texto, use a função embedding() para traduzir o texto num vetor. Na mesma consulta, aplique este vetor ao pgvector operador de vizinho mais próximo, <->, para encontrar as linhas da base de dados com as incorporações semanticamente mais semelhantes.

Uma vez que embedding() devolve uma matriz real, tem de converter a chamada embedding() para vector para usar estes 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 apresentar de linhas semanticamente semelhantes.

  • TABLE: a tabela que contém a incorporação à qual compara o texto.

  • EMBEDDING_COLUMN: a coluna que contém as incorporações armazenadas.

  • MODEL_ID: o ID do modelo a consultar.

    Se estiver a usar o Model Garden do 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 incorporações de texto. Para mais informações, consulte o artigo Incorporações de texto.

  • VERSION_TAG (Opcional): a etiqueta de versão do modelo a consultar. Adicione @ antes da etiqueta.

    Se estiver a usar um dos modelos textembedding-gecko com a Vertex AI, especifique uma das etiquetas de versão indicadas em Versões do modelo.

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

  • ROW_COUNT: o número de linhas a devolver. Se quiser apenas a melhor correspondência única, especifique 1 como o valor deste 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 etiquetas de versão do modelo para evitar erros

O Cloud SQL recomenda vivamente que use sempre uma versão estável do modelo de incorporações escolhido. Para a maioria dos modelos, isto significa definir uma etiqueta de versão explicitamente.

A invocação da função embedding() sem especificar a etiqueta de versão do modelo é sintaticamente válida, mas pode ser propensa a erros.

Se omitir a etiqueta de versão quando usar um modelo no Vertex AI Model Garden, o Vertex AI usa 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 modelos do Vertex AI disponíveis, consulte o artigo Versões de modelos.

Uma determinada versão do modelo da Vertex AI devolve sempre a mesma resposta a uma determinada entrada de texto.embedding() Se não especificar a versão do modelo nas suas chamadas de incorporação, é possível que uma versão do modelo publicada recentemente possa alterar abruptamente o vetor devolvido para uma determinada entrada. Isto pode causar erros ou outro comportamento inesperado nas suas aplicações.

O que se segue?