Como criar instruções para rotuladores humanos

Beta

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

As instruções oferecem aos rotuladores humanos informações sobre como aplicar rótulos aos seus dados. As instruções devem conter exemplos de dados rotulados e outras orientações explícitas.

O serviço de rotulagem de dados do AI Platform é compatível com instruções em PDF:

• Instruções em PDF. As instruções em PDF podem oferecer orientações sofisticadas, como exemplos positivos e negativos ou descrições para cada caso. Também são mais práticas de serem criadas especialmente para algumas tarefas complicadas, como caixas delimitadoras de imagens ou rastreamento de objetos de vídeo.

Um projeto pode ter vários conjuntos de instruções, cada um usado para uma solicitação diferente do serviço de rotulagem de dados. É possível conseguir uma lista com as instruções disponíveis e excluir instruções desnecessárias. Consulte a página de recursos de instruções para mais informações.

Criar boas instruções

Boas instruções são o fator mais importante para conseguir bons resultados de rotulagem humana. Como você conhece melhor seu caso de uso, é preciso deixar os rotuladores humanos saberem o que você quer que eles façam. Aqui estão algumas diretrizes para criar boas instruções:

• Os rotuladores humanos não têm conhecimento do seu domínio. As distinções que você pede aos rotuladores precisam ser fáceis de serem compreendidas por alguém não familiarizado com seu caso de uso.

• Evite deixar as instruções muito longas. É bom que um rotulador possa analisá-las e compreendê-las em até 20 minutos.

• As instruções precisam descrever o conceito da tarefa, bem como detalhes sobre como rotular os dados. Por exemplo, para uma tarefa com caixa delimitadora, descreva como você quer que os rotuladores desenhem a caixa delimitadora. Será uma caixa justa ou folgada? Se houver várias instâncias do objeto, eles precisarão desenhar uma caixa delimitadora grande ou várias menores?

• Se as instruções têm um conjunto de rótulos correspondente, elas precisam abranger todos os rótulos nesse conjunto. O nome do rótulo nas instruções precisa corresponder ao nome no conjunto de rótulos.

• Geralmente, são necessárias várias iterações para criar boas instruções. Recomendamos que você rotule um conjunto de dados pequeno primeiro e depois ajuste suas instruções com base no que vê nos resultados recebidos.

Um bom arquivo de instruções precisa incluir as seções a seguir:

• Lista de rótulos e descrição: liste todos os rótulos que você quer usar e descreva o significado de cada um deles.
• Exemplos: para cada rótulo, forneça pelo menos três exemplos positivos e um negativo. Esses exemplos precisam cobrir casos diferentes.
• Cubra os casos extremos. Esclareça o máximo de casos extremos que puder. Isso reduz a necessidade de o rotulador interpretar o rótulo. Por exemplo, se você precisa desenhar uma caixa delimitadora para uma pessoa, é melhor esclarecer os itens abaixo:
  • Você precisará de uma caixa por pessoa se houver várias pessoas?
  • Você precisará da caixa se uma pessoa estiver obstruída?
  • Você precisará de uma caixa para uma pessoa que é mostrada parcialmente na imagem?
  • Você precisará de uma caixa para uma pessoa em uma foto ou pintura?
• Descreva como adicionar anotações. Por exemplo:
  • Você precisa de uma caixa delimitadora justa ou folgada?
  • Para a extração de entidade de texto, onde a entidade interessada começará e terminará?
• Esclarecimento nos rótulos. Se dois rótulos são semelhantes ou fáceis de serem confundidos, ofereça exemplos para esclarecer a diferença.

Criar instruções

Instruções em PDF

Abaixo, mostramos exemplos do que as instruções em PDF podem incluir. Os marcadores analisarão as instruções antes de iniciarem a tarefa.

É possível criar as instruções criando um arquivo no Apresentações Google e exportando os slides como um arquivo PDF.

Adicionar instruções a um projeto

IU da Web

1. Abra a IU do serviço de rotulagem de dados.

   A página Instruções mostra o status das instruções criadas anteriormente para o projeto atual.

   Para adicionar instruções a um projeto diferente, selecione o projeto na lista suspensa no canto superior direito da barra de título.

2. Clique no botão Criar na barra de título.

3. Na página Nova instrução, insira um nome e uma descrição para o arquivo de instruções.

4. Na lista suspensa Tipo de dados, escolha o tipo de itens de dados para os quais os rotuladores aplicarão rótulos: imagem, vídeo ou texto.

5. Na seção Localização das instruções, insira o caminho completo para os arquivos de instruções.

   Especifique um arquivo de instruções em PDF. O arquivo precisa estar no mesmo bucket do Google Cloud Storage que o conjunto de dados e de rótulos.

6. Clique em Criar instrução.

   Você retornará à página da lista de Instruções. Suas instruções vão mostrar um status em andamento enquanto estiverem sendo importadas.

Linha de comando

No exemplo a seguir, criamos um conjunto de rótulos chamado test_spec_set_display_name. É preciso ter as variáveis de ambiente PROJECT_ID e GCS_PDF_FILE_PATH definidas e apontando para o ID do projeto do Google Cloud e para o URI do Cloud Storage do PDF que você quer usar, respectivamente.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json" \
     https://datalabeling.googleapis.com//v1beta1/projects/${PROJECT_ID}/instructions \
     -d '{
         "instruction": {
             "displayName": "curl_testing_instruction",
             "description": "instruction for curl commands testing",
             "dataType": "IMAGE",
           "pdfInstruction": {
                 "gcsFileUri": "${GCS_PDF_FILE_PATH}"
           }
         },
     }'

A saída será semelhante a esta:

{
  "name": "projects/data-labeling-codelab/instructions/5c73dbc1_0000_23e0_a25b_94eb2c119c4c"
}

Python

Antes de executar este código de exemplo, você precisa instalar as bibliotecas de cliente do Python.

PdfInstruction precisa ser fornecido. Para instruções de outros tipos de dados substitua dataType de "IMAGE" por tipos de dados correspondentes.

def create_instruction(project_id, data_type, instruction_gcs_uri):
    """Creates a data labeling PDF instruction for the given Google Cloud
    project. The PDF file should be uploaded to the project in
    Google Cloud Storage.
    """
    from google.cloud import datalabeling_v1beta1 as datalabeling

    client = datalabeling.DataLabelingServiceClient()

    project_path = f"projects/{project_id}"

    pdf_instruction = datalabeling.PdfInstruction(gcs_file_uri=instruction_gcs_uri)

    instruction = datalabeling.Instruction(
        display_name="YOUR_INSTRUCTION_DISPLAY_NAME",
        description="YOUR_DESCRIPTION",
        data_type=data_type,
        pdf_instruction=pdf_instruction,
    )

    operation = client.create_instruction(
        request={"parent": project_path, "instruction": instruction}
    )

    result = operation.result()

    # The format of the resource name:
    # project_id/{project_id}/instruction/{instruction_id}
    print(f"The instruction resource name: {result.name}")
    print(f"Display name: {result.display_name}")
    print(f"Description: {result.description}")
    print("Create time:")
    print(f"\tseconds: {result.create_time.timestamp_pb().seconds}")
    print(f"\tnanos: {result.create_time.timestamp_pb().nanos}")
    print(f"Data type: {datalabeling.DataType(result.data_type).name}")
    print("Pdf instruction:")
    print(f"\tGcs file uri: {result.pdf_instruction.gcs_file_uri}\n")

    return result

Java

Antes de executar este código de exemplo, é preciso instalar as bibliotecas de cliente do Java.

PdfInstruction precisa ser fornecido. Para instruções de outros tipos de dados substitua dataType de "IMAGE" por tipos de dados correspondentes.

import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.datalabeling.v1beta1.CreateInstructionMetadata;
import com.google.cloud.datalabeling.v1beta1.CreateInstructionRequest;
import com.google.cloud.datalabeling.v1beta1.DataLabelingServiceClient;
import com.google.cloud.datalabeling.v1beta1.DataLabelingServiceSettings;
import com.google.cloud.datalabeling.v1beta1.DataType;
import com.google.cloud.datalabeling.v1beta1.Instruction;
import com.google.cloud.datalabeling.v1beta1.PdfInstruction;
import com.google.cloud.datalabeling.v1beta1.ProjectName;
import java.io.IOException;
import java.util.concurrent.ExecutionException;

class CreateInstruction {

  // Create a instruction for a dataset.
  static void createInstruction(String projectId, String pdfUri) throws IOException {
    // String projectId = "YOUR_PROJECT_ID";
    // String pdfUri = "gs://YOUR_BUCKET_ID/path_to_pdf_or_csv";

    DataLabelingServiceSettings settings =
        DataLabelingServiceSettings.newBuilder()
            .build();
    try (DataLabelingServiceClient dataLabelingServiceClient =
        DataLabelingServiceClient.create(settings)) {
      ProjectName projectName = ProjectName.of(projectId);

      // There are two types of instructions: CSV (CsvInstruction) or PDF (PdfInstruction)
      PdfInstruction pdfInstruction = PdfInstruction.newBuilder().setGcsFileUri(pdfUri).build();

      Instruction instruction =
          Instruction.newBuilder()
              .setDisplayName("YOUR_INSTRUCTION_DISPLAY_NAME")
              .setDescription("YOUR_DESCRIPTION")
              .setDataType(DataType.IMAGE) // DataTypes: AUDIO, IMAGE, VIDEO, TEXT
              .setPdfInstruction(pdfInstruction) // .setCsvInstruction() or .setPdfInstruction()
              .build();

      CreateInstructionRequest createInstructionRequest =
          CreateInstructionRequest.newBuilder()
              .setInstruction(instruction)
              .setParent(projectName.toString())
              .build();

      OperationFuture<Instruction, CreateInstructionMetadata> operation =
          dataLabelingServiceClient.createInstructionAsync(createInstructionRequest);

      Instruction result = operation.get();

      System.out.format("Name: %s\n", result.getName());
      System.out.format("DisplayName: %s\n", result.getDisplayName());
      System.out.format("Description: %s\n", result.getDescription());
      System.out.format("GCS SOURCE URI: %s\n", result.getPdfInstruction().getGcsFileUri());
    } catch (IOException | InterruptedException | ExecutionException e) {
      e.printStackTrace();
    }
  }
}

Atualizar instruções em um projeto

Para atualizar as instruções, atualize o arquivo de instruções e faça um novo upload conforme descrito em Adicionar instruções a um projeto.

Quando você envia uma tarefa de rotulagem de dados, o serviço recebe um instantâneo do arquivo de instruções e o usa para direcionar a rotulagem de dados realizada por essa tarefa. Isso impede que o serviço retorne resultados inconsistentes no caso em que você atualiza as instruções enquanto uma tarefa de rotulagem de dados está em andamento. Se você atualizar as instruções, envie uma nova tarefa de rotulagem de dados para usar as novas instruções.