注釈前と注釈後の Lambda 関数の要件

このセクションでは、注釈前と注釈後の Lambda 関数に送信されるリクエストの構文と、Ground Truth でカスタムラベル付けワークフローを実行するために必要な応答構文について学習します。

前注釈 Lambda

ラベル付けタスクがワーカーに送信される前に、注釈前の Lambda 関数が呼び出されます。

Ground Truth は、ラベル付けジョブとデータオブジェクトに関する詳細を提供する JSON形式のリクエストを Lambda 関数に送信します。次の表に、注釈前リクエストスキーマを示します。各パラメータの詳細は以下のとおりです。

次の表は、注釈前リクエストのコードブロックの例です。これらのリクエストの例の各パラメータの説明は、タブ付きテーブルの下にあります。

代わりに、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 と同じラベル付けジョブで使用されるワーカータスクテンプレートには、dataObject を取り込むために以下のような Liquid 要素を含める必要があります。

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

入力マニフェストファイルが source を使用してデータオブジェクトを識別する場合は、ワーカータスクテンプレートは、以下を使用して dataObject を取り込むことができます。

{{ task.input.source }}

次の注釈前 Lambda の例には、dataObject で使用されたキーを識別するロジックが含まれており、Lambda の return ステートメントで 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://amzn-s3-demo-bucket/annotations.json"
    }
 }

次のコードブロックには、ペイロードスキーマが含まれています。これは、注釈後の Lambda リクエストpayloadJSONオブジェクトの s3Uriパラメータで示されるファイルです。例えば、前のコードブロックが注釈後の Lambda リクエストの場合、次の注釈ファイルの場所は s3://amzn-s3-demo-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 ではデータの詳細な処理は行いません。