Realizar pesquisa semântica e geração aumentada de 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 de recuperação (RAG).

Este tutorial abrange as seguintes tarefas:

• Criar um modelo remoto do BigQuery ML usando um modelo de incorporação da Vertex AI.
• Uso do modelo remoto com a função ML.GENERATE_EMBEDDING para gerar embeddings a partir de texto em uma tabela do BigQuery.
• Crie um índice de vetor para indexar os embeddings e melhorar o desempenho da pesquisa.
• Usar a função VECTOR_SEARCH com os embeddings para procurar textos semelhantes.
• Realize a RAG gerando texto com a função ML.GENERATE_TEXT, 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).
• Conceda 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.*
• Defina a conexão padrão: bigquery.config.*
• Defina as permissões da conta de serviço: resourcemanager.projects.getIamPolicy e resourcemanager.projects.setIamPolicy
• Crie um modelo e execute 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.
• Vertex AI: You incur costs for calls to the Vertex AI service that's represented by the remote model.

Para gerar uma estimativa de custo baseada na sua projeção de uso, utilize 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 Preços do BigQuery na documentação do BigQuery.

Para mais informações sobre preços da Vertex AI, consulte esta página.

Antes de começar

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

2. Verify that billing is enabled for your Google Cloud project.

3. Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the APIs

crie um conjunto de dados

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

Console

1. No console do Google Cloud , 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 EUA (várias regiões nos Estados Unidos).

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

bq

Para criar um novo conjunto de dados, utilize o comando bq mk com a sinalização --location. Para obter uma lista completa de parâmetros, consulte a referência comando bq mk --dataset.

1. Crie um conjunto de dados chamado bqml_tutorial com o local dos dados definido como US e uma descrição de BigQuery ML tutorial dataset:

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

   Em vez de usar a flag --dataset, o comando usa o atalho -d. Se você omitir -d e --dataset, o comando vai criar um conjunto de dados por padrão.

2. 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"
  }
}

BigQuery DataFrames

Antes de testar esta amostra, siga as instruções de configuração dos BigQuery DataFrames no Guia de início rápido do BigQuery: como usar os BigQuery DataFrames. Para mais informações, consulte a documentação de referência do BigQuery DataFrames.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local.

import google.cloud.bigquery

bqclient = google.cloud.bigquery.Client()
bqclient.create_dataset("bqml_tutorial", exists_ok=True)

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 Vertex AI hospedado:

1. No console do Google Cloud , 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 alguns segundos para ser concluída. Depois disso, o modelo embedding_model pode ser acessado no 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 função ML.GENERATE_EMBEDDING e, em seguida, gravá-los em uma tabela do BigQuery para que possam ser pesruisados.

1. No console do Google Cloud , 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 ML.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(ml_generate_embedding_status) = 0;

Essa consulta leva aproximadamente 5 minutos para ser concluída.

A geração de embeddings usando a função ML.GENERATE_EMBEDDING pode falhar devido a quotas ou indisponibilidade de serviço do LLM da Vertex AI. Os detalhes do erro são retornados na coluna ml_generate_embedding_status. Uma coluna ml_generate_embedding_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 reduz o recall e, portanto, retorna resultados mais aproximados.

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:

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`(ml_generate_embedding_result)
   OPTIONS(index_type = 'IVF',
     distance_type = 'COSINE',
     ivf_options = '{"num_lists":500}')

A criação de um índice de vetor 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 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 recall menor e 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.

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`, 'ml_generate_embedding_result',
     (
     SELECT ml_generate_embedding_result, content AS query
     FROM ML.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 Vertex AI hospedado:

1. No console do Google Cloud , 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 alguns segundos para ser concluída. Depois disso, o modelo text_model pode ser acessado no 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 função ML.GENERATE_TEXT

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

   Acessar o BigQuery

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

   SELECT ml_generate_text_llm_result AS generated, prompt
   FROM ML.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`, 'ml_generate_embedding_result',
         (
           SELECT ml_generate_embedding_result, content AS query
           FROM ML.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, TRUE AS flatten_json_output));

   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: a exclusão de 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. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

A seguir

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