本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 建立和啟動人工循環 *人工循環*會啟動您的人工審核工作流程，並將資料審核任務傳送給人力工作者。當您使用其中一個 Amazon A2I 內建任務類型時，對應的 AWS 服務會在符合流程定義中指定的條件時，代表您建立並啟動人工迴圈。如果您的流程定義中未指定任何條件，則會為每個物件建立人工循環。在為自訂任務使用 Amazon A2I 時，人工循環會在應用程式中呼叫 `StartHumanLoop` 時啟動。 使用下列指示來設定具有 Amazon Rekognition 或 Amazon Textract 內建任務類型和自訂任務類型的人工循環。 **先決條件** 若要建立和啟動人工循環，您必須將`AmazonAugmentedAIFullAccess`政策連接至設定或啟動人工循環的 AWS Identity and Access Management (IAM) 使用者或角色。這將是您用來設定將 `HumanLoopConfig` 用於內建任務類型的人工循環的身分。對於自訂任務類型，這將是您用來呼叫 `StartHumanLoop` 的身分。 此外，使用內建任務類型時，您的使用者或角色必須具有叫用與您的任務類型相關聯之 AWS 服務的 API 操作的許可。例如，如果將 Amazon Rekognition 和增強版 AI 搭配使用，您必須連接呼叫 `DetectModerationLabels` 所需的許可。如需您可以用來授予這些許可的以身分為基礎的政策範例，請參閱 [Amazon Rekognition 以身分為基礎的範例政策](https://docs.aws.amazon.com/rekognition/latest/dg/security_iam_id-based-policy-examples.html)和 [Amazon Textract 以身分為基礎的政策範例](https://docs.aws.amazon.com/textract/latest/dg/security_iam_id-based-policy-examples.html)。您也可以使用比較一般的政策 `AmazonAugmentedAIIntegratedAPIAccess`，來授予這些許可。如需更多詳細資訊，請參閱[使用調用 Amazon A2I、Amazon Textract 和 Amazon Rekognition API 作業的許可來建立使用者](a2i-permissions-security.md#a2i-grant-general-permission)。 若要建立和啟動人工循環，您需要流程定義 ARN。若要了解如何建立流程定義 (或人工審核工作流程)，請參閱[建立人工審核工作流程 (API)](a2i-create-flow-definition.md)。 **重要** Amazon A2I 要求所有包含人工循環輸入影像資料的 S3 儲存貯體都必須連接 CORS 政策。若要進一步了解此變更，請參閱[CORS 許可要求](a2i-permissions-security.md#a2i-cors-update)。 ## 建立並啟動內建任務類型的人工循環 若要使用內建任務類型來啟動人工循環，請使用相對應服務的 API 來提供您的輸入資料，並設定人工循環。對於 Amazon Textract，您可以使用 `AnalyzeDocument` API 作業。對於 Amazon Rekognition，您可以使用 `DetectModerationLabels` API 作業。您可以使用 AWS CLI 或特定語言 SDK，使用這些 API 操作建立請求。 **重要** 當您使用內建任務類型建立人工循環時，您可以使用 `DataAttributes` 指定與提供給 `StartHumanLoop` 作業的輸入相關的一組 `ContentClassifiers`。使用內容分類器來宣告您的內容不含個人識別資訊或成人內容。 若要使用 Amazon Mechanical Turk，請確保您的資料不含個人可識別資訊，包括 HIPAA 受保護的健康資訊。包括 `FreeOfPersonallyIdentifiableInformation` 內容分類器。如果您不使用此內容分類器，SageMaker AI 不會將您的任務傳送至 Mechanical Turk。如果您的資料不含成人內容，亦請包括 `'FreeOfAdultContent'` 分類器。如果您不使用這些內容分類器，SageMaker AI 可能會限制可以檢視您的任務的 Mechanical Turk 工作者。 使用內建任務類型的 AWS 服務 API 啟動 ML 任務後，Amazon A2I 會監控該服務的推論結果。例如，在使用 Amazon Rekognition 執行工作時，Amazon A2I 會檢查每個影像的推論可信度分數，並將其與流程定義中指定的可信度閾值進行比較。如果啟動人工審核任務的條件已滿足，或者您未在流程定義中指定條件，則人工審核任務會傳送給工作者。 ### 建立 Amazon Textract 人工循環 Amazon A2I 與 Amazon Textract 整合，以便您使用 Amazon Textract API 設定並啟動人工循環。若要將文件檔案傳送至 Amazon Textract 以進行文字分析，請使用 Amazon Textract [`AnalyzeDocument` API 作業](https://docs.aws.amazon.com/textract/latest/dg/API_AnalyzeDocument.html)。若要將人工循環新增至此文件分析工作，您必須設定參數 `HumanLoopConfig`。 設定人工循環時，您在 `HumanLoopConfig` 的 `FlowDefinitionArn` 中指定的流程定義必須位於與 `Document` 參數的 `Bucket` 中指定的儲存貯體相同的 AWS 區域。 下表顯示如何搭配 AWS CLI 和 使用此操作的範例 適用於 Python (Boto3) 的 AWS SDK。 ------ #### [ 適用於 Python (Boto3) 的 AWS SDK ] 以下請求範例會使用適用於 Python 的軟體開發套件 (Boto3)。如需詳細資訊，請參閱*適用於 Python 的AWS SDK (Boto) API 參考*中的 [analyze\_document](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/textract.html#Textract.Client.analyze_document)。 ``` import boto3 textract = boto3.client('textract', {{aws_region}}) response = textract.analyze_document( Document={'S3Object': {'Bucket': {{bucket_name}}, 'Name': {{document_name}}}}, FeatureTypes=["TABLES", "FORMS"], HumanLoopConfig={ 'FlowDefinitionArn': 'arn:aws:sagemaker:{{aws_region}}:{{aws_account_number}}:flow-definition/{{flow_def_name}}', 'HumanLoopName': '{{human_loop_name}}', 'DataAttributes': {'ContentClassifiers': ['FreeOfPersonallyIdentifiableInformation','FreeOfAdultContent']} } ) ``` ------ #### [ AWS CLI ] 下列請求範例使用 AWS CLI。如需詳細資訊，請參閱 *[AWS CLI 命令參考](https://docs.aws.amazon.com/cli/latest/reference/)*中的[分析文件](https://docs.aws.amazon.com/cli/latest/reference/textract/analyze-document.html)。 ``` $ aws textract analyze-document \ --document '{"S3Object":{"Bucket":"{{bucket_name}}","Name":"{{document_name}}"}}' \ --human-loop-config HumanLoopName="{{human_loop_name}}",FlowDefinitionArn="arn:aws:sagemaker:{{aws-region}}:{{aws_account_number}}:flow-definition/{{flow_def_name}}",DataAttributes='{ContentClassifiers=["FreeOfPersonallyIdentifiableInformation", "FreeOfAdultContent"]}' \ --feature-types '["TABLES", "FORMS"]' ``` ``` $ aws textract analyze-document \ --document '{"S3Object":{"Bucket":"{{bucket_name}}","Name":"{{document_name}}"}}' \ --human-loop-config \ '{"HumanLoopName":"{{human_loop_name}}","FlowDefinitionArn":"arn:aws:sagemaker:{{aws_region}}:{{aws_account_number}}:flow-definition/{{flow_def_name}}","DataAttributes": {"ContentClassifiers":["FreeOfPersonallyIdentifiableInformation","FreeOfAdultContent"]}}' \ --feature-types '["TABLES", "FORMS"]' ``` ------ 在您使用已設定的人工循環執行 `AnalyzeDocument` 之後，Amazon A2I 會監控 `AnalyzeDocument` 的結果，並根據流程定義的啟動條件對其進行檢查。如果一或多個鍵值對的 Amazon Textract 推論可信度分數符合審核的條件，則 Amazon A2I 會啟動人工審核循環，並將 [https://docs.aws.amazon.com/textract/latest/dg/API_HumanLoopActivationOutput.html](https://docs.aws.amazon.com/textract/latest/dg/API_HumanLoopActivationOutput.html) 物件包含在 `AnalyzeDocument` 回應中。 ### 建立 Amazon Rekognition 人工循環 Amazon A2I 與 Amazon Rekognition 整合，以便您使用 Amazon Rekognition API 設定並啟動人工循環。若要將影像傳送至 Amazon Rekognition 以進行內容審核，請使用 Amazon Rekognition [`DetectModerationLabels` API 作業](https://docs.aws.amazon.com/rekognition/latest/dg/API_DetectModerationLabels.html)。若要設定人工循環，請在設定 `DetectModerationLabels` 時設定 `HumanLoopConfig` 參數。 設定人工循環時，您在 `HumanLoopConfig` 的 `FlowDefinitionArn` 中指定的流程定義必須位於與 `Image` 參數的 `Bucket` 中指定的 S3 儲存貯體相同的 AWS 區域。 下表顯示如何搭配 AWS CLI 和 使用此操作的範例 適用於 Python (Boto3) 的 AWS SDK。 ------ #### [ 適用於 Python (Boto3) 的 AWS SDK ] 以下請求範例使用適用於 Python 的軟體開發套件 (Boto3)。如需詳細資訊，請參閱位在*適用於 Python 的AWS SDK (Boto) API 參考*中的 [detect\_moderation\_labels](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rekognition.html#Rekognition.Client.detect_moderation_labels)。 ``` import boto3 rekognition = boto3.client("rekognition", {{aws_region}}) response = rekognition.detect_moderation_labels( \ Image={'S3Object': {'Bucket': {{bucket_name}}, 'Name': {{image_name}}}}, \ HumanLoopConfig={ \ 'HumanLoopName': '{{human_loop_name}}', \ 'FlowDefinitionArn': , "arn:aws:sagemaker:{{aws_region}}:{{aws_account_number}}:flow-definition/{{flow_def_name}}" \ 'DataAttributes': {'ContentClassifiers': ['FreeOfPersonallyIdentifiableInformation','FreeOfAdultContent']} }) ``` ------ #### [ AWS CLI ] 下列請求範例使用 AWS CLI。如需詳細資訊，請參閱[偵測-審核-標籤](https://docs.aws.amazon.com/cli/latest/reference/rekognition/detect-moderation-labels.html)，位在 *[AWS CLI 命令參考](https://docs.aws.amazon.com/cli/latest/reference/)*。 ``` $ aws rekognition detect-moderation-labels \ --image "S3Object={Bucket='{{bucket_name}}',Name='{{image_name}}'}" \ --human-loop-config HumanLoopName="{{human_loop_name}}",FlowDefinitionArn="arn:aws:sagemaker:{{aws_region}}:{{aws_account_number}}:flow-definition/{{flow_def_name}}",DataAttributes='{ContentClassifiers=["FreeOfPersonallyIdentifiableInformation", "FreeOfAdultContent"]}' ``` ``` $ aws rekognition detect-moderation-labels \ --image "S3Object={Bucket='{{bucket_name}}',Name='{{image_name}}'}" \ --human-loop-config \ '{"HumanLoopName": "{{human_loop_name}}", "FlowDefinitionArn": "arn:aws:sagemaker:{{aws_region}}:{{aws_account_number}}:flow-definition/{{flow_def_name}}", "DataAttributes": {"ContentClassifiers": ["FreeOfPersonallyIdentifiableInformation", "FreeOfAdultContent"]}}' ``` ------ 在您使用已設定的人工循環執行 `DetectModerationLabels` 之後，Amazon A2I 會監控 `DetectModerationLabels` 的結果，並根據流程定義的啟動條件對其進行檢查。如果影像的 Amazon Rekognition 推論可信度分數符合審核的條件，則 Amazon A2I 會啟動人工審核循環，並在 `DetectModerationLabels` 回應中包含回應元素 `HumanLoopActivationOutput`。 ## 建立和啟動自訂任務類型的人工循環 若要為自訂人工審核任務設定人工循環，請使用應用程式內的 `StartHumanLoop` 作業。本節提供使用 適用於 Python (Boto3) 的 AWS SDK 和 AWS Command Line Interface () 的人工循環請求範例AWS CLI。有關支援 `StartHumanLoop` 的其他語言特定軟體開發套件的文件，請使用 Amazon 增強版 AI 執行期 API 文件中的 [StartHumanLoop](https://docs.aws.amazon.com/augmented-ai/2019-11-07/APIReference/API_StartHumanLoop.html) 之**另請參閱**小節。請參閱[使用 Amazon A2I 的使用案例和範例](a2i-task-types-general.md)，查看示範如何將 Amazon A2I 用於自訂任務類型的範例。 **先決條件** 若要完成此程序，您需要： + 輸入資料格式化為 JSON 格式檔案的字串顯示方式 + 您的流程定義的 Amazon Resource Name (ARN) **設定人工循環** 1. 對於 `DataAttributes`，指定一組與提供給 `StartHumanLoop` 作業的輸入有關的 `ContentClassifiers`。使用內容分類器來宣告您的內容不含個人識別資訊或成人內容。 若要使用 Amazon Mechanical Turk，請確保您的資料不含個人可識別資訊，包括依 HIPAA 規定的受保護的健康資訊，並包括 `FreeOfPersonallyIdentifiableInformation` 內容分類器。如果您不使用此內容分類器，SageMaker AI 不會將您的任務傳送至 Mechanical Turk。如果您的資料不含成人內容，亦請包括 `'FreeOfAdultContent'` 分類器。如果您不使用這些內容分類器，SageMaker AI 可能會限制可以檢視您的任務的 Mechanical Turk 工作者。 1. 對於 `FlowDefinitionArn`，請輸入您的流程定義的 Amazon Resource Name (ARN)。 1. 對於 `HumanLoopInput`，輸入您的輸入資料以做為 JSON 格式檔案的字串顯示方式。建構輸入資料和自訂工作者任務範本，以便在啟動人工循環時將輸入資料正確顯示給人力工作者。請參閱[預覽工作者任務範本](a2i-custom-templates.md#a2i-preview-your-custom-template) 以了解如何預覽您的自訂工作者任務範本。 1. 對於 `HumanLoopName`，請輸入人工循環的名稱。該名稱在您的帳戶中的區域內必須是唯一的，最多可以有 63 個字元。有效字元：a-z、0-9 和 - (連字號)。 **開始人工循環** + 若要啟動人工循環，請使用您偏好的語言特定 SDK 提交類似下列範例的請求。 ------ #### [ 適用於 Python (Boto3) 的 AWS SDK ] 以下請求範例會使用適用於 Python 的軟體開發套件 (Boto3)。有關詳細資訊，請參閱 [Boto 3 增強版 AI 執行期](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker-a2i-runtime.html#AugmentedAIRuntime.Client.start_human_loop)，位在*適用於 Python 的AWS SDK (Boto) API 參考*。 ``` import boto3 a2i_runtime_client = boto3.client('sagemaker-a2i-runtime') response = a2i_runtime_client.start_human_loop( HumanLoopName='{{human_loop_name}}', FlowDefinitionArn='arn:aws:sagemaker:{{aws-region}}:{{xyz}}:flow-definition/{{flow_def_name}}', HumanLoopInput={ 'InputContent': {{'{"InputContent": {\"prompt\":\"What is the answer?\"}}'}} }, DataAttributes={ 'ContentClassifiers': [ {{'FreeOfPersonallyIdentifiableInformation'|'FreeOfAdultContent'}}, ] } ) ``` ------ #### [ AWS CLI ] 下列請求範例使用 AWS CLI。有關詳細資訊，請參閱[啟動-人工循環](https://docs.aws.amazon.com/cli/latest/reference/sagemaker-a2i-runtime/start-human-loop.html)，位在 *[AWS CLI 命令參考](https://docs.aws.amazon.com/cli/latest/reference/)*。 ``` $ aws sagemaker-a2i-runtime start-human-loop --flow-definition-arn 'arn:aws:sagemaker:{{aws_region}}:{{xyz}}:flow-definition/{{flow_def_name}}' \ --human-loop-name '{{human_loop_name}}' \ --human-loop-input '{{{"InputContent": "{\"prompt\":\"What is the answer?\"}"}}}' \ --data-attributes ContentClassifiers={{"FreeOfPersonallyIdentifiableInformation","FreeOfAdultContent"}} \ ``` ------ 當您透過直接調用 `StartHumanLoop` 成功啟動人工循環時，回應包括 `HumanLoopARN` 和被設為 `NULL` 的 `HumanLoopActivationResults` 物件。您可以使用此人工循環名稱來監控和管理您的人工循環。 ## 後續步驟： 在開始人工循環之後，您可以使用 Amazon 增強版 AI 執行期 API 和 Amazon CloudWatch Events 進行管理和監控。如需進一步了解，請參閱[監控和管理您的人工循環](a2i-monitor-humanloop-results.md)。