Criar conjunto de dados

Um conjunto de dados rotulado de documentos é necessário para treinar, aprimorar o treinamento ou avaliar uma versão do processador.

Nesta página, você vai aprender a criar um conjunto de dados, importar documentos e definir um esquema. Para rotular os documentos importados, consulte Rotular documentos.

Nesta página, presume-se que você já criou um processador que oferece suporte a treinamento, aprimoramento de treinamento ou avaliação. Se o processador for compatível, a guia Treinar vai aparecer no console do Google Cloud .

Opções de armazenamento de conjuntos de dados

Você pode escolher entre duas opções para salvar seu conjunto de dados:

• Gerenciada pelo Google
• Local personalizado do Cloud Storage

A menos que você tenha requisitos especiais (por exemplo, para manter documentos em um conjunto de pastas ativadas para CMEK), recomendamos a opção mais simples de armazenamento gerenciado pelo Google. Depois de criada, a opção de armazenamento do conjunto de dados não pode ser alterada para o processador.

A pasta ou subpasta de um local personalizado do Cloud Storage precisa começar vazia e ser tratada como somente leitura. Qualquer mudança manual no conteúdo pode tornar o conjunto de dados inutilizável e causar a perda dele. A opção de armazenamento gerenciado pelo Google não tem esse risco.

Siga estas etapas para provisionar seu local de armazenamento.

Armazenamento gerenciado pelo Google (recomendado)

1. Mostrar opções avançadas ao criar um novo processador.

   

2. Mantenha a opção padrão do grupo de botões de opção como armazenamento gerenciado pelo Google.

   

3. Selecione Criar.

   

4. Confirme se o conjunto de dados foi criado e se o local dele é gerenciado pelo Google.

   

Opção de armazenamento personalizado

1. Ative ou desative as opções avançadas.

   

2. Selecione Vou especificar meu próprio local de armazenamento.

   

3. Escolha uma pasta do Cloud Storage no componente de entrada.

   

4. Selecione Criar.

   

Operações da API Dataset

Este exemplo mostra como usar o método processors.updateDataset para criar um conjunto de dados. Um recurso de conjunto de dados é um recurso singleton em um processador, o que significa que não há um RPC de recurso de criação. Em vez disso, use a RPC updateDataset para definir as preferências. A Document AI oferece uma opção para armazenar os documentos do conjunto de dados em um bucket do Cloud Storage fornecido por você ou para que eles sejam gerenciados automaticamente pelo Google.

Antes de usar os dados da solicitação, faça as substituições a seguir:

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 sua solicitação, use Curl:

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o seguinte 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

Um conjunto de dados recém-criado está vazio. Para adicionar documentos, selecione Importar documentos e escolha uma ou mais pastas do Cloud Storage que contenham os documentos que você quer adicionar ao conjunto de dados.

Se o Cloud Storage estiver em um projeto Google Cloud diferente, conceda acesso para que a Document AI possa ler arquivos desse local. Especificamente, você precisa conceder o papel Leitor de objetos do Storage ao agente de serviço principal da Document AI service-{project-id}@gcp-sa-prod-dai-core.iam.gserviceaccount.com. Para mais informações, consulte Agentes de serviço.

Em seguida, escolha uma das seguintes opções de atribuição:

• Treinamento: atribua ao conjunto de treinamento.
• Teste: atribuir ao conjunto de teste.
• Divisão automática: organiza aleatoriamente os documentos nos conjuntos de treinamento e teste.
• Não atribuído: não é usado no treinamento ou na avaliação. É possível atribuir manualmente mais tarde.

Você pode modificar as atividades depois.

Quando você seleciona Importar, a Document AI importa todos os tipos de arquivos compatíveis e os arquivos JSON Document para o conjunto de dados. Para arquivos JSON Document, a Document AI importa o documento e converte o entities em instâncias de rótulo.

A Document AI não modifica a pasta de importação nem lê dela após a conclusão da importação.

Selecione Atividade na parte de cima da página para abrir o painel Atividade, que lista os arquivos importados e os que não foram.

Se você já tiver uma versão do seu processador, marque a caixa de seleção Importar com a rotulagem automática na caixa de diálogo Importar documentos. Os documentos são rotulados automaticamente usando o processador anterior quando são importados. Não é possível treinar ou fazer um novo treinamento com documentos rotulados automaticamente nem usá-los no conjunto de teste sem marcá-los como rotulados. Depois de importar os documentos rotulados automaticamente, revise e corrija manualmente. Em seguida, selecione Salvar para salvar as correções e marcar o documento como rotulado. Em seguida, atribua os documentos conforme necessário. Consulte Rotulagem automática.

RPC de importação de documentos

Este exemplo mostra como usar o método dataset.importDocuments para importar documentos para o conjunto de dados.

Antes de usar os dados da solicitação, faça as substituições a seguir:

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

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

  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 exclusão de documentos

Este exemplo mostra como usar o método dataset.batchDeleteDocuments para excluir documentos do conjunto de dados.

Antes de usar os dados da solicitação, faça as substituições a seguir:

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

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

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

Atribuir documentos ao conjunto de treinamento ou teste

Em Divisão de dados, selecione os documentos e atribua-os ao conjunto de treinamento, de teste ou não atribuídos.

Práticas recomendadas para o conjunto de teste

A qualidade do conjunto de teste determina a qualidade da avaliação.

O conjunto de teste precisa ser criado no início do ciclo de desenvolvimento do processador e bloqueado para que você possa acompanhar a qualidade dele ao longo do tempo.

Recomendamos pelo menos 100 documentos por tipo de documento para o conjunto de teste. É fundamental garantir que o conjunto de teste seja representativo dos tipos de documentos que os clientes estão usando para o modelo em desenvolvimento.

O conjunto de teste precisa ser representativo do tráfego de produção em termos de frequência. Por exemplo, se você estiver processando formulários W2 e espera que 70% sejam de 2020 e 30% de 2019, cerca de 70% do conjunto de teste deve consistir em documentos W2 de 2020. Essa composição garante que a importância adequada seja dada a cada subtipo de documento ao avaliar a performance do processador. Além disso, se você estiver extraindo nomes de pessoas de formulários internacionais, verifique se o conjunto de teste inclui formulários de todos os países segmentados.

Práticas recomendadas para o conjunto de treinamento

Os documentos que já foram incluídos no conjunto de teste não devem ser incluídos no conjunto de treinamento.

Ao contrário do conjunto de teste, o conjunto de treinamento final não precisa ser tão estritamente representativo do uso do cliente em termos de diversidade ou frequência de documentos. Alguns rótulos são mais difíceis de treinar do que outros. Assim, você pode melhorar o desempenho ao inclinar o conjunto de treinamento para esses rótulos.

No início, não há uma boa maneira de descobrir quais rótulos são difíceis. Comece com um conjunto de treinamento inicial pequeno e amostrado aleatoriamente usando a mesma abordagem descrita para o conjunto de teste. Esse conjunto de treinamento inicial precisa conter aproximadamente 10% do número total de documentos que você planeja anotar. Em seguida, avalie de forma iterativa a qualidade do processador (procurando padrões de erros específicos) e adicione mais dados de treinamento.

Definir esquema do processado

Depois de criar um conjunto de dados, é possível definir um esquema de processador antes ou depois de importar documentos.

O schema do processador define os rótulos, como nome e endereço, a serem extraídos dos documentos.

Selecione Editar esquema e crie, edite, ative e desative rótulos conforme necessário.

Não se esqueça de selecionar Salvar quando terminar.

Observações sobre o gerenciamento de rótulos de esquema:

• Depois que um rótulo de esquema é criado, o nome dele não pode ser editado.

• Um rótulo de esquema só pode ser editado ou excluído quando não há versões treinadas do processador. Só é possível editar o tipo de dados e o tipo de ocorrência.

• A desativação de um rótulo também não afeta a previsão. Quando você envia uma solicitação de processamento, a versão do processador extrai todos os rótulos que estavam ativos no momento do treinamento.

Receber esquema de dados

Este exemplo mostra como usar o conjunto de dados. getDatasetSchema para receber o esquema atual. DatasetSchema é um recurso singleton, que é criado automaticamente quando você cria um recurso de conjunto de dados.

Antes de usar os dados da solicitação, faça as substituições a seguir:

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

Atualizar esquema de documento

Esta amostra mostra como usar o dataset.updateDatasetSchema para atualizar o esquema atual. Este exemplo mostra um comando para atualizar o esquema do conjunto de dados para ter um rótulo. Se você quiser adicionar um novo rótulo, não excluir ou atualizar os atuais, chame getDatasetSchema primeiro e faça as mudanças adequadas na resposta.

Antes de usar os dados da solicitação, faça as substituições a seguir:

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

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

  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"

Escolher atributos de rótulo

Tipo de dado

• Plain text: um valor de string.
• Number: um número inteiro ou de ponto flutuante.
• Money: um valor monetário. Ao rotular, não inclua o símbolo da moeda.
  • Quando a entidade é extraída, ela é normalizada para google.type.Money.
• Currency: um símbolo de moeda.
• Datetime: um valor de data ou hora.
  • Quando a entidade é extraída, ela é normalizada para o formato de texto ISO 8601.
• Address: um endereço de local.
  • Quando a entidade é extraída, ela é normalizada e enriquecida com o EKG.
• Checkbox: um valor booleano true ou false.

Ocorrência

Escolha REQUIRED se uma entidade sempre aparecer em documentos de um determinado tipo. Escolha OPTIONAL se não houver essa expectativa.

Escolha ONCE se uma entidade tiver um valor, mesmo que o mesmo valor apareça várias vezes no mesmo documento. Escolha MULTIPLE se uma entidade puder ter vários valores.

Rótulos principais e secundários

Os rótulos de pai-filho (também conhecidos como entidades tabulares) são usados para rotular dados em uma tabela. A tabela a seguir contém três linhas e quatro colunas.

É possível definir essas tabelas usando rótulos pai-filho. Neste exemplo, o rótulo principal line-item define uma linha da tabela.

Criar um marcador principal

1. Na página Editar esquema, selecione Criar rótulo.

2. Marque a caixa de seleção Este é um rótulo principal e insira as outras informações. O marcador principal precisa ter uma ocorrência de optional_multiple ou require_multiple para que possa ser repetido e capturar todas as linhas da tabela.

3. Selecione Salvar.

O marcador principal aparece na página Editar esquema, com a opção Adicionar marcador secundário ao lado.

Para criar um marcador filho

1. Ao lado do rótulo principal na página Editar esquema, selecione Adicionar rótulo secundário.

2. Insira as informações do rótulo infantil.

3. Selecione Salvar.

Repita para cada marcador secundário que você quiser adicionar.

Os rótulos filhos aparecem com recuo abaixo do rótulo principal na página Editar esquema.

Os rótulos pai-filho são um recurso de prévia e só são compatíveis com tabelas. A profundidade de aninhamento é limitada a 1, o que significa que as entidades filhas não podem conter outras entidades filhas.

Criar rótulos de esquema com base em documentos rotulados

Crie automaticamente rótulos de esquema importando arquivos JSON Document pré-rotulados.

Enquanto a importação de Document está em andamento, os rótulos de esquema recém-adicionados são incluídos no Editor de esquema. Selecione "Editar esquema" para verificar ou mudar o tipo de dados e a ocorrência dos novos rótulos de esquema. Depois de confirmar, selecione os rótulos de esquema e clique em Ativar.

Conjuntos de dados de amostra

Para ajudar você a começar a usar o Document AI Workbench, fornecemos conjuntos de dados em um bucket público do Cloud Storage que inclui arquivos JSON Document de amostra pré-rotulados e não rotulados de vários tipos de documentos.

Eles podem ser usados para treinamento adicional ou extratores personalizados, dependendo do 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/