Esta página foi traduzida pela API Cloud Translation.

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.

Esta página descreve como 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 compatível com treinamento, aprimoramento de treinamento ou avaliação. Se o processador tiver suporte, a guia Train 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, manter documentos em um conjunto de pastas com CMEK), recomendamos a opção de armazenamento gerenciado pelo Google mais simples. Depois de criada, a opção de armazenamento de conjuntos 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, arriscando 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)

Mostrar opções avançadas ao criar um novo processador.
Mantenha a opção padrão do grupo de botões como armazenamento gerenciado pelo Google.
Selecione Criar.
Confirme se o conjunto de dados foi criado e se o local do conjunto de dados é Gerenciado pelo Google.

Opção de armazenamento personalizada

Ative ou desative as opções avançadas.
Selecione Vou especificar meu próprio local de armazenamento.
Escolha uma pasta do Cloud Storage no componente de entrada.
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 criação de recursos. Em vez disso, use o RPC updateDataset para definir as preferências. O Document AI oferece a opção de armazenar os documentos do conjunto de dados em um bucket do Cloud Storage fornecido por você ou de gerenciá-los 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

Bucket fornecido

Siga as próximas etapas para criar uma solicitação de conjunto de dados com um bucket do Cloud Storage fornecido.

Método HTTP

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

JSON da solicitação:

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

Gerenciada pelo Google

Caso você queira criar o conjunto de dados gerenciado pelo Google, atualize as seguintes informações:

Método HTTP

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

JSON da solicitação:

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

Para enviar sua solicitação, use o Curl:

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

Você receberá uma resposta JSON semelhante a esta:

  {
      "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 selecione uma ou mais pastas do Cloud Storage que contêm os documentos que você quer adicionar ao conjunto de dados.

Se o Cloud Storage estiver em um projeto diferente do Google Cloud , conceda acesso para que a Document AI possa ler arquivos desse local. Especificamente, conceda o papel de 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.

create-dataset-8

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

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

Você pode modificar as atribuições mais tarde.

Quando você seleciona Importar, o Document AI importa todos os tipos de arquivo compatíveis e 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 faz uma leitura a partir 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 aqueles que não foram importados.

Se você já tiver uma versão do 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 atualizar o treinamento em documentos rotulados automaticamente ou usá-los no conjunto de teste sem marcá-los como rotulados. Depois de importar documentos rotulados automaticamente, revise e corrija manualmente os documentos rotulados automaticamente. Em seguida, selecione Salvar para salvar as correções e marcar o documento como marcado. Em seguida, você pode atribuir os documentos conforme apropriado. 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.

Treinar ou testar um conjunto de dados

Se você quiser adicionar documentos ao conjunto de dados de treinamento ou teste:

Método HTTP

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

JSON da solicitação:

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

Treinar e testar o conjunto de dados

Se você quiser dividir automaticamente os documentos entre o conjunto de dados de treinamento e de teste:

Método HTTP

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

JSON da solicitação:

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

  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"

Você receberá uma resposta JSON semelhante a esta:

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

Excluir documentos RPC

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

Excluir documentos

Método HTTP

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

JSON da solicitação:

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

  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"

Você receberá uma resposta JSON semelhante a esta:

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

Atribuir documentos a um conjunto de treinamento ou teste

Em Divisão de dados, selecione os documentos e atribua-os ao conjunto de treinamento, ao conjunto de teste ou sem atribuição.

create-dataset-9

Práticas recomendadas para o conjunto de testes

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

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

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

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

Práticas recomendadas para o conjunto de treinamento

Os documentos que já foram incluídos no conjunto de teste não podem 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 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 ter uma performance melhor distorcendo 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 cerca de 10% do número total de documentos que você planeja anotar. Em seguida, é possível avaliar de forma iterativa a qualidade do processador (procurando padrões de erros específicos) e adicionar mais dados de treinamento.

Definir esquema do processado

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

O schema do processador define os rótulos, como nome e endereço, para extrair dos seus documentos.

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

Selecione Salvar quando terminar.

create-dataset-10

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 de processador treinadas. Só é possível editar o tipo de dados e o tipo de ocorrência.
Desativar 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 método getDatasetSchema do conjunto de dados para acessar o esquema atual. DatasetSchema é um recurso único, 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

Receber esquema de dados

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

Você receberá uma resposta JSON semelhante a esta:

  {
      "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 o esquema do documento

Este exemplo 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, e não excluir ou atualizar rótulos existentes, 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.

Atualizar esquema

Método HTTP

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

JSON da solicitação:

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

  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 do 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 do local.
- Quando a entidade é extraída, ela é normalizada e enriquecida com EKG.
Checkbox: um valor booleano true ou false.

Ocorrência

Escolha REQUIRED se uma entidade precisa aparecer sempre 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 tiver vários valores.

Rótulos principais e secundários

Rótulos 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.

create-dataset-11

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

Criar um marcador pai

Na página Editar esquema, selecione Criar rótulo.
Marque a caixa de seleção Este é um rótulo pai e insira as outras informações. O rótulo pai precisa ter uma ocorrência de optional_multiple ou require_multiple para que possa ser repetido e capturar todas as linhas da tabela.
Selecione Salvar.

create-dataset-12

O rótulo pai aparece na página Editar esquema, com a opção Adicionar rótulo filho ao lado.

Para criar um rótulo filho

Ao lado do rótulo pai na página Editar esquema, selecione Adicionar rótulo filho.
Insira as informações do rótulo filho.
Selecione Salvar.

Repita para cada rótulo filho que você quer adicionar.

Os rótulos filhos aparecem recuados abaixo do rótulo pai na página Editar esquema.

create-dataset-13

Os rótulos pai-filho são um recurso de pré-lançamento 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 a partir de documentos rotulados

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

Enquanto a importação de Document estiver em andamento, os rótulos de esquema recém-adicionados serão adicionados ao editor de esquemas. Selecione "Editar esquema" para verificar ou mudar o tipo de dados e de ocorrência dos novos rótulos de esquema. Depois de confirmar, selecione rótulos de esquema e clique em Ativar.

Conjuntos de dados de amostra

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

Eles podem ser usados para treinamento avançado 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/

Processo de identificação