註釋前及註釋後 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 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 不會針對資料提供進一步處理。