Gere incorporações vetoriais para dados textuais em massa através de DML particionada

Este documento explica como gerar e preencher incorporações de vetores em massa para dados textuais (STRING ou JSON) armazenados no Spanner através de SQL e dos modelos de incorporação de texto da Vertex AI.

Pré-requisitos

Tem de ter uma tabela na sua base de dados do Spanner que contenha dados textuais (STRING ou JSON). Para mais informações sobre a importação de dados, consulte a vista geral da importação e exportação do Spanner.

Exemplo de utilização

Suponhamos que tem uma tabela no Spanner com o seguinte esquema. Esta tabela contém milhões de registos.

GoogleSQL 

CREATE TABLE Products (
  product_id INT64 NOT NULL,
  name STRING(MAX),
  description STRING(MAX)
) PRIMARY KEY(product_id);

PostgreSQL 

CREATE TABLE Products (
  product_id INT8 NOT NULL,
  name TEXT,
  description TEXT,
  PRIMARY KEY(product_id)
);

O seu objetivo é gerar incorporações de vetores para a coluna description nesta tabela para encontrar itens semelhantes a recomendar aos clientes de modo a melhorar a respetiva experiência de compra através da pesquisa vetorial.

Registe um modelo de incorporação

GoogleSQL

Registe um modelo de incorporação de texto com o ponto final do modelo do Vertex AI na sua base de dados do Spanner:

CREATE MODEL MODEL_NAME
INPUT(
  content STRING(MAX)
)
OUTPUT(
  embeddings STRUCT<values ARRAY<FLOAT32>>
)
REMOTE OPTIONS(
    endpoint = '//aiplatform.googleapis.com/projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
  default_batch_size = 5
)

Substitua o seguinte:

  • MODEL_NAME: o nome do modelo de incorporação de texto da Vertex AI
  • PROJECT: o projeto que aloja o ponto final do Vertex AI
  • LOCATION: a localização do ponto final da Vertex AI

PostgreSQL

No dialeto PostgreSQL, não é necessário registar o modelo. Transmite o nome do ponto final diretamente para a chamada da função spanner.ML_PREDICT_ROW.

Para ver práticas recomendadas, considere o seguinte:

  • Para manter o isolamento das quotas, use um ponto final num projeto diferente para gerar e preencher incorporações em vez do ponto final de produção. Reserve o ponto final de produção para publicar tráfego de produção.
  • Certifique-se de que o ponto final do modelo suporta o valor de default_batch_size. Pode substituir o default_batch_size pela sugestão de consulta @{remote_udf_max_rows_per_rpc=NEW_NUMBER}. Para ver informações sobre o limite de cada região, consulte o artigo Obtenha incorporações de texto para um fragmento de texto.default_batch_size
  • Defina o ponto final com uma versão específica do modelo (por exemplo, @003) em vez de @latest. Isto deve-se ao facto de os vetores de incorporação gerados para o mesmo fragmento de texto poderem diferir consoante a versão do modelo que usa. É por isso que deve evitar usar versões diferentes do modelo para gerar incorporações no mesmo conjunto de dados. Além disso, a atualização da versão do modelo na declaração de definição do modelo não atualiza as incorporações já geradas com este modelo. Uma forma de gerir a versão do modelo para incorporações é criar uma coluna adicional na tabela que armazene a versão do modelo.
  • Os modelos de incorporação de texto personalizados não são suportados com as funções ML.PREDICT GoogleSQL e PostgreSQL spanner.ML_PREDICT_ROW.

Teste a integração ponto a ponto do modelo de incorporações

Pode executar uma consulta para testar se o modelo de incorporação está configurado com êxito e se as incorporações são obtidas. Por exemplo, execute a seguinte consulta:

GoogleSQL 

SELECT embeddings.values
FROM SAFE.ML.PREDICT(
  MODEL MODEL_NAME,
  (SELECT description AS content FROM products LIMIT 10)
);

Substitua o seguinte:

  • MODEL_NAME: o nome do modelo de incorporação de texto da Vertex AI

PostgreSQL 

SELECT spanner.ML_PREDICT_ROW(
    'projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
    JSONB_BUILD_OBJECT('instances', JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content', description))))
FROM Products
LIMIT 10;

Substitua o seguinte:

  • PROJECT: o projeto que aloja o ponto final do Vertex AI
  • LOCATION: a localização do ponto final da Vertex AI
  • MODEL_NAME: o nome do modelo de incorporação de texto da Vertex AI

Atualize a tabela de origem para incluir colunas adicionais para armazenar as incorporações

Em seguida, atualize o esquema da tabela de origem para incluir uma coluna adicional do tipo de dados ARRAY<FLOAT32> para armazenar as incorporações geradas:

GoogleSQL 

ALTER TABLE TABLE_NAME
ADD COLUMN EMBEDDING_COLUMN_NAME ARRAY<FLOAT32>;

Substitua o seguinte:

  • TABLE_NAME: o nome da tabela de origem
  • EMBEDDING_COLUMN_NAME: o nome da coluna na qual quer adicionar incorporações geradas

PostgreSQL 

ALTER TABLE TABLE_NAME
ADD COLUMN EMBEDDING_COLUMN_NAME real[];

Substitua o seguinte:

  • TABLE_NAME: o nome da tabela de origem
  • EMBEDDING_COLUMN_NAME: o nome da coluna na qual quer adicionar incorporações geradas

Por exemplo, usando o exemplo da tabela products, execute:

GoogleSQL 

ALTER TABLE Products
ADD COLUMN desc_embed ARRAY<FLOAT32>;

PostgreSQL 

ALTER TABLE Products
ADD COLUMN desc_embed real[];

Pode adicionar outra coluna para gerir a versão do modelo de incorporação.

GoogleSQL 

ALTER TABLE Products
ADD COLUMN desc_embed_model_version INT64;

PostgreSQL 

ALTER TABLE Products
ADD COLUMN desc_embed_model_version INT8;

Aumente a quota do Vertex AI

Pode ter de aumentar a quota da API Vertex AI para a região que usa o modelo de incorporação de texto. Para pedir um aumento, consulte o artigo Aumentos de quotas do Vertex AI.

Para mais informações, consulte as quotas e os limites da Vertex AI.

Incorporações de repreenchimento

Por fim, execute a seguinte declaração UPDATEusando DML particionada para gerar incorporações para a coluna de dados textuais e armazenar as incorporações na sua base de dados. Pode armazenar a versão do modelo juntamente com as incorporações. Recomendamos que execute esta consulta durante um período de baixo tráfego na sua base de dados.

GoogleSQL 

UPDATE TABLE_NAME
SET
  TABLE_NAME.EMBEDDING_COLUMN_NAME = (
    SELECT embeddings.values
    FROM SAFE.ML.PREDICT(
      MODEL MODEL_NAME,
      (SELECT TABLE_NAME.DATA_COLUMN_NAME AS content)
    ) @{remote_udf_max_rows_per_rpc=MAX_ROWS}
  ),
  TABLE_NAME.EMBEDDING_VERSION_COLUMN = MODEL_VERSION
WHERE FILTER_CONDITION;

Substitua o seguinte:

  • TABLE_NAME: o nome da tabela com os dados textuais
  • EMBEDDING_COLUMN_NAME: o nome da coluna na qual quer adicionar incorporações geradas
  • DATA_COLUMN_NAME: o nome da coluna com os dados textuais
  • MODEL_NAME: o nome do modelo de incorporação da Vertex AI
  • MAX_ROWS: o número máximo de linhas por RPC
  • EMBEDDING_VERSION_COLUMN: a coluna que gere a versão do modelo de incorporação usado para preencher as suas incorporações
  • MODEL_VERSION: a versão do modelo de incorporação de texto
  • FILTER_CONDITION: uma condição de filtro divisível que quer aplicar

A utilização de SAFE.ML.PREDICT devolve NULL para pedidos com falha. Também pode usar SAFE.ML.PREDICT em combinação com um filtro WHERE embedding_column IS NULL para executar novamente a consulta sem calcular as incorporações dos campos que já foram calculados.

PostgreSQL 

UPDATE TABLE_NAME
SET
  EMBEDDING_COLUMN_NAME = spanner.FLOAT32_ARRAY(spanner.ML_PREDICT_ROW(
    'projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
    JSONB_BUILD_OBJECT('instances', JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content', DATA_COLUMN_NAME)))
  ) /*@ remote_udf_max_rows_per_rpc=MAX_ROWS */ ->'predictions'->0->'embeddings'->'values'),
  EMBEDDING_VERSION_COLUMN = MODEL_VERSION
WHERE FILTER_CONDITION;

Substitua o seguinte:

  • TABLE_NAME: o nome da tabela com os dados textuais
  • EMBEDDING_COLUMN_NAME: o nome da coluna na qual quer adicionar incorporações geradas
  • DATA_COLUMN_NAME: o nome da coluna com os dados textuais
  • PROJECT: o projeto que aloja o ponto final do Vertex AI
  • LOCATION: a localização do ponto final da Vertex AI
  • MODEL_NAME: o nome do modelo de incorporação da Vertex AI
  • MODEL_VERSION: a versão do modelo de incorporação da Vertex AI
  • MAX_ROWS: o número máximo de linhas por RPC
  • EMBEDDING_VERSION_COLUMN: a coluna que gere a versão do modelo de incorporação de texto usado para preencher as suas incorporações
  • FILTER_CONDITION: uma condição de filtro divisível que quer aplicar

Um exemplo de consulta de preenchimento para a tabela products:

GoogleSQL 

UPDATE products
SET
  products.desc_embed = (
    SELECT embeddings.values
    FROM SAFE.ML.PREDICT(
      MODEL embedding_model,
      (SELECT products.description AS content)
    ) @{remote_udf_max_rows_per_rpc=200}
  ),
  products.desc_embed_model_version = 3
WHERE products.desc_embed IS NULL;

PostgreSQL 

UPDATE products
SET
  desc_embed = spanner.FLOAT32_ARRAY(spanner.ML_PREDICT_ROW(
    'projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
    JSONB_BUILD_OBJECT('instances', JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content', description)))
  ) /*@ remote_udf_max_rows_per_rpc=200 */ ->'predictions'->0->'embeddings'->'values'),
  desc_embed_model_version = 3
WHERE desc_embed IS NULL;

Para ver práticas recomendadas, considere o seguinte:

  • O tempo limite gRPC predefinido para a API Spanner é de uma hora. Consoante a quantidade de incorporações que está a preencher, pode ter de aumentar este limite de tempo para garantir que o DML particionado tem tempo suficiente para ser concluído.UPDATE Para mais informações, consulte o artigo Configure limites de tempo e novas tentativas personalizados.

Desempenho e outras considerações

Considere o seguinte para otimizar o desempenho ao preencher previamente dados de incorporação.

Número de nós

O DML particionado executa a instrução DML fornecida em diferentes partições em paralelo. Para instâncias com um número elevado de nós, pode observar erros de quota durante a execução de DML particionada. Se os pedidos da API Vertex AI forem limitados devido aos limites de quota da API Vertex AI, o Spanner tenta novamente estas falhas no modo de transação DML particionado um máximo de 20 vezes. Se observar uma taxa elevada de erros de quota no Vertex AI, aumente a quota do Vertex AI. Também pode ajustar o paralelismo com a sugestão ao nível da declaração @{pdml_max_parallelism=DESIRED_NUMBER} enquanto usa o GoogleSQL. O exemplo seguinte define o paralelismo como "5":

GoogleSQL 

@{pdml_max_parallelism=5} UPDATE products
SET products.desc_embed =(
  SELECT embeddings.values
  FROM SAFE.ML.PREDICT(MODEL embedding_model, (
        SELECT products.value AS CONTENT
        )
  )
      @{remote_udf_max_rows_per_rpc=200}
),
products.desc_embed_model_version = MODEL_VERSION
WHERE products.desc_embed IS NULL;

Tamanho do texto na coluna de dados

O modelo de incorporação da Vertex AI tem limites no número máximo de tokens para cada entrada de texto. As diferentes versões do modelo têm limites de tokens diferentes. Cada pedido da Vertex AI pode ter vários campos de texto de entrada, mas existe um limite para o número máximo de tokens presentes num único pedido. Para bases de dados GoogleSQL, se encontrar um erro INVALID_ARGUMENT com a mensagem "O pedido é demasiado grande", experimente reduzir o tamanho do lote para evitar o erro. Para o fazer, pode configurar default_batch_size ou usar a sugestão de consulta @{remote_udf_max_outstanding_rpcs} quando regista o modelo.

Número de pedidos de API enviados para a Vertex AI

Pode usar a sugestão de consulta @{remote_udf_max_outstanding_rpcs} para aumentar ou diminuir o número de pedidos enviados para o Vertex AI a partir do Spanner. Tenha em atenção que o aumento deste limite pode aumentar a utilização da CPU e da memória da instância do Spanner. Para bases de dados GoogleSQL, a utilização desta sugestão de consulta substitui o default_batch_size configurado para o seu modelo.

Monitorize o progresso do preenchimento

Pode monitorizar o número de pedidos, a latência e os bytes de rede enviados para o Vertex AI a partir do Spanner através do painel de controlo de estatísticas do sistema.

O que se segue?