演示：开始使用 Amazon A2I API

本演练介绍了您可用于开始使用的 API 操作Amazon A2I。

要使用 Jupyter Notebook 执行这些操作，请从中选择一个 Jupyter 笔记本使用的使用案例和示例 Amazon A2I，并使用将SageMaker笔记本实例与 Amazon A2I Jupyter 笔记本结合使用了解如何在SageMaker笔记本实例中使用它。

要了解有关可以与结合使用的 API 操作的更多信息Amazon A2I，请参阅在 Amazon Augmented AI 中使用 API。

创建私有工作团队

您可以创建私有工作团队并将自己添加为工作线程，以便预览 Amazon A2I。

如果您不熟悉 Amazon Cognito，我们建议您使用 SageMaker 控制台创建私有人力并将自己添加为私有工作人员。有关说明，请参阅步骤 1：创建工作团队。

如果您熟悉 Amazon Cognito ，则可以按照以下说明操作，使用 SageMaker API 创建私有工作团队。创建工作团队后，记下工作团队 ARN （WorkteamArn）。

要了解有关私有人力和其他可用配置的更多信息，请参阅使用私有人力。

创建私有人力

如果您尚未创建私有人力，则可以使用 Amazon Amazon Cognito 用户池执行此操作。确保您已将自己添加到此用户池。您可以使用 AWS Python 开发工具包（Boto3 函数创建私有工作团队。 create_workforce对于其他特定于语言SDKs请参阅 CreateWorkforce 中的列表。


    
    response = client.create_workforce(
        CognitoConfig={
            "UserPool": "Pool_ID",
            "ClientId": "app-client-id"
        },
        WorkforceName="workforce-name"
    )

创建私有工作团队

在 AWS 区域中创建私有人力以配置并启动人工循环后，您可以使用 AWS Python 开发工具包（Boto3 函数创建私有工作团队create_workteam。对于其他特定于语言SDKs，请参阅中的列表CreateWorkteam。



    response = client.create_workteam(
        WorkteamName="work-team-name",
        WorkforceName= "workforce-name",
        MemberDefinitions=[
            {
                "CognitoMemberDefinition": {
                    "UserPool": "<aws-region>_ID",
                    "UserGroup": "user-group",
                    "ClientId": "app-client-id"
                },
            }
        ]
    )

访问您的工作团队 ARN，如下所示：



    workteamArn = response["WorkteamArn"]

列出您账户中的私有工作团队

如果您已创建私有工作团队，则可以使用 AWS Python 开发工具包（Boto3 函数列出您的账户中给定 AWS 区域中的所有工作团队list_workteams。对于其他特定于语言SDKs，请参阅中的列表ListWorkteams。



    response = client.list_workteams()

如果您的账户中有许多工作团队，则可能需要使用 MaxResults、 SortBy和 NameContains 筛选您的结果。

创建人工审核工作流程

您可以使用 Amazon A2I 操作创建人工审核工作流程CreateFlowDefinition。在创建人工审核工作流程之前，您需要创建人工任务 UI。您可以使用 CreateHumanTaskUi 操作执行此操作。

如果您将 Amazon A2I 与 Amazon Textract 或 Amazon Rekognition 集成结合使用，则可以使用 JSON 指定激活条件。

创建人工任务 UI

如果要创建人工审核工作流程以用于 Amazon Textract 或 Amazon Rekognition 集成，您需要使用和修改预先生成的工作人员任务模板。对于所有自定义集成，您可以使用自己的自定义工作人员任务模板。可以使用下表了解如何使用两个内置集成的工作人员任务模板创建人工任务 UI。将模板替换为您自己的模板以自定义此请求。

Amazon Textract- Key-value pair extraction

要了解有关此模板的更多信息，请参阅Amazon Textract 的自定义模板示例。


template = r"""
<script src="https://assets.crowd.aws/crowd-html-elements.js"></script>
{% capture s3_uri %}http://s3.amazonaws.com/{{ task.input.aiServiceRequest.document.s3Object.bucket }}/{{ task.input.aiServiceRequest.document.s3Object.name }}{% endcapture %}
<crowd-form>
  <crowd-textract-analyze-document 
      src="{{ s3_uri | grant_read_access }}" 
      initial-value="{{ task.input.selectedAiServiceResponse.blocks }}" 
      header="Review the key-value pairs listed on the right and correct them if they don"t match the following document." 
      no-key-edit="" 
      no-geometry-edit="" 
      keys="{{ task.input.humanLoopContext.importantFormKeys }}" 
      block-types='["KEY_VALUE_SET"]'>
    <short-instructions header="Instructions">
        <p>Click on a key-value block to highlight the corresponding key-value pair in the document.
        </p><p><br></p>
        <p>If it is a valid key-value pair, review the content for the value. If the content is incorrect, correct it.
        </p><p><br></p>
        <p>The text of the value is incorrect, correct it.</p>
        <p><img src="https://assets.crowd.aws/images/a2i-console/correct-value-text.png">
        </p><p><br></p>
        <p>A wrong value is identified, correct it.</p>
        <p><img src="https://assets.crowd.aws/images/a2i-console/correct-value.png">
        </p><p><br></p>
        <p>If it is not a valid key-value relationship, choose No.</p>
        <p><img src="https://assets.crowd.aws/images/a2i-console/not-a-key-value-pair.png">
        </p><p><br></p>
        <p>If you can’t find the key in the document, choose Key not found.</p>
        <p><img src="https://assets.crowd.aws/images/a2i-console/key-is-not-found.png">
        </p><p><br></p>
        <p>If the content of a field is empty, choose Value is blank.</p>
        <p><img src="https://assets.crowd.aws/images/a2i-console/value-is-blank.png">
        </p><p><br></p>
        <p><strong>Examples</strong></p>
        <p>Key and value are often displayed next or below to each other.
        </p><p><br></p>
        <p>Key and value displayed in one line.</p>
        <p><img src="https://assets.crowd.aws/images/a2i-console/sample-key-value-pair-1.png">
        </p><p><br></p>
        <p>Key and value displayed in two lines.</p>
        <p><img src="https://assets.crowd.aws/images/a2i-console/sample-key-value-pair-2.png">
        </p><p><br></p>
        <p>If the content of the value has multiple lines, enter all the text without line break. 
        Include all value text even if it extends beyond the highlight box.</p>
        <p><img src="https://assets.crowd.aws/images/a2i-console/multiple-lines.png"></p>
    </short-instructions>
    <full-instructions header="Instructions"></full-instructions>
  </crowd-textract-analyze-document>
</crowd-form>
"""

Amazon Rekognition - Image moderation

要了解有关此模板的更多信息，请参阅Amazon Rekognition 的自定义模板示例。


template = r"""
<script src="https://assets.crowd.aws/crowd-html-elements.js"></script>
{% capture s3_uri %}http://s3.amazonaws.com/{{ task.input.aiServiceRequest.image.s3Object.bucket }}/{{ task.input.aiServiceRequest.image.s3Object.name }}{% endcapture %}

<crowd-form>
  <crowd-rekognition-detect-moderation-labels
    categories='[
      {% for label in task.input.selectedAiServiceResponse.moderationLabels %}
        {
          name: "{{ label.name }}",
          parentName: "{{ label.parentName }}",
        },
      {% endfor %}
    ]'
    src="{{ s3_uri | grant_read_access }}"
    header="Review the image and choose all applicable categories."
  >
    <short-instructions header="Instructions">
      <style>
        .instructions {
          white-space: pre-wrap;
        }
      </style>
      <p class="instructions">Review the image and choose all applicable categories.
If no categories apply, choose None.

<b>Nudity</b>
Visuals depicting nude male or female person or persons

<b>Partial Nudity</b>
Visuals depicting covered up nudity, for example using hands or pose

<b>Revealing Clothes</b>
Visuals depicting revealing clothes and poses

<b>Physical Violence</b>
Visuals depicting violent physical assault, such as kicking or punching

<b>Weapon Violence</b>
Visuals depicting violence using weapons like firearms or blades, such as shooting

<b>Weapons</b>
Visuals depicting weapons like firearms and blades
    </short-instructions>

    <full-instructions header="Instructions"></full-instructions>
  </crowd-rekognition-detect-moderation-labels>
</crowd-form>"""

Custom Integration

以下是可在自定义集成中使用的示例模板。此模板用于此笔记本中，演示了与的自定义集成Amazon Comprehend。


template = r"""
<script src="https://assets.crowd.aws/crowd-html-elements.js"></script>

<crowd-form>
    <crowd-classifier
      name="sentiment"
      categories='["Positive", "Negative", "Neutral", "Mixed"]'
      initial-value="{{ task.input.initialValue }}"
      header="What sentiment does this text convey?"
    >
      <classification-target>
        {{ task.input.taskObject }}
      </classification-target>
      
      <full-instructions header="Sentiment Analysis Instructions">
        <p><strong>Positive</strong> sentiment include: joy, excitement, delight</p>
        <p><strong>Negative</strong> sentiment include: anger, sarcasm, anxiety</p>
        <p><strong>Neutral</strong>: neither positive or negative, such as stating a fact</p>
        <p><strong>Mixed</strong>: when the sentiment is mixed</p>
      </full-instructions>

      <short-instructions>
       Choose the primary sentiment that is expressed by the text. 
      </short-instructions>
    </crowd-classifier>
</crowd-form>
"""

使用上面指定的模板，您可以使用 AWS Python 开发工具包（Boto3 函数创建模板create_human_task_ui。对于其他特定于语言SDKs，请参阅中的列表CreateHumanTaskUi。


    
    response = client.create_human_task_ui(
        HumanTaskUiName="human-task-ui-name",
        UiTemplate={
            "Content": template
        }
    )

此响应元素包含人工任务 UI ARN。如下所示保存：



    humanTaskUiArn = response["HumanTaskUiArn"]

创建 JSON 以指定激活条件

对于 Amazon Textract 和 Amazon Rekognition 内置集成，您可以将激活条件保存在 JSON 对象中，并在CreateFlowDefinition请求中使用此条件。

接下来，选择一个选项卡以查看可用于这些内置集成的示例激活条件。有关激活条件选项的其他信息，请参阅Amazon Augmented AI 中用于人工循环激活条件的 JSON 架构。

Amazon Textract- Key-value pair extraction

此示例指定文档中的特定键（如 Mail address）的条件。如果 Amazon Textract的置信度超出此处设置的阈值，则文档将发送给工作人员以进行审查，并提示工作人员查看触发人工循环的特定键。



      import json  

      humanLoopActivationConditions = json.dumps(
        {
            "Conditions": [
                {
                  "Or": [
                    
                    {
                        "ConditionType": "ImportantFormKeyConfidenceCheck",
                        "ConditionParameters": {
                            "ImportantFormKey": "Mail address",
                            "ImportantFormKeyAliases": ["Mail Address:","Mail address:", "Mailing Add:","Mailing Addresses"],
                            "KeyValueBlockConfidenceLessThan": 100,
                            "WordBlockConfidenceLessThan": 100
                        }
                    },
                    {
                        "ConditionType": "MissingImportantFormKey",
                        "ConditionParameters": {
                            "ImportantFormKey": "Mail address",
                            "ImportantFormKeyAliases": ["Mail Address:","Mail address:","Mailing Add:","Mailing Addresses"]
                        }
                    },
                    {
                        "ConditionType": "ImportantFormKeyConfidenceCheck",
                        "ConditionParameters": {
                            "ImportantFormKey": "Phone Number",
                            "ImportantFormKeyAliases": ["Phone number:", "Phone No.:", "Number:"],
                            "KeyValueBlockConfidenceLessThan": 100,
                            "WordBlockConfidenceLessThan": 100
                        }
                    },
                    {
                      "ConditionType": "ImportantFormKeyConfidenceCheck",
                      "ConditionParameters": {
                        "ImportantFormKey": "*",
                        "KeyValueBlockConfidenceLessThan": 100,
                        "WordBlockConfidenceLessThan": 100
                      }
                    },
                    {
                      "ConditionType": "ImportantFormKeyConfidenceCheck",
                      "ConditionParameters": {
                        "ImportantFormKey": "*",
                        "KeyValueBlockConfidenceGreaterThan": 0,
                        "WordBlockConfidenceGreaterThan": 0
                      }
                    }
            ]
        }
            ]
        }
    )

Amazon Rekognition - Image moderation

此处使用的人工循环激活条件针对Amazon Rekognition内容审核定制；它们基于特定审核标签 Suggestive 和的置信度阈值Female Swimwear Or Underwear。



        import json  

        humanLoopActivationConditions = json.dumps(
        {
            "Conditions": [
                {
                  "Or": [
                    {
                        "ConditionType": "ModerationLabelConfidenceCheck",
                        "ConditionParameters": {
                            "ModerationLabelName": "Suggestive",
                            "ConfidenceLessThan": 98
                        }
                    },
                    {
                        "ConditionType": "ModerationLabelConfidenceCheck",
                        "ConditionParameters": {
                            "ModerationLabelName": "Female Swimwear Or Underwear",
                            "ConfidenceGreaterThan": 98
                        }
                    }
                  ]
               }
            ]
        }
    )

创建人工审核工作流程

本节提供使用在前面部分中创建的资源的 CreateFlowDefinition AWS Python 开发工具包（Boto3 请求的示例。对于其他特定于语言SDKs请参阅 CreateFlowDefinition 中的列表。可以使用下表中的选项卡查看为 Amazon Textract 和Amazon Rekognition内置集成创建人工审核工作流程的请求。

Amazon Textract- Key-value pair extraction

如果您将内置集成与结合使用Amazon Textract，则必须"AWS/Textract/AnalyzeDocument/Forms/V1"在 "AwsManagedHumanLoopRequestSource" 中为指定 HumanLoopRequestSource。



    response = client.create_flow_definition(
        FlowDefinitionName="human-review-workflow-name",
        HumanLoopRequestSource={
            "AwsManagedHumanLoopRequestSource": "AWS/Textract/AnalyzeDocument/Forms/V1"
        }, 
        HumanLoopActivationConfig={
            "HumanLoopActivationConditionsConfig": {
                "HumanLoopActivationConditions": humanLoopActivationConditions
            }
        },
        HumanLoopConfig={
            "WorkteamArn": workteamArn,
            "HumanTaskUiArn": humanTaskUiArn,
            "TaskTitle": "Document entry review",
            "TaskDescription": "Review the document and instructions. Complete the task",
            "TaskCount": 1,
            "TaskAvailabilityLifetimeInSeconds": 43200,
            "TaskTimeLimitInSeconds": 3600,
            "TaskKeywords": [
                "document review",
            ],
        },
        OutputConfig={
            "S3OutputPath": "s3:///prefix/",
        },
        RoleArn="arn:aws:iam::<account-number>:role/<role-name>",
        Tags=[
            {
                "Key": "string",
                "Value": "string"
            },
        ]
    )

Amazon Rekognition - Image moderation

如果您将内置集成与结合使用Amazon Rekognition，则必须"AWS/Rekognition/DetectModerationLabels/Image/V3"在 "AwsManagedHumanLoopRequestSource" 中为指定 HumanLoopRequestSource。



    response = client.create_flow_definition(
        FlowDefinitionName="human-review-workflow-name",
        HumanLoopRequestSource={
            "AwsManagedHumanLoopRequestSource": "AWS/Rekognition/DetectModerationLabels/Image/V3"
        }, 
        HumanLoopActivationConfig={
            "HumanLoopActivationConditionsConfig": {
                "HumanLoopActivationConditions": humanLoopActivationConditions
            }
        },
        HumanLoopConfig={
            "WorkteamArn": workteamArn,
            "HumanTaskUiArn": humanTaskUiArn,
            "TaskTitle": "Image content moderation",
            "TaskDescription": "Review the image and instructions. Complete the task",
            "TaskCount": 1,
            "TaskAvailabilityLifetimeInSeconds": 43200,
            "TaskTimeLimitInSeconds": 3600,
            "TaskKeywords": [
                "content moderation",
            ],
        },
        OutputConfig={
            "S3OutputPath": "s3:///prefix/",
        },
        RoleArn="arn:aws:iam::<account-number>:role/<role-name>",
        Tags=[
            {
                "Key": "string",
                "Value": "string"
            },
        ]
    )

Custom Integration

如果您使用自定义集成，请排除以下参数：HumanLoopRequestSource、HumanLoopActivationConfig。



    response = client.create_flow_definition(
        FlowDefinitionName="human-review-workflow-name",
        HumanLoopConfig={
            "WorkteamArn": workteamArn,
            "HumanTaskUiArn": humanTaskUiArn,
            "TaskTitle": "Image content moderation",
            "TaskDescription": "Review the image and instructions. Complete the task",
            "TaskCount": 1,
            "TaskAvailabilityLifetimeInSeconds": 43200,
            "TaskTimeLimitInSeconds": 3600,
            "TaskKeywords": [
                "content moderation",
            ],
        },
        OutputConfig={
            "S3OutputPath": "s3:///prefix/",
        },
        RoleArn="arn:aws:iam::<account-number>:role/<role-name>",
        Tags=[
            {
                "Key": "string",
                "Value": "string"
            },
        ]
    )

创建人工审核工作流程后，您可以从响应中检索流定义 ARN：



    humanReviewWorkflowArn = response["FlowDefinitionArn"]

创建人工循环

用于启动人工循环的 API 操作取决于您使用的Amazon A2I集成。

如果您使用Amazon Textract内置集成，则可以使用 AnalyzeDocument 操作。
如果您使用Amazon Rekognition内置集成，则可使用 DetectModerationLabels操作。
如果您使用自定义集成，则可使用 StartHumanLoop 操作。

在下表中选择任务类型以查看针对 Amazon Textract 和Amazon Rekognition使用适用于 Python 的 AWS 开发工具包（Boto3 的示例请求。

Amazon Textract- Key-value pair extraction

以下示例使用适用于 Python 的 AWS 开发工具包（Boto3 在 us-west-2 analyze_document 中调用。将红色的斜体文本替换为您的资源。如果您使用的是人力，则包括 DataAttributesAmazon Mechanical Turk 参数。有关更多信息，请参阅适用于 Python 的 AWS 开发工具包（Boto） API 参考中的 analyt_document 文档。



   response = client.analyze_document(
         Document={"S3Object": {"Bucket": "AWSDOC-EXAMPLE-BUCKET", "Name": "document-name.pdf"},
         HumanLoopConfig={
            "FlowDefinitionArn":"arn:aws:sagemaker:us-west-2:111122223333:flow-definition/flow-definition-name",
            "HumanLoopName":"human-loop-name",
            "DataAttributes" : {ContentClassifiers:["FreeOfPersonallyIdentifiableInformation"|"FreeOfAdultContent"]}
         }
         FeatureTypes=["FORMS"]
    )

仅当 Amazon Textract的文档分析任务的置信度满足您在人工审核工作流中指定的激活条件时，才会创建人工循环。您可以检查 response 元素以确定是否已创建人工循环。要查看此响应中包含的所有内容，HumanLoopActivationOutput请参阅。



    if "HumanLoopArn" in analyzeDocumentResponse["HumanLoopActivationOutput"]:
        # A human loop has been started!
        print(f"A human loop has been started with ARN: {analyzeDocumentResponse["HumanLoopActivationOutput"]["HumanLoopArn"]}"

Amazon Rekognition - Image moderation

以下示例使用适用于 Python 的 AWS 开发工具包（Boto3 在 us-west-2 detect_moderation_labels 中调用。将红色的斜体文本替换为您的资源。如果您使用的是人力，则包括 DataAttributesAmazon Mechanical Turk 参数。有关更多信息，请参阅适用于 Python 的 AWS 开发工具包（Boto） API 参考中的 detect_moderation_labels 文档。



   response = client.detect_moderation_labels(
            Image={"S3Object":{"Bucket": "AWSDOC-EXAMPLE-BUCKET", "Name": "image-name.png"}},
            HumanLoopConfig={
               "FlowDefinitionArn":"arn:aws:sagemaker:us-west-2:111122223333:flow-definition/flow-definition-name",
               "HumanLoopName":"human-loop-name",
               "DataAttributes":{ContentClassifiers:["FreeOfPersonallyIdentifiableInformation"|"FreeOfAdultContent"]}
             }
    )

仅当 Amazon Rekognition对图像审核任务的置信度满足您在人工审核工作流中指定的激活条件时，才会创建人工循环。您可以检查 response 元素以确定是否已创建人工循环。要查看此响应中包含的所有内容，HumanLoopActivationOutput请参阅。



    if "HumanLoopArn" in response["HumanLoopActivationOutput"]:
        # A human loop has been started!
        print(f"A human loop has been started with ARN: {response["HumanLoopActivationOutput"]["HumanLoopArn"]}")

Custom Integration

以下示例使用适用于 Python 的 AWS 开发工具包（Boto3 在 us-west-2 start_human_loop 中调用。将红色的斜体文本替换为您的资源。如果您使用的是人力，则包括 DataAttributesAmazon Mechanical Turk 参数。有关更多信息，请参阅适用于 Python 的 AWS 开发工具包（Boto） API 参考中的 start_human_loop 文档。



   response = client.start_human_loop(
        HumanLoopName= "human-loop-name",
        FlowDefinitionArn= "arn:aws:sagemaker:us-west-2:111122223333:flow-definition/flow-definition-name",
        HumanLoopInput={"InputContent": inputContentJson},
        DataAttributes={"ContentClassifiers":["FreeOfPersonallyIdentifiableInformation"|"FreeOfAdultContent"]}
   )

此示例将输入内容存储在变量中 inputContentJson。假设输入内容包含两个元素：文本模糊和情绪（如正、负或中），格式如下：



    inputContent = {
        "initialValue": sentiment,
         "taskObject": blurb
     }

键 initialValue 和 taskObject 必须对应于工作人员任务模板的 Liquid 元素中使用的键。请参阅中的自定义模板创建人工任务 UI以查看示例。

要创建 inputContentJson，请执行以下操作。



    import json
    
    inputContentJson = json.dumps(inputContent)

每次调用时，人工循环都会启动start_human_loop。要检查人工循环的状态，请使用 describe_human_loop：



    human_loop_info = a2i.describe_human_loop(HumanLoopName="human_loop_name")
    print(f"HumanLoop Status: {resp["HumanLoopStatus"]}")
    print(f"HumanLoop Output Destination: {resp["HumanLoopOutput"]}")

Javascript 在您的浏览器中被禁用或不可用。

要使用 AWS 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

演示：在 Amazon A2I 控制台中开始使用

使用案例和示例