GSP925

Descripción general

La API de Document AI es una solución de comprensión de documentos que toma datos no estructurados, como documentos, correos electrónicos, etc., y facilita la comprensión, el análisis y el consumo de los datos.

En este lab, usarás la API de Document AI con Python para crear varios procesadores, incluidos un procesador general de formularios y un procesador de OCR para documentos y, luego, realizarás llamadas síncronas y asíncronas a la API con Python. En este lab, se crea una instancia de Vertex AI Workbench para ti; la usarás con notebooks de JupyterLab para trabajar con los módulos cliente de Python de Document AI.

Objetivos

En este lab, aprenderás a hacer lo siguiente:

• Habilitar la API de Document AI y crear procesadores
• Instalar la biblioteca cliente para Python en una instancia de Vertex AI Workbench
• Analizar datos de un formulario escaneado usando Python para realizar una llamada síncrona a la API
• Analizar datos de formularios escaneados usando Python para realizar una llamada asíncrona a la API

Configuración y requisitos

Antes de hacer clic en el botón Comenzar lab

Lee estas instrucciones. Los labs son cronometrados y no se pueden pausar. El cronómetro, que comienza a funcionar cuando haces clic en Comenzar lab, indica por cuánto tiempo tendrás a tu disposición los recursos de Google Cloud.

Este lab práctico te permitirá realizar las actividades correspondientes en un entorno de nube real, no en uno de simulación o demostración. Para ello, se te proporcionan credenciales temporales nuevas que utilizarás para acceder a Google Cloud durante todo el lab.

Para completar este lab, necesitarás lo siguiente:

• Acceso a un navegador de Internet estándar (se recomienda el navegador Chrome)

Nota: Usa una ventana de navegador privada o de Incógnito para ejecutar este lab. Así evitarás cualquier conflicto entre tu cuenta personal y la cuenta de estudiante, lo que podría generar cargos adicionales en tu cuenta personal.

• Tiempo para completar el lab: Recuerda que, una vez que comienzas un lab, no puedes pausarlo.

Nota: Si ya tienes un proyecto o una cuenta personal de Google Cloud, no los uses en este lab para evitar cargos adicionales en tu cuenta.

Activa Cloud Shell

Cloud Shell es una máquina virtual que cuenta con herramientas para desarrolladores. Ofrece un directorio principal persistente de 5 GB y se ejecuta en Google Cloud. Cloud Shell proporciona acceso de línea de comandos a tus recursos de Google Cloud.

1. Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud.

Cuando te conectes, habrás completado la autenticación, y el proyecto estará configurado con tu PROJECT_ID. El resultado contiene una línea que declara el PROJECT_ID para esta sesión:

Your Cloud Platform project in this session is set to YOUR_PROJECT_ID

gcloud es la herramienta de línea de comandos de Google Cloud. Viene preinstalada en Cloud Shell y es compatible con la función de autocompletado con tabulador.

2. Puedes solicitar el nombre de la cuenta activa con este comando (opcional):

gcloud auth list

3. Haz clic en Autorizar.

4. Ahora, el resultado debería verse de la siguiente manera:

Resultado:

ACTIVE: * ACCOUNT: student-01-xxxxxxxxxxxx@qwiklabs.net To set the active account, run: $ gcloud config set account `ACCOUNT`

5. Puedes solicitar el ID del proyecto con este comando (opcional):

gcloud config list project

Resultado:

[core] project = <project_ID>

Resultado de ejemplo:

[core] project = qwiklabs-gcp-44776a13dea667a6 Nota: Para obtener toda la documentación de gcloud, consulta la guía con la descripción general de gcloud CLI en Google Cloud.

Tarea 1. Crea y prueba un procesador general de formularios

En esta tarea, habilitarás la API de Document AI, y crearás y probarás un procesador general de formularios. Esta herramienta procesará cualquier tipo de documento y extraerá todo el contenido de texto que pueda identificar en el documento. No se limita a texto impreso, puede manejar texto escrito a mano y texto en cualquier orientación, admite varios idiomas y entiende cómo se relacionan entre sí los elementos de datos de los formularios para que puedas extraer pares clave-valor de los campos de formulario que tienen etiquetas de texto.

Habilita la API de Cloud Document AI

Antes de comenzar a usar Document AI, debes habilitar la API.

1. En la consola de Cloud, en el menú de navegación (), haz clic en APIs y servicios > Biblioteca.

2. Busca API de Cloud Document AI y, luego, haz clic en el botón Habilitar para usar la API en tu proyecto de Google Cloud.

Si la API de Cloud Document AI ya está habilitada, verás el botón Administrar y podrás continuar con el resto del lab.

Verificar que la API de Cloud Document AI esté habilitada

Crea un procesador general de formularios

Crea un procesador de Document AI con el analizador de formularios de Document AI.

1. En la consola, en el menú de navegación (), haz clic en Document AI > Descripción general.

2. Haz clic en Explorar procesadores y selecciona Form Parser, que es un tipo de procesador general.

3. Especifica el nombre analizador-formularios para el procesador y selecciona la región EE.UU. (Estados Unidos) de la lista.

4. Haz clic en Crear para crear el procesador general analizador-formularios.

Esto creará el procesador y te devolverá a la página de detalles del procesador, que mostrará el ID del procesador, el estado y el extremo de predicción.

5. Anota el ID del procesador, ya que tendrás que usarlo para actualizar variables en los notebooks de JupyterLab en tareas posteriores.

Tarea 2. Configura tu instancia de Vertex AI Workbench para realizar llamadas a la API de Document AI

A continuación, conéctate a JupyterLab que se ejecuta en la instancia de Vertex AI Workbench que se creó para ti cuando comenzó el lab y, luego, configura ese entorno para las tareas del lab restantes.

1. En el menú de navegación de la consola de Google Cloud, haz clic en Vertex AI > Workbench.

2. Busca la instancia y haz clic en el botón Abrir JupyterLab.

La interfaz de JupyterLab para tu instancia de Workbench se abrirá en una pestaña nueva del navegador.

3. Haz clic en Terminal para abrir una shell de la terminal dentro de la instancia de Vertex AI Workbench.

4. Ingresa el siguiente comando en la shell de la terminal para importar los archivos del lab a tu instancia de Vertex AI Workbench:

gsutil cp {{{project_0.startup_script.notebook_files_path|notebook_files_path}}} .

5. Ingresa el siguiente comando en la shell de la terminal para instalar las bibliotecas cliente de Python necesarias para Document AI y otras bibliotecas requeridas:

python -m pip install --upgrade google-cloud-core google-cloud-documentai google-cloud-storage prettytable

Deberías ver un resultado que indica que las bibliotecas se instalaron correctamente.

Nota: Si aparecen errores relacionados con los permisos, vuelve a ejecutar el comando para asegurarte de que las bibliotecas se instalaron correctamente. Es posible que los permisos tarden algunos minutos en aplicarse.

6. Ingresa el siguiente comando en la shell de la terminal para importar el formulario de ingreso de datos de salud de muestra:

gsutil cp {{{project_0.startup_script.health_intake_form_path|form_path}}} form.pdf

7. En la interfaz del notebook, abre el notebook de JupyterLab llamado .

8. En el diálogo Seleccionar kernel, elige Python 3 en la lista de kernels disponibles.

Verificar que la instancia de Vertex AI se haya preparado para realizar llamadas síncronas a la API de Document AI

Tarea 3. Realiza una solicitud síncrona de procesamiento de documento

Realiza una llamada de procesamiento de documento usando una llamada síncrona a la API de Document AI. Para procesar grandes cantidades de documentos a la vez, también puedes usar la API asíncrona, que utilizarás en una tarea posterior.

Revisa el código de Python para las llamadas síncronas a la API de Document AI

Tómate un minuto para revisar el código de Python en el notebook .

El primer bloque de código importa las bibliotecas necesarias y, luego, inicializa algunas variables.

from google.cloud import documentai_v1beta3 as documentai from google.cloud import storage from prettytable import PrettyTable project_id = %system gcloud config get-value core/project project_id = project_id[0] location = 'us' file_path = 'form.pdf'

La celda de código Set your Processor ID establece el ID del procesador que tienes que configurar manualmente antes de poder procesar documentos con el notebook.

processor_id = 'PROCESSOR_ID' # TODO: Replace with a valid Processor ID

Para este paso, necesitarás el ID del procesador de Document AI que creaste en la Tarea 1.

Sugerencia: Si no lo guardaste, en la pestaña de la consola de Cloud, abre el menú de navegación (), haz clic en Document AI > Mis procesadores y, luego, haz clic en el nombre de tu procesador para abrir la página de detalles. Aquí, puedes copiar el ID del procesador.

La celda de código Process Document Function define la función process_document que se usa para realizar una llamada síncrona a un procesador de Document AI. La función crea un objeto cliente de API de Document AI.

El nombre del procesador requerido por la llamada a la API se crea usando los parámetros project_id, locations y processor_id, y el documento PDF de muestra se lee y almacena en una estructura mime_type.

La función crea un objeto de solicitud que contiene el nombre completo del procesador del documento y usa ese objeto como parámetro para una llamada síncrona al cliente de API de Document AI. Si la solicitud es correcta, el objeto documento que se devuelve incluirá propiedades que contienen las entidades detectadas en el formulario.

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) return result.document

La celda de código Process Document llama a la función process_document, guarda la respuesta en la variable document y, luego, imprime el texto sin procesar que se detectó. Todos los procesadores informarán algunos datos para la propiedad document.text.

document=process_document() # print all detected text. # All document processors will display the text content print("Document processing complete.") print("Text: {}".format(document.text))

La celda de código Get Text Function define la función get_text() que recupera el texto de un elemento nombrado usando las propiedades text_anchor, start_index y end_index de text_segments del elemento nombrado. Esta función se usa para recuperar el nombre y el valor de los datos del formulario si el procesador los devuelve.

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

La celda Display Form Data itera sobre todas las páginas que se detectaron y por cada form_field detectado usa la función get_text() para recuperar el nombre y el valor del campo. A continuación, se imprimen esos valores, junto con sus correspondientes puntuaciones de confianza. Los procesadores que usen el analizador de formularios general o los analizadores especializados devolverán los datos del formulario, pero este no será el caso con los procesadores creados con el analizador de OCR para documentos.

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

La celda Display Entity Data extrae los datos de entidades del objeto de documento y muestra el tipo de entidad, el valor y las propiedades de confianza de cada entidad detectada. Solo los procesadores que utilizan analizadores especializados de Document AI, como el analizador de gastos de adquisición, devolverán los datos de entidades. El analizador de formularios general y el analizador de OCR para documentos no devolverán datos de entidades.

if 'entities' in dir(document): entities = document.entities # Grab each key/value pair and their confidence scores. table = PrettyTable(['Type', 'Value', 'Confidence']) for entity in entities: entity_type = entity.type_ value = entity.mention_text confience = round(entity.confidence,4) table.add_row([entity_type, value, confience]) print(table) else: print("Document does not contain entity data.")

Tarea 4. Ejecuta el código síncrono de Document AI con Python

Ejecuta el código para realizar llamadas síncronas a la API de Document AI en el notebook de JupyterLab.

1. En la segunda celda de código Set your Processor ID, reemplaza el texto del marcador de posición PROCESSOR_ID por el ID del analizador-formularios que creaste en un paso anterior.

2. Selecciona la primera celda, haz clic en el menú Ejecutar y, luego, haz clic en Ejecutar la celda seleccionada y todas las siguientes para ejecutar todo el código del notebook.

Si usaste el formulario de ingreso de datos de salud de muestra, verás datos similares a los siguientes para la celda de resultado de los datos del formulario:

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

Si puedes crear un procesador especializado, la celda final mostrará los datos de la entidad; de lo contrario, mostrará una tabla vacía.

3. En el menú de JupyterLab, haz clic en Archivo y, luego, en Guardar notebook para guardar tu progreso.

Verificar que se haya procesado un documento usando la API síncrona de Cloud Document AI

Tarea 5. Crea un procesador de OCR para documentos de Document AI

En esta tarea, crearás un procesador de Document AI usando el analizador general de OCR para documentos.

1. En el menú de navegación, haz clic en Document AI > Descripción general.

2. Haz clic en Explorar procesadores y, luego, en Crear procesador para el OCR para documentos. Este es un tipo de procesador general.

3. Especifica el nombre procesador-ocr para el procesador y selecciona la región EE.UU. (Estados Unidos) de la lista.

4. Haz clic en Crear para crear tu procesador.

5. Toma nota del ID del procesador. Tendrás que especificarlo en una tarea posterior.

Tarea 6. Prepara tu entorno para las llamadas asíncronas a la API de Document AI

En esta tarea, debes subir el notebook de muestra de JupyterLab para probar las llamadas asíncronas a la API de Document AI y copiar algunos formularios de muestra para el lab en Cloud Storage para el procesamiento asíncrono.

1. Haz clic en la pestaña Terminal para volver a abrir la shell de la terminal dentro de la instancia de Vertex AI Workbench.

2. Crea un bucket de Cloud Storage para los documentos de entrada y copia los formularios W2 de muestra en el bucket:

export PROJECT_ID="$(gcloud config get-value core/project)" export BUCKET="${PROJECT_ID}"_doc_ai_async gsutil mb gs://${BUCKET} gsutil -m cp {{{project_0.startup_script.async_files_path|async_files_path}}} gs://${BUCKET}/input

3. En la interfaz del notebook, abre el notebook de JupyterLab llamado .

4. En el diálogo Seleccionar kernel, elige Python 3 en la lista de kernels disponibles.

Verificar que la instancia de Vertex AI se haya preparado para llamadas asíncronas a la API de Document AI

Tarea 7. Realiza una solicitud asíncrona de procesamiento de documento

Revisa el código de Python para las llamadas asíncronas a la API de Document AI

Tómate un minuto para revisar el código de Python en el notebook .

La primera celda de código importa las bibliotecas necesarias.

from google.cloud import documentai_v1beta3 as documentai from google.cloud import storage import re import os import pandas as pd import simplejson as json

La celda de código Set your Processor ID establece el ID del procesador que tienes que configurar manualmente antes de poder procesar documentos con el notebook.

processor_id = "PROCESSOR_ID" # TODO: Replace with a valid Processor ID

La celda de código Set your variables define los parámetros que se usarán para realizar la llamada asíncrona, incluida la ubicación de los buckets de Cloud Storage de entrada y salida que se usarán para los datos de origen y los archivos de salida. Actualizarás los valores de marcador de posición en esta celda para PROJECT_ID y PROCESSOR_ID en la próxima sección del lab antes de que ejecutes el código. Las otras variables contienen la configuración predeterminada para la ubicación del procesador, el bucket de Cloud Storage de entrada y el de salida que no es necesario cambiar.

project_id = %system gcloud config get-value core/project project_id = project_id[0] location = 'us' # Replace with 'eu' if processor does not use 'us' location gcs_input_bucket = project_id+"_doc_ai_async" # Bucket name only, no gs:// prefix gcs_input_prefix = "input/" # Input bucket folder e.g. input/ gcs_output_bucket = project_id+"_doc_ai_async" # Bucket name only, no gs:// prefix gcs_output_prefix = "output/" # Input bucket folder e.g. output/ timeout = 300

La celda de código Define Google Cloud client objects inicializa los clientes de Document AI y Cloud Storage.

client_options = {"api_endpoint": "{}-documentai.googleapis.com".format(location)} client = documentai.DocumentProcessorServiceClient(client_options=client_options) storage_client = storage.Client()

La celda de código Create input configuration crea el parámetro de array de configuración de entrada para los datos de origen que se pasarán a la solicitud asíncrona de Document AI como configuración de entrada. Este array almacena la ubicación de origen de Cloud Storage, y el tipo de MIME, para cada uno de los archivos que se encuentran en la ubicación de entrada de Cloud Storage.

blobs = storage_client.list_blobs(gcs_input_bucket, prefix=gcs_input_prefix) input_configs = [] print("Input Files:") for blob in blobs: if ".pdf" in blob.name: source = "gs://{bucket}/{name}".format(bucket = gcs_input_bucket, name = blob.name) print(source) input_config = documentai.types.document_processor_service.BatchProcessRequest.BatchInputConfig( gcs_source=source, mime_type="application/pdf" ) input_configs.append(input_config)

La celda de código Create output configuration crea el parámetro de salida para la solicitud asíncrona que contiene la ubicación del bucket de Cloud Storage de salida y lo almacena como una configuración de salida por lotes de Document AI.

destination_uri = f"gs://{gcs_output_bucket}/{gcs_output_prefix}" output_config = documentai.types.document_processor_service.BatchProcessRequest.BatchOutputConfig( gcs_destination=destination_uri )

La celda de código Create the Document AI API request compila el objeto de solicitud de proceso por lotes asíncrono de Document AI usando los objetos de configuración de entrada y salida.

name = f"projects/{project_id}/locations/{location}/processors/{processor_id}" request = documentai.types.document_processor_service.BatchProcessRequest( name=name, input_configs=input_configs, output_config=output_config, )

La celda de código Start the batch (asynchronous) API operation realiza una solicitud de proceso de documentos asíncrona pasando el objeto de solicitud al método batch_process_documents(). Esta es una llamada asíncrona, por lo que usas el método result() para forzar al notebook a esperar hasta que el trabajo asíncrono en segundo plano haya finalizado.

operation = client.batch_process_documents(request) # Wait for the operation to finish operation.result(timeout=timeout) print ("Batch process completed.")

La celda Fetch list of output files enumera los objetos en la ubicación del bucket de salida definida en la variable destination_uri.

La celda Display detected text from asynchronous output JSON files carga cada archivo JSON de salida que se encuentra como un objeto de documento de Document AI y se imprimen los datos de texto detectados por el procesador de OCR para documentos.

La celda Display entity data mostrará cualquier dato de entidad que se encuentre. Sin embargo, los datos de entidad solo están disponibles para los procesadores que se crearon usando un analizador especializado. Los datos de entidad no se mostrarán con el analizador de OCR general de Document AI utilizado en esta tarea.

Ejecuta el código asíncrono de Document AI con Python

Usa el código de muestra proporcionado en el notebook de Jupyterlab para procesar documentos de forma asíncrona usando una solicitud de procesamiento por lotes de Document AI.

1. En la segunda celda de código, reemplaza el texto de marcador de posición de PROCESSOR_ID por el ID del procesador analizador-formularios que creaste en un paso anterior.

2. Selecciona la primera celda, haz clic en el menú Ejecutar y, luego, haz clic en Ejecutar la celda seleccionada y todas las siguientes para ejecutar todo el código del notebook.

3. A medida que se ejecutan las celdas de código, puedes recorrer el notebook revisando el código y los comentarios que explican cómo se crea y usa el objeto de solicitud asíncrona.

El notebook esperará uno o dos minutos a que la operación asíncrona de proceso por lotes se complete en la celda de código Start the batch (asynchronous) API operation. Mientras que la propia llamada a la API de proceso por lotes es asíncrona, el notebook usa el método result para forzar al notebook a esperar hasta que la llamada asíncrona haya finalizado antes de enumerar y mostrar los datos de salida.

Si el trabajo asíncrono tarda más de lo esperado y se agota el tiempo de espera, es posible que debas volver a ejecutar las celdas restantes para mostrar el resultado. Estas son las celdas posteriores a la celda Start the batch (asynchronous) API operation.

El resultado contendrá una lista de los datos de Document AI detectados en cada archivo. El analizador de OCR para documentos no detecta datos de formularios ni de entidades, por lo que no se producirán datos de formularios ni de entidades. Si puedes crear un procesador especializado, también verás que la celda final imprime datos de entidad.

4. En el menú de JupyterLab, haz clic en Archivo y, luego, en Guardar notebook para guardar tu progreso.

Document processing complete. Text: 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. Date: Sally Walker Name: 9/14/19 ... Verificar si se procesó un documento usando la API asíncrona de Cloud Document AI

¡Felicitaciones!

Realizaste correctamente llamadas síncronas y asíncronas a la API de Document AI. En este lab, habilitaste la API de Document AI y creaste procesadores. Instalaste la biblioteca cliente para Python en una instancia de Vertex AI Workbench, analizaste datos de un formulario escaneado usando Python para realizar una llamada síncrona a la API y analizaste datos de formularios escaneados usando Python para realizar una llamada asíncrona a la API.

Finaliza la Quest

Este lab de autoaprendizaje forma parte de la Quest para obtener la insignia de habilidad Detect Manufacturing Defects using Visual Inspection AI. Una Quest es una serie de labs relacionados que forman una ruta de aprendizaje. Si completas esta Quest, obtendrás una insignia como reconocimiento por tu logro. Comparte la insignia en tu currículum y tus plataformas sociales, y anuncia tu logro con el hashtag #GoogleCloudBadge. Puedes publicar la insignia y agregar un vínculo a ella en tu currículum en línea o en tus cuentas de redes sociales. Inscríbete en una Quest y obtén un crédito inmediato de finalización después de haber realizado este lab. Consulta otras Quests disponibles.

Próximos pasos y más información

• Para obtener más información sobre el uso de las APIs de Document AI, consulta la guía.

Capacitación y certificación de Google Cloud

Recibe la formación que necesitas para aprovechar al máximo las tecnologías de Google Cloud. Nuestras clases incluyen habilidades técnicas y recomendaciones para ayudarte a avanzar rápidamente y a seguir aprendiendo. Para que puedas realizar nuestros cursos cuando más te convenga, ofrecemos distintos tipos de capacitación de nivel básico a avanzado: a pedido, presenciales y virtuales. Las certificaciones te ayudan a validar y demostrar tus habilidades y tu conocimiento técnico respecto a las tecnologías de Google Cloud.

Última actualización del manual: 8 de octubre de 2024

Prueba más reciente del lab: 8 de octubre de 2024

Copyright 2024 Google LLC. All rights reserved. Google y el logotipo de Google son marcas de Google LLC. Los demás nombres de productos y empresas pueden ser marcas de las respectivas empresas a las que estén asociados.