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 o descrizioni positivi e negativi 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 esaminarli e comprenderli 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 a quello 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à.

Istruzioni PDF 1

Istruzioni PDF 2

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

Aggiungere istruzioni a un progetto

UI web

  1. Apri l'interfaccia utente di Data Labeling Service.

    La pagina Istruzioni mostra lo stato delle istruzioni create in precedenza per il progetto corrente.

    Per aggiungere istruzioni per un altro progetto, selezionalo dall'elenco a discesa in alto a destra nella barra del titolo.

  2. Fai clic sul pulsante Crea nella barra del titolo.

  3. Nella pagina Nuova istruzione, inserisci un nome e una descrizione per il file di istruzioni.

  4. Dal menu a discesa Tipo di dati, scegli il tipo di elementi di dati a cui gli etichettatori applicheranno le etichette: immagini, video o testo.

  5. Nella sezione Posizione delle istruzioni, inserisci il percorso completo del file di istruzioni.

    Devi specificare un file di istruzioni PDF. Il file deve trovarsi nello stesso bucket Google Cloud Storage del set di dati e delle etichette impostati.

  6. Fai clic su Crea istruzione.

    Tornerai alla pagina dell'elenco Istruzioni. Le istruzioni mostreranno uno stato in corso durante l'importazione.

Riga di comando

L'esempio seguente crea un set di etichette denominato test_spec_set_display_name. Devi avere definito le variabili di ambiente PROJECT_ID e GCS_PDF_FILE_PATH che rimandano rispettivamente all'ID progetto Google Cloud e all'URI Cloud Storage del PDF che vuoi utilizzare. 
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}"
           }
         },
     }'

Dovresti vedere un output simile al seguente:

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

Python

Prima di poter eseguire questo esempio di codice, devi installare le librerie client Python.

È necessario specificare PdfInstruction. Per le istruzioni relative ad altri tipi di dati, sostituire dataType da "IMAGE" ai tipi di dati corrispondenti.

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

Prima di poter eseguire questo esempio di codice, devi installare le librerie client Java.

È necessario specificare PdfInstruction. Per le istruzioni relative ad altri tipi di dati, sostituire dataType da "IMAGE" ai tipi di dati corrispondenti.

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.