Geração autónoma de incorporações

Este documento descreve como usar a geração de incorporações autónoma para os seus dados, o que permite ao BigQuery manter uma coluna de incorporações numa tabela com base numa coluna de origem. Quando adiciona ou modifica dados na coluna de origem, o BigQuery gera ou atualiza automaticamente a coluna de incorporação para esses dados através de um modelo de incorporação do Vertex AI. Isto é útil se quiser permitir que o BigQuery mantenha as suas incorporações quando os dados de origem são atualizados regularmente.

As incorporações são úteis para aplicações de IA generativa modernas, como a geração aumentada de recuperação (RAG), mas podem ser complexas de criar, gerir e consultar. Pode usar a geração de incorporações autónoma para simplificar o processo de criação, manutenção e consulta de incorporações para utilização em pesquisas de similaridade e outras aplicações de IA generativa.

Por exemplo, pode usar consultas semelhantes às seguintes para criar uma tabela com a geração de incorporações autónoma ativada, inserir dados e, em seguida, fazer uma pesquisa semântica:

CREATE TABLE mydataset.products (
  name STRING,
  description STRING,
  description_embedding STRUCT<result ARRAY<FLOAT64>, status STRING>
    GENERATED ALWAYS AS (
      AI.EMBED(description, connection_id => 'us.example_connection',
        endpoint => 'text-embedding-005'))
    STORED OPTIONS( asynchronous = TRUE ));

# Values in the description_embedding column are automatically generated.
INSERT INTO mydataset.products (name, description) VALUES
  ("Super slingers"), ("An exciting board game for the whole family"), ...;

SELECT * FROM AI.SEARCH(TABLE mydataset.products, 'description', "A really fun toy");

Antes de começar

Para ativar a geração de incorporações autónoma numa tabela, tem de ter as autorizações e a ligação necessárias.

Funções necessárias

Para receber as autorizações de que precisa para ativar a geração de incorporações autónoma, peça ao seu administrador para lhe conceder as seguintes funções de IAM:

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Crie uma associação e conceda autorização a uma conta de serviço

Para ativar a geração autónoma de incorporações numa tabela, tem de criar uma ligação de recursos da nuvem. Em seguida, conceda a função de utilizador do Vertex AI (roles/aiplatform.user) à conta de serviço que foi criada quando criou a associação.

Crie uma tabela com geração de incorporações autónoma

Pode usar a geração autónoma de incorporações para gerar incorporações através da função AI.EMBED numa declaração CREATE TABLE.

CREATE TABLE DATASET_ID.TABLE (
  [COLUMN, ...]
  STRING_COL STRING,
  EMBEDDING_COL_NAME STRUCT<result ARRAY<FLOAT64>, status STRING>
    GENERATED ALWAYS AS (
      AI.EMBED(
        STRING_COL,
        connection_id => CONNECTION_ID,
        endpoint => ENDPOINT)
    )
    STORED OPTIONS (asynchronous = TRUE)
);

Substitua o seguinte:

  • DATASET_ID: o nome do conjunto de dados no qual quer criar a tabela.
  • TABLE: o nome da tabela na qual criar a geração de incorporações autónoma.
  • COLUMN, ...: todas as colunas que a tabela deve conter, além da coluna que quer incorporar automaticamente.
  • STRING_COL: o nome da coluna STRING que quer incorporar automaticamente.
  • EMBEDDING_COL_NAME: o nome da coluna de incorporação gerada automaticamente.
  • CONNECTION_ID: um valor STRING que contém o nome de uma associação a usar, como my_project.us.example_connection. Tem de conceder a função Utilizador do Vertex AI à conta de serviço da associação no projeto em que cria a tabela.
  • ENDPOINT: um valor STRING que especifica um ponto final do modelo de incorporação de texto da Vertex AI suportado a usar para o modelo de incorporação de texto. O valor do ponto final que especificar tem de incluir a versão do modelo, por exemplo, text-embedding-005. Se especificar o nome do modelo em vez de um URL, o BigQuery ML identifica automaticamente o modelo e usa o ponto final completo do modelo.

A tarefa de geração de incorporações em segundo plano começa pouco depois de a tabela ser criada ou depois de atualizar os dados na coluna de origem.

Para acompanhar o progresso da geração de incorporações, pode usar uma consulta semelhante à seguinte:

SELECT
  COUNT(*) AS total_num_rows,
  COUNTIF(description_embedding IS NOT NULL
          AND description_embedding.status = '') AS total_num_generated_embeddings
FROM
  PROJECT_ID.DATASET_ID.TABLE;

Depois de criar a tabela com incorporações, pode criar um índice vetorial na coluna STRUCT que contém a incorporação gerada automaticamente.

Exemplo

Suponhamos que é um grande retalhista que vende muitos produtos diferentes. Tem uma tabela de nomes e descrições de produtos e quer ajudar os seus clientes a encontrar os produtos que procuram. As consultas seguintes mostram como configurar a geração de incorporações autónoma para ajudar na pesquisa semântica das descrições dos seus produtos.

Primeiro, crie um conjunto de dados:

CREATE SCHEMA mydataset;

Em seguida, crie uma tabela com a geração de incorporações autónoma ativada para conter as informações dos produtos. A coluna gerada automaticamente chama-se description_embedding e baseia-se na coluna description.

# Create a table of products and descriptions with a generated embedding column.
CREATE TABLE mydataset.products (
  name STRING,
  description STRING,
  description_embedding STRUCT<result ARRAY<FLOAT64>, status STRING>
    GENERATED ALWAYS AS (AI.EMBED(
      description,
      connection_id => 'us.example_connection',
      endpoint => 'text-embedding-005'
    ))
    STORED OPTIONS( asynchronous = TRUE )
);

A seguinte consulta insere alguns nomes e descrições de produtos na tabela. Não especifica um valor para description_embedding porque é gerado automaticamente.

# Insert product descriptions into the table.
# The description_embedding column is automatically updated.
INSERT INTO mydataset.products (name, description) VALUES
  ("Lounger chair", "A comfortable chair for relaxing in."),
  ("Super slingers", "An exciting board game for the whole family."),
  ("Encyclopedia set", "A collection of informational books.");

Opcionalmente, pode criar um índice vetorial na tabela para acelerar a pesquisa. Um índice vetorial requer mais de três linhas, pelo que a consulta seguinte pressupõe que inseriu dados adicionais. Sempre que insere dados, a coluna description_embedding é atualizada automaticamente.

CREATE VECTOR INDEX my_index
ON mydataset.products(description_embedding)
OPTIONS(index_type = 'IVF');

Por último, pode usar a função AI.SEARCH para fazer uma pesquisa semântica nos seus produtos de um brinquedo divertido:

# Search for products that are fun to play with.
SELECT base.name, base.description, distance
FROM AI.SEARCH(TABLE mydataset.products, 'description', "A really fun toy");

/*------------------+----------------------------------------------+----------------------+
 | name             | description                                  | distance             |
 +------------------+----------------------------------------------+----------------------+
 | Super slingers   | An exciting board game for the whole family. | 0.80954913893618929  |
 | Lounger chair    | A comfortable chair for relaxing in.         | 0.938933930620146    |
 | Encyclopedia set | A collection of informational books.         | 1.1119297739353384   |
 +------------------+----------------------------------------------+----------------------*/

Obtenha informações sobre as colunas de incorporação geradas automaticamente

Para verificar se uma coluna é uma coluna de incorporação gerada automaticamente, consulte a vista INFORMATION_SCHEMA.COLUMNS.

A consulta seguinte mostra informações sobre todas as colunas de incorporação geradas automaticamente:

SELECT *
FROM PROJECT_ID.DATASET_ID.INFORMATION_SCHEMA.COLUMNS
WHERE is_generated = 'ALWAYS';

O campo generation_expression mostra a chamada para a função AI.EMBED que é usada para gerar as incorporações na coluna.

Use a sua própria reserva

Por predefinição, o BigQuery usa slots a pedido para processar os dados necessários para manter a coluna de incorporação gerada. Para garantir um desempenho previsível e consistente, pode, opcionalmente, criar uma reserva e definir o job_type como BACKGROUND. Quando existe uma reserva em segundo plano, o BigQuery usa-a para manter a coluna de incorporação gerada.

Resolução de problemas

A coluna de incorporação gerada contém dois campos: result e status. Se ocorrer um erro quando o BigQuery tenta gerar uma incorporação para uma linha específica na sua tabela, o campo result é NULL e o campo status descreve o erro. Por exemplo, se a coluna de origem for NULL, a incorporação result também é NULL e o estado é NULL value is not supported for embedding generation.

Um erro mais grave pode impedir a geração de incorporações. Neste caso, pode consultar a vista INFORMATION_SCHEMA.JOBS para a tarefa em segundo plano e analisar as informações no campo error_result. O ID da tarefa de uma tarefa de incorporação em segundo plano tem o prefixo gc_. Por exemplo, a seguinte consulta extrai todas as tarefas em segundo plano cujo resultado de erro não seja NULL:

SELECT * FROM `region-REGION.INFORMATION_SCHEMA.JOBS` j
WHERE EXISTS (
  SELECT 1
  FROM unnest(j.referenced_tables) t
  WHERE
    j.project_id = 'PROJECT_ID'
    AND t.dataset_id = 'DATASET_ID'
    AND t.table_id = 'TABLE'
)
AND starts_with(job_id, 'gc')
AND error_result IS NOT NULL
ORDER BY j.creation_time DESC;

Monitorize os custos

A geração de incorporações autónoma envia pedidos ao Vertex AI, o que pode gerar custos. Para acompanhar os custos da Vertex AI incorridos por tarefas de incorporação em segundo plano, siga estes passos:

  1. Veja os seus relatórios de faturação no Cloud Billing.

  2. Use filtros para refinar os resultados.

    Para serviços, selecione Vertex AI.

  3. Para ver os custos de uma tarefa específica, filtre por etiqueta.

    Defina a chave como bigquery_ml_job e o valor como o ID da tarefa da tarefa de incorporação. Todas as tarefas de incorporação em segundo plano têm o prefixo gc_.

Algumas cobranças podem demorar até 24 horas a aparecer na faturação na nuvem.

Limitações

  • Cada tabela suporta, no máximo, uma coluna de incorporação gerada automaticamente.
  • Não existe nenhuma indicação de que uma coluna é gerada automaticamente quando vê o esquema de uma tabela através da Google Cloud consola, do comando bq show ou do campo ddl da vista INFORMATION_SCHEMA.TABLES.
  • Não pode adicionar colunas de incorporação geradas a uma tabela existente através de ALTER TABLE ADD COLUMN.
  • Se criar uma cópia, um clone ou um instantâneo de uma tabela que tenha uma coluna de incorporação gerada, apenas os dados são copiados. A configuração de geração não se aplica à nova tabela e as atualizações à coluna de origem da nova tabela não resultam em novas incorporações.
  • Se restaurar uma tabela que tinha a geração de incorporações autónoma ativada a partir de uma captura instantânea, a configuração de geração de incorporações não é restaurada.
  • Só pode criar colunas de incorporação geradas através de SQL. Não pode usar os comandos bq mk ou bq update para criar colunas de incorporação geradas.
  • A coluna de origem da coluna gerada tem de ser uma coluna STRING.

  • Depois de criar a coluna de incorporação gerada, aplicam-se as seguintes limitações:

    • Não pode eliminar nem mudar o nome da coluna de origem, mas pode eliminar ou mudar o nome da coluna de incorporação gerada. Se eliminar a coluna de incorporação, pode eliminar ou mudar o nome da coluna de origem.
    • Não é possível alterar o tipo de dados da coluna de origem nem da coluna de incorporação gerada.

  • Não pode especificar valores predefinidos para colunas de incorporação geradas automaticamente.

  • Não pode escrever diretamente em colunas de incorporação geradas através dos seguintes métodos:

    • DML
    • Escritas de streaming
    • bq insert
    • bq copy -a

  • As tabelas com colunas de incorporação geradas não suportam políticas de segurança ao nível da coluna, como etiquetas de políticas.

  • Quando chama uma função de pesquisa, como VECTOR_SEARCH ou AI.SEARCH, as linhas com incorporações em falta na tabela base são ignoradas durante a pesquisa.

  • Não pode criar um índice vetorial particionado numa tabela que tenha a geração de incorporações autónoma ativada.

  • Se criar um índice vetorial na coluna de incorporação gerada automaticamente, o treino do índice começa depois de, pelo menos, 80% das linhas terem gerado incorporações. Pode usar a seguinte consulta para verificar a percentagem de incorporações na sua tabela que foram geradas:

    SELECT
  COUNTIF(description_embedding IS NOT NULL
  AND description_embedding.status = '') * 100.0 / COUNT(*) AS percent
FROM PROJECT_ID.DATASET_ID.TABLE;

O que se segue?