Créer un ensemble de données

Un ensemble de données de documents étiquetés 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 ajouter des libellés aux documents importés, consultez Étiqueter des documents.

Cette page suppose 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

Vous avez le choix entre deux options pour enregistrer votre ensemble de données:

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

Sauf si vous avez des exigences particulières (par exemple, pour conserver des documents dans un ensemble de dossiers compatibles avec CMEK), nous vous recommandons l'option de stockage gérée par Google. 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 commencer par être vide et être traité en lecture seule. Toute modification manuelle de son contenu peut rendre l'ensemble de données inutilisable et risquer de le perdre. L'option de stockage géré par Google ne présente pas ce risque.

Suivez ces étapes pour provisionner votre emplacement de stockage.

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

    create-dataset-1

  2. Laissez l'option par défaut du groupe de cases d'option définie sur l'espace de stockage géré par Google.

    create-dataset-2

  3. Sélectionnez Créer.

    create-dataset-3

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

    create-dataset-4

Option de stockage personnalisée

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

    create-dataset-5

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

    create-dataset-6

  3. Choisissez un dossier Cloud Storage dans le composant de saisie.

    create-dataset-7

  4. Sélectionnez Créer.

    create-dataset-8

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'y a pas de RPC de création de ressources. Vous pouvez utiliser la RPC updateDataset à la place 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

Bucket fourni

Suivez les étapes suivantes pour créer une requête d'ensemble de données avec un bucket Cloud Storage que vous fournissez.

Méthode HTTP

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

Requête JSON:

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

Géré par Google

Si vous souhaitez créer un ensemble de données géré par Google, mettez à jour les informations suivantes:

Méthode HTTP

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

Requête JSON:

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

Pour envoyer votre requête, vous pouvez utiliser Curl:

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

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"

Vous devriez recevoir une réponse JSON de ce type :

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

Importer des documents

Un nouvel ensemble de données 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 à partir de 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 la page Agents de service.

create-dataset-8

Choisissez ensuite l'une des options suivantes:

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

Vous pourrez toujours les modifier plus tard.

Lorsque vous sélectionnez Importer, Document AI importe tous les types de fichiers compatibles, ainsi que les fichiers JSON Document dans le jeu de données. Pour les fichiers JSON Document, Document AI importe le document et convertit son 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 importés avec succès ainsi que ceux qui n'ont pas été importés.

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'outil de traitement précédent lors de leur importation. Vous ne pouvez pas entraîner ni mettre à jour un modèle avec des documents étiquetés automatiquement, ni les utiliser dans l'ensemble de test, sans les marquer comme étiquetés. Après avoir importé des documents étiquetés automatiquement, examinez-les manuellement et corrigez-les. Sélectionnez ensuite Enregistrer pour enregistrer les corrections et marquer le document comme libellé. Vous pouvez ensuite attribuer les documents en fonction de 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.

Ensemble de données d'entraînement ou de test

Pour ajouter des documents à un ensemble de données d'entraînement ou de test:

Méthode HTTP

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

Requête JSON:

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

Ensemble de données d'entraînement et de test

Si vous souhaitez scinder automatiquement les documents entre l'ensemble de données d'entraînement et l'ensemble de données de test:

Méthode HTTP

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

Requête JSON:

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

  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"

Vous devriez recevoir une réponse JSON de ce type :

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

Supprimer des documents

Méthode HTTP

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

Requête JSON:

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

  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"

Vous devriez recevoir une réponse JSON de ce type :

  {
      "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 les documents et attribuez-les à l'ensemble d'entraînement, à l'ensemble de test ou à l'ensemble non attribué.

create-dataset-9

Bonnes pratiques concernant l'ensemble de test

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

L'ensemble de test 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 vous recommandons d'utiliser 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 prévoyez que 70% d'entre eux sont pour l'année 2020 et 30% pour l'année 2019, environ 70% de l'ensemble de test doit être constitué de documents W2 2020. Une telle composition d'ensemble de test garantit que chaque sous-type de document est accordé une importance appropriée lors de l'évaluation des performances du processeur. De plus, si vous extrayez les noms des personnes à partir de formulaires internationaux, assurez-vous que votre ensemble de test inclut des formulaires de tous les pays ciblés.

Bonnes pratiques concernant l'ensemble d'entraînement

Les documents déjà inclus dans l'ensemble de test ne doivent pas être inclus 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 le client en termes de diversité ou de fréquence des documents. Certaines étiquettes sont plus difficiles à entraîner que d'autres. Vous pouvez donc obtenir de meilleures performances en orientant l'ensemble d'entraînement vers ces libellés.

Au début, il n'existe pas de bon moyen 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 d'autres 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 l'outil de traitement avant ou après l'importation de documents.

Le schema de l'outil de traitement définit les étiquettes, telles que le nom et l'adresse, à extraire de vos documents.

Sélectionnez Edit Schema (Modifier le schéma), puis créez, modifiez, activez et désactivez les libellés si nécessaire.

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

create-dataset-10

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

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

  • Un libellé de schéma ne peut être modifié ou supprimé que lorsqu'il n'existe aucune version de processeur entraînée. 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 requête de traitement, la version du processeur extrait toutes les étiquettes qui étaient actives au moment de l'entraînement.

Obtenir le schéma de données

Cet exemple montre comment utiliser la méthode getDatasetSchema pour obtenir le schéma actuel. DatasetSchema est une ressource singleton, 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

Obtenir le schéma de données

Méthode 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"

Vous devriez recevoir une réponse JSON de ce type :

  {
      "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 seul libellé. Si vous souhaitez ajouter un libellé, et non supprimer ou mettre à jour des libellés existants, 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.

Mettre à jour le schéma

Méthode HTTP

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

Requête JSON:

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

  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 des attributs d'étiquette

Type de données

  • Plain text: valeur de chaîne.
  • Number: nombre (entier ou à virgule flottante).
  • Money: valeur monétaire. Lorsque vous ajoutez un libellé, n'incluez pas le symbole de la devise.
  • Currency: symbole de devise.
  • Datetime: valeur de date ou d'heure.
    • Lorsque l'entité est extraite, elle est normalisée au format de texte ISO 8601.
  • Address : adresse d'un établissement.
    • 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é doit toujours apparaître dans les documents d'un type donné. Sélectionnez OPTIONAL si aucune attente de ce type n'existe.

Choisissez ONCE si une entité doit avoir une seule valeur, même si la même valeur apparaît plusieurs fois dans le même document. Choisissez MULTIPLE si une entité doit 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 comporte trois lignes et quatre colonnes.

create-dataset-11

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 de la table.

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 de require_multiple afin qu'il puisse être répété pour capturer toutes les lignes du tableau.

  3. Sélectionnez Enregistrer.

create-dataset-12

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. Sur la page Modifier le schéma, à côté du libellé parent, sélectionnez Ajouter un libellé enfant.

  2. Saisissez les informations de l'étiquette enfant.

  3. Sélectionnez Enregistrer.

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

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

create-dataset-13

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 Activer.

Exemples d'ensembles de données

Pour vous aider à vous lancer dans Document AI Workbench, des ensembles de données sont fournis dans un bucket Cloud Storage public qui inclut des exemples de fichiers JSON Document pré-étiquetés et non étiquetés de plusieurs types de documents.

Ils peuvent être utilisés pour l'entraînement avancé ou les extracteurs personnalisés, en fonction du 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/