Realizar pesquisas semânticas e geração aumentada de recuperação

Este tutorial explica o processo completo de criação e utilização de incorporações 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 sobre um modelo de incorporação do Vertex AI.
• Usando o modelo remoto com a função ML.GENERATE_EMBEDDING para gerar incorporações a partir de texto numa tabela do BigQuery.
• Criar um índice vetorial para indexar as incorporações de forma a melhorar o desempenho da pesquisa.
• Usando a função VECTOR_SEARCH com as incorporações para pesquisar texto semelhante.
• Realize a RAG gerando texto com a função ML.GENERATE_TEXT e usando os resultados da pesquisa vetorial para aumentar a entrada de comandos e melhorar os resultados.

Este tutorial usa a tabela pública do BigQuery patents-public-data.google_patents_research.publications.

Funções necessárias

Para executar este tutorial, precisa das seguintes funções de gestão de identidade e de acesso (IAM):

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

Estas funções predefinidas contêm as autorizações necessárias para realizar as tarefas descritas neste documento. Para ver as autorizações exatas necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

• Crie um conjunto de dados: bigquery.datasets.create
• Crie, delegue e use uma associação: bigquery.connections.*
• Defina a ligação predefinida: bigquery.config.*
• Defina as autorizaçõ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

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Custos

Neste documento, usa 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 custos com base na sua utilização projetada, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Para mais informações acerca dos preços do BigQuery, consulte os preços do BigQuery na documentação do BigQuery.

Para mais informações sobre os preços do Vertex AI, consulte a página de preços do Vertex AI.

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 o seu modelo de ML.

Consola

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda à página do BigQuery

2. No painel Explorador, clique no nome do 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 ID do conjunto de dados, introduza bqml_tutorial.

   • Em Tipo de localização, selecione Várias regiões e, de seguida, selecione EUA (várias regiões nos Estados Unidos).

   • Deixe as restantes predefinições como estão e clique em Criar conjunto de dados.

bq

Para criar um novo conjunto de dados, use o comando bq mk com a flag --location. Para uma lista completa de parâmetros possíveis, consulte a referência do comando bq mk --dataset.

1. Crie um conjunto de dados com o nome bqml_tutorial com a localização dos dados definida 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 omitir -d e --dataset, o comando cria um conjunto de dados por predefinição.

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

DataFrames do BigQuery

Antes de experimentar este exemplo, siga as instruções de configuração dos DataFrames do BigQuery no início rápido do BigQuery com os DataFrames do BigQuery. Para mais informações, consulte a documentação de referência do BigQuery DataFrames.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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)

Crie o modelo remoto para a geração de incorporações de texto

Crie um modelo remoto que represente um modelo de geração de incorporações de texto do Vertex AI alojado:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

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

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

   A consulta demora vários segundos a ser concluída. Após a conclusão, o modelo embedding_model aparece no conjunto de dados bqml_tutorial no painel Explorador. Uma vez que a consulta usa uma declaração CREATE MODEL para criar um modelo, não existem resultados da consulta.

Gere incorporações de texto

Gere incorporações de texto a partir de resumos de patentes com a função ML.GENERATE_EMBEDDING e, em seguida, escreva-as numa tabela do BigQuery para que possam ser pesquisadas.

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No editor de consultas, execute a seguinte declaraçã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;

Esta consulta demora aproximadamente 5 minutos a concluir.

A geração de incorporações através da função ML.GENERATE_EMBEDDING pode falhar devido às quotas do MDG do Vertex AI ou à indisponibilidade do serviço. Os detalhes dos erros são devolvidos na coluna ml_generate_embedding_status. Uma coluna ml_generate_embedding_statusvazia indica que a geração de incorporações foi bem-sucedida.

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

Crie um índice vetorial

Se criar um índice vetorial numa coluna de incorporação, uma pesquisa vetorial realizada nessa coluna usa a técnica de pesquisa Approximate Nearest Neighbor. Esta técnica melhora o desempenho da pesquisa vetorial, com a contrapartida de reduzir a relembrança e, por isso, devolver resultados mais aproximados.

Para criar um índice vetorial, use a declaração de linguagem de definição de dados (LDD):CREATE VECTOR INDEX

1. Aceda à página do BigQuery.

   Aceda ao BigQuery

2. No editor de consultas, execute a seguinte declaraçã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}')

Normalmente, a criação de um índice vetorial demora apenas alguns segundos. Demora mais 2 ou 3 minutos para o índice vetorial ser preenchido e ficar pronto a usar.

Valide a prontidão do índice de vetores

O índice vetorial é preenchido de forma assíncrona. Pode verificar se o índice está pronto a ser usado consultando a vista INFORMATION_SCHEMA.VECTOR_INDEXES e verificando se o valor da coluna coverage_percentage é superior a 0 e o valor da coluna last_refresh_time não é NULL.

1. Aceda à página do BigQuery.

   Aceda ao BigQuery

2. No editor de consultas, execute a seguinte declaraçã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 pelo ID do seu projeto.

Faça uma pesquisa de semelhança de texto através do índice de vetores

Use a função VECTOR_SEARCH para pesquisar patentes relevantes que correspondam a incorporações geradas a partir de uma consulta de texto.

O argumento top_k determina o número de correspondências a devolver, neste caso, cinco. A opção fraction_lists_to_search determina a percentagem de listas de índices vetoriais a pesquisar. O índice de vetores que criou tem 500 listas, pelo que o valor fraction_lists_to_search de .01 indica que esta pesquisa de vetores analisa cinco dessas listas. Um valor de fraction_lists_to_search mais baixo, como mostrado aqui, oferece uma recolha mais baixa e um desempenho mais rápido. Para mais informações acerca das listas de índices vetoriais, consulte a num_lists opção de índice vetorial.

O modelo que usa para gerar as incorporações nesta consulta tem de ser o mesmo que usa para gerar as incorporações na tabela com a qual está a fazer a comparação. Caso contrário, os resultados da pesquisa não são precisos.

1. Aceda à página do BigQuery.

   Aceda ao BigQuery

2. No editor de consultas, execute a seguinte declaraçã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 é semelhante ao 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...       |
   +-----------------------------+--------------------+-------------------------------------------------+-------------------------------------------------+
   

Crie o modelo remoto para geração de texto

Crie um modelo remoto que represente um modelo de geração de texto do Vertex AI alojado:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

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

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

   A consulta demora vários segundos a ser concluída. Após a conclusão, o modelo text_model aparece no conjunto de dados bqml_tutorial no painel Explorador. Uma vez que a consulta usa uma declaração CREATE MODEL para criar um modelo, não existem resultados da consulta.

Gere texto melhorado com resultados da pesquisa vetorial

Introduza os resultados da pesquisa como comandos para gerar texto com a função ML.GENERATE_TEXT

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No editor de consultas, execute a seguinte declaraçã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 é semelhante ao seguinte:

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

Atenção: a eliminação de um projeto tem os seguintes efeitos:

• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.

Se planeia explorar várias arquiteturas, tutoriais ou inícios rápidos, a reutilização de projetos pode ajudar a evitar exceder os limites de quota de projetos.

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.

O que se segue?

• Experimente o tutorial Analise PDFs num pipeline de geração aumentada de recuperação para saber como criar um pipeline de RAG com base no conteúdo de PDFs analisados.