GSP924

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 efetivação dos dados. Com o processador de formulários geral usado neste laboratório, você pode extrair pares de chave/valor de um documento simples.

Neste laboratório, você vai aprender a criar analisadores de documentos usando a Document AI, enviar documentos para processamento via Google Cloud usando o console do Cloud e a linha de comando e usar Python para fazer chamadas de API síncronas.

O que você vai aprender

Você vai aprender a realizar as tarefas a seguir:

• Criar e testar o processador da Document AI usando o console.
• Testar processadores da Document AI usando a linha de comando.
• Testar chamadas de API síncronas do Document AI usando Python.

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 do Cloud

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

Clique em Verificar meu progresso para conferir os objetivos.

API Cloud Document AI ativada

Tarefa 2: Criar e testar um processador de formulários geral

Em seguida, você vai criar um processador da Document AI usando o analisador de formulários da Document AI.

Criar um processador

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

2. Clique em Conheça os processadores.

3. Clique em Criar processador para Analisador de formulários, que é um tipo de processador geral.

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

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

6. Anote o ID do processador, porque você vai usá-lo com o curl para fazer uma chamada POST à API em uma tarefa posterior.

Faça o download do formulário de amostra

Nesta tarefa, você vai baixar o formulário de amostra do Cloud Storage. Para fazer upload deste formulário na próxima tarefa, primeiro você precisa baixá-lo para sua máquina local.

1. Faça o download do arquivo form.pdf para sua máquina local.

O arquivo deve ser baixado diretamente. Se o arquivo abrir no navegador, faça o download usando os controles do navegador. O arquivo form.pdf é um FORMULÁRIO DE ADMISSÃO DE SAÚDE com dados de amostra escritos à mão.

Fazer upload de um formulário para processamento da Document AI

Em seguida, você vai fazer upload do formulário de amostra que baixou para o processador form-parser. Ele será analisado e os resultados serão exibidos no console.

1. Na página form-parser, clique no botão Fazer upload do documento de teste. Uma caixa de diálogo será aberta. Selecione o arquivo que você baixou na tarefa anterior para fazer o upload.

Uma barra de progresso vai indicar o nível de conclusão do processo de análise e, por fim, os resultados serão exibidos. Você verá que o processador geral capturou os dados do formulário em um conjunto de pares de chave/valor.

Os pares de chave/valor analisados do documento de origem serão apresentados no console. O painel esquerdo lista os dados, e o painel direito destaca com retângulos azuis os locais de origem no documento analisado. Analise a saída e compare os resultados com os dados de origem.

Nesta tarefa, você vai testar um processador de formulários geral da Document AI fazendo chamadas de API na linha de comando.

Clique em Verificar meu progresso para conferir os objetivos.

criar e testar um processador de formulários geral

Tarefa 3: Configurar a instância do laboratório

Nesta seção, você vai configurar a instância do laboratório para usar a API Document AI.

Conecte-se à instância de VM usando o SSH

Você vai realizar o restante das tarefas do laboratório na VM chamada document-ai-dev.

1. No Menu de navegação (), clique em Compute Engine > Instâncias de VM.

2. Clique no link SSH da instância de VM chamada document-ai-dev.

Você precisará do ID do processador do Document AI referente ao processador criado na Tarefa 1 para esta etapa. Se você não salvou, na guia do console do Cloud:

• Abra o Menu de navegação ().
• Clique em Document AI > Processadores .
• Clique no nome do seu processador para abrir a página de detalhes.
• A partir daqui, você pode copiar o ID do processador.

3. Na sessão SSH, crie uma variável de ambiente para conter o ID do processador da Document AI. Você precisa substituir o marcador de posição de [your processor id]:

export PROCESSOR_ID=[your processor id]

4. Na sessão SSH, confirme se a variável de ambiente contém o ID do processador da Document AI:

echo Your processor ID is:$PROCESSOR_ID

5. Isso vai imprimir o ID do processador de forma semelhante ao seguinte:

O ID do seu processador é:4897d834d2f4415d

Você vai usar essa sessão SSH para as tarefas restantes deste laboratório.

Autenticar as solicitações de API

Para fazer solicitações à API Document AI, você precisa fornecer uma credencial válida. Nesta tarefa, você vai criar uma conta de serviço, limitar as permissões concedidas a essa conta às necessárias para o laboratório e gerar uma credencial para essa conta que possa ser usada para autenticar solicitações da API Document AI.

1. Defina uma variável de ambiente com seu ID do projeto, que será usado neste laboratório:

export PROJECT_ID=$(gcloud config get-value core/project)

2. Crie uma nova conta de serviço para acessar a API Document AI usando:

export SA_NAME="document-ai-service-account" gcloud iam service-accounts create $SA_NAME --display-name $SA_NAME

3. Vincule a conta de serviço à função do usuário da API Document AI:

gcloud projects add-iam-policy-binding ${PROJECT_ID} \ --member="serviceAccount:$SA_NAME@${PROJECT_ID}.iam.gserviceaccount.com" \ --role="roles/documentai.apiUser"

4. Crie as credenciais que serão usadas para fazer login como sua nova conta de serviço e salve-as em um arquivo JSON chamado key.json no seu diretório de trabalho:

gcloud iam service-accounts keys create key.json \ --iam-account $SA_NAME@${PROJECT_ID}.iam.gserviceaccount.com

5. Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS, que a biblioteca usa para encontrar suas credenciais, para apontar para o arquivo de credenciais:

export GOOGLE_APPLICATION_CREDENTIALS="$PWD/key.json"

6. Verifique se a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS está definida com o caminho completo do arquivo JSON de credenciais que você criou antes:

echo $GOOGLE_APPLICATION_CREDENTIALS

Essa variável de ambiente é usada pela ferramenta de linha de comando gcloud para especificar quais credenciais usar ao executar comandos. Para saber mais sobre essa autenticação de formulário, consulte o guia do Application Default Credentials.

Baixe o formulário de amostra na instância de VM

Agora você pode baixar um formulário de amostra e codificá-lo em base64 para envio à API Document AI.

1. Insira o seguinte comando na janela SSH para fazer o download do formulário de amostra no seu diretório de trabalho:

gsutil cp gs://spls/gsp924/health-intake-form.pdf .

2. Crie um arquivo de solicitação JSON para enviar o formulário codificado em base64 para processamento:

echo '{"inlineDocument": {"mimeType": "application/pdf","content": "' > temp.json base64 health-intake-form.pdf >> temp.json echo '"}}' >> temp.json cat temp.json | tr -d \\n > request.json

Clique em Verificar meu progresso para conferir os objetivos.

Autenticar solicitações de API e fazer download do formulário de amostra

Tarefa 4: Fazer uma solicitação síncrona de documento de processo usando curl

Nesta tarefa, você vai processar o documento de amostra fazendo uma chamada para o endpoint síncrono da API da Document AI usando curl.

1. Envie um formulário para processamento usando o curl. O resultado será armazenado em output.json:

export LOCATION="us" export PROJECT_ID=$(gcloud config get-value core/project) curl -X POST \ -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \ -H "Content-Type: application/json; charset=utf-8" \ -d @request.json \ https://${LOCATION}-documentai.googleapis.com/v1beta3/projects/${PROJECT_ID}/locations/${LOCATION}/processors/${PROCESSOR_ID}:process > output.json

2. Verifique se o arquivo output.json contém os resultados da chamada de API:

cat output.json Se você receber um erro de autenticação, verifique se definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS para apontar para o arquivo JSON de credenciais que você criou anteriormente. Talvez seja necessário esperar alguns minutos para que a política do IAM seja propagada. Tente de novo se receber um erro.

O token de acesso da conta de serviço do Cloud IAM é gerado dinamicamente e transmitido para a API usando o cabeçalho HTTP Authorization:. A resposta contém dados formatados em JSON que são salvos no arquivo output.json.

Extrair as entidades do formulário

Agora, confira algumas das informações extraídas do formulário de amostra.

1. Extraia o texto bruto detectado no documento da seguinte forma:

sudo apt-get update sudo apt-get install jq cat output.json | jq -r ".document.text"

Isso lista todo o texto detectado no documento enviado.

2. Extraia a lista de campos de formulário detectados pelo processador de formulários:

cat output.json | jq -r ".document.pages[].formFields"

Isso lista os dados do objeto para todos os campos do formulário detectados no documento. Os valores textAnchor.startIndex e textAnchor.endIndex de cada formulário podem ser usados para localizar os nomes dos formulários detectados no campo document.text. O script Python que você vai usar na próxima tarefa vai fazer esse mapeamento.

O arquivo JSON é bem grande porque inclui o documento de origem codificado em base64, além de todo o texto detectado e as propriedades do documento. Você pode analisar o arquivo JSON abrindo-o em um editor de texto ou usando uma ferramenta de consulta JSON como o jq.

Verifique se um documento foi processado pela API Document AI.

Tarefa 5: Testar um processador de formulários da Document AI usando as bibliotecas de cliente Python

Fazer uma chamada síncrona para a API Document AI usando as bibliotecas de cliente Python da Document AI.

Agora você vai processar um documento usando o endpoint síncrono. Para processar grandes quantidades de documentos de uma só vez, é possível usar a API assíncrona. Para saber mais sobre como usar as APIs Document AI, leia o guia.

Se você quiser executar scripts Python diretamente, precisará fornecer as credenciais apropriadas a esses scripts para que eles possam fazer chamadas para a API usando uma conta de serviço que foi configurada com as permissões corretas. Para saber mais sobre como configurar essa forma de autenticação, consulte a documentação Como autenticar como uma conta de serviço.

Configurar a instância de VM para usar o cliente Python da Document AI

Agora instale as bibliotecas de cliente do Google Cloud para Python na instância de VM.

1. Insira o seguinte comando no shell do terminal SSH para importar os arquivos do laboratório para sua instância de VM:

gsutil cp gs://spls/gsp924/synchronous_doc_ai.py .

2. Insira o seguinte comando para instalar as bibliotecas de cliente obrigatórias do Python para a Document AI e outras bibliotecas necessárias para este laboratório:

sudo apt install python3-pip python3 -m pip install --upgrade google-cloud-documentai google-cloud-storage prettytable

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

Revisar o código Python da API Document AI

Reserve um minuto para revisar o código Python no arquivo de amostra. Você pode usar um editor de sua escolha, como vi ou nano, para revisar o código na sessão SSH ou usar o comando da seção anterior para copiar o código de exemplo no Cloud Shell e usar o Editor de código para visualizar o código-fonte, se preferir.

1. Os dois primeiros blocos de código importam as bibliotecas necessárias e analisam os parâmetros para inicializar as variáveis que identificam o processador da Document AI e os dados de entrada.

import argparse from google.cloud import documentai_v1beta3 as documentai from google.cloud import storage from prettytable import PrettyTable parser = argparse.ArgumentParser() parser.add_argument("-P", "--project_id", help="Google Cloud Project ID") parser.add_argument("-D", "--processor_id", help="Document AI Processor ID") parser.add_argument("-F", "--file_name", help="Input file name", default="form.pdf") parser.add_argument("-L", "--location", help="Processor Location", default="us") args = parser.parse_args()

2. A função process_document é 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,location e processor_id, e o documento a ser processado é lido e armazenado em uma estrutura mime_type.

O nome do processador e o documento são transmitidos ao objeto do cliente da API Document e uma chamada síncrona é feita à API. Se a solicitação for bem-sucedida, o objeto de documento retornado incluirá propriedades que contêm os dados detectados pelo processador da Document AI.

def process_document(project_id, location, processor_id, 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}" # Read the file into memory with open(file_path, "rb") as image: image_content = image.read() # Create the document object document = {"content": image_content, "mime_type": "application/pdf"} # Configure the process request request = {"name": name, "document": document} # Use the Document AI client synchronous endpoint to process the request result = client.process_document(request=request) return result.document

3. O script chama a função process_document com os parâmetros necessários e salva a resposta na variável document.

document = process_document(args.project_id,args.location,args.processor_id,args.file_name )

4. O bloco final de código imprime a propriedade .text que contém todo o texto detectado no documento e exibe as informações do formulário usando os dados de âncora de texto para cada um dos campos do formulário detectados pelo analisador de formulários.

print("Document processing complete.") # print the raw text print("Text: \n{}\n".format(document.text)) # Define a function to retrieve an object dictionary for a named element 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 = "" # Se um segmento do texto abranje várias linhas, # ele será armazenado em diferentes segmentos de texto. 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 # Grab each key/value pair and their corresponding confidence scores. 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")

Clique em Verificar meu progresso para conferir os objetivos.

Teste um processador de formulários da Document AI

Tarefa 6: Executar o código Python da Document AI

Execute o exemplo de código e processe o mesmo arquivo de antes.

1. Crie variáveis de ambiente para o ID do projeto e o arquivo de credenciais da conta de serviço do IAM:

export PROJECT_ID=$(gcloud config get-value core/project) export GOOGLE_APPLICATION_CREDENTIALS="$PWD/key.json"

2. Chame o programa Python synchronous_doc_ai.py com os parâmetros necessários:

python3 synchronous_doc_ai.py \ --project_id=$PROJECT_ID \ --processor_id=$PROCESSOR_ID \ --location=us \ --file_name=health-intake-form.pdf | tee results.txt

Você verá o seguinte bloco de texto: 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. Data: Sally Walker Nome: 14/09/2019 ...

O primeiro bloco de texto é um único elemento do texto que contém todo o texto do documento. Esse bloco de texto não inclui nenhuma consciência dos dados baseados em formulário, então alguns itens, como as entradas Data e Nome, são misturados nesse valor de texto bruto.

Em seguida, o código gera uma visualização mais estruturada dos dados usando os dados do formulário que o form-parser inferiu da estrutura do documento. Essa saída estruturada também inclui a pontuação de confiança dos nomes e valores dos campos do formulário. A saída desta seção fornece um mapeamento muito mais útil entre os nomes dos campos do formulário e os valores, como pode ser visto com o link entre os campos do formulário Date e Name e seus valores corretos.

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

Clique em Verificar meu progresso para conferir os objetivos.

Executar o código Python da Document AI

Parabéns!

Você usou corretamente a API Document AI para extrair dados de documentos usando um processador de formulários geral. Neste laboratório, você criou e testou um processador da Document AI usando o console e a linha de comando e fez chamadas síncronas da API Document AI usando Python.

Próximas etapas/ Saiba mais

• Saiba mais na documentação da API Document AI do Cloud.

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 abril de 2024

Laboratório testado em 07 de dezembro de 2023

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.