Créer un ensemble de données

Un ensemble de données de documents étiqueté est requis pour entraîner, surentraîner ou évaluer une version de l'outil de traitement.

Cette page explique comment créer un ensemble de données, importer des documents et définir un schéma. Pour libeller les documents importés, consultez Libeller des documents.

Dans cette page, nous partons du principe que vous avez déjà créé un processeur compatible avec l'entraînement, le surentraînement ou l'évaluation. Si votre processeur est compatible, l'onglet Entraînement s'affiche dans la console Google Cloud .

Options de stockage des ensembles de données

Deux options s'offrent à vous pour enregistrer votre ensemble de données :

• Géré par Google
• Emplacement Cloud Storage personnalisé

Sauf si vous avez des exigences spécifiques (par exemple, conserver des documents dans un ensemble de dossiers compatibles avec CMEK), nous vous recommandons l'option de stockage gérée par Google, qui est plus simple. Une fois l'option de stockage de l'ensemble de données créée, elle ne peut plus être modifiée pour le processeur.

Le dossier ou le sous-dossier d'un emplacement Cloud Storage personnalisé doit être vide au départ et être traité en lecture seule. Toute modification manuelle de son contenu peut rendre l'ensemble de données inutilisable et entraîner sa perte. L'option de stockage géré par Google ne présente pas ce risque.

Suivez ces étapes pour provisionner votre emplacement de stockage.

Stockage géré par Google (recommandé)

1. Affichez les options avancées lorsque vous créez un processeur.

   

2. Conservez l'option par défaut Géré par Google pour le groupe de boutons radio.

   

3. Sélectionnez Créer.

   

4. Vérifiez que l'ensemble de données a bien été créé et que son emplacement est Emplacement géré par Google.

   

Option de stockage personnalisé

1. Activez ou désactivez les options avancées.

   

2. Sélectionnez Je spécifierai mon propre emplacement de stockage.

   

3. Choisissez un dossier Cloud Storage dans le composant d'entrée.

   

4. Sélectionnez Créer.

   

Opérations de l'API Dataset

Cet exemple montre comment utiliser la méthode processors.updateDataset pour créer un ensemble de données. Une ressource d'ensemble de données est une ressource singleton dans un processeur, ce qui signifie qu'il n'existe pas de RPC de création de ressource. Vous pouvez utiliser le RPC updateDataset pour définir les préférences. Document AI vous permet de stocker les documents de l'ensemble de données dans un bucket Cloud Storage que vous fournissez ou de les faire gérer automatiquement par Google.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

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

Pour envoyer votre demande, vous pouvez utiliser Curl :

Enregistrez le corps de la requête dans un fichier nommé request.json. Exécutez la commande suivante :

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

Importer des documents

Un ensemble de données nouvellement créé est vide. Pour ajouter des documents, sélectionnez Importer des documents, puis sélectionnez un ou plusieurs dossiers Cloud Storage contenant les documents que vous souhaitez ajouter à votre ensemble de données.

Si votre Cloud Storage se trouve dans un autre projet Google Cloud , assurez-vous d'accorder l'accès afin que Document AI soit autorisé à lire les fichiers à cet emplacement. Plus précisément, vous devez attribuer le rôle Lecteur des objets de l'espace de stockage à l'agent de service principal de Document AI service-{project-id}@gcp-sa-prod-dai-core.iam.gserviceaccount.com. Pour en savoir plus, consultez Agents de service.

Choisissez ensuite l'une des options suivantes :

• Entraînement : attribuez-le à l'ensemble d'entraînement.
• Test : attribuez-le à l'ensemble de test.
• Répartition automatique : les documents sont répartis de manière aléatoire entre les ensembles d'entraînement et de test.
• Non attribué : n'est pas utilisé pour l'entraînement ni l'évaluation. Vous pourrez l'attribuer manuellement plus tard.

Vous pourrez toujours modifier les devoirs ultérieurement.

Lorsque vous sélectionnez Importer, Document AI importe tous les types de fichiers compatibles ainsi que les fichiers JSON Document dans l'ensemble de données. Pour les fichiers JSON Document, Document AI importe le document et convertit ses entities en instances de libellé.

Document AI ne modifie pas le dossier d'importation et ne lit pas ses données une fois l'importation terminée.

Sélectionnez Activité en haut de la page pour ouvrir le panneau Activité, qui liste les fichiers qui ont été importés avec succès et ceux qui n'ont pas pu l'être.

Si vous disposez déjà d'une version de votre processeur, vous pouvez cocher la case Importer avec l'étiquetage automatique dans la boîte de dialogue Importer des documents. Les documents sont étiquetés automatiquement à l'aide de l'ancien processeur lors de leur importation. Vous ne pouvez pas entraîner ni réentraîner des modèles sur des documents étiquetés automatiquement, ni les utiliser dans l'ensemble de test, sans les marquer comme étiquetés. Après avoir importé les documents étiquetés automatiquement, examinez-les et corrigez-les manuellement. Sélectionnez ensuite Enregistrer pour enregistrer les corrections et marquer le document comme étiqueté. Vous pouvez ensuite attribuer les documents selon vos besoins. Consultez Étiquetage automatique.

RPC d'importation de documents

Cet exemple montre comment utiliser la méthode dataset.importDocuments pour importer des documents dans l'ensemble de données.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

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/"
          }
          }
      }
  }

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

  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 de suppression de documents

Cet exemple montre comment utiliser la méthode dataset.batchDeleteDocuments pour supprimer des documents de l'ensemble de données.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

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
      }
      }
  }

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

Attribuer des documents à un ensemble d'entraînement ou de test

Sous Répartition des données, sélectionnez des documents et attribuez-les à l'ensemble d'entraînement, à l'ensemble de test ou à la catégorie "Non attribué".

Bonnes pratiques pour l'ensemble de test

La qualité de votre ensemble de test détermine la qualité de votre évaluation.

L'ensemble de tests doit être créé au début du cycle de développement du processeur et verrouillé afin que vous puissiez suivre la qualité du processeur au fil du temps.

Nous recommandons d'avoir au moins 100 documents par type de document pour l'ensemble de test. Il est essentiel de s'assurer que l'ensemble de test est représentatif des types de documents que les clients utilisent pour le modèle en cours de développement.

L'ensemble de test doit être représentatif du trafic de production en termes de fréquence. Par exemple, si vous traitez des formulaires W2 et que vous vous attendez à ce que 70 % soient pour l'année 2020 et 30 % pour l'année 2019, environ 70 % de l'ensemble de test doivent être constitués de documents W2 2020. Cette composition de l'ensemble de tests garantit que l'importance appropriée est accordée à chaque sous-type de document lors de l'évaluation des performances du processeur. De plus, si vous extrayez des noms de personnes à partir de formulaires internationaux, assurez-vous que votre ensemble de test inclut des formulaires de tous les pays ciblés.

Bonnes pratiques pour l'ensemble d'entraînement

Les documents qui ont déjà été inclus dans l'ensemble de test ne doivent pas l'être dans l'ensemble d'entraînement.

Contrairement à l'ensemble de test, l'ensemble d'entraînement final n'a pas besoin d'être aussi strictement représentatif de l'utilisation par les clients en termes de diversité ou de fréquence des documents. Certains libellés sont plus difficiles à entraîner que d'autres. Vous pourriez donc obtenir de meilleures performances en biaisant l'ensemble d'entraînement vers ces libellés.

Au début, il n'est pas facile de déterminer quelles étiquettes sont difficiles. Vous devez commencer par un petit ensemble d'entraînement initial échantillonné de manière aléatoire en utilisant la même approche que celle décrite pour l'ensemble de test. Cet ensemble d'entraînement initial doit contenir environ 10 % du nombre total de documents que vous prévoyez d'annoter. Vous pouvez ensuite évaluer de manière itérative la qualité du processeur (en recherchant des schémas d'erreur spécifiques) et ajouter des données d'entraînement.

Définir le schéma de l'outil de traitement

Une fois que vous avez créé un ensemble de données, vous pouvez définir un schéma de processeur avant ou après avoir importé des documents.

Le schema du processeur définit les libellés, tels que le nom et l'adresse, à extraire de vos documents.

Sélectionnez Modifier le schéma, puis créez, modifiez, activez et désactivez les libellés selon vos besoins.

Veillez à sélectionner Enregistrer lorsque vous avez terminé.

Remarques sur la gestion des libellés de schéma :

• Une fois qu'un libellé de schéma est créé, son nom ne peut plus être modifié.

• Un libellé de schéma ne peut être modifié ou supprimé que s'il n'existe aucune version entraînée du processeur. Seuls le type de données et le type d'occurrence peuvent être modifiés.

• La désactivation d'un libellé n'a pas non plus d'incidence sur la prédiction. Lorsque vous envoyez une demande de traitement, la version du processeur extrait tous les libellés actifs au moment de l'entraînement.

Obtenir le schéma de données

Cet exemple montre comment utiliser l'ensemble de données. getDatasetSchema pour obtenir le schéma actuel. DatasetSchema est une ressource singleton, qui est créée automatiquement lorsque vous créez une ressource d'ensemble de données.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

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": {}
          }
          ]
      }
  }

Mettre à jour le schéma du document

Cet exemple vous montre comment utiliser dataset.updateDatasetSchema pour mettre à jour le schéma actuel. Cet exemple montre une commande permettant de mettre à jour le schéma de l'ensemble de données pour qu'il comporte un libellé. Si vous souhaitez ajouter un libellé, et non en supprimer ou en modifier un, vous pouvez d'abord appeler getDatasetSchema et apporter les modifications appropriées dans sa réponse.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

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": {}
              }
          ]
      }
  }

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

  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"

Choisir les attributs de l'étiquette

Type de données

• Plain text : valeur de chaîne.
• Number : nombre entier ou à virgule flottante.
• Money : montant monétaire. N'incluez pas le symbole de la devise dans le libellé.
  • Lorsque l'entité est extraite, elle est normalisée en google.type.Money.
• Currency : symbole de devise.
• Datetime : valeur de date ou d'heure.
  • Une fois l'entité extraite, elle est normalisée au format de texte ISO 8601.
• Address : adresse d'un lieu.
  • Lorsque l'entité est extraite, elle est normalisée et enrichie avec EKG.
• Checkbox : valeur booléenne true ou false.

Occurrence

Choisissez REQUIRED si une entité est censée apparaître systématiquement dans les documents d'un type donné. Sélectionnez OPTIONAL si aucune attente de ce type n'existe.

Choisissez ONCE si une entité est censée avoir une valeur, même si la même valeur apparaît plusieurs fois dans le même document. Choisissez MULTIPLE si une entité est censée avoir plusieurs valeurs.

Libellés parent et enfant

Les libellés parent-enfant (également appelés entités tabulaires) permettent d'étiqueter les données d'un tableau. Le tableau suivant contient trois lignes et quatre colonnes.

Vous pouvez définir ces tables à l'aide de libellés parent-enfant. Dans cet exemple, le libellé parent line-item définit une ligne du tableau.

Créer un libellé parent

1. Sur la page Modifier le schéma, sélectionnez Créer un libellé.

2. Cochez la case Il s'agit d'un libellé parent, puis saisissez les autres informations. Le libellé parent doit comporter une occurrence de optional_multiple ou require_multiple pour pouvoir être répété et capturer toutes les lignes du tableau.

3. Sélectionnez Enregistrer.

Le libellé parent s'affiche sur la page Modifier le schéma, avec l'option Ajouter un libellé enfant à côté.

Pour créer un libellé enfant

1. À côté du libellé parent sur la page Modifier le schéma, sélectionnez Ajouter un libellé enfant.

2. Saisissez les informations concernant la maison de disques enfant.

3. Sélectionnez Enregistrer.

Répétez l'opération pour chaque libellé enfant que vous souhaitez ajouter.

Les libellés enfants apparaissent en retrait sous le libellé parent sur la page Modifier le schéma.

Les libellés parent-enfant sont une fonctionnalité en version Preview et ne sont compatibles qu'avec les tableaux. La profondeur d'imbrication est limitée à 1, ce qui signifie que les entités enfants ne peuvent pas contenir d'autres entités enfants.

Créer des libellés de schéma à partir de documents étiquetés

Créez automatiquement des libellés de schéma en important des fichiers JSON Document pré-étiquetés.

Pendant l'importation de Document, les libellés de schéma nouvellement ajoutés sont ajoutés à l'éditeur de schéma. Sélectionnez "Modifier le schéma" pour vérifier ou modifier le type de données et le type d'occurrence des nouveaux libellés de schéma. Une fois la confirmation effectuée, sélectionnez les libellés de schéma, puis cliquez sur Activer.

Exemples d'ensembles de données

Pour vous aider à démarrer avec Document AI Workbench, des ensembles de données sont fournis dans un bucket Cloud Storage public. Ils incluent des exemples de fichiers JSON Document étiquetés et non étiquetés de plusieurs types de documents.

Ils peuvent être utilisés pour l'entraînement ou les extracteurs personnalisés, selon le type de document.

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/