Procesar documentos con la función ML.PROCESS_DOCUMENT

En este documento se describe cómo usar la función ML.PROCESS_DOCUMENT con un modelo remoto para extraer información valiosa de documentos en una tabla de objetos.

Ubicaciones admitidas

Debes crear el modelo remoto que se usa en este procedimiento en la US o en la EU multirregión. Debes ejecutar la función ML.PROCESS_DOCUMENT en la misma región que el modelo remoto.

Roles obligatorios

Para crear un modelo remoto y procesar documentos, necesitas los siguientes roles de Gestión de Identidades y Accesos (IAM) a nivel de proyecto:

• Crear un procesador de documentos: editor de Document AI (roles/documentai.editor)
• Crear y usar conjuntos de datos, tablas y modelos de BigQuery: Editor de datos de BigQuery (roles/bigquery.dataEditor)

• Crear, delegar y usar conexiones de BigQuery: Administrador de conexión de BigQuery (roles/bigquery.connectionsAdmin)

  Si no tiene configurada una conexión predeterminada, puede crear una y definirla al ejecutar la instrucción CREATE MODEL. Para ello, debes tener el rol Administrador de BigQuery (roles/bigquery.admin) en tu proyecto. Para obtener más información, consulta Configurar la conexión predeterminada.

• Concede permisos a la cuenta de servicio de la conexión: administrador de gestión de identidades y accesos del proyecto (roles/resourcemanager.projectIamAdmin).

• Crear tareas de BigQuery: usuario de tareas de BigQuery (roles/bigquery.jobUser)

Estos roles predefinidos contienen los permisos necesarios para realizar las tareas descritas en este documento. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:

Permisos obligatorios

• Crea un conjunto de datos: bigquery.datasets.create
• Crear, delegar y usar una conexión: bigquery.connections.*
• Define los permisos de la cuenta de servicio: resourcemanager.projects.getIamPolicy y resourcemanager.projects.setIamPolicy
• Crea un modelo y ejecuta la inferencia:
  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata
• Crea una tabla de objetos: bigquery.tables.create y bigquery.tables.update
• Crea un procesador de documentos:
  • documentai.processors.create
  • documentai.processors.update
  • documentai.processors.delete

También puedes obtener estos permisos con roles personalizados u otros roles predefinidos.

Antes de empezar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery, BigQuery Connection API, and Document AI APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery, BigQuery Connection API, and Document AI APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Crear un procesador

Crea un procesador en Document AI para procesar los documentos. El procesador debe ser de un tipo admitido.

Crear conjunto de datos

Debes crear el conjunto de datos, la conexión y el procesador de documentos en la misma región.

Crea un conjunto de datos de BigQuery para que contenga tus recursos:

Consola

1. En la Google Cloud consola, ve a la página BigQuery.

   Ir a la página de BigQuery

2. En el panel Explorador, haz clic en el nombre de tu proyecto.

3. Haz clic en Ver acciones > Crear conjunto de datos.

4. En la página Crear conjunto de datos, haz lo siguiente:

   • En ID del conjunto de datos, escribe un nombre para el conjunto de datos.

   • En Tipo de ubicación, seleccione una ubicación para el conjunto de datos.

   • Haz clic en Crear conjunto de datos.

bq

1. Para crear un conjunto de datos, usa el comando bq mk con la marca --location:

   bq --location=LOCATION mk -d DATASET_ID

   Haz los cambios siguientes:

   • LOCATION: la ubicación del conjunto de datos.
   • DATASET_ID es el ID del conjunto de datos que vas a crear.

2. Confirma que se ha creado el conjunto de datos:

   bq ls

Crear una conexión

Puedes saltarte este paso si tienes una conexión predeterminada configurada o si tienes el rol Administrador de BigQuery.

Crea una conexión de recursos de Cloud para que la use el modelo remoto y obtén la cuenta de servicio de la conexión. Crea la conexión en la misma ubicación que el conjunto de datos que has creado en el paso anterior.

Selecciona una de las opciones siguientes:

Consola

1. Ve a la página BigQuery.

   Ir a BigQuery

2. En el panel Explorador, haga clic en Añadir datos:

   

   Se abrirá el cuadro de diálogo Añadir datos.

3. En el panel Filtrar por, en la sección Tipo de fuente de datos, selecciona Aplicaciones empresariales.

   También puede introducir Vertex AI en el campo Buscar fuentes de datos.

4. En la sección Fuentes de datos destacadas, haga clic en Vertex AI.

5. Haz clic en la tarjeta de solución Modelos de Vertex AI: federación de BigQuery.

6. En la lista Tipo de conexión, selecciona Modelos remotos, funciones remotas y BigLake (recurso de Cloud) de Vertex AI.

7. En el campo ID de conexión, introduce un nombre para la conexión.

8. Haga clic en Crear conexión.

9. Haz clic en Ir a la conexión.

10. En el panel Información de conexión, copia el ID de la cuenta de servicio para usarlo en un paso posterior.

bq

1. En un entorno de línea de comandos, crea una conexión:

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID

   El parámetro --project_id anula el proyecto predeterminado.

   Haz los cambios siguientes:

   • REGION: tu región de conexión
   • PROJECT_ID: tu ID de proyecto Google Cloud
   • CONNECTION_ID: un ID para tu conexión

   Cuando creas un recurso de conexión, BigQuery crea una cuenta de servicio del sistema única y la asocia a la conexión.

   Solución de problemas: si aparece el siguiente error de conexión, actualiza el SDK de Google Cloud:

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. Obtén y copia el ID de la cuenta de servicio para usarlo en un paso posterior:

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   El resultado debería ser similar al siguiente:

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "[e-mail]"}
   

Terraform

Usa el recurso google_bigquery_connection.

Nota: Para crear objetos de BigQuery con Terraform, debes habilitar la API Cloud Resource Manager.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configurar la autenticación para bibliotecas de cliente.

En el siguiente ejemplo se crea una conexión de recursos de Cloud llamada my_cloud_resource_connection en la región US:

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Para aplicar la configuración de Terraform en un proyecto, sigue los pasos que se indican en las siguientes secciones. Google Cloud

Preparar Cloud Shell

1. Abre Cloud Shell.

2. Define el Google Cloud proyecto Google Cloud predeterminado en el que quieras aplicar tus configuraciones de Terraform.

   Solo tiene que ejecutar este comando una vez por proyecto y puede hacerlo en cualquier directorio.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Las variables de entorno se anulan si defines valores explícitos en el archivo de configuración de Terraform.

Preparar el directorio

Cada archivo de configuración de Terraform debe tener su propio directorio (también llamado módulo raíz).

1. En Cloud Shell, crea un directorio y un archivo nuevo en ese directorio. El nombre del archivo debe tener la extensión .tf. Por ejemplo, main.tf. En este tutorial, nos referiremos al archivo como main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Si estás siguiendo un tutorial, puedes copiar el código de ejemplo de cada sección o paso.

   Copia el código de ejemplo en el archivo main.tf que acabas de crear.

   También puedes copiar el código de GitHub. Se recomienda cuando el fragmento de Terraform forma parte de una solución integral.

3. Revisa y modifica los parámetros de ejemplo para aplicarlos a tu entorno.
4. Guarda los cambios.
5. Inicializa Terraform. Solo tienes que hacerlo una vez por directorio.

   terraform init

   Si quieres usar la versión más reciente del proveedor de Google, incluye la opción -upgrade:

   terraform init -upgrade

Aplica los cambios

1. Revisa la configuración y comprueba que los recursos que va a crear o actualizar Terraform se ajustan a tus expectativas:

   terraform plan

   Haga las correcciones necesarias en la configuración.

2. Aplica la configuración de Terraform ejecutando el siguiente comando e introduciendo yes en la petición:

   terraform apply

   Espera hasta que Terraform muestre el mensaje "Apply complete!".

3. Abre tu Google Cloud proyecto para ver los resultados. En la Google Cloud consola, ve a tus recursos en la interfaz de usuario para asegurarte de que Terraform los ha creado o actualizado.

Nota: Los ejemplos de Terraform suelen presuponer que las APIs necesarias están habilitadas en tu proyecto. Google Cloud

Conceder acceso a la cuenta de servicio

Selecciona una de las opciones siguientes:

Consola

1. Ve a la página IAM y administración.

   Ir a IAM y administración

2. Haz clic en Conceder acceso.

   Se abrirá el cuadro de diálogo Añadir principales.

3. En el campo Nuevos principales, introduce el ID de la cuenta de servicio que has copiado anteriormente.

4. En el campo Selecciona un rol, elige Document AI y, a continuación, Lector de Document AI.

5. Haz clic en Añadir otro rol.

6. En el campo Selecciona un rol, elige Cloud Storage y, a continuación, Visor de objetos de Storage.

7. Haz clic en Guardar.

gcloud

Usa el comando gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/documentai.viewer' --condition=None
gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/storage.objectViewer' --condition=None

Haz los cambios siguientes:

• PROJECT_NUMBER: tu número de proyecto.
• MEMBER: el ID de la cuenta de servicio que has copiado anteriormente.

Si no se concede el permiso, se producirá un error Permission denied.

Nota: Si creas el procesador en un proyecto distinto del segmento de Cloud Storage que usa la tabla de objetos, asigna los siguientes roles de Gestión de Identidades y Accesos (IAM) a la cuenta de servicio:

• Asigna a la cuenta de servicio el rol Lector de Document AI en el proyecto que contiene el procesador.
• Asigna a la cuenta de servicio el rol Lector de objetos de almacenamiento en el proyecto que contiene el segmento de Cloud Storage.

Crear un modelo

Crea un modelo remoto con un REMOTE_SERVICE_TYPE de CLOUD_AI_DOCUMENT_V1:

CREATE OR REPLACE MODEL
`PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
OPTIONS (
  REMOTE_SERVICE_TYPE = 'CLOUD_AI_DOCUMENT_V1',
  DOCUMENT_PROCESSOR = 'PROCESSOR_ID'
);

Haz los cambios siguientes:

• PROJECT_ID: tu ID de proyecto.
• DATASET_ID: ID del conjunto de datos que contendrá el modelo.
• MODEL_NAME: el nombre del modelo.
• REGION: la región que usa la conexión.
• CONNECTION_ID: el ID de la conexión. Por ejemplo, myconnection.

  Cuando consultas los detalles de la conexión en la consola de Google Cloud , el ID de conexión es el valor de la última sección del ID de conexión completo que se muestra en ID de conexión. Por ejemplo, projects/myproject/locations/connection_location/connections/myconnection.

• PROCESSOR_ID: el ID del procesador de documentos. Para encontrar este valor, consulta los detalles del procesador y, a continuación, busca la fila ID en la sección Información básica.
Importante: Debe especificar el ID del proyecto de la conexión aunque la conexión esté en el proyecto predeterminado.

Para ver las columnas de salida del modelo, haz clic en Ir al modelo en el resultado de la consulta después de crear el modelo. Las columnas de salida se muestran en la sección Etiquetas de la pestaña Esquema.

Crear una tabla de objetos

Crea una tabla de objetos sobre un conjunto de documentos de Cloud Storage. Los documentos de la tabla de objetos deben ser de un tipo admitido.

Procesar documentos

Procesa todos los documentos con ML.PROCESS_DOCUMENT:

SELECT *
FROM ML.PROCESS_DOCUMENT(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE `PROJECT_ID.DATASET_ID.OBJECT_TABLE_NAME`
  [, PROCESS_OPTIONS => ( JSON 'PROCESS_OPTIONS')]
);

Haz los cambios siguientes:

• PROJECT_ID: tu ID de proyecto.
• DATASET_ID: el ID del conjunto de datos que contiene el modelo.
• MODEL_NAME: el nombre del modelo.
• OBJECT_TABLE_NAME: el nombre de la tabla de objetos que contiene los URIs de los documentos que se van a procesar.
• PROCESS_OPTIONS: la configuración JSON que especifica cómo procesar los documentos. Por ejemplo, se usa para especificar la fragmentación de documentos para el analizador de diseño.

También puedes procesar algunos de los documentos con ML.PROCESS_DOCUMENT:

SELECT *
FROM ML.PROCESS_DOCUMENT(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  (SELECT *
  FROM `PROJECT_ID.DATASET_ID.OBJECT_TABLE_NAME`
  WHERE FILTERS
  LIMIT NUM_DOCUMENTS
  )
  [, PROCESS_OPTIONS => ( JSON 'PROCESS_OPTIONS')]
);

Haz los cambios siguientes:

• PROJECT_ID: tu ID de proyecto.
• DATASET_ID: el ID del conjunto de datos que contiene el modelo.
• MODEL_NAME: el nombre del modelo.
• OBJECT_TABLE_NAME: el nombre de la tabla de objetos que contiene los URIs de los documentos que se van a procesar.
• FILTERS: condiciones para filtrar los documentos que quieras procesar en las columnas de la tabla de objetos.
• NUM_DOCUMENTS: el número máximo de documentos que quieres procesar.
• PROCESS_OPTIONS: la configuración JSON que define la configuración, como la configuración de fragmentación del analizador de diseño.

Ejemplos

Ejemplo 1

En el siguiente ejemplo se usa el analizador de gastos para procesar los documentos representados por la tabla documents:

SELECT *
FROM ML.PROCESS_DOCUMENT(
  MODEL `myproject.mydataset.expense_parser`,
  TABLE `myproject.mydataset.documents`
);

Esta consulta devuelve los informes de gastos analizados, incluida la moneda, el importe total, la fecha del recibo y las líneas de pedido de los informes de gastos. La columna ml_process_document_result contiene el resultado sin procesar del analizador de gastos y la columna ml_process_document_status contiene los errores devueltos por el procesamiento del documento.

Ejemplo 2

En el siguiente ejemplo se muestra cómo filtrar la tabla de objetos para elegir qué documentos se van a procesar y, a continuación, escribir los resultados en una tabla nueva:

CREATE TABLE `myproject.mydataset.expense_details`
AS
SELECT uri, content_type, receipt_date, purchase_time, total_amount, currency
FROM
  ML.PROCESS_DOCUMENT(
    MODEL `myproject.mydataset.expense_parser`,
    (SELECT * FROM `myproject.mydataset.expense_reports`
    WHERE uri LIKE '%restaurant%'));

Siguientes pasos

• Para obtener más información sobre la inferencia de modelos en BigQuery ML, consulta el resumen de la inferencia de modelos.
• Para obtener más información sobre cómo usar las APIs de IA de Cloud para realizar tareas de IA, consulta el artículo Descripción general de las aplicaciones de IA.
• Para obtener más información sobre las instrucciones y funciones de SQL admitidas en los modelos de IA generativa, consulta Recorridos de usuario completos de los modelos de IA generativa.