Créer des instructions pour les étiqueteurs humains

Bêta

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Les instructions donnent des informations aux étiqueteurs humains quant à la façon dont les étiquettes doivent être appliquées à vos données. Les instructions doivent inclure des exemples de données étiquetées et d’autres instructions explicites.

Le service d'étiquetage de données AI Platform est compatible avec les instructions au format PDF :

• Instructions PDF. Les instructions PDF peuvent fournir des instructions sophistiquées, telles que des descriptions ou exemples positifs et négatifs pour chaque cas. Elles sont par ailleurs plus pratiques à créer si vos tâches sont complexes, par exemple dans le cas de cadres de délimitation d'images ou de suivi d'objets vidéo.

Un projet peut avoir plusieurs ensembles d'instructions, chacun utilisé pour une requête différente envoyée au service d'ajout d'étiquettes aux données. Vous pouvez ainsi obtenir la liste des instructions disponibles et supprimer les instructions dont vous n’avez plus besoin. Pour en savoir plus, consultez la page sur les ressources d'instructions.

Créer des instructions de bonne qualité

Si vous espérez que votre tâche d'ajout d'étiquettes renvoie de bons résultats, vos instructions doivent être de bonne qualité. Personne d'autre que vous ne connaît mieux votre cas d'utilisation : vous devez donc informer les étiqueteurs humains vous-même de ce que vous attendez d'eux. Voici quelques consignes pour créer des instructions de bonne qualité :

• Les étiqueteurs humains n'ont pas votre connaissance du domaine. Lorsque vous leur demandez de faire certaines distinctions, assurez-vous qu'elles soient faciles à comprendre pour une personne qui ne connaît pas votre cas d'utilisation.

• Faites en sorte que les instructions ne soient pas trop longues. Il serait préférable qu'un étiqueteur puisse les réviser et les comprendre en moins de 20 minutes.

• Les instructions doivent décrire le concept de la tâche et donner des détails sur la manière d'étiqueter les données. Par exemple, pour une tâche de cadre de délimitation, décrivez comment vous souhaitez que les étiqueteurs tracent le cadre de délimitation. Le cadre doit-il être restreint ou relativement large ? S'il existe plusieurs instances du même objet, faut-il tracer un grand cadre ou plusieurs petits cadres ?

• Si vos instructions comportent un ensemble d'étiquettes correspondant, elles doivent couvrir toutes les étiquettes de cet ensemble. Le nom d'étiquette donné dans les instructions doit correspondre à celui donné dans l'ensemble d'étiquettes.

• Il faut souvent plusieurs itérations avant d'arriver à créer des instructions de bonne qualité. Nous vous recommandons d'utiliser d'abord un petit ensemble de données, puis de modifier vos instructions en fonction des résultats obtenus.

Un fichier d'instructions de bonne qualité doit inclure les sections suivantes :

• Liste et description des étiquettes : répertoriez toutes les étiquettes que vous souhaitez utiliser et décrivez la signification de chaque étiquette.
• Exemples : pour chaque étiquette, donnez au moins trois exemples positifs et un exemple négatif. Ces exemples doivent couvrir différents cas.
• Couvrez les cas spéciaux. Clarifiez autant de cas spéciaux que possible. Cela réduit la nécessité pour l'étiqueteur d'interpréter l'étiquette. Par exemple, si vous devez dessiner un cadre de délimitation pour une personne, il est préférable de préciser les points suivants :
  • S'il y a plusieurs personnes, avez-vous besoin d'un cadre pour chaque personne ?
  • Avez-vous besoin d'un cadre si une personne est cachée ?
  • Avez-vous besoin d'un cadre pour une personne qui n'apparaît que partiellement dans l'image ?
  • Avez-vous besoin d'un cadre pour une personne figurant dans une photo ou un tableau ?
• Indiquez comment ajouter des annotations. Exemple :
  • Dans le cas d'un cadre de délimitation, avez-vous besoin d'un cadre restreint ou relativement large ?
  • Dans le cas d'une extraction d'entité de texte, où doit commencer et finir l'entité en question ?
• Clarification concernant les étiquettes. Si deux étiquettes sont similaires ou faciles à confondre, donnez des exemples pour clarifier la différence.

Créer des instructions

Instructions PDF

Les exemples ci-dessous présentent ce que peuvent inclure des instructions PDF. Les étiqueteurs examineront les instructions avant de commencer la tâche.

Vous pouvez créer des instructions dans une présentation Google Slides, puis exporter les diapositives au format PDF.

Ajouter des instructions à un projet

UI Web

1. Ouvrez l'interface utilisateur du service d'ajout d'étiquettes aux données.

   La page Instructions indique l'état des instructions créés précédemment pour le projet en cours.

   Si vous souhaitez ajouter une instruction pour un autre projet, sélectionnez-le dans la liste déroulante située dans l'angle supérieur droit de la barre de titre.

2. Cliquez sur le bouton Créer dans la barre de titre.

3. Sur la page Nouvelle instruction, saisissez un nom et une description pour le fichier d'instructions.

4. Dans la liste déroulante Type de données, choisissez le type d'éléments de données auxquels les étiqueteurs appliqueront les étiquettes : images, vidéos ou texte.

5. Dans la section Emplacement des instructions, saisissez le chemin d'accès complet au fichier d'instructions.

   Vous devez spécifier un fichier d'instructions PDF. Le fichier doit figurer dans le même bucket Google Cloud Storage que l'ensemble de données et l'ensemble d'étiquettes.

6. Cliquez sur Créer une instruction.

   Vous êtes redirigé vers la page Instructions. Vos instructions affichent l'état "En cours" pendant l'importation.

Ligne de commande

L'exemple suivant crée un ensemble d'étiquettes nommé test_spec_set_display_name. Les variables d’environnement PROJECT_ID et GCS_PDF_FILE_PATH sont définies et pointent respectivement vers l'ID du projet Google Cloud et vers l’URI de Cloud Storage du fichier PDF que vous souhaitez utiliser.

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

La sortie obtenue doit ressembler à ceci :

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

Python

Avant de pouvoir exécuter cet exemple de code, vous devez installer les bibliothèques clientes Python.

PdfInstruction devrait être fourni. Pour envoyer des instructions pour d'autres types de données, remplacez dataType (actuellement "IMAGE") par le type de données correspondant.

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

Avant de pouvoir exécuter cet exemple de code, vous devez installer les bibliothèques clientes Java.

PdfInstruction devrait être fourni. Pour envoyer des instructions pour d'autres types de données, remplacez dataType (actuellement "IMAGE") par le type de données correspondant.

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

Mettre à jour les instructions dans un projet

Pour mettre à jour les instructions, mettez à jour le fichier d'instructions, puis importez-le à nouveau comme décrit à la section Ajouter des instructions à un projet.

Lorsque vous envoyez une tâche d'ajout d'étiquettes aux données, le service prend un instantané du fichier d'instructions et l'utilise pour diriger l'ajout d'étiquettes aux données effectué par cette tâche. Cela empêche le service de renvoyer des résultats incohérents dans le cas où vous mettez à jour les instructions pendant qu'une tâche d'ajout d'étiquettes aux données est en cours. Si vous mettez à jour les instructions, envoyez une nouvelle tâche d'ajout d'étiquettes aux données afin de pouvoir utiliser les nouvelles instructions.