Use a Document AI para processar seus formulários escritos à mão de maneira inteligente (Python)
Sobre este codelab
1. Visão geral
O que é a Document AI?
A API Document AI é uma solução de compreensão de documentos que usa dados não estruturados, como documentos, e-mails e assim, e facilita a compreensão, a análise e o consumo dos dados. A API fornece estrutura por meio da classificação do conteúdo, extração de entidades, pesquisa avançada e muito mais.
Neste tutorial, você usará a API Document AI com o Python. O tutorial demonstra como analisar um formulário médico simples.
O que você aprenderá
- Como ativar a API Document AI
- Como autenticar solicitações de API
- Como instalar a biblioteca de cliente para Python
- Como analisar dados de um formulário digitalizado
Pré-requisitos
Pesquisa
Como você usará este tutorial?
Como você classificaria sua experiência com o Python?
Como você classificaria sua experiência de uso dos serviços do Google Cloud?
2. Configuração e requisitos
Configuração de ambiente personalizada
- Faça login no Console do Cloud e crie um novo projeto ou reutilize um existente. Crie uma se você ainda não tiver uma conta do Gmail ou do G Suite.
Lembre-se do ID do projeto, um nome exclusivo em todos os projetos do Google Cloud. (seu nome acima já foi escolhido e não funcionará para você). Você precisará fornecer esse ID posteriormente como PROJECT_ID.
- Em seguida, é necessário ativar o faturamento no Console do Cloud para usar os recursos do Google Cloud.
Siga todas as instruções na seção "Limpeza". Na seção, você aprende a encerrar recursos para não incorrer em cobranças além deste tutorial. Novos usuários do Google Cloud estão qualificados para o programa de avaliação gratuita de US$ 300.
Iniciar Cloud Shell
O Google Cloud pode operar remotamente o Google Cloud no seu laptop, mas este codelab usa o Google Cloud Shell, um ambiente de linha de comando em execução na nuvem.
Ativar o Cloud Shell
- No Console do Cloud, clique em Ativar o Cloud Shell
.
Se você nunca tiver iniciado o Cloud Shell, verá uma tela intermediária (abaixo da dobra) com a descrição do que ele é. Se esse for o caso, clique em Continuar e você não o verá novamente. Esta é uma tela única:
Leva apenas alguns instantes para provisionar e se conectar ao Cloud Shell.
O Cloud Shell oferece acesso de terminal a uma máquina virtual hospedada na nuvem. A máquina virtual inclui todas as ferramentas de desenvolvimento necessárias. Ela oferece um diretório principal persistente de 5 GB, além de ser executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Praticamente todo o seu trabalho neste codelab pode ser feito em um navegador ou no seu Chromebook.
Depois de se conectar ao Cloud Shell, você já estará autenticado e o projeto já estará configurado com seu ID do projeto.
- Execute o seguinte comando no Cloud Shell para confirmar que você está autenticado:
gcloud auth list
Resposta ao comando
Credentialed Accounts
ACTIVE ACCOUNT
* <my_account>@<my_domain.com>
To set the active account, run:
$ gcloud config set account `ACCOUNT`
gcloud config list project
Resposta ao comando
[core] project = <PROJECT_ID>
Se o projeto não estiver configurado, faça a configuração usando este comando:
gcloud config set project <PROJECT_ID>
Resposta ao comando
Updated property [core/project].
3. Ativar a API Document AI do Cloud
Antes de começar a usar a Document AI, você precisa ativar a API. Abra o Console do Cloud no navegador.
- Clique em Menu de navegação > APIs e serviços > Biblioteca.
- Pesquise por "API Document AI" e clique em Ativar para usar a API no seu projeto do Google Cloud
4. Criar e testar um processador
Primeiro, você precisa criar uma instância do processador Form Parser para usar no Document AI Platform para este tutorial.
- No console, navegue até a Visão geral do Document AI Platform.
- Clique em Criar processador e selecione Form Parser
- Especifique um nome de processador e selecione sua região na lista.
- Clique em Criar para criar seu processador.
- Copie o ID do processador. Você precisará usá-la em seu código mais tarde.
(Opcional) É possível testar o processador no console fazendo upload de um documento. Clique em Fazer upload do documento e selecione um formulário para analisar. É possível fazer o download e usar este formulário de exemplo se você não tiver um disponível.
A resposta será parecida com esta: 
5. Autentique as solicitações de API
Para fazer solicitações à API Document AI, você precisa usar uma conta de serviço. Uma conta de serviço pertence ao seu projeto. Ela é usada pela biblioteca Python do cliente do Google para fazer solicitações de API. Como qualquer outra conta de usuário, uma conta de serviço é representada por um endereço de e-mail. Nesta seção, você usará o SDK do Cloud para criar uma conta de serviço e, em seguida, criará as credenciais necessárias para realizar a autenticação.
Primeiro, defina uma variável de ambiente com o PROJECT_ID que você usará em todo este codelab:
export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value core/project)
Em seguida, crie uma nova conta de serviço para acessar a API Document AI usando:
gcloud iam service-accounts create my-docai-sa \
--display-name "my-docai-service-account"
Em seguida, crie credenciais que seu código Python use para fazer login como a nova conta de serviço. Crie e salve essas credenciais como um arquivo JSON "~/key.json" usando o seguinte comando:
gcloud iam service-accounts keys create ~/key.json \
--iam-account my-docai-sa@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com
Por fim, defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS, que é usada pela biblioteca para encontrar suas credenciais. Para saber mais sobre essa autenticação de formulário, consulte o guia. A variável de ambiente deve ser definida para o caminho completo do arquivo JSON de credenciais que você criou. Para isso, use:
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"
6. Faça o download do formulário de amostra
Temos um exemplo de formulário para usar no Google Cloud Storage. Use o seguinte comando para fazer o download dele para seu diretório de trabalho.
gsutil cp gs://cloud-samples-data/documentai/form.pdf .
Confirme se o arquivo foi salvo no Cloudshell usando o comando abaixo:
ls -ltr form.pdf
7. Instale a biblioteca de cliente
Instale a biblioteca de cliente:
pip3 install --upgrade google-cloud-documentai pip3 install --upgrade google-cloud-storage
Você verá algo como:
... Installing collected packages: google-cloud-documentai Successfully installed google-cloud-documentai-0.3.0 . . Installing collected packages: google-cloud-storage Successfully installed google-cloud-storage-1.35.0
Agora você já pode usar a API Document AI.
Inicie o Python interativo
Neste tutorial, você usará um interpretador interativo chamado IPython. Inicie uma sessão executando ipython no Cloud Shell. Este comando executa o interpretador de Python em uma sessão interativa.
ipython
Você verá algo como:
Python 3.7.3 (default, Jul 25 2020, 13:03:44) Type 'copyright', 'credits' or 'license' for more information IPython 7.13.0 -- An enhanced Interactive Python. Type '?' for help. In [1]:
8. Faça uma solicitação de documento de processo síncrono
Nesta etapa, você fará uma chamada de documento de processo usando o endpoint síncrono. Para o processamento de grandes quantidades de documentos de uma vez, você também pode usar a API assíncrona. Para saber mais sobre o uso das APIs do analisador de formulário, leia o guia aqui.
Copie o seguinte código na sua sessão do iPython:
project_id= 'YOUR_PROJECT_ID'
location = 'YOUR_PROJECT_LOCATION' # Format is 'us' or 'eu'
processor_id = 'YOUR_PROCESSOR_ID' # Create processor in Cloud Console
file_path = 'form.pdf' # The local file in your current working directory
from google.cloud import documentai_v1beta3 as documentai
from google.cloud import storage
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)
document = result.document
document_text = document.text
print("Document processing complete.")
print("Text: {}".format(document_text))
Execute o código agora para ver o texto extraído e impresso no console. Nas próximas etapas, você extrairá dados estruturados que podem ser armazenados com mais facilidade em bancos de dados ou usados em outros aplicativos.
Como chamar a função:
process_document()
9. Extraia os pares de chave-valor do formulário
Agora, extraia os pares de chave-valor do formulário e as pontuações de confiança correspondentes. 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 e imprime cada chave, valor e pontuação de confiança.
Na parte inferior da função processDocument(), cole o código abaixo:
document_pages = document.pages
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: "+str(nameConfidence)+", "+str(valueConfidence)+")")
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
Agora execute seu código. Chame a função:
process_document()
Você verá a seguinte resposta se estiver usando nosso documento de amostra:
Document processing complete.
Page Number:1
Marital Status: Single (Confidence Scores: 1.0000, 1.0000)
DOB: 09/04/1986 (Confidence Scores: 0.9999, 0.9999)
City: Towalo (Confidence Scores: 0.9996, 0.9996)
Address: 24 Barney Lane (Confidence Scores: 0.9994, 0.9994)
Referred By: None (Confidence Scores: 0.9968, 0.9968)
Phone #: (906) 917-3486 (Confidence Scores: 0.9961, 0.9961)
State: NJ (Confidence Scores: 0.9960, 0.9960)
Emergency Contact Phone: (906) 334-8926 (Confidence Scores: 0.9924, 0.9924)
Name: Sally Walker (Confidence Scores: 0.9922, 0.9922)
10. Parabéns
Parabéns! Você usou a API Document AI para extrair dados de um formulário escrito à mão. Incentivamos você a fazer experiências com outras imagens de formulário
Limpeza
Para evitar cobranças dos recursos usados neste tutorial na conta do Google Cloud, siga estas etapas:
- No Console do Cloud, acesse a página Gerenciar recursos:
- Na lista de projetos, selecione o projeto e clique em "Excluir".
- Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.