GSP925

Visão geral

A API Document AI é uma solução de compreensão de documentos que usa dados não estruturados, como documentos e e-mails, e facilita a compreensão, a análise e o consumo dos dados.

Neste laboratório, você vai usar a API Document AI com Python para criar vários processadores, incluindo um processador de formulários geral e um processador de OCR de documentos, e depois vai fazer chamadas síncronas e assíncronas para a API usando Python. Este laboratório cria uma instância do Vertex AI Workbench que você vai usar com os notebooks do JupyterLab para trabalhar com os módulos do cliente Python Document AI.

Objetivos

Neste laboratório, você vai aprender a:

• Habilitar a API Document AI e criar processadores.
• Instalar a biblioteca de cliente para Python em uma instância do Vertex AI Workbench.
• Analisar dados de um formulário digitalizado usando Python para fazer uma chamada de API síncrona.
• Analisar dados de formulários digitalizados usando Python para fazer uma chamada de API assíncrona.

Configuração e requisitos

Antes de clicar no botão Começar o Laboratório

Leia estas instruções. Os laboratórios são cronometrados e não podem ser pausados. O timer é ativado quando você clica em Iniciar laboratório e mostra por quanto tempo os recursos do Google Cloud vão ficar disponíveis.

Este laboratório prático permite que você realize as atividades em um ambiente real de nuvem, e não em uma simulação ou demonstração. Você vai receber novas credenciais temporárias para fazer login e acessar o Google Cloud durante o laboratório.

Confira os requisitos para concluir o laboratório:

• Acesso a um navegador de Internet padrão (recomendamos o Chrome).

Observação: para executar este laboratório, use o modo de navegação anônima (recomendado) ou uma janela anônima do navegador. Isso evita conflitos entre sua conta pessoal e de estudante, o que poderia causar cobranças extras na sua conta pessoal.

• Tempo para concluir o laboratório: não se esqueça que, depois de começar, não será possível pausar o laboratório.

Observação: use apenas a conta de estudante neste laboratório. Se usar outra conta do Google Cloud, você poderá receber cobranças nela.

Ativar o Cloud Shell

O Cloud Shell é uma máquina virtual com várias ferramentas de desenvolvimento. Ele tem um diretório principal permanente de 5 GB e é executado no Google Cloud. O Cloud Shell oferece acesso de linha de comando aos recursos do Google Cloud.

1. Clique em Ativar o Cloud Shell na parte de cima do console do Google Cloud.

2. Clique nas seguintes janelas:

   • Continue na janela de informações do Cloud Shell.
   • Autorize o Cloud Shell a usar suas credenciais para fazer chamadas de APIs do Google Cloud.

Depois de se conectar, você verá que sua conta já está autenticada e que o projeto está configurado com seu Project_ID, . A saída contém uma linha que declara o projeto PROJECT_ID para esta sessão:

Your Cloud Platform project in this session is set to {{{project_0.project_id | "PROJECT_ID"}}}

A gcloud é a ferramenta de linha de comando do Google Cloud. Ela vem pré-instalada no Cloud Shell e aceita preenchimento com tabulação.

3. (Opcional) É possível listar o nome da conta ativa usando este comando:

gcloud auth list

4. Clique em Autorizar.

Saída:

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} To set the active account, run: $ gcloud config set account `ACCOUNT`

5. (Opcional) É possível listar o ID do projeto usando este comando:

gcloud config list project

Saída:

[core] project = {{{project_0.project_id | "PROJECT_ID"}}} Observação: consulte a documentação completa da gcloud no Google Cloud no guia de visão geral da gcloud CLI.

Tarefa 1: criar e testar um processador de formulários geral

Nesta tarefa, você vai habilitar a API Document AI, depois vai criar e testar um processador de formulários geral. O processador de formulários geral vai processar qualquer tipo de documento e extrair todo o conteúdo de texto que puder identificar no documento. Ele não se limita a textos impressos, mas também gerencia textos manuscritos e em qualquer orientação, aceita vários idiomas e entende como os elementos de dados do formulário se relacionam entre si, tornando possível extrair pares de chave-valor dos campos do formulário com rótulos de texto.

Ativar a API Document AI do Cloud

Antes de começar a usar a Document AI, você precisa ativar a API.

1. No console do Cloud, no Menu de navegação (), clique em APIs e serviços > Biblioteca.

2. Pesquise API Document AI do Cloud e clique no botão Ativar para usar a API no seu projeto do Google Cloud.

Se a API Document AI do Cloud já estiver ativada, será exibido o botão Gerenciar e você vai poder continuar com o restante do laboratório.

Verifique se a API Document AI do Cloud foi ativada.

Criar um processador de formulários geral

Crie um processador Document AI usando o analisador de formulários do Document AI.

1. No console, no Menu de navegação (), clique em Document AI > Visão geral.

2. Clique em Explorar os processadores e em Criar processador para Analisador de formulários, que é um tipo de processador geral.

3. Especifique o nome do processador como form-parser e selecione a região US (Estados Unidos) na lista.

4. Clique em Criar para que o processador do form-parser geral seja criado.

Isso vai criar o processador e retornar à página de detalhes do processador, que vai exibir o ID do processador, o status e o endpoint de previsões.

5. Anote o ID do processador, porque você precisará atualizar variáveis nos notebooks do JupyterLab com o ID do processador em tarefas posteriores.

Tarefa 2: configurar sua instância do Vertex AI Workbench para executar chamadas da API Document AI

Em seguida, conecte-se ao JupyterLab em execução na instância do Vertex AI Workbench que foi criada para você quando o laboratório foi iniciado e configure esse ambiente para as tarefas restantes do laboratório.

1. No menu de navegação () do console do Google Cloud, clique em Vertex AI > Workbench.

2. Ache a instância e clique no botão Abrir o JupyterLab.

A interface do JupyterLab para sua instância do Workbench é aberta em uma nova guia do navegador.

Observação: se você não encontrar notebooks no JupyterLab, siga estas etapas para redefinir a instância:

1. Feche a guia do JupyterLab no navegador e volte à página inicial do Workbench.

2. Marque a caixa de seleção ao lado do nome da instância e clique em Redefinir.

3. Depois que o botão Abrir o JupyterLab for ativado novamente, aguarde um minuto e clique em Abrir o JupyterLab.

3. Clique em Terminal para abrir um shell do terminal dentro da instância do Vertex AI Workbench.

4. Insira o seguinte comando no shell do terminal para importar os arquivos do laboratório para sua instância do Vertex AI Workbench:

gsutil cp {{{project_0.startup_script.notebook_files_path|notebook_files_path}}} .

5. Insira o seguinte comando no shell do terminal para instalar as bibliotecas de cliente obrigatórias do Python para o Document AI e outras bibliotecas necessárias:

python -m pip install --upgrade google-cloud-core google-cloud-documentai google-cloud-storage prettytable

Será exibida uma saída indicando que as bibliotecas foram instaladas com êxito.

Observação: em caso de erros relacionados a permissões, execute novamente o comando para garantir a instalação bem-sucedida das bibliotecas. Pode levar alguns minutos para que as permissões sejam aplicadas.

6. Insira o seguinte comando no shell do terminal para importar a amostra de formulário de anamnese:

gsutil cp {{{project_0.startup_script.health_intake_form_path|form_path}}} form.pdf

7. Na interface do notebook, abra o notebook do JupyterLab chamado .

8. Na caixa de diálogo Selecionar Kernel, escolha Python 3 na lista de kernels disponíveis.

Verifique se a instância do Vertex AI foi preparada para chamadas assíncronas da API Document AI.

Tarefa 3: fazer uma solicitação síncrona de documento de processo

Faça uma chamada de documento de processo usando uma chamada de API síncrona do Document AI. Para processar grandes quantidades de documentos de uma só vez, também é possível usar a API assíncrona, que será apresentada em uma tarefa posterior.

Revisar no código Python se há chamadas de API síncronas do Document AI

Reserve um minuto para revisar o código Python no notebook .

O primeiro bloco de código importa as bibliotecas necessárias e inicializa algumas variáveis.

from google.cloud import documentai_v1beta3 as documentai from google.cloud import storage from prettytable import PrettyTable project_id = %system gcloud config get-value core/project project_id = project_id[0] location = 'us' file_path = 'form.pdf'

A célula de código Set your Processor ID determina o ID do processador que você precisa estabelecer manualmente antes de processar documentos com o notebook.

processor_id = 'PROCESSOR_ID' # TODO: Replace with a valid Processor ID

Você precisará do ID do processador do Document AI referente ao processador criado na Tarefa 1 para esta etapa.

Dica: se você não salvou, na guia console do Cloud, abra o Menu de navegação (), clique em Document AI > Meus processadores e selecione o nome do seu processador para abrir a página de detalhes. A partir daqui, você pode copiar o ID do processador.

A célula de código Process Document Function define a função process_document, que é usada para fazer uma chamada síncrona a um processador do Document AI. A função cria um objeto de cliente da API Document AI.

O nome do processador exigido pela chamada da API é criado usando os parâmetros project_id, locations e processor_id, e o documento PDF de amostra é lido e armazenado em uma estrutura mime_type.

A função cria um objeto de solicitação que contém o nome completo do processador do documento e usa esse objeto como parâmetro para uma chamada síncrona ao cliente da API Document AI. Se a solicitação for bem-sucedida, o objeto de documento retornado incluirá propriedades que contêm as entidades detectadas no formulário.

def process_document( project_id=project_id, location=location, processor_id=processor_id, file_path=file_path ): # Instantiates a client client = documentai.DocumentProcessorServiceClient() # The full resource name of the processor, e.g.: # projects/project-id/locations/location/processor/processor-id # You must create new processors in the Cloud Console first name = f"projects/{project_id}/locations/{location}/processors/{processor_id}" with open(file_path, "rb") as image: image_content = image.read() # Read the file into memory document = {"content": image_content, "mime_type": "application/pdf"} # Configure the process request request = {"name": name, "document": document} # Use the Document AI client to process the sample form result = client.process_document(request=request) return result.document

A célula de código Process Document chama a função process_document, salva a resposta na variável document e imprime o texto bruto detectado. Todos os processadores vão reportar alguns dados para a propriedade document.text.

document=process_document() # print all detected text. # All document processors will display the text content print("Document processing complete.") print("Text: {}".format(document.text))

A célula de código Get Text Function define a função get_text() que recupera o texto de um elemento nomeado usando as propriedades text_anchor, start_index e end_index dos text_segments do elemento nomeado. Esta função é usada para recuperar o nome e o valor do formulário dentre os dados retornados pelo processador.

def get_text(doc_element: dict, document: dict): """ Document AI identifies form fields by their offsets in document text. This function converts offsets to text snippets. """ response = "" # If a text segment spans several lines, it will # be stored in different text segments. for segment in doc_element.text_anchor.text_segments: start_index = ( int(segment.start_index) if segment in doc_element.text_anchor.text_segments else 0 ) end_index = int(segment.end_index) response += document.text[start_index:end_index] return response

A célula Exibir dados do formulário percorre todas as páginas que foram detectadas e, para cada form_field detectado, ela usa a função get_text() para recuperar o nome e o valor do campo. Então esses valores são impressos com as pontuações de confiança correspondentes. Os dados do formulário serão retornados por processadores que usam o analisador de formulário geral ou os analisadores especializados, mas não serão retornados por processadores que foram criados com o analisador de OCR de documentos.

document_pages = document.pages print("Form data detected:\n") # For each page fetch each form field and display fieldname, value and confidence scores for page in document_pages: print("Page Number:{}".format(page.page_number)) for form_field in page.form_fields: fieldName=get_text(form_field.field_name,document) nameConfidence = round(form_field.field_name.confidence,4) fieldValue = get_text(form_field.field_value,document) valueConfidence = round(form_field.field_value.confidence,4) print(fieldName+fieldValue +" (Confidence Scores: (Name) "+str(nameConfidence)+", (Value) "+str(valueConfidence)+")\n")

A célula Exibir dados da entidade extrai dados da entidade do objeto document e exibe o tipo de entidade, o valor e as propriedades de confiança para cada entidade detectada. Os dados da entidade são retornados somente por processadores que usam analisadores do Document AI especializados, como o analisador de despesas de aquisição. O analisador de formulário geral e o de OCR de documentos não vão retornar dados de entidade.

if 'entities' in dir(document): entities = document.entities # Grab each key/value pair and their confidence scores. table = PrettyTable(['Type', 'Value', 'Confidence']) for entity in entities: entity_type = entity.type_ value = entity.mention_text confience = round(entity.confidence,4) table.add_row([entity_type, value, confience]) print(table) else: print("Document does not contain entity data.")

Tarefa 4: executar o código Python síncrono do Document AI

Execute o código para fazer chamadas síncronas à API Document AI no notebook JupyterLab.

1. Na segunda célula de código Set your Processor ID, substitua o texto do marcador de posição PROCESSOR_ID pelo ID do processador para o processador form-parser que você criou em uma etapa anterior.

2. Selecione a primeira célula, clique no menu Executar e depois em Executar célula selecionada e todas abaixo para executar todo o código no notebook.

Se você usou a amostra de formulário de anamnese, verá dados semelhantes aos seguintes na célula de saída dos dados do formulário:

Form data detected: Page Number:1 Phone #: (906) 917-3486 (Confidence Scores: (Name) 1.0, (Value) 1.0) ... Date: 9/14/19 (Confidence Scores: (Name) 0.9999, (Value) 0.9999) ... Name: Sally Walker (Confidence Scores: (Name) 0.9973, (Value) 0.9973) ...

Se você conseguir criar um processador especializado, a célula final exibirá dados da entidade; caso contrário, mostrará uma tabela vazia.

3. No menu JupyterLab, clique em Arquivo e depois em Salvar Notebook para salvar o progresso.

Verifique se o documento foi processado usando a API Document AI do Cloud.

Tarefa 5: criar um processador de OCR de documentos do Document AI

Nesta tarefa, você vai criar um processador do Document AI usando o analisador de OCR de documentos geral.

1. No Menu de navegação, clique em Document AI > Visão geral.

2. Clique em Explorar os processadores e depois em Criar processador para OCR de documentos. Esse é um tipo de processador geral.

3. Especifique o nome do processador como ocr-processor e selecione a região EUA (Estados Unidos) na lista.

4. Clique em Criar para que o processador seja criado.

5. Anote o ID do processador. Você terá que especificar essa informação em uma tarefa posterior.

Tarefa 6: preparar seu ambiente para chamadas assíncronas da API Document AI

Nesta tarefa, você vai fazer upload do notebook de exemplo do JupyterLab para testar chamadas assíncronas da API Document AI e vai copiar algumas amostras de formulários do laboratório para o Cloud Storage para processamento assíncrono.

1. Clique na guia Terminal para reabrir o shell do terminal dentro da instância do Vertex AI Workbench.

2. Crie um bucket do Cloud Storage para os documentos de entrada e copie os exemplos de formulários W2 para o bucket:

export PROJECT_ID="$(gcloud config get-value core/project)" export BUCKET="${PROJECT_ID}"_doc_ai_async gsutil mb gs://${BUCKET} gsutil -m cp {{{project_0.startup_script.async_files_path|async_files_path}}} gs://${BUCKET}/input

3. Na interface do notebook, abra o notebook do JupyterLab chamado .

4. Na caixa de diálogo Selecionar Kernel, escolha Python 3 na lista de kernels disponíveis.

Verifique se a instância do Vertex AI foi preparada para chamadas assíncronas da API Document AI.

Tarefa 7: fazer uma solicitação de documento de processo assíncrona

Revisar no código Python se há chamadas assíncronas da API Document AI

Reserve um minuto para revisar o código Python no notebook .

A primeira célula de código importa as bibliotecas necessárias.

from google.cloud import documentai_v1beta3 as documentai from google.cloud import storage import re import os import pandas as pd import simplejson as json

A célula de código Set your Processor ID determina o ID do processador que você precisa estabelecer manualmente antes de processar documentos com o notebook.

processor_id = "PROCESSOR_ID" # TODO: Replace with a valid Processor ID

A célula de código Set your variables define os parâmetros que serão usados para fazer a chamada assíncrona, incluindo o local dos buckets de entrada e saída do Cloud Storage que serão usados para os dados de origem e os arquivos de saída. Você deve atualizar os valores do marcador de posição desta célula para PROJECT_ID e PROCESSOR_ID na próxima seção do laboratório antes de executar o código. As outras variáveis contêm padrões para o local do processador, o bucket de entrada do Cloud Storage e o bucket de saída do Cloud Storage que você não precisa alterar.

project_id = %system gcloud config get-value core/project project_id = project_id[0] location = 'us' # Replace with 'eu' if processor does not use 'us' location gcs_input_bucket = project_id+"_doc_ai_async" # Bucket name only, no gs:// prefix gcs_input_prefix = "input/" # Input bucket folder e.g. input/ gcs_output_bucket = project_id+"_doc_ai_async" # Bucket name only, no gs:// prefix gcs_output_prefix = "output/" # Input bucket folder e.g. output/ timeout = 300

A célula de código Define Google Cloud client objects inicializa os clientes do Document AI e do Cloud Storage.

client_options = {"api_endpoint": "{}-documentai.googleapis.com".format(location)} client = documentai.DocumentProcessorServiceClient(client_options=client_options) storage_client = storage.Client()

A célula de código Create input configuration cria o parâmetro de matriz de configuração de entrada para os dados de origem que serão passados para a solicitação assíncrona do Document AI como uma configuração de entrada. Esta matriz armazena o local de origem do Cloud Storage e o tipo MIME para cada um dos arquivos encontrados no local de entrada do Cloud Storage.

blobs = storage_client.list_blobs(gcs_input_bucket, prefix=gcs_input_prefix) input_configs = [] print("Input Files:") for blob in blobs: if ".pdf" in blob.name: source = "gs://{bucket}/{name}".format(bucket = gcs_input_bucket, name = blob.name) print(source) input_config = documentai.types.document_processor_service.BatchProcessRequest.BatchInputConfig( gcs_source=source, mime_type="application/pdf" ) input_configs.append(input_config)

A célula de código Create output configuration cria o parâmetro de saída para a solicitação assíncrona contendo o local do bucket de saída do Cloud Storage e o armazena como uma configuração de saída em lote do Document AI.

destination_uri = f"gs://{gcs_output_bucket}/{gcs_output_prefix}" output_config = documentai.types.document_processor_service.BatchProcessRequest.BatchOutputConfig( gcs_destination=destination_uri )

A célula de código Create the Document AI API request cria o objeto de solicitação de processo em lote assíncrono do Document AI usando os objetos de configuração de entrada e saída.

name = f"projects/{project_id}/locations/{location}/processors/{processor_id}" request = documentai.types.document_processor_service.BatchProcessRequest( name=name, input_configs=input_configs, output_config=output_config, )

A célula do código Start the batch (asynchronous) API operation faz uma solicitação de processo de documento assíncrono passando o objeto de solicitação para o método batch_process_documents(). Esta é uma chamada assíncrona, então você usa o método result() para forçar o notebook a esperar até que o trabalho assíncrono em segundo plano seja concluído.

operation = client.batch_process_documents(request) # Wait for the operation to finish operation.result(timeout=timeout) print ("Batch process completed.")

A célula Buscar lista de arquivos de saída enumera os objetos no local do bucket de saída, conforme definido na variável destination_uri.

A célula Exibir texto detectado de arquivos JSON de saída assíncronos carrega cada arquivo JSON de saída encontrado como um objeto de documento do Document AI e os dados de texto detectados pelo processador de OCR de documentos são impressos.

A célula Exibir dados da entidade vai exibir todos os dados da entidade encontrados. No entanto, os dados da entidade só vão estar disponíveis para processadores que foram criados usando um analisador especializado. Os dados da entidade não serão exibidos com o analisador de OCR geral do Document AI usado nesta tarefa.

Executar o código Python assíncrono do Document AI

Use o exemplo de código fornecido para você no notebook do Jupyterlab para processar documentos de maneira assíncrona usando uma solicitação de processamento em lote do Document AI.

1. Na segunda célula de código, substitua o texto do marcador de posição PROCESSOR_ID pelo ID do processador do analisador de formulários que você criou em uma etapa anterior.

2. Selecione a primeira célula, clique no menu Executar e depois em Executar célula selecionada e todas abaixo para executar todo o código no notebook.

3. À medida que as células de código são executadas, você pode percorrer o notebook revisando o código e os comentários que explicam como o objeto de solicitação assíncrona é criado e usado.

O notebook vai levar um ou dois minutos para aguardar a conclusão da operação do processo em lote assíncrono na célula de código Start the batch (asynchronous) API operation. Embora a chamada de API do processo em lote seja assíncrona, o notebook usa o método result para forçar o notebook a esperar até que a chamada assíncrona seja concluída antes de enumerar e exibir os dados de saída.

Se o trabalho assíncrono demorar mais do que o esperado e expirar, talvez seja necessário executar as células restantes novamente para exibir a saída. Estas são as células após a célula Iniciar a operação de API em lote (assíncrona)..

Sua saída conterá um texto listando os dados do Document AI detectados em cada arquivo. O analisador de OCR de documentos não detecta dados de formulário ou entidade, portanto, nenhum dado de formulário ou entidade será produzido. Se você puder criar um processador especializado, também vai notar dados de entidade impressos pela célula final.

4. No menu JupyterLab, clique em Arquivo e depois em Salvar Notebook para salvar o progresso.

Document processing complete. Text: FakeDoc M.D. HEALTH INTAKE FORM Please fill out the questionnaire carefully. The information you provide will be used to complete your health profile and will be kept confidential. Date: Sally Walker Name: 9/14/19 ... Verifique se um documento foi processado usando a API Cloud Document assíncrona.

Parabéns

Você fez chamadas síncronas e assíncronas para a API Document AI. Neste laboratório, você ativou a API Document AI e criou processadores. Você instalou a biblioteca de cliente do Python em uma instância do Vertex AI Workbench, analisou dados de um formulário digitalizado usando Python para fazer uma chamada de API síncrona e analisou dados de formulários digitalizados usando Python para fazer uma chamada de API assíncrona.

Próximas etapas / Saiba mais

• Para mais informações sobre como usar as APIs Document AI, leia o guia.

Treinamento e certificação do Google Cloud

Esses treinamentos ajudam você a aproveitar as tecnologias do Google Cloud ao máximo. Nossas aulas incluem habilidades técnicas e práticas recomendadas para ajudar você a alcançar rapidamente o nível esperado e continuar sua jornada de aprendizado. Oferecemos treinamentos que vão do nível básico ao avançado, com opções de aulas virtuais, sob demanda e por meio de transmissões ao vivo para que você possa encaixá-las na correria do seu dia a dia. As certificações validam sua experiência e comprovam suas habilidades com as tecnologias do Google Cloud.

Manual atualizado em 17 de janeiro de 2025

Laboratório testado em 17 de janeiro de 2025

Copyright 2025 Google LLC. Todos os direitos reservados. Google e o logotipo do Google são marcas registradas da Google LLC. Todos os outros nomes de produtos e empresas podem ser marcas registradas das respectivas empresas a que estão associados.