Geração de embeddings autônoma

Visualizar

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Observação: para enviar feedback ou solicitar suporte para esse recurso, entre em contato com [e-mail]

Este documento descreve como usar a geração de embeddings autônoma para seus dados, o que permite que o BigQuery mantenha uma coluna de embeddings em uma tabela com base em uma coluna de origem. Ao adicionar ou modificar dados na coluna de origem, o BigQuery gera ou atualiza automaticamente a coluna de embedding para esses dados usando um modelo de embedding da Vertex AI. Isso é útil se você quiser que o BigQuery mantenha seus embeddings 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. É possível usar a geração de embeddings autônoma 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 de embeddings autônoma 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 de embeddings autônoma em uma tabela, você precisa ter as permissões e a conexão necessárias e ativar a API Vertex AI para seu projeto.

Funções exigidas

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

• Para usar um recurso de conexão: usuário de conexões do BigQuery (roles/bigquery.connectionUser) na conexão
• Para criar ou alterar uma tabela: editor de dados do BigQuery (roles/bigquery.dataEditor) na tabela
• Conceda à conta de serviço da conexão o seguinte papel para que ela possa acessar modelos hospedados em endpoints da Vertex AI: Usuário da Vertex AI (roles/aiplatform.user) no projeto que tem a conexão

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 personalizados papéis ou outros predefinidos papéis.

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

Para ativar a geração de embeddings autônoma em uma tabela, é necessário criar uma conexão a recursos do Cloud. Em seguida, conceda o papel de usuário da Vertex AI (roles/aiplatform.user) à conta de serviço criada ao criar a conexão.

Criar uma coluna de embedding gerada automaticamente

É possível criar uma coluna de embedding gerada automaticamente em uma nova tabela ou adicionar uma a uma tabela atual.

Criar uma tabela com uma coluna de embedding gerada automaticamente

É possível usar a geração de embeddings autônoma para gerar embeddings usando 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 de embeddings autônoma será criada.
• COLUMN, ...: todas as colunas que a tabela precisa 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. É necessário conceder o papel 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 embedding de texto da Vertex AI compatível a ser usado para o modelo de embedding de texto. 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 e usar automaticamente o endpoint completo do modelo.

Adicionar uma coluna de embedding gerada automaticamente a uma tabela atual

Também é possível adicionar uma coluna de embedding gerada automaticamente a uma tabela atual usando uma ALTER TABLE ADD COLUMN instrução.

ALTER TABLE DATASET_ID.TABLE
  ADD COLUMN 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)
;

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

Para acompanhar o progresso da geração de embedding, 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 ter a tabela com embeddings, é possível criar um índice vetorial 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 os produtos que estão procurando. As consultas a seguir mostram como configurar a geração de embeddings autônoma para ajudar na pesquisa semântica das descrições dos produtos.

Primeiro, crie um conjunto de dados:

CREATE SCHEMA mydataset;

Em seguida, crie uma tabela com a geração de embeddings autônoma 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 é necessário 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.");

Opcionalmente, é possível criar um índice vetorial 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 dados adicionais. 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, é possível usar a AI.SEARCH função para realizar uma pesquisa semântica nos seus produtos para 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 embedding geradas automaticamente

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

A consulta a seguir mostra informações sobre todas as colunas de embedding 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 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 embedding gerada. Para garantir um desempenho previsível e consistente, é possível 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 embedding gerada.

Solução de problemas

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

Um erro mais grave pode interromper a geração de embedding. Nesse caso, é possível consultar a INFORMATION_SCHEMA.JOBS visualização para o job em segundo plano e conferir as informações no campo error_result. O ID do job de um embedding 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;

Acompanhar custos

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

1. Consulte seus relatórios de faturamento em Cloud Billing.

2. Use filtros para refinar os resultados.

   Para serviços, selecione Vertex AI.

3. Para conferir os encargos 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 embedding. Os jobs de embedding em segundo plano têm um prefixo de gc_.

Pode levar até 24 horas para que alguns encargos apareçam no Cloud Billing.

Limitações

• Cada tabela aceita no máximo uma coluna de embedding gerada automaticamente.
• Operações DML simultâneas podem causar atrasos e falhas temporárias na geração de embedding. Para melhorar o desempenho e reduzir os custos, recomendamos injetar dados em lotes e evitar atualizações frequentes de DML.
• Se você estiver usando a API BigQuery Storage Write para ingerir dados, poderá haver alguns atrasos antes do início da geração de embedding.
• Não há indicação de que uma coluna seja gerada automaticamente ao visualizar o esquema de uma tabela usando o Google Cloud console, o bq show comando, ou o campo ddl da visualização INFORMATION_SCHEMA.TABLES.
• Se você criar uma cópia, um clone ou um snapshot de uma tabela que tenha uma coluna de embedding 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 resultarão em novos embeddings.
• Se você restaurar uma tabela que tinha a geração de embeddings autônoma ativada de um snapshot, a configuração de geração de embedding não será restaurada.
• É possível criar colunas de embedding geradas apenas usando SQL. Não é possível usar os comandos bq mk ou bq update para criar colunas de embedding geradas.
• A coluna de origem da coluna gerada precisa ser uma coluna STRING.

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

  • Não é possível descartar ou renomear a coluna de origem, mas ainda é possível descartar ou renomear a coluna de embedding gerada. Se você descartar a coluna de embedding, poderá descartar ou renomear a coluna de origem.
  • Não é possível alterar o tipo de dados da coluna de origem ou da coluna de embedding gerada.

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

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

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

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

• Ao chamar 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 vetorial particionado em uma tabela que tenha a geração de embeddings autônoma ativada.

• Se você criar um índice vetorial na coluna de embedding gerada automaticamente, o treinamento do índice será iniciado depois que pelo menos 80% das linhas tiverem embeddings gerados. É possível usar a consulta a seguir para verificar qual porcentagem de embeddings na 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

• Saiba mais sobre como criar e gerenciar índices vetoriais.
• Consulte a Introdução à pesquisa de vetor.