O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Realizar pesquisa semântica e geração aumentada de recuperação

Neste tutorial, você vai usar um modelo remoto com a função AI.GENERATE_EMBEDDING para gerar embeddings de texto em uma tabela do BigQuery. Em seguida, crie um índice vetorial para indexar os embeddings e melhorar o desempenho da pesquisa.

Use a função VECTOR_SEARCH com os embeddings para procurar textos semelhantes. A pesquisa vetorial é uma técnica para comparar objetos semelhantes usando embeddings, que são vetores numéricos de alta dimensão que representam uma determinada entidade, como um texto.

Por fim, você realiza a geração aumentada por recuperação (RAG) gerando texto com a função AI.GENERATE_TEXT. A RAG é um framework de IA que combina os pontos fortes dos sistemas de recuperação de informações (como pesquisa e bancos de dados) com os recursos dos modelos de linguagem grande (LLMs) generativos. Ao combinar seus dados e o conhecimento do mundo com as habilidades linguísticas do LLM, a geração com base no mundo real é mais precisa, atualizada e relevante para suas necessidades específicas.

Neste tutorial, usamos dados do conjunto de dados público do Google Patentes.

Objetivos

Criar um modelo remoto do BigQuery ML usando um modelo de embedding da Gemini Enterprise Agent Platform.
Use o modelo remoto com a função AI.GENERATE_EMBEDDING para gerar embeddings de texto em uma tabela do BigQuery.
Crie um índice vetorial para indexar os embeddings e melhorar o desempenho da pesquisa.
Use a função VECTOR_SEARCH com os embeddings para procurar textos semelhantes.
Realize a RAG gerando texto com a função AI.GENERATE_TEXT e usando resultados da pesquisa vetorial para aumentar a entrada do comando e melhorar os resultados.

Custos

Neste documento, você vai usar os seguintes componentes faturáveis do Google Cloud:

BigQuery ML: You incur costs for the data that you process in BigQuery.
Gemini Enterprise Agent Platform: You incur costs for calls to the Agent Platform service that's represented by the remote model.

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.

Novos usuários do Google Cloud podem estar qualificados para um teste sem custo financeiro.

Para mais informações, consulte as seguintes páginas de preços:

Antes de começar

No console do Google Cloud , na página do seletor de projetos, selecione ou crie um projeto do Google Cloud .
Papéis necessários para selecionar ou criar um projeto
- Selecionar um projeto: para selecionar um projeto, não é necessário ter um papel do IAM específico. É possível selecionar qualquer projeto em que você tenha um papel.
- Criar um projeto: para criar um projeto, é preciso ter o papel de criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.
Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

Acessar o seletor de projetos
Verifique se o faturamento está ativado para o projeto do Google Cloud .
Ative as APIs do BigQuery, do Cloud Storage e da Gemini Enterprise Agent Platform, se ainda não estiverem ativadas.
Funções necessárias para ativar APIs
Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.
Ativar as APIs

Funções exigidas

Para conseguir as permissões necessárias para concluir o tutorial, peça ao administrador para conceder a você os seguintes papéis do IAM:

Criar conjuntos de dados, tabelas e modelos: Proprietário de dados do BigQuery (roles/bigquery.dataOwner)
Executar jobs do BigQuery: Usuário de jobs do BigQuery (roles/bigquery.jobUser)
Criar e gerenciar conexões: Administrador de conexão do BigQuery (roles/bigquery.connectionAdmin)

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 um conjunto de dados

Para criar um conjunto de dados do BigQuery, selecione uma das seguintes opções:

Console

No console do Google Cloud , acesse a página BigQuery.

Acessar o BigQuery
No painel à esquerda, clique em Explorer:

Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.
No Explorer, expanda o projeto e clique em Conjuntos de dados.
Na página Conjuntos de dados, clique em Criar conjunto de dados.
No painel Criar conjunto de dados, faça o seguinte:
- Para o código do conjunto de dados, insira bqml_tutorial.
- Em Local dos dados, selecione EUA.
Não altere as outras configurações padrão.
Clique em Criar conjunto de dados.

bq

Para criar um novo conjunto de dados, use o comando bq mk --dataset.

Crie um conjunto de dados chamado bqml_tutorial com o local de dados definido como US:

bq mk --dataset \
  --location=US \
  --description "BigQuery ML tutorial dataset." \
  bqml_tutorial

Confirme se o conjunto de dados foi criado:
```
bq ls
```

API

Chame o método datasets.insert com um recurso de conjunto de dados definido:

{
  "datasetReference": {
     "datasetId": "bqml_tutorial"
  }
}

Criar o modelo remoto para geração de embedding de texto

Nesta seção, você vai criar um modelo remoto que representa um modelo de geração de embedding de texto hospedado da Agent Platform. Ao criar o modelo, use a conexão DEFAULT para chamar a API Text Embeddings e receber embeddings de texto usando o modelo text-embedding-005. Se você não tiver uma conexão padrão, a instrução CREATE MODEL vai criar uma para você.

Para criar o modelo de embedding de texto, siga estas etapas:

No console do Google Cloud , acesse a página BigQuery.

Acessar o BigQuery
Para criar o modelo, cole este comando no editor de consultas e clique em Executar:
```
CREATE OR REPLACE MODEL `bqml_tutorial.embedding_model`
  REMOTE WITH CONNECTION DEFAULT
  OPTIONS (ENDPOINT = 'text-embedding-005');
```
A consulta leva alguns segundos para ser concluída. Depois disso, o modelo embedding_model pode ser acessado pelo painel Explorer.

Você vai receber uma mensagem de confirmação como esta: Successfully created model named embedding_model.

Gerar embeddings de texto

Gerar embeddings de texto com base em resumos de patentes usando a função AI.GENERATE_EMBEDDING e, em seguida, gravá-los em uma tabela do BigQuery para que possam ser pesruisados.

A geração de embeddings usando a função AI.GENERATE_EMBEDDING pode falhar devido a cotas ou indisponibilidade de serviço do LLM da Agent Platform. Se houver falha, os detalhes do erro serão retornados na coluna status nos resultados da consulta.

Para métodos alternativos de geração de embedding de texto no BigQuery, consulte o tutorial de embedding de texto com modelos pré-treinados do TensorFlow.

Para gerar embeddings de texto, cole este comando no editor de consultas e clique em Executar:

  CREATE OR REPLACE TABLE bqml_tutorial.embeddings AS
  SELECT * FROM AI.GENERATE_EMBEDDING(
    MODEL bqml_tutorial.embedding_model,
    (
      SELECT *, abstract AS content
      FROM patents-public-data.google_patents_research.publications
      WHERE LENGTH(abstract) > 0 AND LENGTH(title) > 0 AND country = 'Singapore'
    )
  )
  WHERE LENGTH(status) = 0;

A consulta leva alguns minutos para ser concluída. Você vai receber uma mensagem de confirmação como esta:This statement created a new table named embeddings.

Criar um índice vetorial

Se você criar um índice vetorial em uma coluna de embedding, uma pesquisa vetorial realizada nessa coluna usará a técnica de pesquisa do vizinho aproximado mais próximo. Essa técnica melhora o desempenho da busca vetorial e retorna resultados mais aproximados, mas o recall é reduzido.

Para criar um índice de vetor, use a instrução de linguagem de definição de dados (DDL, na sigla em inglês) CREATE VECTOR INDEX. Para verificar se o índice está disponível, consulte a visualização INFORMATION_SCHEMA.VECTOR_INDEXES para verificar se o valor da coluna coverage_percentage é maior que 0, e o valor da coluna last_refresh_time não é NULL.

Para criar e verificar o índice vetorial, siga estas etapas:

Para criar o índice vetorial, cole este comando no editor de consultas e clique em Executar:
```
CREATE OR REPLACE VECTOR INDEX my_index
ON `bqml_tutorial.embeddings`(embedding)
OPTIONS(index_type = 'IVF',
  distance_type = 'COSINE',
  ivf_options = '{"num_lists":500}');
```
Você vai receber uma mensagem de confirmação como esta: The vector index creation on table bqml_tutorial.embeddings was initiated. Please query bqml_tutorial.INFORMATION_SCHEMA.VECTOR_INDEXES to check the progress of the index.

A criação de um índice vetorial geralmente leva apenas alguns segundos. Leva mais dois a três minutos para que o índice vetorial seja preenchido de forma assíncrona.
Para verificar se o índice está pronto para uso, cole este comando no editor de consultas e clique em Executar:
```
SELECT table_name, index_name, index_status,
coverage_percentage, last_refresh_time, disable_reason
FROM `PROJECT_ID.bqml_tutorial.INFORMATION_SCHEMA.VECTOR_INDEXES`;
```
Substitua PROJECT_ID pelo ID do projeto.

Depois de executar a consulta, o índice estará disponível se a coluna index_status nos resultados mostrar que o índice é ACTIVE e se o valor coverage_percentage for 100.

Realizar uma pesquisa de similaridade de texto usando o índice vetorial

Use a função VECTOR_SEARCH para pesquisar patentes relevantes que correspondem a embeddings gerados a partir de uma consulta de texto.

O argumento top_k determina o número de correspondências a serem retornadas, neste caso, cinco. A opção fraction_lists_to_search determina a porcentagem de listas de índices de vetor a serem pesquisadas. O índice vetorial que você criou tem 500 listas. Portanto, o valor fraction_lists_to_search de .01 indica que essa busca vetorial verifica cinco dessas listas. Um valor de fraction_lists_to_search menor, como mostrado aqui, oferece um recall menor e um desempenho mais rápido.

Para mais informações sobre listas de índices vetoriais, consulte a opção de índice vetorial num_lists.

O modelo usado para gerar os embeddings nesta consulta precisa ser o mesmo usado para gerar os embeddings na tabela que você está comparando. Caso contrário, os resultados da pesquisa não serão precisos.

Para realizar uma pesquisa de similaridade de texto, cole este comando no editor de consultas e clique em Executar:

  SELECT query.query, base.publication_number, base.title, base.abstract
  FROM VECTOR_SEARCH(
    TABLE bqml_tutorial.embeddings, 'embedding',
    (
    SELECT embedding, content AS query
    FROM AI.GENERATE_EMBEDDING(
    MODEL bqml_tutorial.embedding_model,
    (SELECT 'improving password security' AS content))
    ),
    top_k => 5, options => '{"fraction_lists_to_search": 0.01}');

O resultado será o seguinte:

+-----------------------------+--------------------+-------------------------------------------------+-------------------------------------------------+
|            query            | publication_number |                       title                     |                      abstract                   |
+-----------------------------+--------------------+-------------------------------------------------+-------------------------------------------------+
| improving password security | SG-120868-A1       | Data storage device security method and a...    | Methods for improving security in data stora... |
| improving password security | SG-10201610585W-A  | Passsword management system and process...      | PASSSWORD MANAGEMENT SYSTEM AND PROCESS ...     |
| improving password security | SG-148888-A1       | Improved system and method for...               | IMPROVED SYSTEM AND METHOD FOR RANDOM...        |
| improving password security | SG-194267-A1       | Method and system for protecting a password...  | A system for providing security for a...        |
| improving password security | SG-120868-A1       | Data storage device security...                 | Methods for improving security in data...       |
+-----------------------------+--------------------+-------------------------------------------------+-------------------------------------------------+

Criar o modelo remoto para geração de texto

Para criar um modelo remoto que represente um modelo de geração de texto hospedado da Agent Platform, cole este comando no editor de consultas e clique em Executar:

  CREATE OR REPLACE MODEL bqml_tutorial.text_model
    REMOTE WITH CONNECTION DEFAULT
    OPTIONS (ENDPOINT = 'gemini-2.5-flash');

Você vai receber uma mensagem de confirmação semelhante a esta: Successfully created model named text_model.

Gerar texto aumentado pelos resultados da pesquisa vetorial

Alimente os resultados da pesquisa como comandos para gerar texto gerado com a função AI.GENERATE_TEXT.

Para aumentar os resultados da pesquisa vetorial, cole este comando no editor de consultas e clique em Executar:

  SELECT result AS generated, prompt
  FROM AI.GENERATE_TEXT(
    MODEL bqml_tutorial.text_model,
    (
      SELECT CONCAT(
        'Propose some project ideas to improve user password security using the context below: ',
        STRING_AGG(
          FORMAT("patent title: %s, patent abstract: %s", base.title, base.abstract),
          ',\n')
        ) AS prompt,
      FROM VECTOR_SEARCH(
        TABLE bqml_tutorial.embeddings, 'embedding',
        (
          SELECT embedding, content AS query
          FROM AI.GENERATE_EMBEDDING(
            MODEL bqml_tutorial.embedding_model,
            (SELECT 'improving password security' AS content)
          )
        ),
      top_k => 5, options => '{"fraction_lists_to_search": 0.01}')
    ),
    STRUCT(600 AS max_output_tokens));