注释前和注释后 Lambda 函数要求 - Amazon SageMaker
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

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

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

注释前 Lambda

在将标记任务发送到工作线程之前,将调用注释前 Lambda 函数。

Ground Truth 向您的 Lambda 函数发送 JSON 格式的请求,以提供有关标签作业和数据对象的详细信息。下表包含预注释请求模式。下面描述了每个参数。

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(字符串) 这是 Ground Truth 内部使用的版本号。

  • labelingJobArn(字符串) 这是您的贴标任务的 Amazon 资源名称或 ARN。在使用 Ground Truth API 操作时,此 ARN 可用于引用标签作业,例如DescribeLabelingJob.

  • 这些区域有:dataObject(JSON 对象) 密钥包含单个 JSON 行,可以是来自您的输入清单文件或从 Amazon SNS 发送的。清单中的 JSON 行对象的大小最多可达 100 千字节,并且包含各种数据。对于非常基本的图像注释作业,dataObjectJSON 可能只包含source-ref注释后,确定要注释的图像。如果数据对象(例如,一行文本)直接包含在输入清单文件中,则使用source. 如果您创建验证或调整作业,则此行可能包含上一个标签作业中的标签数据和元数据。

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

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

作为回报,Ground Truth 需要格式如下的响应:

例 预期的返回数据

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

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

的影响isHumanAnnotationRequired

此值是可选的,因为它默认为true. 显式设置该值的主要使用案例是当您想要将此数据对象从人工标记范围中排除时。

如果你的清单中有混合对象,其中一些对象需要人工注释,有些不需要它,则可以包含isHumanAnnotationRequired每个数据对象中的值。您可以向预注解 Lambda 添加逻辑以动态确定对象是否需要注释,并相应地设置此布尔值。

预注解 Lambda 函数的示例

以下是基本的预注解 Lambda 函数访问中的 JSON 对象dataObject来自最初的请求,然后将其返回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,然后使用指向那个数据对象taskObject在 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

当所有工作人员都对数据对象进行注释或何时TaskAvailabilityLifetimeInSeconds已达到(以先到者为准),Ground Truth 将这些注释发送到注释后 Lambda。此 Lambda 通常用于合并注释

提示

要查看合并后 Lambda 函数的示例,请参阅annotation_consolidation_lambda.py中的aws-sagemaker-地面真相食谱GitHub 存储库。

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

{ "version": "2018-10-16", "labelingJobArn": <string>, "labelCategories": [<string>], "labelAttributeName": <string>, "roleArn" : <string>, "payload": { "s3Uri": <string> } }
  • version(字符串) Ground Truth 内部使用的版本号。

  • labelingJobArn(字符串) 贴标作业的亚马逊资源名称或 ARN。在使用 Ground Truth API 操作时,此 ARN 可用于引用标签作业,例如DescribeLabelingJob.

  • labelCategories(字符串列表):包括您在控制台中指定或包含在标签类别配置文件中的标签类别和其他属性。

  • labelAttributeName(字符串) 标签作业的名称或创建标签作业时指定的标签属性名称。

  • roleArn(字符串) 您在创建标记作业时指定的 IAM 执行角色的 Amazon 资源名称 (ARN)。

  • payload(JSON 对象) 一个包含s3Urikey,它标识 Amazon S3 中该数据对象的注释数据的位置。下面的第二个代码块显示此注释文件的示例。

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

例 注释后的 Lambda 请求

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

如果没有工作人员在数据对象上工作并且TaskAvailabilityLifetimeInSeconds已到达,则数据对象被标记为失败且不作为注释后 Lambda 调用的一部分包括在内。

以下代码块包含有效负载架构。这是由s3Uri注释后 Lambda 请求中的参数payloadJSON 对象。例如,如果之前的代码块是注释后的 Lambda 请求,则以下注释文件位于s3://DOC-EXAMPLE-BUCKET/annotations.json.

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

例 的注释文件

[ { "datasetObjectId": <string>, "dataObject": { "s3Uri": <string>, "content": <string> }, "annotations": [{ "workerId": <string>, "annotationData": { "content": <string>, "s3Uri": <string> } }] } ]
  • datasetObjectId(字符串) 标识 Ground Truth 分配给您发送到标签作业的每个数据对象的唯一 ID。

  • dataObject(JSON 对象) 被标记的数据对象。如果数据对象包含在输入清单文件中并使用source密钥(例如,字符串),dataObject包括contentkey,它标识数据对象。否则,数据对象的位置(例如,链接或 S3 URI)标识s3Uri.

  • annotations(JSON 对象列表):此列表包含工作人员为此提交的每个注释的单个 JSON 对象dataObject. 单个 JSON 对象包含一个唯一的workerId它可以用来识别提交该注释的工作人员。这些区域有:annotationData密钥包含以下内容之一:

    • content(字符串) 包含注释数据。

    • s3Uri(字符串) 包含标识注释数据位置的 S3 URI。

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

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

注释后 Lambda 函数可能包含类似于以下内容的逻辑,以循环浏览并访问请求中包含的所有注释。有关完整示例,请参阅annotation_consolidation_lambda.py中的aws-sagemaker-地面真相食谱GitHub 存储库。在此 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))
提示

当您对数据运行合并算法时,可以使用Amazon用于存储结果的数据库服务,也可以将处理的结果传回 Ground Truth。您返回到 Ground Truth 的数据存储在为标记作业进行配置期间为输出指定的 S3 存储桶的整合注释清单中。

作为回报,Ground Truth 需要格式如下的响应:

例 预期的返回数据

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

此时,您要发送到 S3 存储桶的所有数据,但datasetObjectId,在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 不提供对数据的进一步处理。