Geração autônoma de embeddings

Neste documento, descrevemos como usar a geração autônoma de embeddings para seus dados, o que permite que o BigQuery mantenha uma coluna de embeddings em uma tabela com base em uma coluna de origem. A coluna de origem precisa ter um tipo de dados STRING ou ObjectRef. Quando você adiciona ou modifica dados na coluna de origem, o BigQuery gera ou atualiza automaticamente a coluna de embedding desses dados usando um modelo de embedding da plataforma de agentes. Isso é útil se você quiser que o BigQuery mantenha os 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 por recuperação (RAG, na sigla em inglês), mas podem ser complexos de criar, gerenciar e consultar. É possível 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, é possível usar consultas semelhantes às seguintes para criar uma tabela com a geração de embeddings autônomos 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 autônoma de embeddings em uma tabela, é preciso ter as permissões e a conexão necessárias e ativar a API Vertex AI no projeto.

Funções exigidas

Para receber as permissões necessárias para ativar a geração autônoma de embeddings, 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 Agent Platform (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 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 embeddings em uma tabela, é necessário criar uma conexão a recursos do Cloud. Em seguida, conceda o papel de usuário da Agent Platform (roles/aiplatform.user) à conta de serviço que foi criada quando você criou 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.

Ao definir a função AI.EMBED para uma coluna de embedding gerada automaticamente, se você não especificar o argumento task_type e o modelo for compatível com task_type, o BigQuery vai definir task_type como RETRIEVAL_DOCUMENT por padrão. Quando você consulta a tabela usando a função AI.SEARCH ou a função VECTOR_SEARCH, o BigQuery gera o embedding de consulta em tempo real usando o seguinte comportamento de task_type:

• Se a coluna de embedding da tabela usar RETRIEVAL_DOCUMENT, seja por padrão ou explicitamente especificado, o BigQuery usará RETRIEVAL_QUERY para incorporar a consulta de pesquisa.
• Caso contrário, o BigQuery vai usar o mesmo task_type configurado para a coluna de embedding da tabela.

Criar uma tabela com uma coluna de embedding gerada automaticamente

É possível usar a geração autônoma de embeddings para gerar embeddings usando a função AI.EMBED em uma instrução CREATE TABLE.

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 embedding autônomo 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 Agent Platform à 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 plataforma de agentes compatível para usar com 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 automaticamente o modelo e usar o endpoint completo dele.

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

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

Adicionar uma coluna de embedding gerada automaticamente a uma tabela

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

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

Para acompanhar o progresso da geração de embeddings, use uma consulta como 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 o que procuram. As consultas a seguir mostram como configurar a geração de embeddings autônomos 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')
      # 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.");

Se quiser, crie um índice de vetor na tabela para acelerar a pesquisa. Um índice vetorial requer 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 realizar uma pesquisa semântica nos seus produtos em busca 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   |
 +------------------+----------------------------------------------+----------------------*/

Embeddings gerados de ObjectRef colunas

É possível adicionar colunas de embedding geradas para uma coluna ObjectRef em uma tabela.

O exemplo a seguir mostra como criar uma tabela com uma coluna ObjectRef e adicionar uma coluna de embedding gerada para essa coluna:

# Create a table with ObjectRef columns.
CREATE TABLE mydataset.images AS
SELECT
  REGEXP_EXTRACT(ref.uri, r'.*/(.*).jpg$') AS name,
  ref
FROM mydataset.object_table;

# Add a generated embedding column for the ObjectRef column.
ALTER TABLE mydataset.images
ADD COLUMN image_embedding STRUCT<result ARRAY<FLOAT64>, status STRING>
GENERATED ALWAYS AS (
  AI.EMBED(
    ref,
    connection_id => "us.my_connection",
    endpoint => "multimodalembedding@001")
)
STORED OPTIONS (asynchronous = true);

Receber informações sobre colunas de embedding geradas automaticamente

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

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, incluindo o argumento padrão task_type => 'RETRIEVAL_DOCUMENT' se você não especificou um task_type para um modelo que o aceita.

Usar sua própria reserva

Por padrão, o BigQuery usa slots on demand para lidar com o processamento necessário para manter a 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.

Cotas

Quando você usa um endpoint da Agent Platform para gerar embeddings especificando o parâmetro endpoint na função AI.EMBED, o BigQuery envia solicitações à Agent Platform para gerar embeddings. Essas solicitações estão sujeitas às cotas da plataforma de agentes. A cota de solicitações por minuto do modelo de embedding afeta diretamente a capacidade de processamento dos jobs de geração de embedding em segundo plano. Se a geração de embeddings estiver lenta, solicite um limite de cota maior para a plataforma de agentes seguindo as instruções em Como solicitar uma cota maior. Se você especificar o parâmetro model na função AI.EMBED, os embeddings serão gerados no BigQuery e nenhuma solicitação será enviada à Agent Platform. Portanto, as cotas da Agent Platform não se aplicam.

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, o embedding 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 coluna async_generation_status na visualização INFORMATION_SCHEMA.COLUMNS para identificar o erro de bloqueio.

Alguns erros de bloqueio:

• Erros de permissão negada
• Erros de não encontrado
• Erros de endpoint de modelo de embedding não compatível
• Erros de API Vertex AI não ativada

Quando o próximo job de geração de embedding for concluído, a coluna async_generation_status será limpa.

A consulta a seguir mostra como verificar se há erros de bloqueio:

SELECT
  column_name,
  async_generation_status
FROM
  mydataset.INFORMATION_SCHEMA.COLUMNS
WHERE
  table_name = 'images';

Se a coluna image_embedding tiver um erro de bloqueio, o resultado será semelhante a este:

[
  {
    "column_name": "image_embedding",
    "async_generation_status": {
      "blocking_error": {
        "message": "<service_account> does not have the permission to access resources used by AI.EMBED. Please follow https://docs.cloud.google.com/bigquery/docs/permissions-for-ai-functions to set up permissions.",
        ...
      }
    }
  }
]

Também é possível consultar a visualização INFORMATION_SCHEMA.JOBS do job em segundo plano e conferir as informações no campo error_result. O código da tarefa de um job de embedding em segundo plano é prefixado com 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

Os custos de geração de embeddings autônomos se enquadram nas categorias a seguir.

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 de acordo com o modelo de faturamento on demand da DML.

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

Para rastrear os valores total_slot_ms e total_bytes_billed de jobs de DML em segundo plano em uma tabela, consulte a visualização INFORMATION_SCHEMA.JOBS para jobs com um prefixo job_id de gc_:

SELECT
  job_id,
  creation_time,
  reservation_id,
  total_slot_ms,
  total_bytes_processed,
  total_bytes_billed
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_')
ORDER BY
  j.creation_time DESC;

Substitua:

• REGION: a região do conjunto de dados que contém sua tabela, por exemplo, us.
• PROJECT_ID: o ID do projeto que contém a tabela.
• DATASET_ID: o nome do conjunto de dados que contém a tabela.
• TABLE: o nome da tabela com a geração autônoma de embeddings ativada.

Se você especificar o modelo embeddinggemma-300m integrado usando o parâmetro model na função AI.EMBED, o BigQuery também vai gerar os embeddings diretamente nesses jobs de DML em segundo plano usando slots do BigQuery. Nenhuma solicitação é enviada à plataforma de agentes, e nenhuma cobrança é feita. Para mais informações, consulte Escolher um modelo.

Custos da Gemini Enterprise Agent Platform

Quando você especifica um modelo da Gemini Enterprise Agent Platform usando o parâmetro endpoint na função AI.EMBED, a geração autônoma de embeddings envia solicitações para a Gemini Enterprise Agent Platform, o que pode gerar custos. Para acompanhar os custos da Plataforma de Agentes gerados por jobs de embedding em segundo plano, siga estas etapas:

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

2. Use filtros para refinar os resultados.

   Em serviços, selecione Vertex AI.

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

   Defina a chave como bigquery_ml_job e o valor como o código da tarefa 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.
• As operações simultâneas de DML podem causar atrasos e falhas temporárias na geração de embeddings. Para melhorar o desempenho e reduzir custos, recomendamos inserir dados em lotes e evitar atualizações frequentes de DML.
• Se você estiver usando a API de streaming legada para ingerir dados, pode haver alguns atrasos antes que a geração de embeddings comece.
• Ao usar a API BigQuery Storage Write (gRPC), os jobs de geração de embedding em segundo plano podem falhar se um job de gravação de streaming estiver em execução simultaneamente. Quando isso ocorre, a cota da Agent Platform e os custos de DML em segundo plano são desperdiçados. O uso da API Storage Write (gRPC) também causa jobs simultâneos de geração de embeddings na tabela, mas isso é processado pelo BigQuery, e nenhuma cota da plataforma de agentes ou custos de DML em segundo plano são desperdiçados.
• Para maior capacidade de processamento em endpoints remotos da Agent Platform, recomendamos o uso de modelos de embedding de texto em vez de modelos do Gemini. Para mais informações, consulte Cotas.
• Não há indicação de que uma coluna é gerada automaticamente quando você visualiza o esquema de uma tabela usando o console do Cloud de Confiance 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, somente 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 vão resultar em novos embeddings.
• Se você restaurar uma tabela que tinha a geração autônoma de embeddings ativada com base em um snapshot, a configuração de geração de embeddings não será restaurada.
• Ao usar a API BigQuery, só é possível especificar a propriedade generatedColumn ao criar uma nova coluna. Não é possível adicionar, atualizar ou remover a propriedade generatedColumn em uma coluna atual.

• 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 você ainda pode descartar ou renomear a coluna de embedding gerada. Se você remover a coluna de embedding, poderá remover 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 load
  • bq copy -a

• As tabelas com colunas de embedding geradas não são compatíveis com nenhuma política 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 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 de embedding autônomo ativada.

• Se você criar um índice vetorial na coluna de embedding gerada automaticamente, o treinamento do índice vai começar depois que pelo menos 80% das linhas tiverem embeddings gerados. Para verificar o progresso da geração de embeddings, siga estas etapas:

  Consulte a porcentagem de embeddings na tabela que foram gerados:

  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 vetorial.