Geração autônoma de embeddings

Este documento descreve como usar a geração autônoma de incorporações para seus dados, o que permite que o BigQuery mantenha uma coluna de incorporações em uma tabela com base em uma coluna de origem. Quando você adiciona ou modifica dados na coluna de origem, o BigQuery gera ou atualiza automaticamente a coluna de incorporação desses dados usando um modelo de incorporação da Vertex AI. Isso é útil se você quiser permitir que o BigQuery mantenha seus encapsulamentos quando os dados de origem forem atualizados regularmente.

Os embeddings são úteis para aplicativos modernos de IA generativa, como a geração aumentada de recuperação (RAG, na sigla em inglês), mas podem ser complexos de criar, gerenciar e consultar. Você pode usar a geração autônoma de embeddings para simplificar o processo de criação, manutenção e consulta de embeddings para uso em pesquisas de similaridade e outros aplicativos de IA generativa.

Por exemplo, você pode usar consultas semelhantes às seguintes para criar uma tabela com a geração autônoma de embeddings ativada, inserir dados e realizar 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 autônoma de incorporações em uma tabela, é necessário ter as permissões e a conexão necessárias.

Funções exigidas

Para receber as permissões necessárias para ativar a geração autônoma de incorporações, peça ao administrador para conceder a você os seguintes papéis do IAM:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Criar uma conexão e conceder permissão a uma conta de serviço

Para ativar a geração autônoma de incorporações em uma tabela, crie uma conexão de recursos do Cloud. Em seguida, conceda o papel de usuário da Vertex AI (roles/aiplatform.user) à conta de serviço criada quando você criou a conexão.

Criar uma tabela com geração autônoma de embeddings

Você pode usar a geração autônoma de embeddings com a AI.EMBED função em uma CREATE TABLE instrução.

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:

  • DATASET_ID: o nome do conjunto de dados em que você quer criar a tabela.
  • TABLE: o nome da tabela em que a geração autônoma de incorporações será criada.
  • COLUMN, ...: todas as colunas que sua tabela deve conter além da coluna que você quer incorporar automaticamente.
  • STRING_COL: o nome da coluna STRING que você quer incorporar automaticamente.
  • EMBEDDING_COL_NAME: o nome da coluna de embedding gerada automaticamente.
  • CONNECTION_ID: um valor STRING que contém o nome de uma conexão a ser usada, como my_project.us.example_connection. Você precisa conceder a função de Usuário da Vertex AI à conta de serviço da conexão no projeto em que você cria a tabela.
  • ENDPOINT: um valor STRING que especifica um endpoint de modelo de incorporação de texto da Vertex AI compatível a ser usado. O valor do endpoint especificado precisa incluir a versão do modelo, por exemplo, text-embedding-005. Se você especificar o nome do modelo em vez de um URL, o BigQuery ML vai identificar automaticamente o modelo e usar o endpoint completo dele.

O job em segundo plano de geração de incorporação começa logo após a criação da tabela ou depois que você atualiza os dados na coluna de origem.

Para acompanhar o progresso da geração de embeddings, use uma consulta semelhante a esta:

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 embeddings, você pode criar um índice de vetor na coluna STRUCT que contém o embedding gerado automaticamente.

Exemplo

Suponha que você seja um grande varejista que vende muitos produtos diferentes. Você tem uma tabela de nomes e descrições de produtos e quer ajudar seus clientes a encontrar o que estão procurando. As consultas a seguir mostram como configurar a geração autônoma de incorporações para ajudar na pesquisa semântica das descrições de produtos.

Primeiro, crie um conjunto de dados:

CREATE SCHEMA mydataset;

Em seguida, crie uma tabela com a geração autônoma de embeddings ativada para armazenar as informações do produto. A coluna gerada automaticamente é chamada de description_embedding e é baseada 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 consulta a seguir insere alguns nomes e descrições de produtos na tabela. Não é preciso especificar um valor para description_embedding porque ele é 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.");

Você também pode criar um índice de vetor na tabela para acelerar a pesquisa. Um índice vetorial exige mais de três linhas. Portanto, a consulta a seguir pressupõe que você inseriu mais dados. Sempre que você insere dados, a coluna description_embedding é atualizada automaticamente.

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

Por fim, use a função AI.SEARCH para fazer uma pesquisa semântica nos seus produtos e encontrar 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   |
 +------------------+----------------------------------------------+----------------------*/

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

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

A consulta a seguir 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 os embeddings na coluna.

Usar sua própria reserva

Por padrão, o BigQuery usa slots sob demanda para processar a manutenção da coluna de incorporação gerada. Para garantir uma performance previsível e consistente, você pode criar uma reserva e definir job_type como BACKGROUND. Quando uma reserva em segundo plano está presente, o BigQuery a usa para manter a coluna de incorporação gerada.

Solução de problemas

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

Um erro mais grave pode interromper a geração de embeddings. Nesse caso, é possível consultar a visualização INFORMATION_SCHEMA.JOBS do job em segundo plano e analisar as informações no campo error_result. O ID de um job de incorporação em segundo plano tem o prefixo gc_. Por exemplo, a consulta a seguir extrai todos os jobs em segundo plano cujo resultado de erro não é 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;

Monitorar custos

A geração autônoma de embeddings envia solicitações para a Vertex AI, o que pode gerar custos. Para acompanhar os custos da Vertex AI gerados por jobs de incorporação em segundo plano, siga estas etapas:

  1. Confira seus relatórios de faturamento no Cloud Billing.

  2. Use filtros para refinar os resultados.

    Em "Serviços", selecione Vertex AI.

  3. Para conferir as cobranças de um job específico, filtre por rótulo.

    Defina a chave como bigquery_ml_job e o valor como o ID do job de incorporação. Todos os jobs de incorporação em segundo plano têm o prefixo gc_.

Pode levar até 24 horas para que algumas cobranças apareçam no Cloud Billing.

Limitações

  • Cada tabela aceita no máximo uma coluna de incorporação gerada automaticamente.
  • Não há indicação de que uma coluna é gerada automaticamente quando você visualiza o esquema de uma tabela usando o console Google Cloud , o comando bq show ou o campo ddl da visualização INFORMATION_SCHEMA.TABLES.
  • Não é possível adicionar colunas de incorporação geradas a uma tabela usando ALTER TABLE ADD COLUMN.
  • Se você criar uma cópia, um clone ou um snapshot de uma tabela que tenha uma coluna de incorporação gerada, apenas os dados serão copiados. A configuração de geração não se aplica à nova tabela, e as atualizações na coluna de origem da nova tabela não resultam em novos embeddings.
  • Se você restaurar uma tabela que tinha a geração autônoma de incorporações ativada de um instantâneo, a configuração de geração de incorporações não será restaurada.
  • Só é possível criar colunas de embedding geradas usando SQL. Não é possível usar os comandos bq mk ou bq update para criar colunas de incorporação geradas.
  • A coluna de origem da coluna gerada precisa ser STRING.

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

    • Não é possível soltar ou renomear a coluna de origem, mas você ainda pode soltar ou renomear a coluna de incorporação gerada. Se você remover a coluna de incorporação, poderá remover ou renomear a coluna de origem.
    • Não é possível mudar o tipo de dados da coluna de origem ou da coluna de incorporação gerada.

  • Não é possível especificar valores padrão para colunas de incorporação geradas automaticamente.

  • Não é possível gravar diretamente em colunas de embeddings geradas usando estes métodos:

    • DML
    • Gravações de streaming
    • bq insert
    • bq copy -a

  • Tabelas com colunas de incorporação geradas não são compatíveis com políticas de segurança no nível da coluna, como tags de política.

  • Quando você chama uma função de pesquisa, como VECTOR_SEARCH ou AI.SEARCH, as linhas com embeddings ausentes na tabela de base são ignoradas durante a pesquisa.

  • Não é possível criar um índice de vetor particionado em uma tabela que tenha a geração autônoma de incorporação ativada.

  • Se você criar um índice vetorial na coluna de incorporação gerada automaticamente, o treinamento do índice vai começar depois que pelo menos 80% das linhas tiverem gerado incorporações. Use a consulta a seguir para verificar qual porcentagem de embeddings na sua tabela foi gerada:

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

A seguir