Crie aplicações de IA generativa com o AlloyDB AI

Importante: para aceder aos URLs indicados nesta página, tem de se ligar à Internet. Os URLs são fornecidos para acesso fora do seu ambiente isolado.

Esta secção descreve como invocar previsões e consultar e indexar incorporações usando a extensão pgvector. Estas funções de IA baseadas na aprendizagem automática estão disponíveis através do AlloyDB AI, que é um conjunto de funcionalidades do AlloyDB para PostgreSQL que lhe permitem aplicar o poder semântico e preditivo dos modelos de aprendizagem automática (ML) aos seus dados.

Saiba mais sobre a IA do AlloyDB em https://cloud.google.com//alloydb/docs/ai.

Invocar previsões

Para integrar o Vertex AI com o AlloyDB Omni e executar previsões em modelos armazenados no Vertex AI, siga estes passos.

Antes de começar

1. Ative as previsões online do Vertex AI no GDC.

2. Crie um segredo do Kubernetes com base na chave da conta de serviço transferida nos passos anteriores executando o seguinte comando. Certifique-se de que cria o segredo do Kubernetes no mesmo espaço de nomes que o recurso DBCluster.

   kubectl create secret generic SECRET_NAME \
   --from-file=PATH_TO_SERVICE_ACCOUNT_KEY/private-key.json \
   -n NAMESPACE

   Substitua o seguinte:

   • SECRET_NAME: o nome do segredo usado quando cria um manifesto DBCluster para permitir que o AlloyDB Omni aceda às funcionalidades de IA do Distributed Cloud. Por exemplo, vertex-ai-key-alloydb.

   • PATH_TO_SERVICE_ACCOUNT_KEY: o caminho para a localização onde transferiu a chave da conta de serviço do private-key.json.

   • NAMESPACE: o espaço de nomes do cluster da base de dados.

3. Instale o operador AlloyDB Omni através dos passos indicados em Escolha um tipo de motor de base de dados e crie um cluster de base de dados.

4. Crie um cluster de base de dados com o AlloyDB AI e defina vertexAIKeyRef para o segredo do Kubernetes criado nos passos anteriores no campo googleMLExtension no manifesto DBCluster.

   apiVersion: v1
   kind: Secret
   metadata:
     name: db-pw-DBCLUSTER_NAME
     namespace: USER_PROJECT
   type: Opaque
   data:
     DBCLUSTER_NAME: "BASE64_PASSWORD"
   ---
   apiVersion: DBENGINE_NAME.dbadmin.gdc.goog/v1
   kind: DBCluster
   metadata:
     name: DBCLUSTER_NAME
     namespace: USER_PROJECT
   spec:
     primarySpec:
       adminUser:
         passwordRef:
           name: db-pw-DBCLUSTER_NAME
       features:
         googleMLExtension:
           config:
             vertexAIKeyRef: SECRET_NAME
       version: "DB_VERSION"
       resources:
         memory: DB_MEMORY
         cpu: DB_CPU
         disks:
         - name: DataDisk
           size: DB_DATA_DISK
   

   Substitua as seguintes variáveis:

   • DBCLUSTER_NAME: o nome do cluster da base de dados.
   • USER_PROJECT: o nome do projeto do utilizador onde o cluster de base de dados vai ser criado.
   • BASE64_PASSWORD: a codificação base64 da palavra-passe do administrador da base de dados.
   • DBENGINE_NAME: o nome do motor da base de dados. Definido como alloydbomni.
   • DB_VERSION: a versão do motor da base de dados.
   • DB_MEMORY: a quantidade de memória atribuída ao cluster da base de dados, por exemplo, 5Gi.
   • DB_CPU: a quantidade de CPUs atribuídas ao cluster da base de dados, por exemplo, 2.
   • DB_DATA_DISK: a quantidade de espaço alocada ao cluster da base de dados, por exemplo, 10 Gi.

   Aplique o manifesto.

   kubectl apply -f DB_CLUSTER_YAML

   Substitua o seguinte:

   • DB_CLUSTER_YAML: o nome deste ficheiro de manifesto do cluster da base de dados, por exemplo, alloydb-omni-db-cluster.yaml.

5. Instale a extensão google_ml_integration.

   CREATE EXTENSION google_ml_integration CASCADE;
   

Invoque uma previsão

Invoque uma previsão online através de um ponto final do modelo do Vertex AI executando a seguinte função SQL ml_predict_row():

  SELECT ml_predict_row('PREDICTION_ENDPOINT/PROJECT_NAMESPACE/ORGANIZATION/ZONE/DNS/DNS_SUFFIX', '{ "instances": [ INSTANCES ], "parameters":
  PARAMETERS');

Substitua o seguinte:

• PREDICTION_ENDPOINT: o nome qualificado do ponto final da Vertex AI

• PROJECT_NAMESPACE: o espaço de nomes no qual o ponto final do Vertex AI é implementado

• ORGANIZATION: o nome da organização na qual o ponto final do Vertex AI está implementado

• ZONE: a zona na qual o seu ponto final da Vertex AI está implementado

• DNS: o DNS da sua organização

• DNS_SUFFIX: o sufixo do objeto DNS

• INSTANCES: as entradas para a chamada de previsão, no formato JSON

• PARAMETERS: os parâmetros da chamada de previsão, no formato JSON

Consultar e indexar incorporações com o 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 AlloyDB oferece otimizações para trabalhar com pgvector, o que lhe permite criar índices que podem acelerar determinadas consultas que envolvem incorporações.

Saiba mais sobre a utilização do AlloyDB como um MDI/CE e a geração e o armazenamento de incorporações de vetores com base num MDI/CE em https://cloud.google.com/alloydb/docs/ai/work-with-embeddings#index.

Crie índices e consulte vetores com o ScaNN

Esta secção mostra como usar incorporações armazenadas para gerar índices e consultar incorporações. Pode criar ScaNN índices com o AlloyDB.

Antes de começar

Antes de poder começar a criar índices, tem de concluir os seguintes pré-requisitos.

• Os vetores de incorporação são adicionados a uma tabela na sua base de dados do AlloyDB.

• A versão vector da extensão 0.5.0 ou posterior baseada em pgvector, expandida pela Google para o AlloyDB, está instalada.

  CREATE EXTENSION IF NOT EXISTS vector;
  

• Para gerar índices ScaNN, instale a extensão postgres_ann, além da extensão vector.

  CREATE EXTENSION IF NOT EXISTS postgres_ann;
  

Nota: a extensão postgres_ann pode ser usada com bases de dados compatíveis com o PostgreSQL 14 e 15.

Crie um ScaNN índice

Pode criar um ScaNNíndice para tabelas na sua base de dados.

Nota: uma vez que os nomes dos índices são partilhados na base de dados, crie um nome de índice exclusivo para cada tabela na sua base de dados.

O AlloyDB postgres_anné uma extensão do PostgreSQL desenvolvida pela Google que implementa um índice de vizinhos mais próximos altamente eficiente com tecnologia do algoritmo ScaNN.

O índice ScaNN é um índice de quantização baseado em árvores para a pesquisa aproximada do vizinho mais próximo. Oferece um tempo de criação de índice baixo e uma pequena pegada de memória. Além disso, oferece CPS rápidas com base na carga de trabalho.

Nota: antes de criar um índice, certifique-se de que adiciona vetores de incorporação a uma tabela na sua base de dados do Distributed Cloud. Se tentar gerar um índice ScaNN numa tabela vazia ou particionada, pode encontrar alguns problemas.

Índice ScaNN de árvore de dois níveis

Para aplicar um índice de árvore de dois níveis usando o algoritmo ScaNN a uma coluna que contenha incorporações de vetores armazenadas, execute a seguinte consulta DDL:

CREATE INDEX INDEX_NAME ON TABLE
  USING scann (EMBEDDING_COLUMN DISTANCE_FUNCTION)
  WITH (num_leaves=NUM_LEAVES_VALUE);

Substitua o seguinte:

• INDEX_NAME: o nome do índice que quer criar, por exemplo, my-scann-index. Os nomes dos índices são partilhados na sua base de dados. Certifique-se de que cada nome de índice é exclusivo para cada tabela na sua base de dados.

• TABLE: a tabela à qual adicionar o índice.

• EMBEDDING_COLUMN: uma coluna que armazena vector dados.

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

  • Distância L2: l2

  • Produto escalar: dot_product

  • Distância do cosseno: cosine

• NUM_LEAVES_VALUE: o número de partições a aplicar a este índice. Defina qualquer valor entre 1 e 1048576.

Índice de árvore de três níveis ScaNN

Para criar um índice de árvore de três níveis usando o algoritmo ScaNN numa coluna que contenha incorporações de vetores armazenadas, execute a seguinte consulta DDL:

CREATE INDEX INDEX_NAME ON TABLE
  USING scann (EMBEDDING_COLUMN DISTANCE_FUNCTION)
  WITH (num_leaves=NUM_LEAVES_VALUE, max_num_levels = MAX_NUM_LEVELS);

Substitua o seguinte:

• MAX_NUM_LEVELS: o número máximo de níveis da árvore de agrupamento K-means. Defina como 1(predefinição) para a quantização baseada em árvore de dois níveis e como 2 para a quantização baseada em árvore de três níveis.

Depois de criar o índice, pode executar consultas de pesquisa de vizinhos mais próximos que usam o índice seguindo as instruções em Faça uma consulta de vizinhos mais próximos com um determinado texto.

Os parâmetros de índice têm de ser definidos para encontrar o equilíbrio certo entre as consultas por segundo e a capacidade de memorização.

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 INDEX_NAME ON TABLE
  USING scann (CAST(EMBEDDING_COLUMN AS vector(DIMENSIONS)) DISTANCE_FUNCTION)
  WITH (num_leaves=NUM_LEAVES_VALUE, max_num_levels = MAX_NUM_LEVELS);

Substitua DIMENSIONS pela largura dimensional da coluna de incorporação.

Para ver o progresso da indexação, use a vista pg_stat_progress_create_index:

SELECT * FROM pg_stat_progress_create_index;

A coluna phase mostra o estado atual da criação do índice e a fase building index: tree training desaparece após a criação do índice.

Execute uma consulta

Depois de armazenar e indexar as incorporações na sua base de dados, pode começar a consultar através da funcionalidade de consulta pgvector. Não pode executar consultas de pesquisa em massa através da extensão postgres_ann.

Para encontrar os vizinhos semânticos mais próximos de um vetor de incorporação, pode executar a consulta de exemplo seguinte, em que define a mesma função de distância que usou durante a criação do índice.

  SELECT * FROM TABLE
    ORDER BY EMBEDDING_COLUMN DISTANCE_FUNCTION_QUERY ['EMBEDDING']
    LIMIT ROW_COUNT

Substitua o seguinte:

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

• INDEX_NAME: o nome do índice que quer usar, por exemplo, my-scann-index.

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

• DISTANCE_FUNCTION_QUERY: a função de distância a usar com esta consulta. Escolha uma das seguintes opções com base na função de distância usada ao criar o índice:

  • Distância L2: <->

  • Produto interior: <#>

  • Distância do cosseno: <=>

• EMBEDDING: o vetor de incorporação para o qual quer encontrar os vizinhos semânticos armazenados mais próximos.

• ROW_COUNT: o número de linhas a devolver.

  Especifique 1 se quiser apenas a melhor correspondência única.

Também pode usar a função embedding() para traduzir o texto num vetor. Aplica o vetor a um dos pgvector operadores de vizinho mais próximo, <-> para a distância L2, para encontrar as linhas da base de dados com as incorporações semanticamente mais semelhantes. Tenha em atenção que tem de registar primeiro o modelo Gecko de incorporação de texto para usar esta função.

Uma vez que embedding() devolve uma matriz real, tem de converter explicitamente a chamada embedding() em vector para usar estes valores com operadores pgvector.

  CREATE EXTENSION google_ml_integration;
  CREATE EXTENSION IF NOT EXISTS vector;

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

Substitua o seguinte:

• MODEL_ID: o ID do modelo a consultar.

  Se estiver a usar o Model Garden da Vertex AI, especifique textembedding-gecko@003 como o ID do modelo. Estes são os modelos baseados na nuvem que o Distributed Cloud pode usar para incorporações de texto.

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

  Se estiver a usar um dos textembedding-geckomodelos em inglês com a Vertex AI, especifique uma das etiquetas de versão, por exemplo, textembedding-gecko@003.

  A Google recomenda vivamente que especifique sempre a etiqueta de versão. Se não especificar a etiqueta de versão, o AlloyDB usa sempre a versão do modelo mais recente, o que pode levar a resultados inesperados.

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

Métricas do índice de vetores

Esta secção apresenta as métricas relacionadas com os índices vetoriais que gera no AlloyDB. Pode ver estas métricas através da vista pg_stat_ann_indexes disponível quando instala a postgres_ann extensão.

Métricas de usabilidade

As métricas de usabilidade incluem métricas que ajudam a compreender o estado de utilização do índice com métricas como a configuração do índice e o número de análises do índice.

Nome da métrica	Tipo de dados	Descrição
relid	OID	Identificador exclusivo da tabela que contém o índice vetorial.
indexrelid	OID	Identificador exclusivo do índice vetorial.
schemaname	NAME	Nome do esquema ao qual o índice pertence.
relname	NAME	Nome da tabela que contém o índice.
indexrelname	NAME	Nome do índice.
indextype	NAME	Tipo de índice. Este valor está sempre definido como postgres_ann.
indexconfig	TEXT[]	Configuração, como a contagem de folhas e o quantizador, definida para o índice quando foi criado.
indexsize	TEXT	Tamanho do índice.
indexscan	BIGINT	Número de análises de índice iniciadas no índice.

Métricas de aperfeiçoamento

As métricas de ajuste fornecem estatísticas sobre a otimização do índice atual, o que lhe permite aplicar recomendações para um desempenho de consulta mais rápido.

Nome da métrica	Tipo de dados	Descrição
insertcount	BIGINT	Número de operações de inserção no índice. Esta métrica também inclui qualquer número de linhas que existiam antes da criação do índice.
updatecount	BIGINT	Número de operações de atualização no índice. Esta métrica não tem em conta as atualizações HOT.
deletecount	BIGINT	Número de operações de eliminação no índice.
distribution	JSONB	Distribuições de vetores em todas as partições do índice. Os seguintes campos mostram a distribuição: maximum (INT8): número máximo de vetores em todas as partições. minimum (INT8): número mínimo de vetores em todas as partições. average (FLOAT) : número médio de vetores em todas as partições. outliers (INT8[]): valores atípicos principais em todas as partições. Este valor mostra os 20 valores atípicos principais. Nota: devido às caraterísticas inerentes do algoritmo de agrupamento K-means, haverá sempre algum grau de variação na distribuição de vetores entre partições, mesmo quando o índice é criado inicialmente.

Ajuste da recomendação com base nas métricas

Mutação

As métricas insertcount, updatecount> e deletecount mostram em conjunto as alterações ou as mutações no vetor do índice.

O índice é criado com um número específico de vetores e partições. Quando são realizadas operações como inserir, atualizar ou eliminar no índice vetorial, estas afetam apenas o conjunto inicial de partições onde os vetores residem. Consequentemente, o número de vetores em cada partição flutua ao longo do tempo, o que pode afetar a capacidade de memorização, o QPS ou ambos.

Se encontrar problemas de lentidão ou precisão, como um baixo QPS ou uma má capacidade de memorização, nas suas consultas de pesquisa de RNA ao longo do tempo, considere rever estas métricas. Um número elevado de mutações relativamente ao número total de vetores pode indicar a necessidade de reindexação.

Distribuição

A métrica distribution mostra as distribuições de vetores em todas as partições.

Quando cria um índice, este é criado com um número específico de vetores e partições fixas. O processo de partição e a distribuição subsequente ocorrem com base nesta consideração. Se forem adicionados vetores adicionais, estes são divididos entre as partições existentes, o que resulta numa distribuição diferente em comparação com a distribuição quando o índice foi criado. Uma vez que a distribuição final não considera todos os vetores em simultâneo, a capacidade de memorização, as QPS ou ambas podem ser afetadas.

Se observar uma diminuição gradual no desempenho das suas consultas de pesquisa de ANN, como tempos de resposta mais lentos ou uma precisão reduzida nos resultados (medida por QPS ou recall), considere verificar esta métrica e reindexar.