Se usó la API de Cloud Translation para traducir esta página.

Crear conjunto de datos

Se requiere un conjunto de datos etiquetados de documentos para entrenar, enriquecer o evaluar una versión del procesador.

En esta página, se describe cómo crear un conjunto de datos, importar documentos y definir un esquema. Para etiquetar los documentos importados, consulta Etiqueta documentos.

En esta página, se da por sentado que ya creaste un procesador que admita el entrenamiento, el enriquecimiento o la evaluación. Si tu procesador es compatible, verás la pestaña Entrenar en la consola de Google Cloud.

Opciones de almacenamiento de conjuntos de datos

Puedes elegir entre dos opciones para guardar tu conjunto de datos:

Google-managed
Cloud Storage de ubicación personalizada

A menos que tengas requisitos especiales (por ejemplo, para mantener documentos en un conjunto de carpetas habilitadas para CMEK), te recomendamos la opción de almacenamiento administrada por Google más simple. Una vez creada, la opción de almacenamiento del conjunto de datos no se puede cambiar para el procesador.

La carpeta o subcarpeta de una ubicación personalizada de Cloud Storage debe comenzar vacía y tratarse como de solo lectura. Cualquier cambio manual en su contenido podría hacer que el conjunto de datos sea inutilizable, lo que podría provocar su pérdida. La opción de almacenamiento administrado por Google no tiene este riesgo.

Sigue estos pasos para aprovisionar tu ubicación de almacenamiento.

Almacenamiento administrado por Google (recomendado)

Muestra opciones avanzadas cuando creas un procesador nuevo.
Mantén la opción predeterminada del grupo de opciones de almacenamiento administrado por Google.
Seleccione Crear.
Confirma que el conjunto de datos se haya creado correctamente y que su ubicación sea una ubicación administrada por Google.

Opción de almacenamiento personalizado

Activa o desactiva las opciones avanzadas.
Selecciona Especificaré mi propia ubicación de almacenamiento.
Elige una carpeta de Cloud Storage en el componente de entrada.
Seleccione Crear.

Operaciones de la API de Dataset

En este ejemplo, se muestra cómo usar el método processors.updateDataset para crear un conjunto de datos. Un recurso de conjunto de datos es un recurso singleton en un procesador, lo que significa que no hay una RPC de creación de recursos. En su lugar, puedes usar la RPC de updateDataset para establecer las preferencias. Document AI proporciona una opción para almacenar los documentos del conjunto de datos en un bucket de Cloud Storage que proporciones o para que Google los administre automáticamente.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

LOCATION: Your processor location
PROJECT_ID: Your Google Cloud project ID
PROCESSOR_ID The ID of your custom processor
GCS_URI: Your Cloud Storage URI where dataset documents are stored

Bucket proporcionado

Sigue los pasos que se indican a continuación para crear una solicitud de conjunto de datos con un bucket de Cloud Storage que proporciones.

Método HTTP

PATCH https://LOCATION-documentai.googleapis.com/v1beta3/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset

JSON de la solicitud:

  {
      "name":"projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset"
      "gcs_managed_config" {
          "gcs_prefix" {
              "gcs_uri_prefix": "GCS_URI"
          }
      }
      "spanner_indexing_config" {}
  }

Administrado por Google

Si deseas crear el conjunto de datos que administra Google, actualiza la siguiente información:

Método HTTP

PATCH https://LOCATION-documentai.googleapis.com/v1beta3/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset

JSON de la solicitud:

  {
      "name":"projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset"
      "unmanaged_dataset_config": {}
      "spanner_indexing_config": {}
  }

Para enviar tu solicitud, puedes usar Curl:

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el siguiente comando:

CURL

  curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth 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/dataset"

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

  {
      "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"
  }

Importar documentos

Un conjunto de datos recién creado está vacío. Para agregar documentos, selecciona Importar documentos y elige una o más carpetas de Cloud Storage que contengan los documentos que deseas agregar a tu conjunto de datos.

Si tu cuenta de Cloud Storage está en un proyecto de Google Cloud diferente, asegúrate de otorgar acceso para que Document AI pueda leer archivos desde esa ubicación. Específicamente, debes otorgar el rol de Visualizador de objetos de almacenamiento al agente de servicio principal de Document AI service-{project-id}@gcp-sa-prod-dai-core.iam.gserviceaccount.com. Para obtener más información, consulta Agentes de servicio.

create-dataset-8

Luego, elige una de las siguientes opciones de tareas:

Entrenamiento: Asigna al conjunto de entrenamiento.
Prueba: Asigna al conjunto de pruebas.
División automática: Mezcla aleatoriamente los documentos en el conjunto de entrenamiento y de prueba.
Sin asignar: No se usa en el entrenamiento ni la evaluación. Puedes asignarlos manualmente más adelante.

Puedes modificar las tareas más adelante.

Cuando seleccionas Importar, Document AI importa todos los tipos de archivos compatibles, así como los archivos JSON Document al conjunto de datos. En el caso de los archivos JSON Document, Document AI importa el documento y convierte su entities en instancias de etiqueta.

Document AI no modifica la carpeta de importación ni lee desde la carpeta después de que se completa la importación.

Selecciona Actividad en la parte superior de la página para abrir el panel Actividad, en el que se enumeran los archivos que se importaron correctamente, así como los que no se pudieron importar.

Si ya tienes una versión existente del procesador, puedes seleccionar la casilla de verificación Importar con etiquetado automático en el diálogo Importar documentos. Los documentos se etiquetan automáticamente con el procesador anterior cuando se importan. No puedes entrenar ni actualizar el entrenamiento en documentos etiquetados automáticamente, ni usarlos en el conjunto de pruebas, sin marcarlos como etiquetados. Después de importar documentos etiquetados automáticamente, revisa y corrige los documentos etiquetados automáticamente de forma manual. Luego, selecciona Guardar para guardar las correcciones y marcar el documento como etiquetado. Luego, puedes asignar los documentos según corresponda. Consulta Etiquetado automático.

RPC de Import documents

En esta muestra, se muestra cómo usar el método dataset.importDocuments para importar documentos al conjunto de datos.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

LOCATION: Your processor location
PROJECT_ID: Your Google Cloud project ID
PROCESSOR_ID: The ID of your custom processor
GCS_URI: Your Cloud Storage URI where dataset documents are stored
DATASET_TYPE: The dataset type to which you want to add documents. The value should be either `DATASET_SPLIT_TRAIN` or `DATASET_SPLIT_TEST`.
TRAINING_SPLIT_RATIO: The ratio of documents which you want to autoassign to the training set.

Conjunto de datos de entrenamiento o prueba

Si quieres agregar documentos al conjunto de datos de entrenamiento o de prueba, haz lo siguiente:

Método HTTP

POST https://LOCATION-documentai.googleapis.com/v1beta3/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset/importDocuments

JSON de la solicitud:

  {
      "batch_documents_import_configs": {
          "dataset_split": DATASET_TYPE
          "batch_input_config": {
          "gcs_prefix": {
              "gcs_uri_prefix": GCS_URI
          }
          }
      }
  }

Conjunto de datos de entrenamiento y prueba

Si deseas dividir automáticamente los documentos entre el conjunto de datos de entrenamiento y el de prueba, haz lo siguiente:

Método HTTP

POST https://LOCATION-documentai.googleapis.com/v1beta3/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset/importDocuments

JSON de la solicitud:

  {
      "batch_documents_import_configs": {
          "auto_split_config": {
          "training_split_ratio": TRAINING_SPLIT_RATIO
          },
          "batch_input_config": {
          "gcs_prefix": {
              "gcs_uri_prefix": "gs://test_sbindal/pdfs-1-page/"
          }
          }
      }
  }

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

CURL

  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth 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/dataset/importDocuments"

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

  {
      "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"
  }

RPC de Delete documents

En esta muestra, se muestra cómo usar el método dataset.batchDeleteDocuments para borrar documentos del conjunto de datos.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

LOCATION: Your processor location
PROJECT_ID: Your Google Cloud project ID
PROCESSOR_ID: The ID of your custom processor
DOCUMENT_ID: The document ID blob returned by <code>ImportDocuments</code> request

Borra documentos

Método HTTP

  POST https://LOCATION-documentai.googleapis.com/v1beta3/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset/batchDeleteDocuments

JSON de la solicitud:

  {
  "dataset_documents": {
      "individual_document_ids": {
      "document_ids": DOCUMENT_ID
      }
      }
  }

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

CURL

  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth 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/dataset/batchDeleteDocuments"

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

  {
      "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"
  }

Asigna documentos al conjunto de entrenamiento o de pruebas

En División de datos, selecciona los documentos y asígnales el conjunto de entrenamiento, el conjunto de pruebas o no asignados.

create-dataset-9

Prácticas recomendadas para el conjunto de pruebas

La calidad de tu conjunto de pruebas determina la calidad de tu evaluación.

El conjunto de pruebas debe crearse al comienzo del ciclo de desarrollo del procesador y bloquearse para que puedas hacer un seguimiento de la calidad del procesador a lo largo del tiempo.

Recomendamos al menos 100 documentos por tipo de documento para el conjunto de prueba. Es fundamental asegurarse de que el conjunto de prueba sea representativo de los tipos de documentos que los clientes usan para el modelo que se está desarrollando.

El conjunto de pruebas debe ser representativo del tráfico de producción en términos de frecuencia. Por ejemplo, si procesas formularios W2 y esperas que el 70% sea del año 2020 y el 30% del año 2019, aproximadamente el 70% del conjunto de pruebas debe consistir en documentos W2 del 2020. Esta composición del conjunto de pruebas garantiza que se le dé la importancia adecuada a cada subtipo de documento cuando se evalúa el rendimiento del procesador. Además, si extraes nombres de personas de formularios internacionales, asegúrate de que tu conjunto de prueba incluya formularios de todos los países de segmentación.

Prácticas recomendadas para el conjunto de entrenamiento

Los documentos que ya se incluyeron en el conjunto de prueba no deben incluirse en el conjunto de entrenamiento.

A diferencia del conjunto de prueba, el conjunto de entrenamiento final no tiene que ser tan representativo del uso del cliente en términos de diversidad o frecuencia de documentos. Algunas etiquetas son más difíciles de entrenar que otras. Por lo tanto, si sesgas el conjunto de entrenamiento hacia esas etiquetas, podrías obtener un mejor rendimiento.

Al principio, no hay una buena manera de saber qué etiquetas son difíciles. Debes comenzar con un conjunto de entrenamiento inicial pequeño y muestreado de forma aleatoria con el mismo enfoque que se describe para el conjunto de prueba. Este conjunto de entrenamiento inicial debe contener aproximadamente el 10% de la cantidad total de documentos que planeas anotar. Luego, puedes evaluar de forma iterativa la calidad del procesador (buscando patrones de error específicos) y agregar más datos de entrenamiento.

Define el esquema del procesador

Después de crear un conjunto de datos, puedes definir un esquema del procesador antes o después de importar documentos.

El schema del procesador define las etiquetas, como el nombre y la dirección, para extraer de tus documentos.

Selecciona Editar esquema y, luego, crea, edita, habilita y desactiva las etiquetas según sea necesario.

Asegúrate de seleccionar Guardar cuando termines.

create-dataset-10

Notas sobre la administración de etiquetas de esquemas:

Una vez que se crea una etiqueta de esquema, no se puede editar su nombre.
Una etiqueta de esquema solo se puede editar o borrar cuando no hay versiones de procesadores entrenadas. Solo se pueden editar el tipo de datos y el tipo de ocurrencia.
Inhabilitar una etiqueta tampoco afecta la predicción. Cuando envías una solicitud de procesamiento, la versión del procesador extrae todas las etiquetas que estaban activas en el momento del entrenamiento.

Cómo obtener el esquema de datos

En esta muestra, se muestra cómo usar el conjunto de datos. getDatasetSchema para obtener el esquema actual. DatasetSchema es un recurso singleton, que se crea automáticamente cuando creas un recurso de conjunto de datos.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

LOCATION: Your processor location
PROJECT_ID: Your Google Cloud project ID
PROCESSOR_ID: The ID of your custom processor

Cómo obtener el esquema de datos

Método HTTP

GET https://LOCATION-documentai.googleapis.com/v1beta3/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset/datasetSchema

CURL

  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth 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/dataset/datasetSchema"

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

  {
      "name": "projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset/datasetSchema",
      "documentSchema": {
          "entityTypes": [
          {
              "name": $SCHEMA_NAME,
              "baseTypes": [
              "document"
              ],
              "properties": [
              {
                  "name": $LABEL_NAME,
                  "valueType": $VALUE_TYPE,
                  "occurrenceType": $OCCURRENCE_TYPE,
                  "propertyMetadata": {}
              },
              ],
              "entityTypeMetadata": {}
          }
          ]
      }
  }

Actualiza el esquema del documento

En este ejemplo, se muestra cómo usar dataset.updateDatasetSchema para actualizar el esquema actual. En este ejemplo, se muestra un comando para actualizar el esquema del conjunto de datos para que tenga una etiqueta. Si quieres agregar una etiqueta nueva, no borrar ni actualizar las etiquetas existentes, primero puedes llamar a getDatasetSchema y hacer los cambios adecuados en su respuesta.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

LOCATION: Your processor location
PROJECT_ID: Your Google Cloud project ID
PROCESSOR_ID: The ID of your custom processor
LABEL_NAME: The label name which you want to add
LABEL_DESCRIPTION: Describe what the label represents
DATA_TYPE: The type of the label. You can specify this as string, number, currency, money, datetime, address, boolean.
OCCURRENCE_TYPE: Describes the number of times this label is expected. Pick an enum value.

Actualizar esquema

Método HTTP

PATCH https://LOCATION-documentai.googleapis.com/v1beta3/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset/datasetSchema

JSON de la solicitud:

  {
      "document_schema": {
          "entityTypes": [
              {
                  "name": $SCHEMA_NAME,
                  "baseTypes": [
                  "document"
                  ],
                  "properties": [
                  {
                      "name": LABEL_NAME,
                      "description": LABEL_DESCRIPTION,
                      "valueType": DATA_TYPE,
                      "occurrenceType": OCCURRENCE_TYPE,
                      "propertyMetadata": {}
                  },
                  ],
                  "entityTypeMetadata": {}
              }
          ]
      }
  }

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

CURL

  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth 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/dataset/datasetSchema"

Elige los atributos de la etiqueta

Tipo de datos

Plain text: Un valor de cadena.
Number: Un número, entero o de punto flotante.
Money: Un valor monetario. Cuando etiquetes, no incluyas el símbolo de moneda.
- Cuando se extrae la entidad, se normaliza a google.type.Money.
Currency: Es un símbolo de moneda.
Datetime: Un valor de fecha o hora.
- Cuando se extrae la entidad, se normaliza al formato de texto ISO 8601.
Address: Es una dirección de ubicación.
- Cuando se extrae la entidad, se normaliza y se enriquece con EKG.
Checkbox: Un valor booleano true o false.

Caso

Elige REQUIRED si se espera que una entidad siempre aparezca en documentos de un tipo determinado. Elige OPTIONAL si no hay tal expectativa.

Elige ONCE si se espera que una entidad tenga un valor, incluso si el mismo valor aparece varias veces en el mismo documento. Elige MULTIPLE si se espera que una entidad tenga varios valores.

Etiquetas superiores y secundarias

Las etiquetas de elementos superiores e inferiores (también conocidas como entidades tabulares) se usan para etiquetar datos en una tabla. La siguiente tabla contiene 3 filas y 4 columnas.

create-dataset-11

Puedes definir esas tablas con etiquetas de superior y secundario. En este ejemplo, la etiqueta superior line-item define una fila de la tabla.

Cómo crear una etiqueta superior

En la página Editar esquema, selecciona Crear etiqueta.
Selecciona la casilla de verificación Esta es una etiqueta para padres y, luego, ingresa el resto de la información. La etiqueta superior debe tener una ocurrencia de optional_multiple o require_multiple para que se pueda repetir y capturar todas las filas de la tabla.
Selecciona Guardar.

create-dataset-12

La etiqueta superior aparece en la página Edit schema, con la opción Add Child Label junto a ella.

Cómo crear una etiqueta secundaria

Junto a la etiqueta superior en la página Editar esquema, selecciona Agregar etiqueta secundaria.
Ingresa la información de la etiqueta secundaria.
Selecciona Guardar.

Repite el proceso para cada etiqueta secundaria que desees agregar.

Las etiquetas secundarias aparecen con sangría debajo de la etiqueta superior en la página Edit schema.

create-dataset-13

Las etiquetas de elementos superiores e inferiores son una función de vista previa y solo se admiten para las tablas. La profundidad de anidación se limita a 1, lo que significa que las entidades secundarias no pueden contener otras entidades secundarias.

Crea etiquetas de esquema a partir de documentos etiquetados

Importa archivos JSON Document etiquetados previamente para crear etiquetas de esquema automáticamente.

Mientras la importación de Document está en curso, las etiquetas de esquema nuevas se agregan al editor de esquemas. Selecciona "Editar esquema" para verificar o cambiar el tipo de datos y el tipo de ocurrencia de las etiquetas de esquema nuevas. Una vez que lo confirmes, selecciona las etiquetas de esquema y elige Habilitar.

Conjunto de datos de muestra

Para ayudarte a comenzar a usar Document AI Workbench, los conjuntos de datos se proporcionan en un bucket público de Cloud Storage que incluye archivos JSON de muestra Document etiquetados y sin etiquetar de varios tipos de documentos.

Se pueden usar para el entrenamiento avanzado o extractores personalizados según el tipo de documento.

gs://cloud-samples-data/documentai/Custom/
gs://cloud-samples-data/documentai/Custom/1040/
gs://cloud-samples-data/documentai/Custom/Invoices/
gs://cloud-samples-data/documentai/Custom/Patents/
gs://cloud-samples-data/documentai/Custom/Procurement-Splitter/
gs://cloud-samples-data/documentai/Custom/W2-redacted/
gs://cloud-samples-data/documentai/Custom/W2/
gs://cloud-samples-data/documentai/Custom/W9/

Proceso de etiquetado