Questa pagina è stata tradotta dall'API Cloud Translation.

Crea set di dati

Per addestrare, eseguire l'uptraining o valutare una versione del processore è necessario un set di dati etichettato dei documenti.

Questa pagina descrive come creare un set di dati, importare documenti e definire uno schema. Per etichettare i documenti importati, consulta Etichettare i documenti.

Questa pagina presuppone che tu abbia già creato un processore che supporti l'addestramento, l'uptraining o la valutazione. Se il tuo processore è supportato, nella console Google Cloud viene visualizzata la scheda Addestramento.

Opzioni di archiviazione dei set di dati

Puoi scegliere tra due opzioni per salvare il set di dati:

Gestita da Google
Località personalizzata Cloud Storage

A meno che tu non abbia requisiti speciali (ad esempio per conservare i documenti in un insieme di collezioni con CMEK abilitato), ti consigliamo l'opzione di archiviazione gestita da Google più semplice. Una volta creata, l'opzione di archiviazione del set di dati non può essere modificata per il processore.

La cartella o la sottocartella per una posizione Cloud Storage personalizzata deve iniziare vuota e deve essere trattata come di sola lettura. Eventuali modifiche manuali ai contenuti potrebbero rendere il set di dati inutilizzabile, con il rischio di perderlo. L'opzione di archiviazione gestita da Google non comporta questo rischio.

Per eseguire il provisioning della posizione di archiviazione, segui questi passaggi.

Spazio di archiviazione gestito da Google (opzione consigliata)

Mostra le opzioni avanzate durante la creazione di un nuovo elaboratore.
Mantieni l'opzione del gruppo di pulsanti di opzione predefinita per lo spazio di archiviazione gestito da Google.
Seleziona Crea.
Verifica che il set di dati sia stato creato correttamente e che la posizione del set di dati sia Posizione gestita da Google.

Opzione di archiviazione personalizzata

Attiva o disattiva le opzioni avanzate.
Seleziona Specificherò personalmente la località di archiviazione.
Scegli una cartella Cloud Storage dal componente di input.
Seleziona Crea.

Operazioni dell'API Dataset

Questo esempio mostra come utilizzare il metodo processors.updateDataset per creare un set di dati. Una risorsa set di dati è una risorsa singleton in un elaboratore, il che significa che non esiste un'operazione RPC di creazione della risorsa. In alternativa, puoi utilizzare l'RPC updateDataset per impostare le preferenze. Document AI offre la possibilità di archiviare i documenti del set di dati in un bucket Cloud Storage fornito da te o di gestirli automaticamente da Google.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

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 fornito

Segui i passaggi successivi per creare una richiesta di set di dati con un bucket Cloud Storage che fornisci.

Metodo HTTP

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

JSON richiesta:

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

Gestita da Google

Se vuoi creare il set di dati gestito da Google, aggiorna le seguenti informazioni:

Metodo HTTP

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

JSON richiesta:

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

Per inviare la richiesta, puoi utilizzare Curl:

Salva il corpo della richiesta in un file denominato request.json. Esegui questo 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"

Dovresti ricevere una risposta JSON simile alla seguente:

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

Importa documenti

Un set di dati appena creato è vuoto. Per aggiungere documenti, seleziona Importa documenti e poi una o più cartelle Cloud Storage contenenti i documenti da aggiungere al set di dati.

Se Cloud Storage si trova in un altro progetto Google Cloud , assicurati di grantare l'accesso in modo che Document AI possa leggere i file da quella posizione. Nello specifico, devi concedere il ruolo Visualizzatore oggetti Storage all'agente di servizio di base di Document AI service-{project-id}@gcp-sa-prod-dai-core.iam.gserviceaccount.com. Per ulteriori informazioni, consulta Agenti di servizio.

create-dataset-8

Scegli una delle seguenti opzioni di compito:

Addestramento: assegna al set di addestramento.
Test: assegna al set di test.
Suddivisione automatica: mescola in modo casuale i documenti nel set di addestramento e di test.
Non assegnato: non viene utilizzato per l'addestramento o la valutazione. Puoi assegnare manualmente in un secondo momento.

Puoi sempre modificare i compiti in un secondo momento.

Quando selezioni Importa, Document AI importa nel set di dati tutti i tipi di file supportati, nonché i file JSON Document. Per i file JSON Document, Document AI importa il documento e converte il relativo entities in istanze di etichetta.

Document AI non modifica la cartella di importazione né legge la cartella dopo che l'importazione è stata completata.

Seleziona Attività nella parte superiore della pagina per aprire il riquadro Attività, che elenca i file importati correttamente e quelli di cui non è riuscita l'importazione.

Se hai già una versione del tuo processore, puoi selezionare la casella di controllo Importa con etichettatura automatica nella finestra di dialogo Importa documenti. I documenti vengono etichettati automaticamente utilizzando il processore precedente al momento dell'importazione. Non puoi addestrare o eseguire l'addestramento avanzato sui documenti con etichetta automatica né utilizzarli nel set di test senza contrassegnarli come etichettati. Dopo aver importato i documenti etichettati automaticamente, esaminali e correggili manualmente. Poi seleziona Salva per salvare le correzioni e contrassegnare il documento come etichettato. Puoi quindi assegnare i documenti come appropriato. Consulta la sezione Etichettatura automatica.

RPC Importa documenti

Questo esempio mostra come utilizzare il metodo dataset.importDocuments per importare i documenti nel set di dati.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

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.

Set di dati di addestramento o di test

Se vuoi aggiungere documenti al set di dati di addestramento o di test:

Metodo HTTP

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

JSON richiesta:

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

Set di dati di addestramento e test

Se vuoi suddividere automaticamente i documenti tra il set di dati di addestramento e quello di test:

Metodo HTTP

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

JSON richiesta:

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

Salva il corpo della richiesta in un file denominato request.json ed esegui il seguente 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"

Dovresti ricevere una risposta JSON simile alla seguente:

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

RPC Elimina documenti

Questo esempio mostra come utilizzare il metodo dataset.batchDeleteDocuments per eliminare i documenti dal set di dati.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

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

Eliminare i documenti

Metodo HTTP

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

JSON richiesta:

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

Salva il corpo della richiesta in un file denominato request.json ed esegui il seguente 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"

Dovresti ricevere una risposta JSON simile alla seguente:

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

Assegnare i documenti al set di addestramento o di test

In Suddivisione dati, seleziona i documenti e assegnali al set di addestramento, al set di test o a Non assegnato.

create-dataset-9

Best practice per il set di test

La qualità del set di test determina la qualità della valutazione.

Il set di test deve essere creato all'inizio del ciclo di sviluppo del processore e bloccato in modo da poter monitorare la qualità del processore nel tempo.

Per il set di test, consigliamo almeno 100 documenti per tipo di documento. È fondamentale assicurarsi che il set di test sia rappresentativo dei tipi di documenti che i clienti utilizzano per il modello in fase di sviluppo.

Il set di test deve essere rappresentativo del traffico di produzione in termini di frequenza. Ad esempio, se stai elaborando moduli W2 e prevedi che il 70% sia relativo all'anno 2020 e il 30% all'anno 2019, circa il 70% del set di test dovrebbe essere costituito da documenti W2 2020. Questa composizione del set di test garantisce che a ogni sottotipo di documento venga assegnata l'importanza appropriata al momento della valutazione del rendimento del processore. Inoltre, se estrai i nomi delle persone da moduli internazionali, assicurati che il set di test includa i moduli di tutti i paesi target.

Best practice per l'insieme di addestramento

I documenti già inclusi nel set di test non devono essere inclusi nel set di addestramento.

A differenza del set di test, il set di addestramento finale non deve essere così strettamente rappresentativo dell'utilizzo del cliente in termini di diversità o frequenza dei documenti. Alcune etichette sono più difficili da addestrare rispetto ad altre. Pertanto, potresti ottenere un rendimento migliore sbilanciando il set di addestramento verso queste etichette.

All'inizio, non esiste un buon modo per capire quali etichette sono difficili. Ti consigliamo di iniziare con un piccolo set di addestramento iniziale campionato in modo casuale utilizzando lo stesso approccio descritto per il set di test. Questo set di addestramento iniziale deve contenere circa il 10% del numero totale di documenti che prevedi di annotare. Poi, puoi valutare in modo iterativo la qualità del processore (cercando pattern di errori specifici) e aggiungere altri dati di addestramento.

Definisci lo schema del processore

Dopo aver creato un set di dati, puoi definire uno schema del processore prima o dopo aver importato i documenti.

schema del processore definisce le etichette, come nome e indirizzo, da estrarre dai tuoi documenti.

Seleziona Modifica schema, quindi crea, modifica, attiva e disattiva le etichette come necessario.

Assicurati di selezionare Salva al termine.

create-dataset-10

Note sulla gestione delle etichette dello schema:

Una volta creata, il nome di un'etichetta dello schema non può essere modificato.
Un'etichetta dello schema può essere modificata o eliminata solo se non sono presenti versioni del processore addestrate. È possibile modificare solo il tipo di dati e il tipo di occorrenza.
Anche la disattivazione di un'etichetta non influisce sulla previsione. Quando invii una richiesta di elaborazione, la versione del processore estrae tutte le etichette attive al momento dell'addestramento.

Ottieni schema di dati

Questo esempio mostra come utilizzare la funzione dataset. getDatasetSchema per ottenere lo schema corrente. DatasetSchema è una risorsa singola, che viene creata automaticamente quando crei una risorsa set di dati.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

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

Ottieni schema di dati

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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Aggiorna lo schema del documento

Questo esempio mostra come utilizzare dataset.updateDatasetSchema per aggiornare lo schema corrente. Questo esempio mostra un comando per aggiornare lo schema del set di dati in modo che abbia un'etichetta. Se vuoi aggiungere una nuova etichetta, non eliminare o aggiornare le etichette esistenti, puoi chiamare prima getDatasetSchema e apportare le modifiche appropriate nella risposta.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

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.

Aggiorna schema

Metodo HTTP

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

JSON richiesta:

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

Salva il corpo della richiesta in un file denominato request.json ed esegui il seguente 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"

Scegli gli attributi delle etichette

Tipo di dati

Plain text: un valore di stringa.
Number: un numero intero o a virgola mobile.
Money: un importo monetario. Quando etichetti, non includere il simbolo di valuta.
- Quando l'entità viene estratta, viene normalizzata in google.type.Money.
Currency: un simbolo di valuta.
Datetime: un valore di data o ora.
- Quando l'entità viene estratta, viene normalizzata in base al formato di testo ISO 8601.
Address: un indirizzo sede.
- Quando l'entità viene estratta, viene normalizzata e arricchita con EKG.
Checkbox: un valore booleano true o false.

Occorrenza

Scegli REQUIRED se è previsto che un'entità venga sempre visualizzata nei documenti di un determinato tipo. Scegli OPTIONAL se non esiste questa aspettativa.

Scegli ONCE se è previsto che un'entità abbia un valore, anche se lo stesso valore appare più volte nello stesso documento. Scegli MULTIPLE se un'entità deve avere più valori.

Etichette principali e secondarie

Le etichette elemento principale-elemento secondario (note anche come entità tabulari) vengono utilizzate per etichettare i dati in una tabella. La seguente tabella contiene 3 righe e 4 colonne.

create-dataset-11

Puoi definire queste tabelle utilizzando le etichette padre-figlio. In questo esempio, l'etichetta principale line-item definisce una riga della tabella.

Creare un'etichetta principale

Nella pagina Modifica schema, seleziona Crea etichetta.
Seleziona la casella di controllo Questa è un'etichetta per i genitori e inserisci le altre informazioni. L'etichetta principale deve avere un'occorrenza di optional_multiple o require_multiple in modo da poter essere ripetuta per acquisire tutte le righe della tabella.
Seleziona Salva.

create-dataset-12

L'etichetta principale viene visualizzata nella pagina Modifica schema, accanto all'opzione Aggiungi etichetta secondaria.

Per creare un'etichetta secondaria

Accanto all'etichetta principale nella pagina Modifica schema, seleziona Aggiungi etichetta secondaria.
Inserisci le informazioni per l'etichetta secondaria.
Seleziona Salva.

Ripeti l'operazione per ogni etichetta secondaria che vuoi aggiungere.

Le etichette secondarie vengono visualizzate rientrate sotto l'etichetta principale nella pagina Modifica schema.

create-dataset-13

Le etichette principali e secondarie sono una funzionalità in anteprima e sono supportate solo per le tabelle. La profondità di nidificazione è limitata a 1, il che significa che le entità secondarie non possono contenere altre entità secondarie.

Creare etichette dello schema da documenti etichettati

Crea automaticamente le etichette dello schema importando file JSON Document preetichettati.

Durante l'importazione di Document, le etichette dello schema appena aggiunte vengono aggiunte a Schema Editor. Seleziona "Modifica schema" per verificare o modificare il tipo di dati e il tipo di occorrenza delle nuove etichette dello schema. Una volta confermata, seleziona le etichette dello schema e Attiva.

Set di dati di esempio

Per aiutarti a iniziare a utilizzare Document AI Workbench, i set di dati vengono forniti in un bucket Cloud Storage pubblico che include file JSON di esempio Document di esempio pre-etichettati e non etichettati di diversi tipi di documenti.

Questi possono essere utilizzati per l'addestramento avanzato o per gli estrattori personalizzati, a seconda del tipo di 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/

Avanti

Procedura di etichettatura