Requisitos de la función de Lambda preanotación y postanotación

Utilice esta sección para obtener información sobre la sintaxis de las solicitudes enviadas a las funciones de Lambda preanotación y postanotación, y la sintaxis de respuesta que Ground Truth necesita para ejecutar un flujo de trabajo de etiquetado personalizado.

Lambda de preanotación

Antes de enviar una tarea de etiquetado al trabajador, se invoca la función de Lambda preanotación.

Ground Truth envía a la función de Lambda una solicitud con formato JSON para proporcionar detalles sobre el trabajo de etiquetado y el objeto de datos. La siguiente tabla contiene los esquemas de la solicitud preanotación. A continuación, se describe cada parámetro.

Data object identified with "source-ref"

{
    "version": "2018-10-16",
    "labelingJobArn": <labelingJobArn>
    "dataObject" : {
        "source-ref": <s3Uri>
    }
}

Data object identified with "source"

{
    "version": "2018-10-16",
    "labelingJobArn": <labelingJobArn>
    "dataObject" : {
        "source": <string>
    }
}

• version (cadena): es un número de versión que utiliza internamente Ground Truth.

• labelingJobArn (cadena): es el nombre del recurso de Amazon, o ARN, de su trabajo de etiquetado. Este ARN se puede usar para hacer referencia al trabajo de etiquetado cuando se utilizan operaciones de la API de Ground Truth, como DescribeLabelingJob.

• El dataObject (objeto JSON): la clave contiene una sola línea JSON, ya sea desde el archivo de manifiesto de entrada o enviada desde Amazon SNS. Los objetos de línea JSON de su manifiesto pueden tener un tamaño de 100 kilobytes como máximo y contener una gran variedad de datos. Para un trabajo de anotación de imágenes muy básico, es posible que el JSON dataObject solo contenga una clave source-ref que identifique la imagen que se va a anotar. Si el objeto de datos (por ejemplo, una línea de texto) se incluye directamente en el archivo de manifiesto de entrada, el objeto de datos se identifica con source. Si crea un trabajo de verificación o ajuste, esta línea puede contener datos de etiqueta y metadatos del trabajo de etiquetado anterior.

La siguiente tabla incluye ejemplos de bloques de código de una solicitud preanotación. Cada parámetro de estas solicitudes de ejemplo se explica debajo de la tabla con pestañas.

Data object identified with "source-ref"

{
    "version": "2018-10-16",
    "labelingJobArn": "arn:aws:sagemaker:<aws_region>:<aws_account_number>:labeling-job/<labeling_job_name>"
    "dataObject" : {
        "source-ref": "s3://<input-data-bucket>/<data-object-file-name>"
    }
}

Data object identified with "source"

{
    "version": "2018-10-16",
    "labelingJobArn": "arn:aws:sagemaker:<aws_region>:<aws_account_number>:labeling-job/<labeling_job_name>"
    "dataObject" : {
        "source": "Sue purchased 10 shares of the stock on April 10th, 2020"
    }
}

A cambio, Ground Truth requiere una respuesta con el siguiente formato:

ejemplo de datos devueltos previstos

{
    "taskInput": <json object>,
    "isHumanAnnotationRequired": <boolean> # Optional
}

En el ejemplo anterior, <json object> debe contener todos los datos que necesita su plantilla de tarea de trabajador personalizado. Si está llevando a cabo una tarea de cuadro delimitador donde las instrucciones no cambien en ningún momento, podría simplemente ser el recurso de HTTP(S) o Amazon S3 para su archivo de imagen. Si se trata de una tarea de análisis de opinión y diferentes objetos pueden tener diferentes opciones, es la referencia de objeto como una cadena y las opciones como una matriz de cadenas.

Implicaciones de isHumanAnnotationRequired

Este valor es opcional, ya que su valor predeterminado será true. El principal caso de uso para establecerlo de forma explícita es cuando se desea excluir este objeto de datos de su etiquetado por parte de trabajadores humanos.

Si tiene una combinación de objetos en el manifiesto, con algunos objetos que requieren anotaciones humanas y otros que no los necesitan, puede incluir un valor isHumanAnnotationRequired en cada objeto de datos. Puede añadir lógica a su Lambda preanotación para determinar dinámicamente si un objeto requiere una anotación y establecer este valor booleano en consecuencia.

Ejemplos de funciones de Lambda preanotación

La siguiente función de Lambda preanotación básica accede al objeto JSON en dataObject desde la solicitud inicial y lo devuelve en el parámetro taskInput.

import json

def lambda_handler(event, context):
    return {
        "taskInput":  event['dataObject']
    }

Suponiendo que el archivo de manifiesto de entrada utiliza "source-ref" para identificar objetos de datos, la plantilla de tareas de trabajador que se utiliza en el mismo trabajo de etiquetado que esta función de Lambda preanotación debe incluir un elemento Liquid como el siguiente para su ingerir dataObject.

{{ task.input.source-ref | grant_read_access }}

Si el archivo de manifiesto de entrada utilizó source para identificar el objeto de datos, la plantilla de tareas de trabajador puede ingerir dataObject con lo siguiente:

{{ task.input.source }}

El siguiente ejemplo de Lambda preanotación incluye lógica para identificar la clave utilizada en dataObject y apuntar a ese objeto de datos mediante taskObject en la instrucción de devolución de Lambda.

import json

def lambda_handler(event, context):

    # Event received
    print("Received event: " + json.dumps(event, indent=2))

    # Get source if specified
    source = event['dataObject']['source'] if "source" in event['dataObject'] else None

    # Get source-ref if specified
    source_ref = event['dataObject']['source-ref'] if "source-ref" in event['dataObject'] else None

    # if source field present, take that otherwise take source-ref
    task_object = source if source is not None else source_ref

    # Build response object
    output = {
        "taskInput": {
            "taskObject": task_object
        },
        "humanAnnotationRequired": "true"
    }

    print(output)
    # If neither source nor source-ref specified, mark the annotation failed
    if task_object is None:
        print(" Failed to pre-process {} !".format(event["labelingJobArn"]))
        output["humanAnnotationRequired"] = "false"

    return output

La función Lambda de postanotación

Cuando todos los trabajadores hayan anotado el objeto de datos o cuando se haya alcanzado TaskAvailabilityLifetimeInSeconds, lo que ocurra primero, Ground Truth envía esas anotaciones a su Lambda postanotación. Esta función Lambda se suele utilizar para Consolidar anotaciones.

sugerencia

Para ver un ejemplo de una función Lambda posterior a la consolidación, consulte annotation_consolidation_lambda.py en aws-sagemaker-ground-truthel GitHub repositorio -recipe.

La siguiente tabla contiene los esquemas de la solicitud postanotación. En la siguiente lista con viñetas se describe cada uno de los parámetros.

{
    "version": "2018-10-16",
    "labelingJobArn": <string>,
    "labelCategories": [<string>],
    "labelAttributeName": <string>,
    "roleArn" : <string>,
    "payload": {
        "s3Uri": <string>
    }
 }

• version (cadena): un número de versión que utiliza internamente Ground Truth.

• labelingJobArn (cadena): el nombre del recurso de Amazon, o ARN, de su trabajo de etiquetado. Este ARN se puede usar para hacer referencia al trabajo de etiquetado cuando se utilizan operaciones de la API de Ground Truth, como DescribeLabelingJob.

• labelCategories (lista de cadenas): incluye las categorías de etiquetas y otros atributos que especificó en la consola o que incluyó en el archivo de configuración de categorías de etiquetas.

• labelAttributeName (cadena): el nombre del trabajo de etiquetado o el nombre del atributo de etiqueta que especificó al crear el trabajo de etiquetado.

• roleArn (cadena): el nombre de recurso de Amazon (ARN) del rol de ejecución de IAM que se especifica al crear el trabajo de etiquetado.

• payload (objeto JSON): un JSON que incluye una clave s3Uri que identifica la ubicación de los datos de anotación de ese objeto de datos en Amazon S3. El segundo bloque de código que aparece a continuación muestra un ejemplo de este archivo de anotaciones.

En el siguiente bloque de código se incluye un ejemplo de una solicitud postanotación. Cada parámetro de esta solicitud de ejemplo se explica debajo del bloque de código.

ejemplo de una solicitud Lambda postanotación

{
    "version": "2018-10-16",
    "labelingJobArn": "arn:aws:sagemaker:us-west-2:111122223333:labeling-job/labeling-job-name",
    "labelCategories": ["Ex Category1","Ex Category2", "Ex Category3"],
    "labelAttributeName": "labeling-job-attribute-name",
    "roleArn" : "arn:aws:iam::111122223333:role/role-name",
    "payload": {
        "s3Uri": "s3://DOC-EXAMPLE-BUCKET/annotations.json"
    }
 }

nota

Si ningún trabajador trabaja en el objeto de datos y se ha alcanzado TaskAvailabilityLifetimeInSeconds, el objeto de datos se marca como erróneo y no se incluirá como parte de la invocación de Lambda postanotación.

El siguiente bloque de código contiene el esquema de carga. Este es el archivo que indica el parámetro s3Uri en el objeto JSON de la solicitud Lambda postanotación payload. Por ejemplo, si el bloque de código anterior es la solicitud Lambda postanotación, el siguiente archivo de anotaciones se encuentra en s3://DOC-EXAMPLE-BUCKET/annotations.json.

En la siguiente lista con viñetas se describe cada uno de los parámetros.

ejemplo de un archivo de anotaciones

[
    {
        "datasetObjectId": <string>,
        "dataObject": {
            "s3Uri": <string>,
            "content": <string>
        },
        "annotations": [{
            "workerId": <string>,
            "annotationData": {
                "content": <string>,
                "s3Uri": <string>
            }
       }]
    }
]

• datasetObjectId (cadena): identifica un identificador único que Ground Truth asigna a cada objeto de datos que envíe al trabajo de etiquetado.

• dataObject (objeto JSON): el objeto de datos que se etiquetó. Si el objeto de datos está incluido en el archivo de manifiesto de entrada y se identifica mediante la clave source (por ejemplo, una cadena), dataObject incluye una clave content que identifica el objeto de datos. De lo contrario, ubicación del objeto de datos (por ejemplo, un enlace o un URI de S3) se identifica con s3Uri.

• annotations (lista de objetos JSON): esta lista contiene un único objeto JSON por cada anotación enviada por los trabajadores para ese dataObject. Un único objeto JSON contiene un workerId único que se puede utilizar para identificar al trabajador que envió esa anotación. La clave annotationData contiene uno de los siguientes valores:

  • content (cadena): contiene los datos de la anotación.

  • s3Uri (cadena): contiene un URI de S3 que identifica la ubicación de los datos de anotación.

La siguiente tabla contiene ejemplos del contenido que puede encontrar en la carga para distintos tipos de anotaciones.

Named Entity Recognition Payload

[
    {
      "datasetObjectId": "1",
      "dataObject": {
        "content": "Sift 3 cups of flour into the bowl."
      },
      "annotations": [
        {
          "workerId": "private.us-west-2.ef7294f850a3d9d1",
          "annotationData": {
            "content": "{\"crowd-entity-annotation\":{\"entities\":[{\"endOffset\":4,\"label\":\"verb\",\"startOffset\":0},{\"endOffset\":6,\"label\":\"number\",\"startOffset\":5},{\"endOffset\":20,\"label\":\"object\",\"startOffset\":15},{\"endOffset\":34,\"label\":\"object\",\"startOffset\":30}]}}"
          }
        }
      ]
    }
]

Semantic Segmentation Payload

[
    {
      "datasetObjectId": "2",
      "dataObject": {
        "s3Uri": "s3://DOC-EXAMPLE-BUCKET/gt-input-data/images/bird3.jpg"
      },
      "annotations": [
        {
          "workerId": "private.us-west-2.ab1234c5678a919d0",
          "annotationData": {
            "content": "{\"crowd-semantic-segmentation\":{\"inputImageProperties\":{\"height\":2000,\"width\":3020},\"labelMappings\":{\"Bird\":{\"color\":\"#2ca02c\"}},\"labeledImage\":{\"pngImageData\":\"iVBOR...\"}}}"
          }
        }
      ]
    }
  ]

Bounding Box Payload

[
    {
      "datasetObjectId": "0",
      "dataObject": {
        "s3Uri": "s3://DOC-EXAMPLE-BUCKET/gt-input-data/images/bird1.jpg"
      },
      "annotations": [
        {
          "workerId": "private.us-west-2.ab1234c5678a919d0",
          "annotationData": {
            "content": "{\"boundingBox\":{\"boundingBoxes\":[{\"height\":2052,\"label\":\"Bird\",\"left\":583,\"top\":302,\"width\":1375}],\"inputImageProperties\":{\"height\":2497,\"width\":3745}}}"
          }
        }
      ]
    }
 ]

La función de Lambda postanotación puede contener una lógica similar a la siguiente para recorrer y acceder a todas las anotaciones contenidas en la solicitud. Para ver un ejemplo completo, consulte annotation_consolidation_lambda.py en el aws-sagemaker-ground-truth repositorio -recipe. GitHub En este GitHub ejemplo, debe añadir su propia lógica de consolidación de anotaciones.

for i in range(len(annotations)):
    worker_id = annotations[i]["workerId"]
    annotation_content = annotations[i]['annotationData'].get('content')
    annotation_s3_uri = annotations[i]['annotationData'].get('s3uri')
    annotation = annotation_content if annotation_s3_uri is None else s3_client.get_object_from_s3(
        annotation_s3_uri)
    annotation_from_single_worker = json.loads(annotation)

    print("{} Received Annotations from worker [{}] is [{}]"
            .format(log_prefix, worker_id, annotation_from_single_worker))

sugerencia

Al ejecutar algoritmos de consolidación en los datos, puede utilizar un servicio de base de datos AWS para almacenar los resultados o puede devolver los resultados procesados a Ground Truth. Los datos que devuelva a Ground Truth se almacenan en manifiestos de anotaciones consolidados en el bucket de S3 especificado para la salida durante la configuración del trabajo de etiquetado.

A cambio, Ground Truth requiere una respuesta con el siguiente formato:

ejemplo de datos devueltos previstos

[
   {        
        "datasetObjectId": <string>,
        "consolidatedAnnotation": {
            "content": {
                "<labelattributename>": {
                    # ... label content
                }
            }
        }
    },
   {        
        "datasetObjectId": <string>,
        "consolidatedAnnotation": {
            "content": {
                "<labelattributename>": {
                    # ... label content
                }
            }
        }
    }
    .
    .
    .
]

En este punto, todos los datos que envíe a su bucket de S3 que no sean datasetObjectId están en el objeto content.

Cuando devuelve anotaciones en content, se obtiene una entrada en el manifiesto de salida de su trabajo como la siguiente:

ejemplo de formato de etiqueta en manifiesto de salida

{  "source-ref"/"source" : "<s3uri or content>", 
   "<labelAttributeName>": {
        # ... label content from you
    },   
   "<labelAttributeName>-metadata": { # This will be added by Ground Truth
        "job_name": <labelingJobName>,
        "type": "groundTruth/custom",
        "human-annotated": "yes", 
        "creation_date": <date> # Timestamp of when received from Post-labeling Lambda
    }
}

Debido a la naturaleza potencialmente compleja de una plantilla personalizada y de los datos que recopila, Ground Truth no ofrece un procesamiento más amplio de los datos.