1. Visão geral
O que é a Document AI?
A Document AI é uma solução de compreensão de documentos que usa dados não estruturados (por exemplo, documentos, e-mails, faturas, formulários etc.) e facilita o entendimento, a análise e a utilização 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 laboratório, você aprenderá a fazer o reconhecimento óptico de caracteres usando a API Document AI com o Python.
Usaremos um arquivo PDF da obra clássica "Winnie the Pooh" de AA Milne, que recentemente se tornou parte do domínio público nos Estados Unidos. O arquivo foi digitalizado e digitalizado pelo Google Livros.
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 texto de um arquivo PDF
- Como executar solicitações assíncronas usando o Google Cloud Storage
Pré-requisitos
- Um projeto do Google Cloud
- Um navegador, como o Chrome ou o Firefox
- Ter familiaridade com o Python (3.7+)
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
Navegue até https://gcpcredits.com/io2022 e clique no botão "Clique aqui para acessar seus créditos":
Na caixa de diálogo seguinte, clique nos botões "Aceitar e continuar" para aceitar os Termos de Serviço:
Depois de aceitar os Termos de Serviço, você será redirecionado para uma página de resumo do faturamento, que inclui um painel como este no canto inferior direito:
Por fim, ao criar seu primeiro projeto, você verá uma caixa de diálogo que permite atribuir uma conta de faturamento ao projeto. Selecione a conta de faturamento associada aos créditos gratuitos e clique no botão "Criar":
Resumindo, agora você tem uma conta de faturamento e um projeto, e essas duas entidades estão vinculadas de modo que qualquer trabalho que você fizer no codelab de hoje será financiado pelos seus créditos gratuitos**.**
Configuração de ambiente personalizada
- Faça login no Console do Cloud e crie um novo projeto ou reutilize um existente. Se você ainda não tiver uma conta do Gmail ou do Google Workspace, crie uma.
Lembre-se do ID do projeto, um nome exclusivo em todos os projetos do Google Cloud. O ID do projeto já foi usado 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:
O provisionamento e a conexão ao Cloud Shell levam apenas alguns instantes.
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. Grande parte do seu trabalho neste codelab, se não todos, pode ser realizada com apenas um navegador.
Depois que você se conectar ao Cloud Shell, sua autenticação já terá sido feita, e o projeto estará definido com o ID do projeto.
- Execute o seguinte comando no Cloud Shell para confirmar se a conta está autenticada:
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. Ative a API Document AI
Antes de começar a usar a Document AI, você precisa ativar a API. Abra o Console do Cloud no navegador.
- Na barra de pesquisa na parte superior do console, procure "API Document AI" e clique em Ativar para usar a API no projeto do Google Cloud.
- Como alternativa, a API pode ser ativada usando o seguinte comando
gcloud.
gcloud services enable documentai.googleapis.com
Você verá algo como:
Operation "operations/..." finished successfully.
Agora você pode usar a Document AI.
4. Criar e testar um processador
Primeiro, você precisa criar uma instância do processador de OCR de documentos que realizará a extração. Faça isso usando o Console do Cloud ou a API Processador de gerenciamento.
Console do Cloud
- No console, navegue até a Visão geral do Document AI Platform.
- Clique em Create Processor e selecione Document OCR.
- Especifique um nome de processador e selecione sua região na lista.
- Clique em Criar para criar seu processador.
- Copie seu ID de processador. Use isso no seu código mais tarde.
É possível testar seu processador no console fazendo upload de um documento. Clique em Fazer upload do documento de teste e selecione o documento a ser analisado.
Você pode fazer o download do arquivo PDF abaixo, que contém as três primeiras páginas do nosso livro.
A resposta será parecida com esta: 
Biblioteca de cliente Python
Siga este codelab para saber como gerenciar processadores da Document AI com a biblioteca de cliente do Python:
Como gerenciar processadores da Document AI com Python: codelab
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 e é usada pela biblioteca de cliente do Python 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. Instale a biblioteca de cliente
Instale as bibliotecas 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-1.2.0 . . Installing collected packages: google-cloud-storage Successfully installed google-cloud-storage-1.43.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.30.1 -- An enhanced Interactive Python. Type '?' for help. In [1]:
7. Faça o download do PDF de amostra
Temos um documento de exemplo com as três primeiras páginas do livro.
Você pode fazer o download do PDF usando o link a seguir. Em seguida, faça o upload para a instância do Cloud Shell.
Também é possível fazer o download dele do nosso bucket público do Google Cloud Storage usando gsutil.
gsutil cp gs://cloud-samples-data/documentai/codelabs/ocr/Winnie_the_Pooh_3_Pages.pdf .
8. Faça uma solicitação de documento de processo síncrono
Nesta etapa, você processará as três primeiras páginas do livro usando o endpoint síncrono. Esse método é mais adequado para documentos menores armazenados localmente. Consulte a lista completa de processadores para ver o número máximo de páginas e o tamanho de arquivo de cada tipo.
Copie o seguinte código na sua sessão do iPython:
from google.cloud import documentai_v1 as documentai
def process_document(project_id: str, location: str,
processor_id: str, file_path: str,
mime_type: str) -> documentai.Document:
"""
Processes a document using the Document AI API.
"""
# Instantiates a client
documentai_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
resource_name = documentai_client.processor_path(
project_id, location, processor_id)
# Read the file into memory
with open(file_path, "rb") as image:
image_content = image.read()
# Load Binary Data into Document AI RawDocument Object
raw_document = documentai.RawDocument(
content=image_content, mime_type=mime_type)
# Configure the process request
request = documentai.ProcessRequest(
name=resource_name, raw_document=raw_document)
# Use the Document AI client to process the sample form
result = documentai_client.process_document(request=request)
return result.document
def main():
"""
Run the codelab.
"""
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 = 'Winnie_the_Pooh_3_Pages.pdf' # The local file in your current working directory
# Refer to https://cloud.google.com/document-ai/docs/processors-list for the supported file types
mime_type = 'application/pdf'
document = process_document(project_id=project_id, location=location,
processor_id=processor_id, file_path=file_path,
mime_type=mime_type)
print("Document processing complete.")
print(f"Text: {document.text}")
Chame a função principal. Você verá o texto extraído e impresso no console.
main()
Você verá a seguinte resposta se estiver usando nosso documento de amostra:
Document processing complete. Text: CHAPTER I IN WHICH We Are Introduced to Winnie-the-Pooh and Some Bees, and the Stories Begin Here is Edward Bear, coming downstairs now, bump, bump, bump, on the back of his head, behind Christopher Robin. It is, as far as he knows, the only way of coming downstairs, but sometimes he feels that there really is another way, if only he could stop bumping for a moment and think of it. And then he feels that perhaps there isn't. Anyhow, here he is at the bottom, and ready to be introduced to you. Winnie-the-Pooh. When I first heard his name, I said, just as you are going to say, "But I thought he was a boy?" "So did I," said Christopher Robin. "Then you can't call him Winnie?" "I don't." "But you said " ... Digitized by Google
9. Fazer uma solicitação de documento de processo assíncrona
Agora, suponha que você queira ler o texto do livro inteiro.
- O método
process_documents()tem limites quanto ao número de páginas e tamanho de arquivo que podem ser enviados e permite apenas um arquivo de documento por chamada de API. - O método
batch_process_documents()permite o processamento assíncrono de arquivos maiores e o processamento em lote de vários arquivos.
Nesta etapa, processaremos todo o romance "Winnie the Pooh" com a API Async Document AI e enviaremos o texto para um bucket do Google Cloud Storage.
Fazer upload do PDF no Cloud Storage
No momento, o método batch_process_documents() aceita arquivos do Google Cloud Storage. Consulte documentai_v1.types.BatchProcessRequest para ver mais informações sobre a estrutura do objeto.
Neste exemplo, você pode copiar o arquivo do bucket de dados de amostra...
gsutil cp gs://cloud-samples-data/documentai/codelabs/ocr/Winnie_the_Pooh.pdf gs://YOUR_BUCKET_NAME/
...ou faça o download do arquivo de amostra da história no link abaixo e faça upload dele para seu próprio bucket.
Você também precisará de um bucket do GCS para armazenar a resposta da API.
Como usar o método batch_process_documents()
Copie o seguinte código na sua sessão do iPython:
import re
from google.api_core.operation import Operation
from google.cloud import documentai_v1 as documentai
from google.cloud import storage
def batch_process_documents(
project_id: str,
location: str,
processor_id: str,
gcs_input_uri: str,
input_mime_type: str,
gcs_output_uri: str,
) -> Operation:
"""
Constructs a request to process a document using the Document AI
Asynchronous API.
"""
# You must set the api_endpoint if you use a location other than 'us', e.g.:
opts = {}
if location == "eu":
opts = {"api_endpoint": "eu-documentai.googleapis.com"}
# Instantiates a client
documentai_client = documentai.DocumentProcessorServiceClient(client_options=opts)
# 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
resource_name = documentai_client.processor_path(project_id, location, processor_id)
# Cloud Storage URI for the Input Document
input_document = documentai.GcsDocument(
gcs_uri=gcs_input_uri, mime_type=input_mime_type
)
# Load GCS Input URI into a List of document files
input_config = documentai.BatchDocumentsInputConfig(
gcs_documents=documentai.GcsDocuments(documents=[input_document])
)
# Cloud Storage URI for Output directory
gcs_output_config = documentai.DocumentOutputConfig.GcsOutputConfig(
gcs_uri=gcs_output_uri
)
# Load GCS Output URI into OutputConfig object
output_config = documentai.DocumentOutputConfig(gcs_output_config=gcs_output_config)
# Configure Process Request
request = documentai.BatchProcessRequest(
name=resource_name,
input_documents=input_config,
document_output_config=output_config,
)
# Future for long-running operations returned from Google Cloud APIs.
operation = documentai_client.batch_process_documents(request)
return operation
def get_documents_from_gcs(
gcs_output_uri: str, operation_name: str
) -> [documentai.Document]:
"""
Download the document output from GCS.
"""
# The GCS API requires the bucket name and URI prefix separately
match = re.match(r"gs://([^/]+)/(.+)", gcs_output_uri)
output_bucket = match.group(1)
prefix = match.group(2)
# The output files will be in a new subdirectory with the Operation ID as the name
operation_id = re.search("operations\/(\d+)", operation_name, re.IGNORECASE).group(1)
output_directory = f"{prefix}/{operation_id}"
storage_client = storage.Client()
# List of all of the files in the directory `gs://gcs_output_uri/operation_id`
blob_list = list(storage_client.list_blobs(output_bucket, prefix=output_directory))
output_documents = []
for blob in blob_list:
# Document AI should only output JSON files to GCS
if ".json" in blob.name:
document = documentai.types.Document.from_json(blob.download_as_bytes())
output_documents.append(document)
else:
print(f"Skipping non-supported file type {blob.name}")
return output_documents
def main():
"""
Run the codelab.
"""
project_id = 'YOUR_PROJECT_ID'
location = 'YOUR_PROJECT_LOCATION' # Format is 'us' or 'eu'
processor_id = 'YOUR_PROCESSOR_ID' # Create processor in Cloud Console
# Format 'gs://input_bucket/directory/file.pdf'
gcs_input_uri = "INPUT_BUCKET_URI"
input_mime_type = "application/pdf"
# Format 'gs://output_bucket/directory'
gcs_output_uri = "YOUR_OUTPUT_BUCKET_URI"
# Batch Process returns a Long Running Operation (LRO)
operation = batch_process_documents(
project_id=project_id,
location=location,
processor_id=processor_id,
gcs_input_uri=gcs_input_uri,
input_mime_type=input_mime_type,
gcs_output_uri=gcs_output_uri,
)
# Format: projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID
operation_name = operation.operation.name
# Continually polls the operation until it is complete.
# This could take some time for larger files
print(f"Waiting for operation {operation_name} to complete...")
result = operation.result(timeout=300)
# NOTE: Can also use callbacks for asynchronous processing
#
# def my_callback(future):
# result = future.result()
#
# operation.add_done_callback(my_callback)
print("Document processing complete.")
# Get the Document Objects from the Output Bucket
document_list = get_documents_from_gcs(
gcs_output_uri=gcs_output_uri, operation_name=operation_name
)
for document in document_list:
print(document.text)
Chame a função principal para ver o texto completo completo extraído e impresso no console.
main()
Talvez isso leve algum tempo para ser concluído porque o arquivo é muito maior do que o exemplo anterior. (Ah, incomoda...)
No entanto, com a API assíncrona, você receberá um código de operação, que pode ser usado para receber o resultado do GCS quando a tarefa for concluída.
This is a reproduction of a library book that was digitized by Google as part of an ongoing effort to preserve the information in books and make it universally accessible. TM Google books https://books.google.com ..... He nodded and went out ... and in a moment I heard Winnie-the-Pooh -bump, bump, bump-go-ing up the stairs behind him. Digitized by Google
10. Parabéns
Você usou a Document AI para extrair texto de um livro usando as APIs síncronas e assíncronas.
Recomendamos que você teste outros documentos e conheça os outros processadores disponíveis na plataforma.
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.
Saiba mais
- Documentação do Document AI
- Biblioteca de cliente Python da Document AI
- Amostras de Python do Document AI
Licença
Este conteúdo está sob a licença Atribuição 2.0 Genérica da Creative Commons.