Creazione di istruzioni per gli etichettatori umani

Le istruzioni forniscono agli etichettatori umani informazioni su come applicare le etichette ai tuoi dati. Le istruzioni devono contenere dati etichettati di esempio e altre indicazioni esplicite.

AI Platform Data Labeling Service supporta le istruzioni PDF:

• Istruzioni PDF. Le istruzioni in formato PDF possono fornire indicazioni sofisticate, come esempi positivi e negativi o descrizioni per ogni caso. È anche più comodo da creare, soprattutto per alcune attività complesse come i riquadri di delimitazione delle immagini o il monitoraggio di oggetti video.

Un progetto può avere più insiemi di istruzioni, ciascuno utilizzato per una richiesta diversa Data Labeling Service. Puoi ottenere un elenco delle istruzioni disponibili ed eliminare quelle di cui non hai più bisogno. Puoi trovare ulteriori informazioni nella pagina delle risorse relative alle istruzioni.

Progettare istruzioni efficaci

Le istruzioni chiare sono il fattore più importante per ottenere buoni risultati di etichettatura da parte di persone. Poiché conosci meglio il tuo caso d'uso, devi comunicare agli etichettatori umani cosa vuoi che facciano. Ecco alcune linee guida per creare buone istruzioni:

• Gli etichettatori umani non hanno le tue conoscenze del dominio. Le distinzioni che chiedi agli etichettatori di fare devono essere facili da comprendere per chi non conosce il tuo caso d'uso.

• Evita di rendere le istruzioni troppo lunghe. È preferibile che un etichettatore possa esaminarle e comprenderle entro 20 minuti.

• Le istruzioni devono descrivere il concetto dell'attività, nonché i dettagli su come etichettare i dati. Ad esempio, per un'attività con riquadro di delimitazione, descrivi come vuoi che gli etichettatori disegnino il riquadro di delimitazione. Deve essere una scatola stretta o una scatola ampia? Se sono presenti più istanze dell'oggetto, devono essere disegnati un riquadro di delimitazione grande o più riquadri più piccoli?

• Se le istruzioni hanno un set di etichette corrispondente, devono coprire tutte le etichette del set. Il nome dell'etichetta nelle istruzioni deve corrispondere al nome nell'insieme di etichette.

• Spesso sono necessarie diverse iterazioni per creare istruzioni efficaci. Ti consigliamo di iniziare con un piccolo set di dati etichettato, quindi di modificare le istruzioni in base a ciò che vedi nei risultati che ricevi.

Un buon file di istruzioni deve includere le seguenti sezioni:

• Elenco e descrizione delle etichette: elenca tutte le etichette che vuoi utilizzare e descrivi il significato di ciascuna.
• Esempi: per ogni etichetta, fornisci almeno 3 esempi positivi e 1 negativo. Questi esempi dovrebbero coprire casi diversi.
• Coprire i casi limite. Chiarisci il maggior numero possibile di casi limite, in modo da ridurre la necessità per l'etichettatore di interpretare l'etichetta. Ad esempio, se devi disegnare un riquadro di delimitazione per una persona, è meglio chiarire:
  • Se ci sono più persone, ti serve una scatola per ogni persona?
  • Hai bisogno di una casella se una persona è coperta?
  • Hai bisogno di una casella per una persona parzialmente visibile nell'immagine?
  • Hai bisogno di una casella per una persona in una foto o un dipinto?
• Descrivi come aggiungere annotazioni. Ad esempio:
  • Per un riquadro di delimitazione, hai bisogno di una casella stretta o una casella larga?
  • Per l'estrazione delle entità di testo, dove deve iniziare e terminare l'entità interessata?
• Chiarimento sulle etichette. Se due etichette sono simili o facili da confondere, fornisci esempi per chiarire la differenza.

Crea istruzioni

Istruzioni PDF

Gli esempi riportati di seguito mostrano cosa possono includere le istruzioni PDF. I titolisti esamineranno le istruzioni prima di iniziare l'attività.

Puoi creare le istruzioni creando una presentazione Google e poi esportando le diapositive come file PDF.

Aggiungere istruzioni a un progetto

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

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

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

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();
    }
  }
}

Aggiornare le istruzioni in un progetto

Per aggiornare le istruzioni, aggiorna il file delle istruzioni e ricaricalo come descritto in Aggiungere istruzioni a un progetto.

Quando invii un'attività di etichettatura dei dati, il servizio acquisisce uno snapshot del file di istruzioni e lo utilizza per indirizzare l'etichettatura dei dati eseguita dall'attività. In questo modo, il servizio non restituisce risultati incoerenti nel caso in cui aggiorni le istruzioni durante l'esecuzione di un'attività di etichettatura dei dati. Se aggiorni le istruzioni, invia una nuova attività di etichettatura dei dati per poter utilizzare le nuove istruzioni.