Exigences relatives à la fonction Lambda de pré-annotation et post-annotation

Utilisez cette section pour en savoir plus sur la syntaxe des requêtes envoyées aux fonctions Lambda pré-annotation et post-annotation, ainsi que sur la syntaxe de réponse requise par Ground Truth pour exécuter un flux d'étiquetage personnalisé.

Lambda de pré-annotation

Avant qu'une tâche d'étiquetage ne soit envoyée à l'employé, votre fonction Lambda de pré-annotation est appelée.

Ground Truth envoie à votre fonction Lambda une demande JSON formatée pour fournir des détails sur la tâche d'étiquetage et l'objet de données. Le tableau suivant contient les schémas de requête de pré-annotation. Chaque paramètre est décrit ci-dessous.

Le tableau suivant inclut des exemples de blocs de code d'une requête de pré-annotation. Chaque paramètre de ces exemples de requêtes est expliqué sous le tableau à onglets.

En retour, Ground Truth nécessite une réponse formatée comme suit :

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

Dans l'exemple précédent, <json object> doit contenir toutes les données dont votre modèle de tâche employé a besoin. Si vous effectuez une tâche encadrée dans laquelle les instructions restent les mêmes en permanence, il se peut qu'il s'agisse simplement de la ressource HTTP (S) ou Amazon S3 pour votre fichier image. S'il s'agit d'une tâche d'analyse de ressenti et que différents objets peuvent comporter des choix différents, la référence de l'objet est une chaîne de caractères et les choix sont un tableau de chaînes de caractères.

Si vous avez un mélange d'objets dans votre manifeste, certains d'entre eux nécessitant une annotation humaine et d'autres pas, vous pouvez inclure une valeur isHumanAnnotationRequired dans chaque objet de données. Vous pouvez ajouter une logique à votre pré-annotation Lambda pour déterminer dynamiquement si un objet nécessite une annotation, et définir cette valeur booléenne en conséquence.

Exemples de fonctions Lambda de pré-annotation

La fonction Lambda de base de pré-annotation suivante accède à JSON l'objet depuis la demande initiale et le renvoie dataObject dans le paramètre. taskInput

import json

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

En supposant que le fichier manifeste source utilise "source-ref" pour identifier les objets de données, le modèle de tâche employé utilisé dans la même tâche d'étiquetage que cette pré-annotation Lambda doit inclure un élément Liquid comme le suivant pour intégrer (les données) dataObject :

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

Si le fichier manifeste source a utilisé source pour identifier l'objet de données, le modèle de tâche employé peut intégrer (les données) dataObject avec les éléments suivants :

{{ task.input.source }}

L'exemple Lambda de pré-annotation suivant inclut une logique pour identifier la clé utilisée dans dataObject, et pour pointer vers cet objet de données en utilisant taskObject dans la déclaration de retour 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

Lambda de post-annotation

Lorsque tous les employés ont annoté l'objet de données ou lorsque TaskAvailabilityLifetimeInSeconds a été atteint, selon la première éventualité, Ground Truth envoie ces annotations à votre fonction Lambda de post-annotation. Cette fonction Lambda est généralement utilisée pour Consolidation des notes.

Le bloc de code suivant contient le schéma de requête de post-annotation. Chaque paramètre est décrit dans la liste à puces suivante.

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

Le bloc de code suivant contient un exemple de requête de post-annotation. Chaque paramètre de cet exemple de requête est expliqué sous le bloc de code.

{
    "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://amzn-s3-demo-bucket/annotations.json"
    }
 }

Le bloc de code suivant contient le schéma de charge utile. Il s'agit du fichier indiqué par le s3Uri paramètre dans l'objet de demande Lambda payload JSON post-annotation. Par exemple, si le bloc de code précédent est la requête Lambda post-annotation, le fichier d'annotation suivant se trouve dans s3://amzn-s3-demo-bucket/annotations.json.

Chaque paramètre est décrit dans la liste à puces suivante.

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

Le tableau suivant contient des exemples de contenu que vous pouvez trouver dans la charge utile pour différents types d'annotations.

Votre fonction Lambda de post-annotation peut contenir une logique similaire à la suivante pour parcourir et accéder à toutes les annotations contenues dans la requête. Pour un exemple complet, consultez le fichier annotation_consolidation_lambda.py dans le GitHub référentiel aws-sagemaker-ground-truth-recipe. Dans cet GitHub exemple, vous devez ajouter votre propre logique de consolidation des annotations.

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))

En retour, Ground Truth nécessite une réponse formatée comme suit :

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

Lorsque vous retournez des annotations dans content, cela génère une entrée dans le manifeste de sortie de votre tâche, comme suit :

{  "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
    }
}

En raison de la nature potentiellement complexe d'un modèle personnalisé et des données qu'il collecte, Ground Truth n'offre pas de traitement ou d'analyse des données.