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 Agent Platform. 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. Você pode 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')
      # Alternatively, you can use the syntax for a built-in model.
      # AI.EMBED(description, model => 'embeddinggemma-300m')
    ) 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 Agent Platform: 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, você deve 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

Você pode 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

Você pode 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 |
          model => MODEL
        })
    )
    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. Conceda 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 compatível com a Agent Platform 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.

• MODEL (Visualização): um valor STRING que especifica um modelo de embedding de texto integrado. O único valor compatível é o embeddinggemma-300m modelo. Se você especificar esse parâmetro, não será possível especificar os parâmetros endpoint ou connection_id.

  Ao especificar o parâmetro MODEL, seus dados permanecem no BigQuery e seus slots são usados para criar os embeddings. Nenhum dado é enviado para a Agent Platform e nenhuma cobrança é feita nela.

Adicionar uma coluna de embedding gerada automaticamente a uma tabela atual

Você também pode adicionar uma coluna de embedding gerada automaticamente a uma tabela atual por meio de uma instrução ALTER TABLE ADD COLUMN.

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 começa 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, você pode 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')
      # Alternatively, you can use the syntax for a built-in model.
      # AI.EMBED(description, model => 'embeddinggemma-300m')
    ) STORED OPTIONS( asynchronous = TRUE )
);

A consulta a seguir insere alguns nomes e descrições de produtos na tabela. Não especifique 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, crie 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, você pode usar a AI.SEARCH função para realizar 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   |
 +------------------+----------------------------------------------+----------------------*/

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.

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, consulte a visualização INFORMATION_SCHEMA.JOBS para o job em segundo plano e confira 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

Os custos de geração de embeddings autônoma se enquadram nas seguintes categorias.

Custos de DML em segundo plano do BigQuery

Os embeddings gerados são gravados na tabela usando jobs de DML em segundo plano. Por padrão, o BigQuery usa slots sob demanda para processar esses jobs. O projeto da tabela é faturado seguindo o modelo de faturamento sob demanda de DML.

Como alternativa, 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 executar os jobs de DML em segundo plano. A reserva em segundo plano será faturada pelo uso do tempo de slot dos jobs de DML em segundo plano.

Custos da plataforma de agentes do Gemini Enterprise

A geração de embeddings autônoma envia solicitações para a plataforma de agentes do Gemini Enterprise, o que pode gerar custos. Para acompanhar os custos da Agent Platform 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 seus resultados.

   Para 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 embedding. Todos os jobs de embedding em segundo plano têm um prefixo de 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 embedding gerada automaticamente.
• Operações DML simultâneas podem causar atrasos e falhas temporárias na geração de embedding. Para melhorar a performance 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.
• 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 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. Use 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.