注释前和注释后 Lambda 函数要求

使用本节可以了解发送到注释前和注释后 Lambda 函数的请求的语法，以及 Ground Truth 运行自定义标注工作流所需的响应语法。

注释前 Lambda

在将标注任务发送给工作人员之前，会调用注释前 Lambda 函数。

Ground Truth 向您的 Lambda 函数发送一个 JSON 格式的请求，以提供有关标注作业和数据对象的详细信息。下表包含注释前请求模式。每个参数的说明如下。

下表包括注释前请求的代码块示例。这些示例请求中的每个参数都在选项卡式表下面进行了说明。

作为返回对象，Ground Truth 需要如下格式的响应：

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

在前面的示例中，<json object> 需要包含自定义工作人员任务模板所需的所有数据。如果您正在执行一个边界框任务，其中指令始终保持不变，那么可能只是图像文件的 HTTP(S) 或 Amazon S3 资源。如果执行的是情绪分析任务，并且不同的对象可能有不同的选择，那么是作为字符串的对象引用和作为字符串数组的选项。

如果清单中的对象多种多样，有些需要人工注释，有些则不需要，那么可以在每个数据对象中包含 isHumanAnnotationRequired 值。您可以在注释前 Lambda 中添加逻辑，以动态确定对象是否需要注释，并相应地设置该布尔值。

注释前 Lambda 函数的示例

下面的基本注释前 Lambda 函数从初始请求访问 dataObject 中的 JSON 对象，并在 taskInput 参数中返回该对象。

import json

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

假设输入清单文件使用 "source-ref" 来标识数据对象，那么在与此注释前 Lambda 相同的标注作业中使用的工作人员任务模板必须包含类似下面的 Liquid 元素，以摄取 dataObject：

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

如果输入清单文件使用 source 来标识数据对象，那么工作任务模板可以通过以下方式摄取 dataObject：

{{ task.input.source }}

下面的注释前 Lambda 示例包含一个逻辑，用于识别 dataObject 中使用的键，并在 Lambda 的返回语句中使用 taskObject 指向该数据对象。

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

当所有工作人员都注释了数据对象或达到 TaskAvailabilityLifetimeInSeconds（以先到者为准）时，Ground Truth 将这些注释发送到您的注释后 Lambda。此 Lambda 通常用于合并注释。

以下代码块包含注释后请求模式。下面的项目符号列表中描述了每个参数。

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

以下代码块包含注释后请求的示例。此示例请求中的每个参数都在代码块下面进行了说明。

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

下面的代码块包含负载模式。这是由注释后 Lambda 请求 payload JSON 对象中的 s3Uri 参数指示的文件。例如，如果前面的代码块是注释后 Lambda 请求，则下面的注释文件位于 s3://DOC-EXAMPLE-BUCKET/annotations.json。

下面的项目符号列表中描述了每个参数。

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

下表包含了您可以在不同类型注释的负载中找到的内容示例。

注释后 Lambda 函数可能包含类似下面的逻辑，以循环访问请求中包含的所有注释。有关完整示例，请参阅 aws-sagemaker-ground-truth-recipe GitHub 存储库中的 annotation_consolidation_lambda.py。在此 GitHub 示例中，您必须添加自己的注释合并逻辑。

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

作为返回对象，Ground Truth 需要如下格式的响应：

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

在 content 中返回注释时，会在作业的输出清单中生成一个条目，如下所示：

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

由于自定义模板及其所收集数据的潜在复杂性，Ground Truth 不会对数据进行进一步处理。