GSP927

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 uso de los datos.

En este lab, crearás una canalización de procesamiento de documentos para analizar automáticamente los documentos subidos a Cloud Storage. La canalización usa una función de Cloud Run con un procesador de formularios de Document AI para extraer datos y almacenarlos en BigQuery. Si el formulario incluye campos de dirección, los datos de dirección se envían a un tema de Pub/Sub. Esto activa una segunda función de Cloud Run, que usa la API de Geocodificación para agregar coordenadas y escribe los resultados en BigQuery.

Esta canalización simple usa un procesador de formularios general para detectar datos de formulario básicos, como campos de dirección etiquetados. Para documentos más complejos, Document AI ofrece analizadores especializados (fuera del alcance de este lab) que extraen información detallada incluso sin etiquetas explícitas. Por ejemplo, el analizador de facturas puede identificar la dirección y los detalles del proveedor de una factura sin etiquetas, gracias a que comprende los diseños de factura más comunes.

La arquitectura general que crearás se verá de la siguiente manera:

1. Sube formularios con datos de dirección a Cloud Storage.
2. Esta carga activa una llamada a la función de Cloud Run para procesar los formularios.
3. Se llama a Document AI desde la función de Cloud Run.
4. Los datos JSON de Document AI se guardan de nuevo en Cloud Storage.
5. La función de Cloud Run escribe los datos de formulario en BigQuery.
6. La función de Cloud Run envía las direcciones a un tema de Pub/Sub.
7. El mensaje de Pub/Sub activa la función de Cloud Run para el procesamiento de geocodificación.
8. Se llama a la API de Geocoding desde la función de Cloud Run.
9. La función de Cloud Run escribe los datos de geocodificación en BigQuery.

Esta arquitectura de ejemplo usa funciones de Cloud Run para implementar una canalización simple, pero no se recomienda usar tales funciones en entornos de producción, ya que las llamadas a la API de Document AI pueden superar los tiempos de espera admitidos por esas funciones. Se recomienda usar Cloud Tasks para una solución sin servidores más sólida.

Qué aprenderás

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

• Habilitar la API de Document AI
• Implementar funciones de Cloud Run que usan las APIs de Document AI, BigQuery, Cloud Storage y Pub/Sub

Configurarás una función de Cloud Run para que haga lo siguiente:

• Se active al subir documentos a Cloud Storage.
• Use la biblioteca cliente de Document AI para Python.
• Se active al crear un mensaje de Pub/Sub.

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.

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 las APIs y crea una clave de API

Debes habilitar las APIs de Document AI, Cloud Run Functions, Cloud Build y Geocoding para este lab, y, luego, crear la clave de API que requiere la función de Cloud Run de geocodificación.

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

2. En Cloud Shell, ingresa los siguientes comandos para habilitar las APIs requeridas por el lab:

gcloud services enable documentai.googleapis.com gcloud services enable cloudfunctions.googleapis.com gcloud services enable cloudbuild.googleapis.com gcloud services enable geocoding-backend.googleapis.com

3. En la consola, abre el menú de navegación y haz clic en APIs y servicios > Credenciales.

4. Selecciona Crear credenciales y, luego, Clave de API en el menú desplegable.

Se mostrará la clave nueva en el cuadro de diálogo "Se creó la clave de API". Una clave de API es una cadena larga que contiene letras mayúsculas y minúsculas, números y guiones. Por ejemplo, a4db08b757294ea94c08f2df493465a1.

5. En Acciones, haz clic en los tres puntos. Luego, en el cuadro de diálogo, haz clic en Editar clave de API.

6. Selecciona Restringir clave en la sección Restricciones de API para agregar restricciones de API a tu nueva clave de API.

7. Haz clic en el menú desplegable Seleccionar APIs y, en el cuadro de filtro, escribe API de Geocoding.

8. Selecciona API de Geocoding y haz clic en Aceptar.

9. Haz clic en el botón Guardar.

Nota: Si no encuentras la API de Geocoding en la lista desplegable Restringir clave, actualiza la página para volver a cargar la lista de APIs disponibles. Verifica que todas las APIs necesarias estén habilitadas.

Tarea 2: Descarga el código fuente del lab

En esta tarea, copiarás los archivos fuente en Cloud Shell. Estos archivos incluyen el código fuente de las funciones de Cloud Run y los esquemas necesarios para las tablas de BigQuery que crearás en el lab.

1. En Cloud Shell, ingresa el siguiente comando para descargar el código fuente de este lab:

mkdir ./documentai-pipeline-demo gcloud storage cp -r \ gs://spls/gsp927/documentai-pipeline-demo/* \ ~/documentai-pipeline-demo/

Tarea 3: Crea un procesador de formularios

Crea una instancia del procesador de formularios genérico para usar en Document AI Platform con el analizador de formularios especializado de Document AI. Esta herramienta genérica procesará cualquier tipo de documento y extraerá todo el contenido de texto que pueda identificar allí. 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 tengan etiquetas de texto.

1. En la consola de Google Cloud, en la barra de búsqueda, escribe Document AI y haz clic en el resultado correspondiente a la página del producto.

2. Haz clic en Explorar procesadores y, luego, en Analizador de formularios para crear un procesador nuevo.

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

4. Haz clic en Crear para crear tu procesador.

Configurarás una función de Cloud Run más adelante en este lab con el ID y la ubicación de este procesador específico, de modo que la función lo use para procesar facturas de muestra.

Tarea 4: Crea buckets de Cloud Storage y un conjunto de datos de BigQuery

En esta sección, prepararás tu entorno creando los recursos de Google Cloud que se requieren para tu canalización de procesamiento de documentos.

Crea buckets de Cloud Storage de entrada, salida y archivo

Crea buckets de Cloud Storage de entrada, salida y archivo para tu canalización de procesamiento de documentos.

1. En Cloud Shell, ingresa el siguiente comando para crear los buckets de Cloud Storage del lab:

export PROJECT_ID=$(gcloud config get-value core/project) export BUCKET_LOCATION="{{{my_primary_project.default_region|REGION}}}" gsutil mb -c standard -l ${BUCKET_LOCATION} -b on \ gs://${PROJECT_ID}-input-invoices gsutil mb -c standard -l ${BUCKET_LOCATION} -b on \ gs://${PROJECT_ID}-output-invoices gsutil mb -c standard -l ${BUCKET_LOCATION} -b on \ gs://${PROJECT_ID}-archived-invoices

Crea un conjunto de datos y las tablas de BigQuery

Crea un conjunto de datos de BigQuery y las tres tablas de salida necesarias para tu canalización de procesamiento de datos.

1. En Cloud Shell, ingresa el siguiente comando para crear las tablas de BigQuery del lab:

bq --location="US" mk -d \ --description "Form Parser Results" \ ${PROJECT_ID}:invoice_parser_results cd ~/documentai-pipeline-demo/scripts/table-schema/ bq mk --table \ invoice_parser_results.doc_ai_extracted_entities \ doc_ai_extracted_entities.json bq mk --table \ invoice_parser_results.geocode_details \ geocode_details.json

Puedes navegar a BigQuery en la consola de Cloud y, con el espacio de trabajo de SQL de BigQuery, inspeccionar los esquemas de las tablas en el conjunto de datos invoice_parser_results.

Crea un tema de Pub/Sub

Inicializa el tema de Pub/Sub que se usa para activar las operaciones de enriquecimiento de datos de la API de Geocoding en la canalización de procesamiento.

1. En Cloud Shell, ingresa el siguiente comando para crear los temas de Pub/Sub del lab:

export GEO_CODE_REQUEST_PUBSUB_TOPIC=geocode_request gcloud pubsub topics \ create ${GEO_CODE_REQUEST_PUBSUB_TOPIC} Verifica que el conjunto de datos de BigQuery, los buckets de Cloud Storage y el tema de Pub/Sub se hayan creado correctamente.

Tarea 5: Crea funciones de Cloud Run

Crea las dos funciones de Cloud Run que tu canalización de procesamiento de datos usará para procesar facturas subidas a Cloud Storage. Estas funciones usan la API de Document AI para extraer datos de formulario de los documentos sin procesar y, luego, la API de Geocoding para recuperar datos de ubicación geográfica en relación con la información de direcciones extraída de los documentos.

Puedes examinar el código fuente de las dos funciones de Cloud Run con el editor de código o cualquier otro editor que elijas. Las funciones de Cloud Run se almacenan en las siguientes carpetas de Cloud Shell:

• Process Invoices: scripts/cloud-functions/process-invoices
• Geocode Addresses: scripts/cloud-functions/geocode-addresses

La función principal de Cloud Run, process-invoices, se activa cuando se suben archivos al bucket de almacenamiento de archivos de entrada que creaste anteriormente.

La carpeta de función scripts/cloud-functions/process-invoices contiene los dos archivos que se usan para crear la función process-invoices de Cloud Run.

En el archivo requirements.txt, se especifican las bibliotecas de Python que requiere la función. Esto incluye la biblioteca cliente de Document AI, así como las otras bibliotecas de Google Cloud que requiere el código de Python para leer los archivos de Cloud Storage, guardar los datos en BigQuery y escribir mensajes en Pub/Sub que activarán las funciones restantes en la canalización de la solución.

El archivo de Python main.py contiene el código de la función de Cloud Run que crea los clientes de API de Document AI, BigQuery y Pub/Sub, y las siguientes funciones internas para procesar los documentos:

• write_to_bq: Escribe un objeto de diccionario en la tabla de BigQuery. Ten en cuenta que debes asegurarte de que el esquema sea válido antes de llamar a esta función.
• get_text: Asigna anclas de texto de nombre y valor de formulario al texto escaneado en el documento. Esto permite que la función identifique elementos específicos de los formularios, como el nombre y la dirección del proveedor, y extraiga el valor pertinente. Un procesador especializado de Document AI proporciona esa información contextual directamente en la propiedad de entidades.
• process_invoice: Usa la API de cliente asíncrona de Document AI para leer y procesar archivos de Cloud Storage de la siguiente manera:
  • Crea una solicitud asíncrona para procesar los archivos que activaron la llamada a la función de Cloud Run.
  • Procesa los datos de formulario para extraer los campos de las facturas y almacena solo campos específicos en un diccionario que forma parte del esquema predefinido.
  • Publica mensajes de Pub/Sub para activar la función de Cloud Run de geocodificación con los datos de dirección del formulario extraídos del documento.
  • Escribe los datos de formulario en una tabla de BigQuery.
  • Borra los archivos intermedios (de salida) de la llamada asíncrona a la API de Document AI.
  • Copia los archivos de entrada en el bucket de archivo.
  • Borra los archivos de entrada procesados.

La función de Cloud Run process_invoices solo procesa los datos de formulario que se detectaron con los siguientes nombres de campos de formulario:

• input_file_name
• address
• supplier
• invoice_number
• purchase_order
• date
• due_date
• subtotal
• tax
• total

La otra función de Cloud Run, geocode-addresses, se activa cuando llega un nuevo mensaje a un tema de Pub/Sub y extrae sus datos de parámetros del mensaje de Pub/Sub.

Crea la función de Cloud Run para procesar los documentos subidos a Cloud Storage

Crea una función de Cloud Run que use un procesador de formularios de Document AI para analizar los documentos de formularios que se subieron a un bucket de Cloud Storage.

1. Ejecuta este comando para obtener la dirección de correo electrónico del agente de servicio de Cloud Storage del proyecto:

gcloud storage service-agent --project=$PROJECT_ID

2. Ejecuta el siguiente comando para otorgar los permisos necesarios a la cuenta de servicio de Cloud Storage:

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") gcloud iam service-accounts create "service-$PROJECT_NUMBER" \ --display-name "Cloud Storage Service Account" || true gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:service-$PROJECT_NUMBER@gs-project-accounts.iam.gserviceaccount.com" \ --role="roles/pubsub.publisher" gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:service-$PROJECT_NUMBER@gs-project-accounts.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountTokenCreator" Nota: Si la cuenta de servicio de Cloud Storage existe, puedes ignorar el error.

3. Crea la función de Cloud Run correspondiente al procesador de facturas:

cd ~/documentai-pipeline-demo/scripts export CLOUD_FUNCTION_LOCATION="{{{my_primary_project.default_region|REGION}}}" gcloud functions deploy process-invoices \ --no-gen2 \ --region=${CLOUD_FUNCTION_LOCATION} \ --entry-point=process_invoice \ --runtime=python39 \ --source=cloud-functions/process-invoices \ --timeout=400 \ --env-vars-file=cloud-functions/process-invoices/.env.yaml \ --trigger-resource=gs://${PROJECT_ID}-input-invoices \ --trigger-event=google.storage.object.finalize Nota: Si el comando falla con un error de permiso, espera un minuto y vuelve a intentarlo.

Crea la función de Cloud Run para buscar los datos de geocodificación de una dirección

Crea una función de Cloud Run que acepte datos de dirección de un mensaje de Pub/Sub y use la API de Geocoding para ubicar la dirección con precisión.

1. Crea la función de Cloud Run correspondiente a la geocodificación:

cd ~/documentai-pipeline-demo/scripts gcloud functions deploy geocode-addresses \ --no-gen2 \ --region=${CLOUD_FUNCTION_LOCATION} \ --entry-point=process_address \ --runtime=python39 \ --source=cloud-functions/geocode-addresses \ --timeout=60 \ --env-vars-file=cloud-functions/geocode-addresses/.env.yaml \ --trigger-topic=${GEO_CODE_REQUEST_PUBSUB_TOPIC}

Tarea 6: Edita las variables de entorno de las funciones de Cloud Run

En esta tarea, terminarás de configurar las funciones de Cloud Run editando las variables de entorno de cada función para reflejar los parámetros específicos de tu lab a través de la consola de Cloud.

Edita las variables de entorno para la función process-invoices de Cloud Run

Configura las variables de entorno de la función process-invoices de Cloud Run.

1. En la consola de Cloud, en la barra de búsqueda, escribe Cloud Run functions y haz clic en el resultado correspondiente a la página del producto.

Se te redireccionará a la consola de Cloud Run. Haz clic en Ir a Cloud Run Functions (1ª gen.) para ver las funciones process-invoices y geocode-addresses implementadas.

Nota: Si no puedes ver el vínculo Ir a Cloud Run Functions (1ª gen.), actualiza la consola de Cloud Run.

2. Haz clic en la función process-invoices de Cloud Run para abrir su página de administración.
3. Haz clic en Editar.
4. Haz clic en Configuración del entorno de ejecución, la compilación, las conexiones y la seguridad para expandir esa sección.
5. En Variables de entorno de ejecución, agrega la variable GCP_PROJECT y el valor para que coincida con el ID de tu proyecto.
6. En Variables de entorno de ejecución, actualiza el valor de PROCESSOR_ID para que coincida con el ID del procesador de facturas que creaste antes.
7. En Variables de entorno de ejecución, actualiza el valor de PARSER_LOCATION para que coincida con la región del procesador de facturas que creaste antes. Será us o eu. Este parámetro debe estar en minúsculas.
8. Haz clic en Siguiente, selecciona .env.yaml y, luego, vuelve a actualizar los valores de PROCESSOR_ID, PARSER_LOCATION y GCP_PROJECT para tu procesador de facturas.

9. Haz clic en Implementar.

Implementa la función process-invoices de Cloud Run.

Edita las variables de entorno para la función geocode-addresses de Cloud Run

Configura las variables de entorno de la función de Cloud Run correspondiente al enriquecimiento de datos de geocodificación.

1. Haz clic en la función geocode-addresses de Cloud Run para abrir su página de administración.
2. Haz clic en Editar.
3. Haz clic en Configuración del entorno de ejecución, la compilación, las conexiones y la seguridad para expandir esa sección.
4. En Variables de entorno de ejecución, actualiza el valor de API_key para que coincida con el valor de la clave de API que creaste en la tarea 1.
5. Haz clic en Siguiente, selecciona .env.yaml y, luego, actualiza el valor de API_key para que coincida con el valor de la clave de API que estableciste en el paso anterior.
6. Haz clic en Implementar.

Implementa la función geocode-addresses de Cloud Run.

Tarea 7: Prueba y valida la solución de extremo a extremo

Sube datos de prueba a Cloud Storage y supervisa el progreso de la canalización a medida que se procesan los documentos y se mejoran los datos extraídos.

1. En Cloud Shell, ingresa el siguiente comando para subir formularios de muestra al bucket de Cloud Storage que activará la función process-invoices de Cloud Run:

export PROJECT_ID=$(gcloud config get-value core/project) gsutil cp gs://spls/gsp927/documentai-pipeline-demo/sample-files/* gs://${PROJECT_ID}-input-invoices/

2. En la consola de Cloud, en la barra de búsqueda, escribe Cloud Run functions y haz clic en el resultado correspondiente a la página del producto.
3. Haz clic en la función process-invoices de Cloud Run para abrir su página de administración.
4. Haz clic en Registros (Logs).

Verás eventos relacionados con la creación de la función y las actualizaciones realizadas para configurar las variables de entorno, seguidos de eventos que muestran detalles sobre el archivo que se está procesando y los datos detectados por Document AI.

Mira los eventos hasta que veas un evento final que indique que la ejecución de la función terminó con LoadJob. Si se informan errores, verifica que los parámetros establecidos en el archivo .env.yaml de la sección anterior sean correctos. En particular, asegúrate de que el ID del procesador, la ubicación y el ID del proyecto sean válidos. La lista de eventos no se actualiza automáticamente.

Al final del procesamiento, tus tablas de BigQuery se completarán con las entidades extraídas de Document AI, así como con los datos enriquecidos proporcionados por la API de Geocoding si el procesador de Document AI detectó datos de dirección en el documento subido.

Cómo abrir la consola de BigQuery

1. En la consola de Google Cloud, selecciona el menú de navegación > BigQuery.

Se abrirá el cuadro de mensaje Te damos la bienvenida a BigQuery en la consola de Cloud. Este cuadro de mensaje contiene un vínculo a la guía de inicio rápido y las notas de la versión.

2. Haz clic en Listo.

Se abrirá la consola de BigQuery.

3. Expande tu ID del proyecto en el Explorador.

4. Expande invoice_parser_results.

5. Selecciona doc_ai_extracted_entities y haz clic en Vista previa.

Puedes ver la información del formulario extraída de las facturas por el procesador de facturas. Asimismo, puedes ver que se detectó la información de la dirección y el nombre del proveedor.

6. Selecciona geocode_details y haz clic en Vista previa.

Puedes ver la dirección con formato, la latitud y la longitud de cada factura procesada que contenía datos de dirección que Document AI pudo extraer.

Verifica que la canalización de extremo a extremo haya procesado los datos de formulario y dirección.

¡Felicitaciones!

Usaste correctamente la API de Document AI y otros servicios de Google Cloud para crear una canalización de procesamiento de facturas de extremo a extremo. En este lab, habilitaste la API de Document AI, implementaste funciones de Cloud Run que usan las APIs de Document AI, BigQuery, Cloud Storage y Pub/Sub, y configuraste una función de Cloud Run para que se active al subir documentos a Cloud Storage. También configuraste una función de Cloud Run para que use la biblioteca cliente de Document AI en Python y para que se active tras la creación de un mensaje de Pub/Sub.

Próximos pasos y más información

• Para leer más sobre esta forma de autenticación, 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: 26 de agosto de 2025

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

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.