Crea instrucciones para las personas a cargo del etiquetado

Las instrucciones proporcionan a los etiquetadores información sobre cómo aplicar etiquetas a los datos. Las instrucciones deben contener muestras de datos etiquetados y otras indicaciones explícitas.

El Servicio de etiquetado de datos de AI Platform admite instrucciones en formato PDF:

  • Instrucciones en PDF: Con las instrucciones en PDF puedes proporcionar indicaciones sofisticadas, como ejemplos positivos y negativos o descripciones para cada caso. También es más conveniente crearlas para algunas tareas complicadas, como los cuadros de límite de imágenes o el seguimiento de objetos de video.

Un proyecto puede tener varios conjuntos de instrucciones, cada uno usado para una solicitud diferente del Servicio de etiquetado de datos. Puedes obtener una lista de las instrucciones disponibles y borrar las instrucciones que ya no necesitas. Puedes encontrar más información en la página de recursos de instrucciones.

Diseña buenas instrucciones

Las instrucciones buenas son el factor más importante para obtener buenos resultados con el etiquetado realizado por personas. Dado que conoces mejor tu caso práctico, debes informarles a las personas que realizarán el etiquetado qué es lo que quieres que hagan. Estos son algunos lineamientos para crear buenas instrucciones:

  • Los etiquetadores no tienen tus conocimientos del tema. Las distinciones que les solicites a los etiquetadores deben ser fáciles de entender para alguien que no esté familiarizado con tu caso práctico.

  • Evita que las instrucciones sean demasiado extensas. Lo mejor es que el etiquetador pueda revisarlas y entenderlas en 20 minutos.

  • En las instrucciones debes describir el concepto de la tarea, además de los detalles sobre cómo etiquetar los datos. Por ejemplo, para una tarea de cuadros de límite, describe cómo deseas que los etiquetadores dibujen el cuadro. ¿Debería ser un cuadro restrictivo o más amplio? Si hay varias instancias del objeto, ¿deberían dibujar un solo cuadro de límite grande o varios más pequeños?

  • Si tienes instrucciones para un conjunto de etiquetas correspondiente, debes abarcar todas las etiquetas de ese conjunto. El nombre de la etiqueta en las instrucciones debe coincidir con el nombre en el conjunto de etiquetas.

  • A menudo, se necesitan varias iteraciones para crear instrucciones buenas. Recomendamos etiquetar primero un conjunto de datos pequeño y, luego, ajustar las instrucciones de acuerdo con lo que se vea en los resultados obtenidos.

Un buen archivo de instrucciones debe incluir las siguientes secciones:

  • Lista de etiquetas y descripción: Enumera todas las etiquetas que desearías usar y describe el significado de cada una
  • Ejemplos: Para cada etiqueta, da al menos 3 ejemplos positivos y 1 ejemplo negativo. Deberías abarcar diferentes casos con estos ejemplos
  • Abarca los casos extremos. Aclara tantos casos extremos como puedas. De esta forma, se reduce la necesidad de que el etiquetador deba interpretar la etiqueta. Por ejemplo, si necesitas dibujar un cuadro de límite para una persona, es mejor aclarar lo siguiente:
    • Si hay varias personas, ¿necesitas un cuadro para cada una?
    • ¿Necesitas un cuadro si una persona está oculta?
    • ¿Necesitas un cuadro para una persona que se vea parcialmente en la imagen?
    • ¿Necesitas un cuadro para una persona en una foto o pintura?
  • Describe cómo agregar anotaciones. Por ejemplo:
    • Para un cuadro de límite, ¿necesitas un cuadro restrictivo o más amplio?
    • Para la extracción de entidades de texto, ¿dónde debería comenzar y terminar la entidad de interés?
  • Aclaración de las etiquetas: Si dos etiquetas son similares o se pueden confundir con facilidad, brinda ejemplos para aclarar la diferencia

Crea instrucciones

Instrucciones en PDF

En los siguientes ejemplos, se muestra lo que pueden incluir las instrucciones en PDF. Los etiquetadores revisarán las instrucciones antes de comenzar la tarea.

Instrucciones en PDF 1

Instrucciones en PDF 2

Puedes crear un archivo de Presentaciones de Google y, luego, exportarlo como PDF para generar las instrucciones.

Agrega instrucciones a un proyecto

IU web

  1. Abre la IU del Servicio de etiquetado de datos.

    En la página Instrucciones, se muestra el estado de las instrucciones creadas antes para el proyecto actual.

    A fin de agregar instrucciones para un proyecto diferente, selecciona el proyecto de la lista desplegable en la esquina superior derecha de la barra de título.

  2. Haz clic en el botón Crear en la barra de título.

  3. En la página Instrucción nueva, ingresa un nombre y una descripción para el archivo de instrucciones.

  4. En el menú desplegable Tipo de datos, elige el tipo de elementos de los datos a los que los etiquetadores aplicarán etiquetas: imágenes, videos o texto.

  5. En la sección Instrucciones de ubicación, ingresa la ruta de acceso completa al archivo de instrucciones.

    Debes especificar un archivo de instrucciones PDF. El archivo debe estar en el mismo bucket de Google Cloud Storage que el conjunto de datos y el conjunto de etiquetas.

  6. Haz clic en Crear instrucción.

    Regresarás a la página de la lista de Instrucciones. En las instrucciones se mostrará un estado de proceso en curso mientras se importan.

Línea de comandos

En el siguiente ejemplo, se crea un conjunto de etiquetas llamado test_spec_set_display_name. Las variables de entorno PROJECT_ID y GCS_PDF_FILE_PATH deben estar definidas y apuntar al ID del proyecto de Google Cloud y al URI de Cloud Storage del PDF que deseas 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}"
           }
         },
     }'

Debería ver un resultado similar al siguiente:

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

Python

Antes de que puedas ejecutar este ejemplo de código, debes instalar las bibliotecas cliente de Python.

Debe proporcionarse PdfInstruction. Para obtener instrucciones de otros tipos de datos, reemplaza dataType de “IMAGE” por los tipos de datos correspondientes.

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 que puedas ejecutar este ejemplo de código, debes instalar las bibliotecas cliente de Java.

Debe proporcionarse PdfInstruction. Para obtener instrucciones de otros tipos de datos, reemplaza dataType de “IMAGE” por los tipos de datos correspondientes.

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

Actualiza instrucciones en un proyecto

Para actualizar las instrucciones, actualiza el archivo de instrucciones y, luego, vuelve a subirlo como se describe en Agrega instrucciones a un proyecto.

Cuando envías una tarea de etiquetado de datos, el servicio toma una instantánea del archivo de instrucciones y la utiliza para dirigir el etiquetado de datos realizado por esa tarea. Esto evita que el servicio muestre resultados incoherentes en el caso de que actualices las instrucciones mientras se ejecuta una tarea de etiquetado. Si actualizas las instrucciones, envía una tarea nueva de etiquetado de datos para que se usen las instrucciones nuevas.