Analisar PDFs em um pipeline de geração aumentada de recuperação

Este tutorial orienta você no processo de criação de um pipeline de geração aumentada de recuperação (RAG, na sigla em inglês) com base no conteúdo de PDF analisado.

Arquivos PDF, como documentos financeiros, podem ser difíceis de usar em pipelines de RAG devido à estrutura complexa e à mistura de texto, figuras e tabelas. Neste tutorial, mostramos como usar os recursos do BigQuery ML em combinação com o Layout Parser da Document AI para criar um pipeline de RAG com base nas principais informações extraídas de um arquivo PDF.

Você também pode realizar este tutorial usando um notebook do Colab Enterprise.

Objetivos

Este tutorial abrange as seguintes tarefas:

  • Criação de um bucket do Cloud Storage e upload de um arquivo PDF de exemplo.
  • Criar uma conexão de recursos do Cloud para se conectar ao Cloud Storage e à Vertex AI no BigQuery.
  • Criar uma tabela de objetos sobre o arquivo PDF para disponibilizá-lo no BigQuery.
  • Criar um processador da Document AI que pode ser usado para analisar o arquivo PDF.
  • Criar um modelo remoto que permita usar a API Document AI para acessar o processador de documentos do BigQuery.
  • Usar o modelo remoto com a função ML.PROCESS_DOCUMENT para analisar o conteúdo do PDF em partes e gravar esse conteúdo em uma tabela do BigQuery.
  • Extrair o conteúdo do PDF dos dados JSON retornados pela função ML.PROCESS_DOCUMENT e gravar esse conteúdo em uma tabela do BigQuery.
  • Criar um modelo remoto que permita usar o modelo de geração de incorporação text-embedding-004 da Vertex AI no BigQuery.
  • Usar o modelo remoto com a função ML.GENERATE_EMBEDDING para gerar embeddings do conteúdo do PDF analisado e, em seguida, gravar esses embeddings em uma tabela do BigQuery. Os embeddings são representações numéricas do conteúdo do PDF que permitem realizar pesquisa semântica e recuperação no conteúdo do PDF.
  • Usar a função VECTOR_SEARCH nos embeddings para identificar conteúdo de PDF semanticamente semelhante.
  • Criar um modelo remoto que permita usar o modelo de geração de texto gemini-1.5-flash da Vertex AI no BigQuery.
  • Realize a geração aumentada de recuperação (RAG, na sigla em inglês) usando o modelo remoto com a função ML.GENERATE_TEXT para gerar texto, usando resultados da pesquisa vetorial para aumentar a entrada do comando e melhorar os resultados.

Custos

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

  • BigQuery: You incur costs for the data that you process in BigQuery.
  • Vertex AI: You incur costs for calls to Vertex AI models.
  • Document AI: You incur costs for calls to the Document AI API.
  • Cloud Storage: You incur costs for object storage in Cloud Storage.

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 as seguintes páginas de preços:

Antes de começar

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

    Go to project selector

  2. Make sure that billing is enabled for your Google Cloud project.

  3. Enable the BigQuery, BigQuery Connection, Vertex AI, Document AI, and Cloud Storage APIs.

    Enable the APIs

Funções exigidas

  • Para criar buckets e objetos do Cloud Storage, você precisa ter a função roles/storage.storageAdmin.

  • Para criar um processador da Document AI, você precisa ter a associação no papel roles/documentai.editor.

  • Para criar uma conexão, você precisa ter a associação no papel roles/bigquery.connectionAdmin.

  • Para conceder permissões à conta de serviço da conexão, você precisa ter a função roles/resourcemanager.projectIamAdmin.

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

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.

    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.

      Página 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.

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": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}
    

Terraform

Use o recurso google_bigquery_connection.

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.

Conceder acesso à conta de serviço

Selecione uma das seguintes opções:

Console

  1. Acesse a página IAM e administrador.

    Acessar IAM e administrador

  2. Clique em Conceder acesso.

    A caixa de diálogo Adicionar principais é aberta.

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

  4. No campo Selecionar um papel, selecione Document AI e, em seguida, Leitor da Document AI.

  5. Clique em Adicionar outro papel.

  6. No campo Selecionar papel, escolha Cloud Storage e, em seguida, Visualizador de objetos do Storage.

  7. Clique em Adicionar outro papel.

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

  9. Clique em Salvar.

gcloud

Use o comando gcloud projects add-iam-policy-binding (em inglês).

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/documentai.viewer' --condition=None
gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/storage.objectViewer' --condition=None
gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/aiplatform.user' --condition=None
 

Substitua:

  • PROJECT_NUMBER: o número do projeto.
  • MEMBER: o ID da conta de serviço que você copiou anteriormente.

Fazer upload do PDF de exemplo para o Cloud Storage

Para fazer upload do PDF de exemplo no Cloud Storage, siga estas etapas:

  1. Faça o download do PDF de amostra scf23.pdf em https://www.federalreserve.gov/publications/files/scf23.pdf e clique em fazer o download .
  2. Crie um bucket do Cloud Storage.
  3. Faça upload do arquivo scf23.pdf no bucket.

Criar uma tabela de objetos

Crie uma tabela de objetos sobre o arquivo PDF no Cloud Storage:

  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 EXTERNAL TABLE `bqml_tutorial.pdf`
    WITH CONNECTION `LOCATION.CONNECTION_ID`
    OPTIONS(
      object_metadata = 'SIMPLE',
      uris = ['gs://BUCKET/scf23.pdf']);

    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.

    • BUCKET: o bucket do Cloud Storage que contém o arquivo scf23.pdf. O valor completo da opção uri precisa ser semelhante a ['gs://mybucket/scf23.pdf'].

Criar um processador de documentos

Crie um processador de documentos com base no processador de análise de layout na multirregião us.

Criar o modelo remoto para o processador de documentos

Crie um modelo remoto para acessar o processador Document AI:

  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.parser_model`
    REMOTE WITH CONNECTION `LOCATION.CONNECTION_ID`
      OPTIONS(remote_service_type = 'CLOUD_AI_DOCUMENT_V1', document_processor = 'PROCESSOR_ID');

    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.

    • PROCESSOR_ID: o ID do processador de documentos. Para encontrar esse valor, confira os detalhes do processador e observe a linha ID na seção Informações básicas.

Analisar o arquivo PDF em partes

Use o processador de documentos com a função ML.PROCESS_DOCUMENT para analisar o arquivo PDF em partes e gravar o conteúdo em uma tabela. A função ML.PROCESS_DOCUMENT retorna os pedaços do PDF no formato JSON.

  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.chunked_pdf AS (
      SELECT * FROM ML.PROCESS_DOCUMENT(
      MODEL bqml_tutorial.parser_model,
      TABLE bqml_tutorial.pdf,
      PROCESS_OPTIONS => (JSON '{"layout_config": {"chunking_config": {"chunk_size": 250}}}')
      )
    );

Analisar os dados do fragmento de PDF em colunas separadas

Extraia o conteúdo do PDF e as informações de metadados dos dados JSON retornados pela função ML.PROCESS_DOCUMENT e grave esse conteúdo em uma tabela:

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

    Ir para o BigQuery

  2. No editor de consultas, execute a seguinte instrução para analisar o conteúdo do PDF:

    CREATE OR REPLACE TABLE bqml_tutorial.parsed_pdf AS (
    SELECT
      uri,
      JSON_EXTRACT_SCALAR(json , '$.chunkId') AS id,
      JSON_EXTRACT_SCALAR(json , '$.content') AS content,
      JSON_EXTRACT_SCALAR(json , '$.pageFooters[0].text') AS page_footers_text,
      JSON_EXTRACT_SCALAR(json , '$.pageSpan.pageStart') AS page_span_start,
      JSON_EXTRACT_SCALAR(json , '$.pageSpan.pageEnd') AS page_span_end
    FROM bqml_tutorial.chunked_pdf, UNNEST(JSON_EXTRACT_ARRAY(ml_process_document_result.chunkedDocument.chunks, '$')) json
    );

  3. No editor de consultas, execute a seguinte instrução para conferir um subconjunto do conteúdo do PDF analisado:

    SELECT *
    FROM `bqml_tutorial.parsed_pdf`
    ORDER BY id
    LIMIT 5;

    O resultado será assim:

    +-----------------------------------+------+------------------------------------------------------------------------------------------------------+-------------------+-----------------+---------------+
    |                uri                |  id  |                                                 content                                              | page_footers_text | page_span_start | page_span_end |
    +-----------------------------------+------+------------------------------------------------------------------------------------------------------+-------------------+-----------------+---------------+
    | gs://mybucket/scf23.pdf           | c1   | •BOARD OF OF FEDERAL GOVERN NOR RESERVE SYSTEM RESEARCH & ANALYSIS                                   | NULL              | 1               | 1             |
    | gs://mybucket/scf23.pdf           | c10  | • In 2022, 20 percent of all families, 14 percent of families in the bottom half of the usual ...    | NULL              | 8               | 9             |
    | gs://mybucket/scf23.pdf           | c100 | The SCF asks multiple questions intended to capture whether families are credit constrained, ...     | NULL              | 48              | 48            |
    | gs://mybucket/scf23.pdf           | c101 | Bankruptcy behavior over the past five years is based on a series of retrospective questions ...     | NULL              | 48              | 48            |
    | gs://mybucket/scf23.pdf           | c102 | # Percentiles of the Distributions of Income and Net Worth                                           | NULL              | 48              | 49            |
    +-----------------------------------+------+------------------------------------------------------------------------------------------------------+-------------------+-----------------+---------------+
     

Criar o modelo remoto para geração de embedding

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.

Gerar embeddings

Gere embeddings para o conteúdo do PDF analisado e grave-os em uma tabela:

  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`,
      TABLE `bqml_tutorial.parsed_pdf`
    );

Execute uma pesquisa vetorial no conteúdo do PDF analisado.

A consulta a seguir recebe a entrada de texto, cria um embedding para essa entrada usando a função ML.GENERATE_EMBEDDING e, em seguida, usa a função VECTOR_SEARCH para associar o embedding de entrada aos embeddings de conteúdo de PDF mais semelhantes. Os resultados são os dez pedaços de PDF mais semelhantes semanticamente à entrada.

  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.id AS pdf_chunk_id, base.content, distance
    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 'Did the typical family net worth increase? If so, by how much?' AS content)
          )
        ),
        top_k => 10,
        OPTIONS => '{"fraction_lists_to_search": 0.01}')
    ORDER BY distance DESC;

    O resultado será assim:

    +-------------------------------------------------+--------------+------------------------------------------------------------------------------------------------------+---------------------+
    |                query                            | pdf_chunk_id |                                                 content                                              | distance            |
    +-------------------------------------------------+--------------+------------------------------------------------------------------------------------------------------+---------------------+
    | Did the typical family net worth increase? ,... | c9           | ## Assets                                                                                            | 0.31113668174119469 |
    |                                                 |              |                                                                                                      |                     |
    |                                                 |              | The homeownership rate increased slightly between 2019 and 2022, to 66.1 percent. For ...            |                     |
    +-------------------------------------------------+--------------+------------------------------------------------------------------------------------------------------+---------------------+
    | Did the typical family net worth increase? ,... | c50          | # Box 3. Net Housing Wealth and Housing Affordability                                                | 0.30973592073929113 |
    |                                                 |              |                                                                                                      |                     |
    |                                                 |              | For families that own their primary residence ...                                                    |                     |
    +-------------------------------------------------+--------------+------------------------------------------------------------------------------------------------------+---------------------+
    | Did the typical family net worth increase? ,... | c50          | 3 In the 2019 SCF, a small portion of the data collection overlapped with early months of            | 0.29270064592817646 |
    |                                                 |              | the COVID- ...                                                                                       |                     |
    +-------------------------------------------------+--------------+------------------------------------------------------------------------------------------------------+---------------------+
     

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.

Gerar texto aumentado pelos resultados da pesquisa vetorial

Realize uma pesquisa vetorial nos embeddings para identificar conteúdo de PDF semanticamente semelhante e use a função ML.GENERATE_TEXT com os resultados da pesquisa vetorial para aumentar a entrada do comando e melhorar os resultados da geração de texto. Nesse caso, a consulta usa informações dos pedaços de PDF para responder a uma pergunta sobre a mudança no patrimônio líquido da família na última década.

  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
      FROM
      ML.GENERATE_TEXT( MODEL `bqml_tutorial.text_model`,
        (
        SELECT
        CONCAT( 'Did the typical family net worth change? How does this compare the SCF survey a decade earlier? Be concise and use the following context:',
        STRING_AGG(FORMAT("context: %s and reference: %s", base.content, base.uri), ',\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
                  'Did the typical family net worth change? How does this compare the SCF survey a decade earlier?' AS content
                )
              )
            ),
            top_k => 10,
            OPTIONS => '{"fraction_lists_to_search": 0.01}')
          ),
          STRUCT(512 AS max_output_tokens, TRUE AS flatten_json_output)
      );

    O resultado será assim:

    +-------------------------------------------------------------------------------+
    |               generated                                                       |
    +-------------------------------------------------------------------------------+
    | Between the 2019 and 2022 Survey of Consumer Finances (SCF), real median      |
    | family net worth surged 37 percent to $192,900, and real mean net worth       |
    | increased 23 percent to $1,063,700.  This represents the largest three-year   |
    | increase in median net worth in the history of the modern SCF, exceeding the  |
    | next largest by more than double.  In contrast, between 2010 and 2013, real   |
    | median net worth decreased 2 percent, and real mean net worth remained        |
    | unchanged.                                                                    |
    +-------------------------------------------------------------------------------+
     

Limpar

  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.