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 supone que ya creaste un procesador que admite entrenamiento, enriquecimiento o 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:

• Administrada por Google
• Ubicación personalizada de Cloud Storage

A menos que tengas requisitos especiales (por ejemplo, mantener documentos en un conjunto de carpetas habilitadas para CMEK), te recomendamos la opción de almacenamiento administrado por Google más simple. Una vez que se crea, 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 y se pierda. La opción de almacenamiento administrado por Google no presenta este riesgo.

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

Almacenamiento administrado por Google (recomendado)

1. Muestra las opciones avanzadas mientras se crea un procesador nuevo.

   

2. Mantén la opción predeterminada del grupo de botones de selección en el almacenamiento administrado por Google.

   

3. Seleccione Crear.

   

4. Confirma que el conjunto de datos se haya creado correctamente y que su ubicación sea administrada por Google.

   

Opción de almacenamiento personalizada

1. Activa o desactiva las opciones avanzadas.

   

2. Selecciona Especificaré mi propia ubicación de almacenamiento.

   

3. Elige una carpeta de Cloud Storage en el componente de entrada.

   

4. 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 RPC de creación de recursos. En su lugar, puedes usar la RPC updateDataset para establecer las preferencias. Document AI ofrece 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

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

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

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

  {
      "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 -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"

  {
      "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 Cloud Storage está en un proyecto 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 Storage 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.

Luego, elige una de las siguientes opciones de asignación:

• 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 asignarlo 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 Document JSON, Document AI importa el documento y convierte su entities en instancias de etiquetas.

Document AI no modifica la carpeta de importación ni lee desde la carpeta una vez 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 y los que no se pudieron importar.

Si ya tienes una versión existente de tu 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 con documentos etiquetados automáticamente, ni usarlos en el conjunto de pruebas, sin marcarlos como etiquetados. Después de importar los documentos etiquetados automáticamente, revísalos y corrígelos 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 este ejemplo, 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.

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

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

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

  {
      "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 -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"

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

RPC para borrar documentos

En este ejemplo, 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

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

  {
  "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 -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"

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

Asigna documentos al conjunto de entrenamiento o de prueba

En División de datos, selecciona documentos y asígnalos al conjunto de entrenamiento, al conjunto de pruebas o a la opción sin asignar.

Prácticas recomendadas para el conjunto de datos de prueba

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 que haya al menos 100 documentos por tipo de documento en 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 para el año 2020 y el 30% para el año 2019, aproximadamente el 70% del conjunto de pruebas debería 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 pruebas incluya formularios de todos los países objetivo.

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 necesita ser tan estrictamente representativo del uso del cliente en términos de diversidad o frecuencia de los documentos. Algunas etiquetas son más difíciles de entrenar que otras. Por lo tanto, es posible que obtengas un mejor rendimiento si sesgas el conjunto de entrenamiento hacia esas etiquetas.

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 pruebas. 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, que se extraerán de tus documentos.

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

Cuando termines, asegúrate de seleccionar Guardar.

Notas sobre la administración de etiquetas de esquema:

• 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 entrenadas del procesador. 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.

Obtén el esquema de datos

En este ejemplo, se muestra cómo usar getDatasetSchema para obtener el esquema actual del conjunto de datos. 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

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

  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"

  {
      "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 de modo que tenga una etiqueta. Si quieres agregar una etiqueta nueva, no borrar ni actualizar las existentes, primero puedes llamar a getDatasetSchema y realizar los cambios correspondientes 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.

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

  {
      "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 -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 atributos de etiquetas

Tipo de datos

• Plain text: Es un valor de cadena.
• Number: Un número, ya sea entero o de punto flotante.
• Money: Es un importe de 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: Es un valor de fecha o hora.
  • Cuando se extrae la entidad, se normaliza al formato de texto ISO 8601.
• Address: Es la dirección de una ubicación.
  • Cuando se extrae la entidad, se normaliza y se enriquece con la 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 principales y secundarias

Las etiquetas de relación superior-subordinado (también conocidas como entidades tabulares) se usan para etiquetar datos en una tabla. La siguiente tabla contiene 3 filas y 4 columnas.

Puedes definir esas tablas con etiquetas de elementos superiores y secundarios. En este ejemplo, la etiqueta principal line-item define una fila de la tabla.

Cómo crear una etiqueta principal

1. En la página Edit schema, selecciona Create Label.

2. Selecciona la casilla de verificación Esta es una etiqueta principal y, luego, ingresa la otra información. La etiqueta principal debe tener una ocurrencia de optional_multiple o require_multiple para que se pueda repetir y capturar todas las filas de la tabla.

3. Selecciona Guardar.

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

Cómo crear una etiqueta secundaria

1. Junto a la etiqueta principal en la página Editar esquema, selecciona Agregar etiqueta secundaria.

2. Ingresa la información de la etiqueta secundaria.

3. Selecciona Guardar.

Repite el proceso para cada etiqueta secundaria que desees agregar.

Las etiquetas secundarias aparecen con sangría debajo de la etiqueta principal en la página Editar esquema.

Las etiquetas secundarias y principales 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

Crea automáticamente etiquetas de esquema importando archivos JSON Document etiquetados previamente.

Mientras se realiza la importación de Document, las etiquetas de esquema recién agregadas se incorporan al Editor de esquemas. Selecciona "Editar esquema" para verificar o cambiar el tipo de datos y el tipo de ocurrencia de las nuevas etiquetas del esquema. Una vez que se confirme, selecciona las etiquetas del esquema y, luego, Habilitar.

Conjunto de datos de muestra

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

Se pueden usar para el entrenamiento adicional o los 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/