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.

Você usa 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 generativos de linguagem grande (LLMs). 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úblicos de pesquisa de patentes do Google.

Objetivos

Crie um modelo remoto do BigQuery ML sobre um modelo de incorporação 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 de vetor 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 .
Funções necessárias para selecionar ou criar um projeto
- Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
- Criar um projeto: para criar um projeto, é necessário 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 BigQuery, Cloud Storage e Gemini Enterprise Agent Platform, caso alguma delas ainda não esteja ativada.
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 com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o 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 este 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.
Em Explorer, expanda seu 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 US.
Não mude as outras configurações padrão.
Clique em Criar conjunto de dados.

bq

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

Crie um conjunto de dados chamado bqml_tutorial com o local dos 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 da Agent Platform hospedado. 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 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 no painel Explorer.

Você recebe 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 ela falhar, os detalhes do erro serão retornados na coluna status dos 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;

Essa consulta leva alguns minutos para ser concluída. Você recebe 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 perto. Essa técnica melhora o desempenho da pesquisa de vetor 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 e verifique 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 de vetor, siga estas etapas:

Para criar o índice de vetor, 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ê recebe 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. O índice vetorial leva mais dois a três minutos para ser 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 pela ID do seu 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 vetores a serem pesquisadas. O índice de vetor que você criou tem 500 listas. Portanto, o valor fraction_lists_to_search de .01 indica que essa pesquisa de vetor 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 num_lists opção de índice vetorial.

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 da Agent Platform hospedado, 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 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));