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

Neste tutorial, orientamos você em todo o processo de criação e uso de embeddings de texto para pesquisa semântica e geração aumentada por recuperação (RAG).

Este tutorial abrange as seguintes tarefas:

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

Neste tutorial, usamos a tabela pública do BigQuery patents-public-data.google_patents_research.publications.

Funções exigidas

Para seguir este tutorial, você precisa dos seguintes papéis do Identity and Access Management (IAM):

• Criar e usar conjuntos de dados, conexões e modelos do BigQuery: administrador do BigQuery (roles/bigquery.admin).
• Conceder permissões à conta de serviço da conexão: administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin).

Esses papéis predefinidos contêm as permissões necessárias para executar as tarefas neste documento. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

• Criar um conjunto de dados: bigquery.datasets.create
• Criar, delegar e usar uma conexão: bigquery.connections.*
• Definir a conexão padrão: bigquery.config.*
• Definir permissões da conta de serviço: resourcemanager.projects.getIamPolicy e resourcemanager.projects.setIamPolicy
• Criar um modelo e executar a inferência:
  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

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, use a calculadora de preços.

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

Para mais informações, consulte Preços do BigQuery em a documentação do BigQuery.

Para mais informações sobre os preços da Agent Platform, consulte a página de preços da Agent Platform.

Antes de começar

1. No Google Cloud console do, na página do seletor de projetos, escolha ou crie um Google Cloud projeto do.

   Funções necessárias para selecionar ou criar um projeto

   • Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar qualquer projeto em que tenha recebido um papel.
   • Criar um projeto: para criar um projeto, você precisa do papel de criador de projetos (roles/resourcemanager.projectCreator), que contém a resourcemanager.projects.create permissão. 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

2. Verifique se o faturamento está ativado para o Google Cloud projeto.

3. Ative as APIs BigQuery, BigQuery Connection e Agent Platform.

   Funções necessárias para ativar APIs

   Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

   Ativar as APIs

crie um conjunto de dados

Crie um conjunto de dados do BigQuery para armazenar o modelo de ML.

Console

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

   Acessar a página do BigQuery

2. No painel Explorer, clique no nome do seu projeto.

3. Clique em Ver ações > Criar conjunto de dados

4. Na página Criar conjunto de dados, faça o seguinte:

   • Para o código do conjunto de dados, insira bqml_tutorial.

   • Em Tipo de local, selecione Multirregião e selecione EUA.

   • Mantenha as configurações padrão restantes e clique em Criar conjunto de dados.

bq

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

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

2. Confirme se o conjunto de dados foi criado:

   bq ls

API

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

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

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

Crie um modelo remoto que represente um modelo de geração de embedding de texto da Agent Platform hospedado:

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

   Acessar o BigQuery

2. No editor de consultas, execute a seguinte instrução:

   CREATE OR REPLACE MODEL `bqml_tutorial.embedding_model`
     REMOTE WITH CONNECTION DEFAULT
     OPTIONS (ENDPOINT = 'text-embedding-005');

   A consulta leva vários segundos para ser concluída. Depois disso, o modelo embedding_model pode ser acessado pelo painel Explorer. Como a consulta usa uma instrução CREATE MODEL para criar um modelo, não há resultados de consulta.

Gerar embeddings de texto

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

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

   Acessar o BigQuery

2. No editor de consultas, execute a seguinte instrução:

   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 aproximadamente 5 minutos para ser concluída.

A geração de embeddings usando a AI.GENERATE_EMBEDDING função pode falhar devido a cotas ou indisponibilidade de serviço do LLM da Agent Platform. Os detalhes do erro são retornados na coluna status. Uma coluna status vazia indica que a geração de embedding foi bem-sucedida.

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

Criar um índice vetorial

Se você criar um índice vetorial em uma coluna de embedding, uma pesquisa de vetor realizada nessa coluna usará a técnica de pesquisa do Vizinho aproximado mais perto. Essa técnica melhora o desempenho da pesquisa de vetor, mas reduzindo o recall e, portanto, retornando resultados mais aproximados.

Para criar um índice de vetor, use a CREATE VECTOR INDEX instrução de linguagem de definição de dados (DDL, na sigla em inglês):

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. No editor de consultas, execute a seguinte instrução SQL:

   CREATE OR REPLACE VECTOR INDEX my_index
   ON `bqml_tutorial.embeddings`(embedding)
   OPTIONS(index_type = 'IVF',
     distance_type = 'COSINE',
     ivf_options = '{"num_lists":500}')

A criação de um índice vetorial geralmente leva apenas alguns segundos. Leva mais dois ou três minutos para que o índice vetorial seja preenchido e fique pronto para uso.

Verificar a prontidão do índice vetorial

O índice vetorial é preenchido de maneira assíncrona. É possível verificar se o índice está pronto para ser usado consultando a visualização INFORMATION_SCHEMA.VECTOR_INDEXES e verificando se o valor da coluna coverage_percentage é maior que 0, e o valor da coluna last_refresh_time não for NULL.

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. No editor de consultas, execute a seguinte instrução SQL:

   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.

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

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

O argumento top_k determina o número de correspondências a serem retornadas, nesse caso, cinco. A opção fraction_lists_to_search determina a porcentagem de listas de índices vetoriais a serem pesquisadas. O índice vetorial criado tem 500 listas. Portanto, o valor fraction_lists_to_search de .01 indica que essa pesquisa de vetor verifica cinco dessas listas. Um valor fraction_lists_to_search menor, conforme 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.

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. No editor de consultas, execute a seguinte instrução SQL:

   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á assim:

   +-----------------------------+--------------------+-------------------------------------------------+-------------------------------------------------+
   |            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

Crie um modelo remoto que represente um modelo de geração de texto da Agent Platform hospedado:

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

   Acessar o BigQuery

2. No editor de consultas, execute a seguinte instrução:

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

   A consulta leva vários segundos para ser concluída. Depois disso, o modelo text_model pode ser acessado pelo painel Explorer. Como a consulta usa uma instrução CREATE MODEL para criar um modelo, não há resultados de consulta.

Gerar texto aumentado pelos resultados da pesquisa vetorial

Alimente os resultados da pesquisa como solicitações para gerar texto com a AI.GENERATE_TEXT função

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

   Acessar o BigQuery

2. No editor de consultas, execute a seguinte instrução:

   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));

   O resultado será assim:

   +------------------------------------------------+------------------------------------------------------------+
   |            generated                           | prompt                                                     |
   +------------------------------------------------+------------------------------------------------------------+
   | These patents suggest several project ideas to | Propose some project ideas to improve user password        |
   | improve user password security.  Here are      | security using the context below: patent title: Active     |
   | some, categorized by the patent they build     | new password entry dialog with compact visual indication   |
   | upon:                                          | of adherence to password policy, patent abstract:          |
   |                                                | An active new password entry dialog provides a compact     |
   | **I. Projects based on "Active new password    | visual indication of adherence to password policies. A     |
   | entry dialog with compact visual indication of | visual indication of progress towards meeting all          |
   | adherence to password policy":**               | applicable password policies is included in the display    |
   |                                                | and updated as new password characters are being...        |
   +------------------------------------------------+------------------------------------------------------------+
    

Limpar

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos nele.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja explorar várias arquiteturas, tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda limites da cota.

1. No Google Cloud console, acesse a página Gerenciar recursos.

   Acessar "Gerenciar recursos"

2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir.
3. Na caixa de diálogo, digite o ID do projeto e clique em Desligar para excluir o projeto.

A seguir

• Confira o tutorial Analisar PDFs em um pipeline de geração aumentada por recuperação para aprender a criar um pipeline de RAG com base no conteúdo de PDF analisado.