GSP1139

Visão geral

A API Document AI é uma solução para compreensão de dados não estruturados, como documentos, e-mails, faturas, formulários etc., que facilita o entendimento, a análise e o uso desses dados. Essa API fornece uma estrutura por meio da classificação de conteúdo, da extração de entidades, da pesquisa avançada e muito mais.

Neste laboratório, você vai aprender a usar o analisador de formulários com a Document AI para analisar um formulário escrito à mão com Python. Vamos usar um formulário médico simples como exemplo, mas esse procedimento funciona com qualquer formulário geral compatível com a DocAI.

Objetivos

Neste laboratório, você vai aprender a fazer o seguinte:

• Extrair dados de um formulário digitalizado usando o analisador de formulários da Document AI
• Extrair pares de chave-valor de um formulário usando o analisador de formulários da Document AI
• Extrair e exportar dados CSV de um formulário usando o analisador de formulários da Document AI

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.

Como iniciar seu laboratório e fazer login no console do Google Cloud

1. Clique no botão Começar o laboratório. Se for preciso pagar por ele, uma caixa de diálogo vai aparecer para você selecionar a forma de pagamento. No painel Detalhes do Laboratório, à esquerda, você vai encontrar o seguinte:

   • O botão Abrir Console do Google Cloud
   • O tempo restante
   • As credenciais temporárias que você vai usar neste laboratório
   • Outras informações, se forem necessárias

2. Se você estiver usando o navegador Chrome, clique em Abrir console do Google Cloud ou clique com o botão direito do mouse e selecione Abrir link em uma janela anônima.

   O laboratório ativa os recursos e depois abre a página Fazer Login em outra guia.

   Dica: coloque as guias em janelas separadas lado a lado.

   Observação: se aparecer a caixa de diálogo Escolher uma conta, clique em Usar outra conta.

3. Se necessário, copie o Nome de usuário abaixo e cole na caixa de diálogo Fazer login.

   {{{user_0.username | "Username"}}}

   Você também encontra o nome de usuário no painel Detalhes do Laboratório.

4. Clique em Próxima.

5. Copie a Senha abaixo e cole na caixa de diálogo de Olá.

   {{{user_0.password | "Password"}}}

   Você também encontra a senha no painel Detalhes do Laboratório.

6. Clique em Próxima.

   Importante: você precisa usar as credenciais fornecidas no laboratório, e não as da sua conta do Google Cloud. Observação: se você usar sua própria conta do Google Cloud neste laboratório, é possível que receba cobranças adicionais.

7. Acesse as próximas páginas:

   • Aceite os Termos e Condições.
   • Não adicione opções de recuperação nem autenticação de dois fatores (porque essa é uma conta temporária).
   • Não se inscreva em testes gratuitos.

Depois de alguns instantes, o console do Google Cloud será aberto nesta guia.

Observação: para acessar os produtos e serviços do Google Cloud, clique no Menu de navegação ou digite o nome do serviço ou produto no campo Pesquisar.

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: ativar a API Document AI

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

1. Para abrir o Cloud Shell, clique no botão Ativar o Cloud Shell na parte de cima do console.

2. No Cloud Shell, execute os seguintes comandos para ativar a API Document AI.

gcloud services enable documentai.googleapis.com

Você vai ver algo parecido com:

Operation "operations/..." finished successfully.

Você também precisa instalar o Pandas, uma biblioteca de análise de dados de código aberto para Python.

3. Execute este comando para instalar o Pandas:

pip3 install --upgrade pandas

4. Execute o seguinte comando para instalar as bibliotecas de cliente Python da API Document AI.

pip3 install --upgrade google-cloud-documentai

Você vai ver algo parecido com:

... Installing collected packages: google-cloud-documentai Successfully installed google-cloud-documentai-2.15.0

Agora você já pode usar a API Document AI.

Clique em Verificar meu progresso para conferir o objetivo.

Ativar a API Document AI.

Tarefa 2: criar um processador para o analisador de formulários

Comece criando uma instância de processador para o analisador de formulários, que será usada na Document AI Platform neste tutorial.

1. No console do Cloud, abra o Menu de navegação (), clique em Ver todos os produtos > Inteligência artificial > Document AI.

2. Clique em Explorar os processadores e, em Geral, clique em Analisador de formulários para abrir a página Criar processador.

3. Nomeie-o como lab-form-parser e selecione a região mais próxima na lista.

4. Clique em Criar para criar seu processador.

5. Copie o ID do processador. Você vai usá-lo no código mais tarde.

Clique em Verificar meu progresso para conferir o objetivo.

Criar um processador

Testar o processador no console do Cloud

É possível fazer upload de um documento para testar o processador no console.

1. Clique com o botão direito do mouse na imagem abaixo e selecione Salvar imagem como para baixar o formulário de exemplo.

2. Na página Detalhes do processador, clique em Fazer upload do documento de teste. Selecione o formulário baixado.

O processador do analisador de formulários vai processar o documento e retornar os dados do formulário analisado. O código será semelhante a este:

Tarefa 3: baixar o formulário de amostra

Nesta seção, você vai baixar um documento de amostra com um formulário médico simples.

1. Execute o comando a seguir para baixar o formulário de amostra no Cloud Shell.

gcloud storage cp gs://cloud-samples-data/documentai/codelabs/form-parser/intake-form.pdf .

2. Confirme se o arquivo foi salvo no Cloud Shell usando o comando abaixo:

ls intake-form.pdf

Tarefa 4: extrair pares de chave-valor do formulário

Nesta seção, você vai usar a API de processamento on-line para chamar o processador do analisador de formulários criado anteriormente. Em seguida, você vai extrair os pares de chave-valor encontrados no documento.

O processamento on-line serve para enviar um único documento e aguardar a resposta. Você também pode usar o processamento em lote se quiser enviar vários arquivos ou se o tamanho do arquivo exceder o máximo de páginas para processamento on-line.

O código para fazer uma solicitação de processo é idêntico para todos os tipos de processador, exceto o ID do processador. O objeto de resposta Document contém uma lista de páginas do documento de entrada. Cada objeto page contém uma lista de campos de formulário e os locais deles no texto.

O código a seguir itera em cada página e extrai cada chave, valor e pontuação de confiança. Esses são dados estruturados que podem ser armazenados com mais facilidade em bancos de dados ou usados em outros aplicativos.

1. No Cloud Shell, crie um arquivo chamado form_parser.py e cole o seguinte código nele:

import pandas as pd from google.cloud import documentai_v1 as documentai def online_process( project_id: str, location: str, processor_id: str, file_path: str, mime_type: str, ) -> documentai.Document: """ Processa um documento usando a API de processamento on-line Document AI. """ opts = {"api_endpoint": f"{location}-documentai.googleapis.com"} # Instancia um cliente documentai_client = documentai.DocumentProcessorServiceClient(client_options=opts) # O nome completo do recurso para o processador, por exemplo: # projects/project-id/locations/location/processor/processor-id # Você deve criar primeiro novos processadores no console do Cloud resource_name = documentai_client.processor_path(project_id, location, processor_id) # Ler o arquivo na memória with open(file_path, "rb") as image: image_content = image.read() # Carregar dados binários no objeto RawDocument da Document AI raw_document = documentai.RawDocument( content=image_content, mime_type=mime_type ) # Configurar a solicitação de processo request = documentai.ProcessRequest( name=resource_name, raw_document=raw_document ) # Usar o cliente da Document AI para processar o formulário de amostra result = documentai_client.process_document(request=request) return result.document def trim_text(text: str): """ Remover caracteres de espaço adicional do texto (em branco, feed de linha, guia etc.) """ return text.strip().replace("\n", " ") PROJECT_ID = "YOUR_PROJECT_ID" LOCATION = "YOUR_PROJECT_LOCATION" # O formato é 'us' ou 'eu' PROCESSOR_ID = "FORM_PARSER_ID" # Criar processador no console do Cloud # O arquivo local no seu diretório atual de trabalho FILE_PATH = "form.pdf" # Consulte to https://cloud.google.com/document-ai/docs/processors-list # para saber os tipos de arquivos compatíveis MIME_TYPE = "application/pdf" document = online_process( project_id=PROJECT_ID, location=LOCATION, processor_id=PROCESSOR_ID, file_path=FILE_PATH, mime_type=MIME_TYPE, ) names = [] name_confidence = [] values = [] value_confidence = [] for page in document.pages: for field in page.form_fields: # Obter os nomes de campo extraídos names.append(trim_text(field.field_name.text_anchor.content)) # Confiança - O quanto o modelo tem "certeza" de que o texto está correto name_confidence.append(field.field_name.confidence) values.append(trim_text(field.field_value.text_anchor.content)) value_confidence.append(field.field_value.confidence) # Criar DataFrame do Pandas para gerar os valores em formato tabular. df = pd.DataFrame( { "Field Name": names, "Field Name Confidence": name_confidence, "Field Value": values, "Field Value Confidence": value_confidence, } ) print(df)

2. Substitua YOUR_PROJECT_ID, YOUR_PROJECT_LOCATION, YOUR_PROCESSOR_ID e FILE_PATH pelos valores adequados para seu ambiente.

Observação: FILE_PATH é o nome do arquivo que você baixou para o Cloud Shell na etapa anterior. Se você não renomeou o arquivo, o nome dele deve ser intake-form.pdf, e você precisará atualizar esse nome no código.

3. Execute o comando a seguir para executar o script:

python3 form_parser.py

Você verá esta resposta:

Nome do campo Confiança no nome do campo Valor do campo Confiança no valor do campo 0 Número de telefone: 0.999982 (906) 917-3486 0.999982 1 Contato em caso de emergência: 0.999972 Eva Walker 0.999972 2 Estado civil: 0.999951 Solteira 0.999951 3 Gênero: 0.999933 F 0.999933 4 Profissão: 0.999914 Engenheira de software 0.999914 5 Indicação: 0.999862 Não há 0.999862 6 Data: 0.999858 14/9/19 0.999858 7 Data de nascimento: 0.999716 04/09/1986 0.999716 8 Endereço: 0.999147 24 Barney Lane 0.999147 9 Cidade: 0.997718 Towaco 0.997718 10 Nome: 0.997345 Sally Walker 0.997345 11 Estado: 0.996944 NJ 0.996944 ...

Tarefa 5: analisar tabelas

O analisador de formulários também consegue extrair dados de tabelas em documentos. Nesta seção, você vai baixar um novo documento de amostra e extrair dados da tabela. Como você está carregando os dados no Pandas, eles podem ser enviados para um arquivo CSV ou em outros formatos com uma única chamada de método.

Baixar o formulário de amostra com tabelas

Há um documento de amostra com um formulário e uma tabela.

1. Execute o comando a seguir para baixar o formulário de amostra no Cloud Shell.

gcloud storage cp gs://cloud-samples-data/documentai/codelabs/form-parser/form_with_tables.pdf .

2. Confirme se o arquivo foi salvo no Cloud Shell usando o comando abaixo:

ls form_with_tables.pdf

Extrair dados da tabela

A solicitação de processamento para dados de tabela é a mesma usada para extrair pares de chave-valor. A diferença é de quais campos você extrai os dados na resposta. Os dados da tabela são armazenados no campo pages[].tables[].

Este exemplo extrai informações das linhas de cabeçalho e do corpo de cada tabela e página, depois exibe a tabela e a salva como um arquivo CSV.

1. Crie um arquivo chamado table_parsing.py e cole o seguinte código nele:

# type: ignore[1] """ Usa o processamento on-line da Document AI para chamar um processador do analisador de formulários Extrai as tabelas e os dados no documento. """ from os.path import splitext from typing import List, Sequence import pandas as pd from google.cloud import documentai def online_process( project_id: str, location: str, processor_id: str, file_path: str, mime_type: str, ) -> documentai.Document: """ Processa um documento usando a API de processamento on-line Document AI. """ opts = {"api_endpoint": f"{location}-documentai.googleapis.com"} # Instancia um cliente documentai_client = documentai.DocumentProcessorServiceClient(client_options=opts) # O nome completo do recurso para o processador, por exemplo: # projects/project-id/locations/location/processor/processor-id # Você deve criar primeiro novos processadores no console do Cloud resource_name = documentai_client.processor_path(project_id, location, processor_id) # Ler o arquivo na memória with open(file_path, "rb") as image: image_content = image.read() # Carregue dados binários no objeto RawDocument da Document AI raw_document = documentai.RawDocument( content=image_content, mime_type=mime_type ) # Configure a solicitação do processo request = documentai.ProcessRequest( name=resource_name, raw_document=raw_document ) # Use o cliente da Document AI para processar o formulário da amostra result = documentai_client.process_document(request=request) return result.document def get_table_data( rows: Sequence[documentai.Document.Page.Table.TableRow], text: str ) -> List[List[str]]: """ Obter dados do texto das linhas da tabela """ all_values: List[List[str]] = [] for row in rows: current_row_values: List[str] = [] for cell in row.cells: current_row_values.append( text_anchor_to_text(cell.layout.text_anchor, text) ) all_values.append(current_row_values) return all_values def text_anchor_to_text(text_anchor: documentai.Document.TextAnchor, text: str) -> str: """ A Document AI identifica os dados da tabela pelos seus deslocamentos em todo o texto do documento. Esta função converte deslocamentos em string. """ response = "" # Se um segmento do texto abranje várias linhas, # ele será armazenado em diferentes segmentos de texto. for segment in text_anchor.text_segments: start_index = int(segment.start_index) end_index = int(segment.end_index) response += text[start_index:end_index] return response.strip().replace("\n", " ") PROJECT_ID = "YOUR_PROJECT_ID" LOCATION = "YOUR_PROJECT_LOCATION" # O formato é 'us' ou 'eu' PROCESSOR_ID = "FORM_PARSER_ID" # Criar processador antes de executar a amostra # O arquivo local no seu diretório atual de trabalho FILE_PATH = "form_with_tables.pdf" # Consulte to https://cloud.google.com/document-ai/docs/file-types # para saber os tipos de arquivos compatíveis MIME_TYPE = "application/pdf" document = online_process( project_id=PROJECT_ID, location=LOCATION, processor_id=PROCESSOR_ID, file_path=FILE_PATH, mime_type=MIME_TYPE, ) header_row_values: List[List[str]] = [] body_row_values: List[List[str]] = [] # Inserir nome de arquivo sem a extensão output_file_prefix = splitext(FILE_PATH)[0] for page in document.pages: for index, table in enumerate(page.tables): header_row_values = get_table_data(table.header_rows, document.text) body_row_values = get_table_data(table.body_rows, document.text) # Crie um Dataframe Pandas para imprimir os valores no formato tabular. df = pd.DataFrame( data=body_row_values, columns=pd.MultiIndex.from_arrays(header_row_values), ) print(f"Page {page.page_number} - Table {index}") print(df) # Salvar cada tabela como um arquivo CSV output_filename = f"{output_file_prefix}_pg{page.page_number}_tb{index}.csv" df.to_csv(output_filename, index=False)

2. Substitua YOUR_PROJECT_ID, YOUR_PROJECT_LOCATION, YOUR_PROCESSOR_ID e FILE_PATH pelos valores adequados para seu ambiente.

Observação: FILE_PATH é o nome do arquivo que você baixou para o Cloud Shell na etapa anterior. Se você não renomeou o arquivo, o nome dele deve ser form_with_tables.pdf, que é o valor padrão e não precisa ser alterado.

3. Execute o comando a seguir para executar o script:

python3 table_parsing.py

Você verá esta resposta:

Page 1 - Table 0 Item Description 0 Item 1 Description 1 1 Item 2 Description 2 2 Item 3 Description 3

Você também precisa ter um novo arquivo CSV no diretório em que executar o código.

4. Execute o comando a seguir para listar os arquivos no diretório de trabalho atual:

Is

Você verá esta resposta:

form_with_tables_pg1_tb0.csv

Parabéns!

Parabéns! Neste laboratório, você usou a API Document AI para extrair dados de um formulário escrito à mão. Você também aprendeu a usar a biblioteca de cliente Python da Document AI para extrair pares de chave-valor de um formulário e dados tabulares de um formulário com tabelas.

Próximas etapas/Saiba mais

Confira os recursos a seguir para saber mais sobre a Document AI e a biblioteca de cliente Python:

• Documentação da Document AI
• Biblioteca de cliente Python da Document AI
• Amostras da Document AI

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 21 de julho de 2025

Laboratório testado em 21 de julho de 2025

Copyright 2026 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.