GSP1140
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 os processadores especializados da Document AI para classificar e analisar documentos especializados usando Python.
Para a análise e a extração de entidades, você vai usar uma fatura como exemplo. Esse procedimento e o exemplo de código funcionam com qualquer documento especializado compatível com a Document AI.
Objetivos
Neste laboratório, você vai aprender a fazer o seguinte:
- Extrair entidades esquematizadas usando processadores especializados.
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
-
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
-
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.
-
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.
-
Clique em Próxima.
-
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.
-
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.
-
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.
-
Clique em Ativar o Cloud Shell 
na parte de cima do console do Google Cloud.
-
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.
- (Opcional) É possível listar o nome da conta ativa usando este comando:
gcloud auth list
- Clique em Autorizar.
Saída:
ACTIVE: *
ACCOUNT: {{{user_0.username | "ACCOUNT"}}}
To set the active account, run:
$ gcloud config set account `ACCOUNT`
- (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.
-
Para abrir o Cloud Shell, clique no botão Ativar o Cloud Shell na parte de cima do console.
-
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.
- Execute este comando para instalar o Pandas:
pip3 install --upgrade pandas
- 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.
- No menu de navegação, clique em VER TODOS OS PRODUTOS em Inteligência artificial. Depois, selecione Document AI.
- Clique em Explorar os processadores, role para baixo até Especializado e, em Analisador de faturas, clique em Criar processador.
-
Nomeie-o como lab-invoice-parser e selecione a região mais próxima na lista.
-
Clique em Criar para que o processador seja criado.
-
Copie o ID do processador. Você vai usá-lo no código mais tarde.
Criar um processador
Baixar amostras de documentos
Temos alguns exemplos que você pode usar neste laboratório.
- Execute o comando a seguir para baixar os formulários de amostra no Cloud Shell.
gcloud storage cp gs://cloud-samples-data/documentai/codelabs/specialized-processors/procurement_multi_document.pdf.
gcloud storage cp gs://cloud-samples-data/documentai/codelabs/specialized-processors/google_invoice.pdf.
- Confirme se os arquivos foram baixados no Cloud Shell usando este comando:
ls
Você vai ver algo parecido com:
google_invoice.pdf procurement_multi_document.pdf
Tarefa 3: extrair as entidades
Agora você pode extrair as entidades esquematizadas dos arquivos, incluindo pontuações de confiança, propriedades e valores normalizados.
O código para fazer a solicitação de API é idêntico ao da etapa anterior e pode ser feito com solicitações on-line ou em lote.
Você vai acessar as seguintes informações das entidades:
-
Tipo de entidade
- (por exemplo,
invoice_date, receiver_name, total_amount)
-
Valores brutos
- Valores de dados conforme apresentados no arquivo original do documento.
-
Valores normalizados
- Valores de dados em um formato normalizado e padrão, se aplicável.
- Também pode incluir aprimoramento do Enterprise Knowledge Graph
-
Níveis de confiança
- O quanto o modelo tem "certeza" de que os valores são precisos.
Alguns tipos de entidade, como line_item, também podem incluir propriedades, que são entidades aninhadas, como line_item/unit_price e line_item/description. Este exemplo simplifica a estrutura aninhada para facilitar a visualização.
Analisador de faturas
- No Cloud Shell, crie um arquivo chamado
extraction.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
# Primeiro, é preciso criar novos processadores no console do Cloud
resource_name = documentai_client.processor_path(project_id, location, processor_id)
# Leia o arquivo na memória
with open(file_path, "rb") as file:
file_content = file.read()
# Carregue dados binários no objeto RawDocument da Document AI
raw_document = documentai.RawDocument(content=file_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
PROJECT_ID = "YOUR_PROJECT_ID"
LOCATION = "YOUR_PROJECT_LOCATION" # O formato é 'us' ou 'eu'
PROCESSOR_ID = "INVOICE_PARSER_ID" # Crie um processador no console do Cloud
# O arquivo local no seu diretório atual de trabalho
FILE_PATH = "google_invoice.pdf"
# Consulte 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,
)
types = []
raw_values = []
normalized_values = []
confidence = []
# Obtenha cada par de chave-valor e as pontuações de confiança correspondentes.
for entity in document.entities:
types.append(entity.type_)
raw_values.append(entity.mention_text)
normalized_values.append(entity.normalized_value.text)
confidence.append(f"{entity.confidence:.0%}")
# Obtenha as propriedades (Sub-Entities) com pontuações de confiança
for prop in entity.properties:
types.append(prop.type_)
raw_values.append(prop.mention_text)
normalized_values.append(prop.normalized_value.text)
confidence.append(f"{prop.confidence:.0%}")
# Crie um Dataframe Pandas para imprimir os valores no formato tabular.
df = pd.DataFrame(
{
"Type": types,
"Raw Value": raw_values,
"Normalized Value": normalized_values,
"Confidence": confidence,
}
)
print(df)
-
Substitua INVOICE_PARSER_ID pelo ID do processador de análise de faturas que você criou antes e use o arquivo google_invoice.pdf.
-
Substitua YOUR_PROJECT_ID e YOUR_PROJECT_LOCATION pelo ID do seu projeto do Google Cloud e pela localização do processador, respectivamente.
-
Execute o script:
python3 extraction.py
A saída será parecida com esta:
Type Raw Value Normalized Value Confidence
0 due_date Sep 30, 2019 2019-09-30 99%
1 net_amount 22,379.39 22379.39 99%
2 total_amount 19,647.68 19647.68 99%
3 invoice_date Sep 24, 2019 2019-09-24 98%
4 total_tax_amount 1,767.97 1767.97 94%
5 receiver_name Jane Smith, 88%
6 receiver_address 1600 Amphitheatre Pkway Mountain View, CA 94043 77%
7 invoice_id 23413561D 60%
8 freight_amount 199.99 199.99 60%
9 invoice_type invoice_statement 59%
10 currency $ USD 58%
11 supplier_name Google Google 37%
12 line_item 9.99 12 12 ft HDMI cable 119.88 100%
13 line_item/unit_price 9.99 9.99 95%
14 line_item/quantity 12 12 75%
15 line_item/description 12 ft HDMI cable 64%
16 line_item/amount 119.88 119.88 90%
17 line_item 12 399.99 27" Computer Monitor 4,799.88 100%
18 line_item/quantity 12 12 76%
19 line_item/unit_price 399.99 399.99 95%
20 line_item/description 27" Computer Monitor 42%
21 line_item/amount 4,799.88 4799.88 93%
22 line_item Ergonomic Keyboard 12 59.99 719.88 100%
23 line_item/description Ergonomic Keyboard 42%
24 line_item/quantity 12 12 75%
25 line_item/unit_price 59.99 59.99 94%
26 line_item/amount 719.88 719.88 85%
27 line_item Optical mouse 12 19.99 239.88 100%
28 line_item/description Optical mouse 55%
29 line_item/quantity 12 12 72%
30 line_item/unit_price 19.99 19.99 94%
31 line_item/amount 239.88 239.88 81%
32 line_item Laptop 12 1,299.99 15,599.88 100%
33 line_item/description Laptop 65%
34 line_item/quantity 12 12 71%
35 line_item/unit_price 1,299.99 1299.99 94%
36 line_item/amount 15,599.88 15599.88 91%
37 line_item Misc processing fees 899.99 899.99 1 100%
38 line_item/description Misc processing fees 54%
39 line_item/unit_price 899.99 899.99 92%
40 line_item/amount 899.99 899.99 82%
41 line_item/quantity 1 1 68%
- Crie um bucket do Cloud Storage e faça upload da saída gerada do comando
docai_outputs.txt para o bucket.
# Crie um bucket
export PROJECT_ID=$(gcloud config get-value project)
gsutil mb gs://$PROJECT_ID-docai
# Crie e faça upload do arquivo
python3 extraction.py > docai_outputs.txt
gsutil cp docai_outputs.txt gs://$PROJECT_ID-docai
Crie um bucket do Cloud Storage e faça upload do arquivo de saída
Opcional: teste outros processadores especializados
Você conseguiu usar a Document AI para compras para classificar documentos e analisar uma fatura. A Document AI também aceita outras soluções especializadas listadas aqui:
Você pode seguir o mesmo procedimento e usar o mesmo código para lidar com qualquer processador especializado.
Se quiser testar outras soluções especializadas, execute o laboratório novamente com outros tipos de processadores e documentos de amostra especializados.
Observação: alguns processadores de identidade, empréstimo e contrato estão com acesso limitado no momento. Se você tiver um caso de uso comercial para esses processadores, preencha e envie o formulário de solicitação apropriado antes de continuar.
Documentos de amostra
Aqui estão alguns exemplos de documentos que você pode usar para testar os outros processadores especializados.
Veja outros documentos de amostra e a saída do processador na documentação.
Parabéns!
Parabéns! Você conseguiu usar a Document AI para analisar uma fatura. Você também aprendeu a usar a biblioteca de cliente Python para chamar a API Document AI.
Próximas etapas / Saiba mais
Confira os recursos a seguir para saber mais sobre a Document AI e a biblioteca de cliente Python:
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 07 de novembro de 2024
Laboratório testado em 07 de novembro de 2024
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.
