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, incluindo o uso de índices vetoriais para melhorar o desempenho da pesquisa.

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.
• Usar a função VECTOR_SEARCH com os embeddings para procurar textos semelhantes.
• Realize a geração de recuperação aumentada (RAG, na sigla em inglês) 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.

Papéis e permissões necessárias

• Para criar uma conexão, você precisa da associação no seguinte papel do Identity and Access Management (IAM):

  • roles/bigquery.connectionAdmin

• Para conceder permissões à conta de serviço da conexão, você precisa da seguinte permissão:

  • resourcemanager.projects.setIamPolicy

• As permissões do IAM necessárias neste tutorial para as demais operações do BigQuery estão incluídas nos dois papéis a seguir:

  • Editor de dados do BigQuery (roles/bigquery.dataEditor) para criar modelos, tabelas e índices.
  • Usuário do BigQuery (roles/bigquery.user) para executar jobs do BigQuery.

Custos

Neste documento, você 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 projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

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.

   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. Make sure that billing is enabled for your Google Cloud project.

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

   Enable the APIs

Criar um conjunto de dados

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

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

   Acesse a página do BigQuery

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

3. Clique em Conferir 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).

     Os conjuntos de dados públicos são armazenados na multirregião US. Para simplificar, armazene seus conjuntos de dados no mesmo local.

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

     

Criar uma conexão

Crie uma Conexão de recursos do Cloud e tenha acesso à conta de serviço da conexão. Crie a conexão no mesmo local do conjunto de dados criado na etapa anterior.

Selecione uma das seguintes opções:

Console

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. Para criar uma conexão, clique em Adicionar e em Conexões com fontes de dados externas.

3. Na lista Tipo de conexão, selecione Modelos remotos da Vertex AI, funções remotas e BigLake (Cloud Resource).

4. No campo ID da conexão, insira um nome para a conexão.

5. Clique em Criar conexão.

6. Clique em Ir para conexão.

7. No painel Informações da conexão, copie o ID da conta de serviço para uso em uma etapa posterior.

bq

1. Em um ambiente de linha de comando, crie uma conexão:

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID

   O parâmetro --project_id substitui o projeto padrão.

   Substitua:

   • REGION: sua região de conexão
   • PROJECT_ID: o ID do projeto do Google Cloud
   • CONNECTION_ID: um ID para sua conexão

   Quando você cria um recurso de conexão, o BigQuery cria uma conta de serviço do sistema exclusiva e a associa à conexão.

   Solução de problemas: se você receber o seguinte erro de conexão, atualize o SDK Google Cloud:

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. Recupere e copie o ID da conta de serviço para uso em uma etapa posterior:

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   O resultado será assim:

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "[e-mail]"}
   

Terraform

Use o recurso google_bigquery_connection.

Observação: para criar objetos do BigQuery usando o Terraform, é necessário ativar a API Cloud Resource Manager.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

O exemplo a seguir cria uma conexão de recurso do Cloud chamada my_cloud_resource_connection na região US:

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Para aplicar a configuração do Terraform em um projeto do Google Cloud, conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

1. Inicie o Cloud Shell.

2. Defina o projeto padrão do Google Cloud em que você quer aplicar as configurações do Terraform.

   Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

1. No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

   Copie o exemplo de código no main.tf recém-criado.

   Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.

3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
4. Salve as alterações.
5. Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório.

   terraform init

   Opcionalmente, para usar a versão mais recente do provedor do Google, inclua a opção -upgrade:

   terraform init -upgrade

Aplique as alterações

1. Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas:

   terraform plan

   Faça as correções necessárias na configuração.

2. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt:

   terraform apply

   Aguarde até que o Terraform exiba a mensagem "Apply complete!".

3. Abra seu projeto do Google Cloud para ver os resultados. No console do Google Cloud, navegue até seus recursos na IU para verificar se foram criados ou atualizados pelo Terraform.

Observação: as amostras do Terraform geralmente presumem que as APIs necessárias estejam ativadas no projeto do Google Cloud.

Conceder acesso à conta de serviço

Conceda à conta de serviço da conexão a função de usuário da Vertex AI. É necessário conceder essa função no mesmo projeto que você criou ou selecionou na seção Antes de começar. Conceder o papel em um projeto diferente resulta no erro [e-mail] does not have the permission to access resource.

Para conceder o papel, siga estas etapas:

1. Acessar a página AM e administrador

   Acessar IAM e administrador

2. Clique em Conceder acesso.

3. No campo Novos principais, digite o ID da conta de serviço que você copiou anteriormente.

4. No campo Selecionar um papel, escolha Vertex AI e, em seguida, selecione o papel Usuário da Vertex AI.

5. Clique em Salvar.

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 `LOCATION.CONNECTION_ID`
     OPTIONS (ENDPOINT = 'text-embedding-004');

   Substitua:

   • LOCATION: o local da conexão
   • CONNECTION_ID: o ID da sua conexão do BigQuery

     Quando você visualiza os detalhes da conexão no console do Google Cloud, CONNECTION_ID é o valor na última seção do ID da conexão totalmente qualificado, mostrado em ID da conexão, por exemplo, projects/myproject/locations/connection_location/connections/myconnection

   A consulta leva alguns segundos para ser concluída. Depois disso, o modelo embedding_model aparece no conjunto de dados bqml_tutorial 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;

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

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}')

Verificar a criação do índice de vetor

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 as cinco principais patentes relevantes que correspondem a embeddings gerados a partir de uma consulta de texto. 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 `LOCATION.CONNECTION_ID`
     OPTIONS (ENDPOINT = 'gemini-1.5-flash-002');

   Substitua:

   • LOCATION: o local da conexão
   • CONNECTION_ID: o ID da sua conexão do BigQuery

     Quando você visualiza os detalhes da conexão no console do Google Cloud, CONNECTION_ID é o valor na última seção do ID da conexão totalmente qualificado, mostrado em ID da conexão, por exemplo, projects/myproject/locations/connection_location/connections/myconnection

   A consulta leva alguns segundos para ser concluída. Depois disso, o modelo text_model aparece no conjunto de dados bqml_tutorial 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: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto existente para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos no projeto.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um código 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 passar por várias arquiteturas, tutoriais ou guias de início rápido, a reutilização de projetos pode evitar que você exceda os limites da cota do projeto.

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

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