GSP1139

Descripción general

Document AI es una solución de comprensión de documentos que toma datos no estructurados, como documentos, correos electrónicos, facturas y formularios, entre otros, y facilita la comprensión, el análisis y el consumo de los datos. La API proporciona una estructura a través de la clasificación de contenido, la extracción de entidades, la búsqueda avanzada y mucho más.

En este lab, aprenderás a usar el analizador de formularios de Document AI para analizar un formulario escrito a mano con Python. Usarás un formulario de admisión médica simple como ejemplo, pero este procedimiento funcionará con cualquier formulario generalizado compatible con DocAI.

Objetivos

En este lab, aprenderás a realizar las siguientes tareas:

• Extraer datos de un formulario escaneado con el analizador de formularios de Document AI
• Extraer pares clave-valor de un formulario con el analizador de formularios de Document AI
• Extraer y exportar datos CSV de un formulario con el analizador de formularios de Document AI

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 Document AI

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

1. Para abrir Cloud Shell, haz clic en el botón Activar Cloud Shell en la parte superior de la consola.

2. En Cloud Shell, ejecuta el siguiente comando para habilitar la API de Document AI.

gcloud services enable documentai.googleapis.com

Deberías ver algo como esto:

Operation "operations/..." finished successfully.

También deberás instalar Pandas, una biblioteca de análisis de datos de código abierto para Python.

3. Ejecuta el siguiente comando para instalar Pandas:

pip3 install --upgrade pandas

4. Ejecuta el siguiente comando para instalar las bibliotecas cliente de Python para Document AI.

pip3 install --upgrade google-cloud-documentai

Deberías ver algo como esto:

... Installing collected packages: google-cloud-documentai Successfully installed google-cloud-documentai-2.15.0

Ya está todo listo para usar la API de Document AI.

Haz clic en Revisar mi progreso para verificar el objetivo.

Habilitar la API de Document AI

Tarea 2: Crea un procesador de analizador de formularios

Primero debes crear una instancia de procesador del analizador de formularios para usarla en la plataforma de Document AI para este instructivo.

1. En la consola de Cloud, abre el menú de navegación (), haz clic en Ver todos los productos > Inteligencia Artificial > Document AI.

2. Haz clic en Explorar procesadores y, en General, haz clic en Form Parser para abrir la página Crear procesador.

3. Asígnale el nombre lab-form-parser y selecciona la región más cercana de la lista.

4. Haz clic en Crear para crear tu procesador.

5. Copia el ID del procesador. Debes usarlo en el código más adelante.

Haz clic en Revisar mi progreso para verificar el objetivo.

Crear un procesador

Prueba el procesador en la consola de Cloud

Para probar tu procesador en la consola, puedes subir un documento.

1. Haz clic con el botón derecho en la siguiente imagen y selecciona Guardar imagen como para descargar el formulario de muestra.

2. En la página Detalles del procesador, haz clic en Subir documento de prueba. Selecciona el formulario que acabas de descargar.

Tu procesador de Form Parser procesará el documento y devolverá los datos del formulario analizados. Debería verse algo similar a esto:

Tarea 3: Descarga el formulario de muestra

En esta sección, descargarás un documento de muestra que contiene un formulario simple de admisión médica.

1. Ejecuta el siguiente comando para descargar el formulario de muestra en Cloud Shell.

gcloud storage cp gs://cloud-samples-data/documentai/codelabs/form-parser/intake-form.pdf .

2. Confirma que el archivo se haya descargado a Cloud Shell con el siguiente comando:

ls intake-form.pdf

Tarea 4: Extrae los pares clave-valor del formulario

En esta sección, usarás la API de procesamiento en línea para llamar al procesador de Form Parser que creaste anteriormente. Luego, extraerás los pares clave-valor que se encuentran en el documento.

El procesamiento en línea se usa para enviar un solo documento y esperar la respuesta. También puedes usar el procesamiento por lotes si deseas enviar varios archivos o si el tamaño del archivo supera el límite de páginas del procesamiento en línea.

El código para realizar una solicitud de procesamiento es idéntico para todos los tipos de procesadores, con la excepción del ID del procesador. El objeto de respuesta Document contiene una lista de páginas del documento de entrada. Cada objeto page contiene una lista de campos de formulario y sus ubicaciones en el texto.

El siguiente código itera en cada página y extrae cada clave, valor y puntuación de confianza. Estos son datos estructurados que se pueden almacenar más fácilmente en bases de datos o en otras aplicaciones.

1. En Cloud Shell, crea un archivo llamado form_parser.py y pega el siguiente código en él:

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: """ Procesa un documento con la API de Document AI Online Processing. """ opts = {"api_endpoint": f"{location}-documentai.googleapis.com"} # Crea una instancia de un cliente documentai_client = documentai.DocumentProcessorServiceClient(client_options=opts) # El nombre de recurso completo del procesador, p. ej.: # projects/project-id/locations/location/processor/processor-id # Primero debes crear nuevos procesadores en la consola de Cloud resource_name = documentai_client.processor_path(project_id, location, processor_id) # Lee el archivo y guárdalo en la memoria with open(file_path, "rb") as image: image_content = image.read() # Carga los datos binarios en el objeto RawDocument de Document AI raw_document = documentai.RawDocument( content=image_content, mime_type=mime_type ) # Configura la solicitud de procesamiento request = documentai.ProcessRequest( name=resource_name, raw_document=raw_document ) # Usa el cliente de Document AI para procesar el formulario de muestra result = documentai_client.process_document(request=request) return result.document def trim_text(text: str): """ Quita los espacios adicionales del texto (en blanco, línea nueva, tabulación, etcétera.) """ return text.strip().replace("\n", " ") PROJECT_ID = "YOUR_PROJECT_ID" LOCATION = "YOUR_PROJECT_LOCATION" # El formato debe ser 'us' o 'eu' PROCESSOR_ID = "FORM_PARSER_ID" # Crea el procesador en la consola de Cloud # El archivo local en tu directorio de trabajo actual FILE_PATH = "form.pdf" # Consulta https://cloud.google.com/document-ai/docs/processors-list # para ver los tipos de archivos admitidos 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, ) names = [] name_confidence = [] values = [] value_confidence = [] for page in document.pages: for field in page.form_fields: # Obtén los nombres de campos extraídos names.append(trim_text(field.field_name.text_anchor.content)) # Confianza: Qué tan "seguro" está el modelo de que el texto es correcto name_confidence.append(field.field_name.confidence) values.append(trim_text(field.field_value.text_anchor.content)) value_confidence.append(field.field_value.confidence) # Crea un DataFrame de Pandas para imprimir los valores en formato tabular. df = pd.DataFrame( { "Field Name": names, "Field Name Confidence": name_confidence, "Field Value": values, "Field Value Confidence": value_confidence, } ) print(df)

2. Reemplaza YOUR_PROJECT_ID, YOUR_PROJECT_LOCATION, YOUR_PROCESSOR_ID y FILE_PATH por los valores adecuados para tu entorno.

Ten en cuenta que FILE_PATH es el nombre del archivo que descargaste en Cloud Shell en el paso anterior. Si no cambiaste el nombre del archivo, debería ser intake-form.pdf, que deberás actualizar en el código.

3. Usa el siguiente comando para ejecutar la secuencia de comandos:

python3 form_parser.py

Deberías ver el siguiente resultado:

Field Name Field Name Confidence Field Value Field Value Confidence 0 Phone #: 0.999982 (906) 917-3486 0.999982 1 Emergency Contact: 0.999972 Eva Walker 0.999972 2 Marital Status: 0.999951 Single 0.999951 3 Gender: 0.999933 F 0.999933 4 Occupation: 0.999914 Software Engineer 0.999914 5 Referred By: 0.999862 None 0.999862 6 Date: 0.999858 9/14/19 0.999858 7 DOB: 0.999716 09/04/1986 0.999716 8 Address: 0.999147 24 Barney Lane 0.999147 9 City: 0.997718 Towaco 0.997718 10 Name: 0.997345 Sally Walker 0.997345 11 State: 0.996944 NJ 0.996944 ...

Tarea 5: Analiza tablas

El analizador de formularios también puede extraer datos de tablas dentro de documentos. En esta sección, descargarás un nuevo documento de muestra y extraerás datos de la tabla. Dado que cargarás los datos en Pandas, se pueden guardar en un archivo CSV y en muchos otros formatos con una sola llamada de método.

Descarga el formulario de muestra con tablas

Tenemos un documento de muestra que contiene un formulario y una tabla de muestra.

1. Ejecuta el siguiente comando para descargar el formulario de muestra en Cloud Shell.

gcloud storage cp gs://cloud-samples-data/documentai/codelabs/form-parser/form_with_tables.pdf .

2. Confirma que el archivo se haya descargado a Cloud Shell con el siguiente comando:

ls form_with_tables.pdf

Extrae datos de tablas

La solicitud de procesamiento de datos de tablas es exactamente la misma que la de extracción de pares clave-valor. La diferencia radica en los campos de los que extraes los datos en la respuesta. Los datos de la tabla se almacenan en el campo pages[].tables[].

En este ejemplo, se extrae información de las filas de encabezado y de cuerpo de cada tabla y página, luego se imprime la tabla y se guarda como un archivo CSV.

1. Crea un archivo llamado table_parsing.py y pega el siguiente código en él:

# type: ignore[1] """ Usa el procesamiento en línea de Document AI para llamar un procesador de analizador de formularios. Extrae las tablas y los datos en el documento. """ from os.path import splitext from typing import List, Sequence import pandas as pd from google.cloud import documentai def online_process( project_id: str, location: str, processor_id: str, file_path: str, mime_type: str, ) -> documentai.Document: """ Procesa un documento con la API de Document AI Online Processing. """ opts = {"api_endpoint": f"{location}-documentai.googleapis.com"} # Crea una instancia de un cliente documentai_client = documentai.DocumentProcessorServiceClient(client_options=opts) # El nombre de recurso completo del procesador, p. ej.: # projects/project-id/locations/location/processor/processor-id # Primero debes crear nuevos procesadores en la consola de Cloud resource_name = documentai_client.processor_path(project_id, location, processor_id) # Lee el archivo y guárdalo en la memoria with open(file_path, "rb") as image: image_content = image.read() # Carga los datos binarios en el objeto RawDocument de Document AI raw_document = documentai.RawDocument( content=image_content, mime_type=mime_type ) # Configura la solicitud de procesamiento request = documentai.ProcessRequest( name=resource_name, raw_document=raw_document ) # Usa el cliente de Document AI para procesar el formulario de muestra result = documentai_client.process_document(request=request) return result.document def get_table_data( rows: Sequence[documentai.Document.Page.Table.TableRow], text: str ) -> List[List[str]]: """ Obtén datos de texto de las filas de la tabla """ all_values: List[List[str]] = [] for row in rows: current_row_values: List[str] = [] for cell in row.cells: current_row_values.append( text_anchor_to_text(cell.layout.text_anchor, text) ) all_values.append(current_row_values) return all_values def text_anchor_to_text(text_anchor: documentai.Document.TextAnchor, text: str) -> str: """ Document AI identifica los datos de la tabla según las posiciones de todo el texto en el documento. Esta función convierte las posiciones en una cadena. """ response = "" # Si un segmento de texto abarca varias líneas, # se almacenará en diferentes segmentos de texto. for segment in text_anchor.text_segments: start_index = int(segment.start_index) end_index = int(segment.end_index) response += text[start_index:end_index] return response.strip().replace("\n", " ") PROJECT_ID = "YOUR_PROJECT_ID" LOCATION = "YOUR_PROJECT_LOCATION" # El formato debe ser 'us' o 'eu' PROCESSOR_ID = "FORM_PARSER_ID" # Crea el procesador antes de ejecutar la muestra # El archivo local en tu directorio de trabajo actual FILE_PATH = "form_with_tables.pdf" # Consulta https://cloud.google.com/document-ai/docs/file-types # para ver los tipos de archivos admitidos 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, ) header_row_values: List[List[str]] = [] body_row_values: List[List[str]] = [] # Ingresa el nombre de archivo sin la extensión output_file_prefix = splitext(FILE_PATH)[0] for page in document.pages: for index, table in enumerate(page.tables): header_row_values = get_table_data(table.header_rows, document.text) body_row_values = get_table_data(table.body_rows, document.text) # Crea un DataFrame de Pandas para imprimir los valores en formato tabular. df = pd.DataFrame( data=body_row_values, columns=pd.MultiIndex.from_arrays(header_row_values), ) print(f"Page {page.page_number} - Table {index}") print(df) # Guarda cada tabla como un archivo CSV output_filename = f"{output_file_prefix}_pg{page.page_number}_tb{index}.csv" df.to_csv(output_filename, index=False)

2. Reemplaza YOUR_PROJECT_ID, YOUR_PROJECT_LOCATION, YOUR_PROCESSOR_ID y FILE_PATH por los valores adecuados para tu entorno.

Ten en cuenta que FILE_PATH es el nombre del archivo que descargaste en Cloud Shell en el paso anterior. Si no cambiaste el nombre del archivo, debería ser form_with_tables.pdf, que es el valor predeterminado y no es necesario cambiarlo.

3. Usa el siguiente comando para ejecutar la secuencia de comandos:

python3 table_parsing.py

Deberías ver el siguiente resultado:

Page 1 - Table 0 Item Description 0 Item 1 Description 1 1 Item 2 Description 2 2 Item 3 Description 3

También deberías tener un nuevo archivo CSV en el directorio desde el que ejecutas el código.

4. Ejecuta el siguiente comando para generar una lista de los archivos en tu directorio de trabajo actual:

ls

Deberías ver el siguiente resultado:

form_with_tables_pg1_tb0.csv

¡Felicitaciones!

Felicitaciones, en este lab usaste correctamente la API de Document AI para extraer datos de un formulario escrito a mano. También aprendiste a usar la biblioteca cliente de Python de Document AI para extraer pares clave-valor de un formulario y datos tabulares de un formulario con tablas.

Próximos pasos y más información

Consulta los siguientes recursos para obtener más información sobre Document AI y la biblioteca cliente de Python:

• Documentación de Document AI
• Biblioteca cliente de Python para Document AI
• Muestras de 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: 21 de julio de 2025

Prueba más reciente del lab: 21 de julio de 2025

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