GSP924

Descripción general

La API de Document AI es una solución de comprensión de documentos que toma datos no estructurados, como documentos y correos electrónicos, y facilita la comprensión, el análisis y el consumo de los datos. Con el procesador general de formularios que se usa en este lab, puedes extraer pares clave-valor de un documento simple.

En este lab, aprenderás a crear analizadores de documentos con Document AI, enviar documentos para su procesamiento a través de Google Cloud con la consola de Cloud y la línea de comandos, y usar Python para realizar llamadas síncronas a la API.

Aprendizajes esperados

Aprenderás a realizar las siguientes tareas:

• Crear y probar un procesador de Document AI con la consola
• Probar procesadores de Document AI con la línea de comandos
• Probar llamadas síncronas a la API de Document AI con Python

Configuración y requisitos

Antes de hacer clic en el botón Comenzar lab

Lee estas instrucciones. Los labs cuentan con un temporizador que no se puede pausar. El temporizador, 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 del navegador privada o de incógnito (opción recomendada) para ejecutar el lab. Así evitarás conflictos 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: Usa solo la cuenta de estudiante para este lab. Si usas otra cuenta de Google Cloud, es posible que se apliquen cargos a esa cuenta.

Cómo iniciar tu lab y acceder a la consola de Google Cloud

1. Haz clic en el botón Comenzar lab. Si debes pagar por el lab, se abrirá un diálogo para que selecciones la forma de pago. A la izquierda, se encuentra el panel Detalles del lab, que tiene estos elementos:

   • El botón para abrir la consola de Google Cloud
   • El tiempo restante
   • Las credenciales temporales que debes usar para el lab
   • Otra información para completar el lab, si es necesaria

2. Haz clic en Abrir la consola de Google Cloud (o haz clic con el botón derecho y selecciona Abrir el vínculo en una ventana de incógnito si ejecutas el navegador Chrome).

   El lab inicia recursos y abre otra pestaña en la que se muestra la página de acceso.

   Sugerencia: Ordena las pestañas en ventanas separadas, una junto a la otra.

   Nota: Si ves el diálogo Elegir una cuenta, haz clic en Usar otra cuenta.

3. De ser necesario, copia el nombre de usuario a continuación y pégalo en el diálogo Acceder.

   {{{user_0.username | "Username"}}}

   También puedes encontrar el nombre de usuario en el panel Detalles del lab.

4. Haz clic en Siguiente.

5. Copia la contraseña que aparece a continuación y pégala en el diálogo Te damos la bienvenida.

   {{{user_0.password | "Password"}}}

   También puedes encontrar la contraseña en el panel Detalles del lab.

6. Haz clic en Siguiente.

   Importante: Debes usar las credenciales que te proporciona el lab. No uses las credenciales de tu cuenta de Google Cloud. Nota: Usar tu propia cuenta de Google Cloud para este lab podría generar cargos adicionales.

7. Haz clic para avanzar por las páginas siguientes:

   • Acepta los Términos y Condiciones.
   • No agregues opciones de recuperación o autenticación de dos factores (esta es una cuenta temporal).
   • No te registres para obtener pruebas gratuitas.

Después de un momento, se abrirá la consola de Google Cloud en esta pestaña.

Nota: Para acceder a los productos y servicios de Google Cloud, haz clic en el menú de navegación o escribe el nombre del servicio o producto en el campo Buscar.

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.

2. Haz clic para avanzar por las siguientes ventanas:

   • Continúa en la ventana de información de Cloud Shell.
   • Autoriza a Cloud Shell para que use tus credenciales para realizar llamadas a la API 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 {{{project_0.project_id | "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.

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

gcloud auth list

4. Haz clic en Autorizar.

Resultado:

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} 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_0.project_id | "PROJECT_ID"}}} Nota: Para obtener toda la documentación de gcloud, en Google Cloud, consulta la guía con la descripción general de gcloud CLI.

Tarea 1: Habilita la API de Cloud Document AI

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 solo a texto impreso, también funciona con 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 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.

Haz clic en Revisar mi progreso para verificar los objetivos.

API de Cloud Document AI habilitada

Tarea 2: Crea y prueba un procesador general de formularios

A continuación, crearás un procesador de Document AI con el analizador de formularios de Document AI.

Crea un procesador

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

2. Haz clic en Explorar procesadores.

3. Haz clic en Crear procesador en Analizador de formularios, que es un tipo de procesador general.

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

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

Con estos pasos, se creará el procesador y volverás a la página de detalles del procesador, en la que verás el ID del procesador, el estado y el extremo de predicción.

6. Anota el ID del procesador, ya que lo usarás con curl para hacer una llamada POST a la API en una tarea posterior.

Descarga el formulario de ejemplo

En esta tarea, descargarás el formulario de muestra desde Cloud Storage. Para subir este formulario en la próxima tarea, primero debes descargarlo en tu máquina local.

1. Descarga el archivo form.pdf en tu máquina local.

El archivo debería descargarse directamente. Si el archivo se abre en tu navegador, descárgalo con los controles de archivo del navegador. El archivo form.pdf es un FORMULARIO DE INGRESO DE DATOS DE SALUD con datos de ejemplo escritos a mano.

Sube un formulario para el procesamiento de Document AI

Ahora, subirás el formulario de muestra que descargaste a tu procesador analizador-formularios. Luego, se analizará y los resultados se mostrarán en la consola.

1. En la página analizador-formularios, haz clic en el botón Subir documento de prueba. Aparecerá un diálogo en el que debes seleccionar el archivo que descargaste en la tarea anterior para subirlo.

Una barra de progreso indicará el avance del proceso de análisis y, finalmente, se mostrarán los resultados. Verás que el procesador general registró los datos del formulario en un conjunto de pares clave-valor.

Los pares clave-valor analizados del documento fuente se presentarán en la consola. En el panel izquierdo, se muestran los datos, y en el panel derecho, se resaltan con rectángulos azules las ubicaciones de origen en el documento analizado. Examina los datos de salida y compara los resultados con los datos de origen.

En esta tarea, probarás un procesador general de formularios de Document AI a través de llamadas a la API desde la línea de comandos.

Haz clic en Revisar mi progreso para verificar los objetivos.

Crear y probar un procesador general de formularios

Tarea 3: Configura la instancia del lab

En esta sección, configurarás la instancia del lab para usar la API de Document AI.

Conéctate a la instancia de VM del lab a través de SSH

Realizarás el resto de las tareas del lab en la VM del lab llamada document-ai-dev.

1. En el menú de navegación (), haz clic en Compute Engine > Instancias de VM.

2. Haz clic en el vínculo SSH para la instancia de VM llamada document-ai-dev.

Para este paso, necesitarás el ID del procesador de Document AI que creaste en la Tarea 1. Si no lo guardaste, sigue estos pasos en la pestaña de la consola de Cloud:

• Abre el menú de navegación ().
• Haz clic en Document AI > Procesadores .
• Haz clic en el nombre de tu procesador para abrir la página de detalles.
• Aquí, puedes copiar el ID del procesador.

3. En la sesión de SSH, crea una variable de entorno para contener el ID del procesador de Document AI. Debes reemplazar el marcador de posición de [el ID de tu procesador]:

export PROCESSOR_ID=[el ID de tu procesador]

4. En la sesión de SSH, confirma que la variable de entorno contiene el ID del procesador de Document AI:

echo Your processor ID is:$PROCESSOR_ID

5. Esto debería imprimir un ID del procesador similar al que se muestra a continuación:

Your processor ID is:4897d834d2f4415d

Usarás esta sesión de SSH para las tareas restantes de este lab.

Autentica solicitudes a la API

Para realizar solicitudes a la API de Document AI, debes proporcionar una credencial válida. En esta tarea, crearás una cuenta de servicio, limitarás los permisos otorgados a esa cuenta de servicio a los necesarios para el lab y, luego, generarás una credencial para esa cuenta que se pueda usar para autenticar solicitudes a la API de Document AI.

1. Configura una variable de entorno con tu ID del proyecto, que usarás durante todo este lab:

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

2. Crea una cuenta de servicio nueva para acceder a la API de Document AI con el siguiente comando:

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

3. Vincula la cuenta de servicio al rol de usuario de la API de Document AI:

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

4. Crea las credenciales que se usarán para acceder con tu nueva cuenta de servicio y guárdalas en un archivo JSON llamado key.json en tu directorio de trabajo:

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

5. Configura la variable de entorno GOOGLE_APPLICATION_CREDENTIALS, que la biblioteca usa para encontrar tus credenciales, de forma que apunte al archivo de credenciales:

export GOOGLE_APPLICATION_CREDENTIALS="$PWD/key.json"

6. Verifica que la variable de entorno GOOGLE_APPLICATION_CREDENTIALS esté configurada en la ruta de acceso completa del archivo JSON de credenciales que creaste anteriormente:

echo $GOOGLE_APPLICATION_CREDENTIALS

La herramienta de línea de comandos de gcloud usa esta variable de entorno para especificar qué credenciales usar cuando se ejecutan comandos. Para leer más sobre esta forma de autenticación, consulta la Guía de credenciales predeterminadas de la aplicación.

Descarga el formulario de ejemplo en la instancia de VM

Ahora puedes descargar un formulario de ejemplo y, luego, codificarlo en Base64 para enviarlo a la API de Document AI.

1. Ingresa el siguiente comando en la ventana de SSH para descargar el formulario de ejemplo en tu directorio de trabajo:

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

2. Crea un archivo de solicitud JSON para enviar el formulario codificado en Base64 para su procesamiento:

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

Haz clic en Revisar mi progreso para verificar los objetivos.

Autenticar solicitudes a la API y descargar el formulario de ejemplo

Tarea 4: Realiza una solicitud síncrona de procesamiento de documento con curl

En esta tarea, procesarás el documento de ejemplo a través de una llamada al extremo síncrono de la API de Document AI con curl.

1. Envía un formulario para su procesamiento con curl. El resultado se almacenará en 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. Asegúrate de que tu archivo output.json tenga los resultados de la llamada a la API:

cat output.json Si recibes un error de autenticación, asegúrate de haber configurado la variable de entorno GOOGLE_APPLICATION_CREDENTIALS para que apunte al archivo JSON de credenciales que creaste anteriormente. Es posible que debas esperar unos minutos para que se propague la política de IAM, así que vuelve a intentarlo si recibes un error.

El token de acceso para la cuenta de servicio de Cloud IAM se genera sobre la marcha y se pasa a la API con el encabezado HTTP Authorization:. La respuesta contiene datos con formato JSON que se guardan en el archivo output.json.

Extrae las entidades del formulario

A continuación, explora parte de la información extraída del formulario de ejemplo.

1. Extrae el texto sin procesar detectado en el documento de la siguiente manera:

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

De esta forma, se enumeran todos los textos detectados en el documento subido.

2. Extrae la lista de campos de formulario detectados por el procesador de formularios:

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

Con este comando, se enumeran los datos de los objetos de todos los campos de formulario detectados en el documento. Los valores textAnchor.startIndex y textAnchor.endIndex de cada formulario se pueden usar para ubicar los nombres de los formularios detectados en el campo document.text. La secuencia de comandos de Python que usarás en la próxima tarea se encargará de realizar esta asignación.

El archivo JSON es bastante grande, ya que incluye el documento fuente codificado en Base64, así como todo el texto detectado y las propiedades del documento. Para explorar el archivo JSON, ábrelo en un editor de texto o usa una herramienta de consulta JSON como jq.

Verificar que la API de Document AI haya procesado un documento

Tarea 5: Prueba un procesador de formularios de Document AI con las bibliotecas cliente de Python

Realiza una llamada síncrona a la API de Document AI con las bibliotecas cliente de Python de Document AI.

Ahora procesarás un documento con el extremo síncrono. Para procesar grandes cantidades de documentos a la vez, puedes usar la API asíncrona. Para obtener más información sobre el uso de las APIs de Document AI, consulta la guía.

Si quieres ejecutar secuencias de comandos de Python directamente, debes proporcionar las credenciales adecuadas a esas secuencias de comandos para que puedan hacer llamadas a la API con una cuenta de servicio que se haya configurado con los permisos correctos. Para leer más sobre cómo configurar esta forma de autenticación, consulta la documentación Autenticación como cuenta de servicio.

Configura tu instancia de VM para usar el cliente de Python de Document AI

Ahora, instala las bibliotecas cliente de Google Cloud para Python en la instancia de VM.

1. Ingresa el siguiente comando en la shell de la terminal SSH para importar los archivos del lab a tu instancia de VM:

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

2. Ingresa el siguiente comando para instalar las bibliotecas cliente de Python necesarias para Document AI y las otras bibliotecas requeridas en este lab:

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

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

Revisa el código de Python de la API de Document AI

Tómate un minuto para revisar el código de Python en el archivo de ejemplo. Puedes usar un editor de tu elección, como vi o nano, para revisar el código en la sesión SSH o puedes usar el comando de la sección anterior para copiar el código de ejemplo en Cloud Shell y usar el editor de código para ver el código fuente si lo prefieres.

1. Los primeros dos bloques de código importan las bibliotecas necesarias y analizan los parámetros para inicializar las variables que identifican el procesador de Document AI y los datos 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. La función process_document 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 que requiere la llamada a la API se crea con los parámetros project_id,location y processor_id, y el documento que se procesará se lee y almacena en una estructura mime_type.

Luego, el nombre del procesador y el documento se pasan al objeto cliente de la API de Document y se realiza una llamada síncrona a la API. Si la solicitud es correcta, el objeto documento que se devuelve incluirá propiedades con los datos que detectó el procesador de Document AI.

def process_document(project_id, location, processor_id, file_path ): # Crea una instancia de un cliente client = documentai.DocumentProcessorServiceClient() # El nombre completo del recurso del procesador, p. ej.: # projects/project-id/locations/location/processor/processor-id # Primero, debes crear procesadores nuevos en la consola de Cloud name = f"projects/{project_id}/locations/{location}/processors/{processor_id}" # Lee el archivo en la memoria with open(file_path, "rb") as image: image_content = image.read() # Crea el objeto documento document = {"content": image_content, "mime_type": "application/pdf"} # Configura la solicitud de procesamiento request = {"name": name, "document": document} # Usa el extremo síncrono del cliente de Document AI para procesar la solicitud result = client.process_document(request=request) return result.document

3. Luego, la secuencia de comandos llama a la función process_document con los parámetros requeridos y guarda la respuesta en la variable document.

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

4. El último bloque de código imprime la propiedad .text que contiene todo el texto detectado en el documento y, luego, muestra la información del formulario con los datos de las anclas de texto para cada uno de los campos del formulario detectados por el analizador de formularios.

print("Document processing complete.") # imprime el texto sin procesar print("Text: \n{}\n".format(document.text)) # Define una función para recuperar un diccionario de objetos para un elemento designado def get_text(doc_element: dict, document: dict): """ Document AI identifica las etiquetas de formulario por sus offsets en el texto del documento. Esta función convierte los offsets en fragmentos de texto. """ response = "" # Si un segmento de texto abarca varias líneas, # se almacenará en 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 # Obtén cada par clave-valor y sus puntuaciones de confianza correspondientes. document_pages = document.pages print("Form data detected:\n") # Por cada página, recupera cada campo del formulario y muestra el nombre del campo, su valor y las puntuaciones de confianza 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")

Haz clic en Revisar mi progreso para verificar los objetivos.

Probar un procesador de formularios de Document AI

Tarea 6: Ejecuta el código de Document AI con Python

Ejecuta el código de muestra y procesa el mismo archivo que antes.

1. Crea variables de entorno para el ID del proyecto y el archivo de credenciales de la cuenta de servicio de IAM:

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

2. Llama al programa de Python synchronous_doc_ai.py con los parámetros que requiere:

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

Verás el siguiente bloque 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. Date: Sally Walker Name: 9/14/19 ...

El primer bloque de texto es un solo elemento de texto que contiene todo el texto del documento. Este bloque de texto no incluye ningún reconocimiento de datos basados en el formulario, por lo que algunos elementos, como las entradas Date y Name, se mezclan en este valor de texto sin procesar.

Luego, el código genera una vista más estructurada de los datos con los datos del formulario que infirió analizador-formularios de la estructura del documento. Esta salida estructurada también incluye la puntuación de confianza para los nombres y valores de los campos del formulario. El resultado de esta sección es una asignación mucho más útil entre los nombres de los campos del formulario y los valores, como se puede ver con el vínculo entre los campos del formulario Date y Name y sus valores correctos.

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

Haz clic en Revisar mi progreso para verificar los objetivos.

Ejecutar el código de Document AI con Python

¡Felicitaciones!

Usaste correctamente la API de Document AI para extraer datos de documentos con un procesador general de formularios. En este lab, creaste y probaste un procesador de Document AI con la consola y la línea de comandos, y realizaste llamadas síncronas a la API de Document AI con Python.

Próximos pasos y más información

• Obtén más información en la documentación de la API de Cloud Document AI.

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

Prueba más reciente del lab: 07 de diciembre de 2023

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