Creazione di istruzioni per etichettatori umani

Beta

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

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 direzioni esplicite.

AI Platform Data Labeling Service supporta le istruzioni in formato PDF:

• Istruzioni PDF. Le istruzioni in formato PDF possono fornire indicazioni dettagliate, come descrizioni o esempi positivi e negativi. Inoltre, è più comodo crearlo, soprattutto per attività complicate, come riquadri di delimitazione delle immagini o monitoraggio di oggetti video.

Un progetto può avere più insiemi di istruzioni, ciascuno utilizzato per una diversa richiesta a Data Labeling Service. Puoi visualizzare un elenco delle istruzioni disponibili ed eliminare quelle che non ti servono più. Per ulteriori informazioni, consulta la pagina delle risorse delle istruzioni.

Progetta istruzioni efficaci

Una buona istruzione è il fattore più importante per ottenere buoni risultati di etichettatura umana. Dato che conosci meglio il tuo caso d'uso, devi comunicare agli etichettatori umani cosa vuoi che facciano. Ecco alcune linee guida per creare istruzioni efficaci:

• Gli etichettatori umani non conoscono il tuo dominio. Le distinzioni che chiedi agli etichettatori di fare devono essere facili da capire per qualcuno che non conosce il tuo caso d'uso.

• Dovresti evitare di rendere troppo lunghe le istruzioni. È meglio che un etichettatore possa esaminarli e comprenderli entro 20 minuti.

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

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

• Spesso sono necessarie diverse iterazioni per creare istruzioni efficaci. Ti consigliamo di assegnare prima un piccolo set di dati e poi di modificare le istruzioni in base a ciò che vedi nei risultati ottenuti.

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 ogni etichetta.
• Esempi: per ogni etichetta, fornisci almeno 3 esempi positivi e 1 esempio negativo. Questi esempi devono riguardare casi diversi.
• Cover per casi limite. Chiarisci il maggior numero possibile di casi limite. In questo modo, l'etichettatore non dovrà interpretare l'etichetta. Ad esempio, se devi disegnare un riquadro di delimitazione per una persona, è meglio chiarire:
  • Ti serve una scatola per ogni persona se ci sono più persone?
  • Hai bisogno di una scatola se c'è una persona occulta?
  • Hai bisogno di una scatola per una persona che appare parzialmente nell'immagine?
  • Hai bisogno di una scatola per una persona in un quadro o in un dipinto?
• Descrivi come aggiungere le annotazioni. Ad esempio:
  • Ti serve una scatola stretta o sfusa per un riquadro di delimitazione?
  • Per l'estrazione delle entità di testo, da dove deve iniziare e fine l'entità interessata?
• Chiarimento sulle etichette. Se due etichette sono simili o facili da confondere, fornisci degli esempi per chiarire la differenza.

Crea istruzioni

Istruzioni PDF

I seguenti esempi mostrano cosa possono includere le istruzioni in formato PDF. Gli etichettatori esamineranno le istruzioni prima di iniziare.

Per le istruzioni puoi creare una presentazione Google e poi esportarle 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, seleziona il progetto 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 istruzioni, 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 al file di istruzioni.

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

6. Fai clic su Crea istruzione.

   Tornerai alla pagina con l'elenco Istruzioni. Le istruzioni mostreranno lo stato In corso durante l'importazione.

Riga di comando

L'esempio seguente crea un set di etichette denominato test_spec_set_display_name. Devi aver definito le variabili di ambiente PROJECT_ID e GCS_PDF_FILE_PATH e che puntano 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 di Python.

È necessario specificare PdfInstruction. Per istruzioni relative ad altri tipi di dati, sostituisci dataType da "IMAGE" con i 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 istruzioni relative ad altri tipi di dati, sostituisci dataType da "IMAGE" con i 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();
    }
  }
}

Aggiorna 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 un'istantanea del file di istruzioni e la utilizza per indirizzare l'etichettatura dei dati eseguita da quell'attività. Ciò impedisce al servizio di restituire risultati incoerenti nel caso in cui aggiorni le istruzioni mentre è in corso un'attività di etichettatura dei dati. Se aggiorni le istruzioni, invia una nuova attività di etichettatura dei dati per utilizzare quelle nuove.