Didacticiel : Démarrer à l’aide de l’API Amazon A2I - Amazon SageMaker

Didacticiel : Démarrer à l’aide de l’API Amazon A2I

Ce didacticiel explique les opérations d'API que vous pouvez utiliser pour commencer à utiliser Amazon A2I.

Pour utiliser un bloc-notes Jupyter pour exécuter ces opérations, sélectionnez un bloc-notes Jupyter dans Cas d'utilisation et exemples d’utilisation d'Amazon A2I et utilisez Utiliser l'instance de bloc-notes SageMaker avec un bloc-notes Jupyter Amazon A2I pour savoir comment l'utiliser dans une instance de bloc-notes SageMaker.

Pour en savoir plus sur les opérations d'API que vous pouvez utiliser avec Amazon A2I, veuillez consulter la section Utilisation des API dans Amazon Augmented AI.

Créer une équipe de travail privée

Vous pouvez créer une équipe de travail privée et vous ajouter en tant qu’employé afin de pouvoir prévisualiser Amazon A2I.

Si vous ne connaissez pas bien Amazon Cognito, nous vous recommandons d'utiliser la console SageMaker pour créer une main-d'œuvre privée et vous ajouter en tant qu’employé privé. Pour obtenir des instructions, veuillez consulter la section Étape 1 : Créer une équipe de travail.

Si vous connaissez Amazon Cognito, utilisez les instructions suivantes pour créer une équipe de travail privée à l'aide de l'API SageMaker. Après avoir créé une équipe de travail, notez l'ARN de l'équipe de travail (WorkteamArn).

Pour en savoir plus sur la main-d'œuvre privée et d'autres configurations disponibles, veuillez consulter la section Utilisation d'une main-d'œuvre privée.

Créer une main-d'œuvre privée

Si vous n'avez pas créé de main-d'œuvre privée, vous pouvez le faire à l'aide d'un groupe d'utilisateurs Amazon Cognito. Vérifiez que vous vous êtes ajouté à ce groupe d'utilisateurs. Vous pouvez créer une équipe de travail privée à l'aide de la fonction AWS SDK for Python (Boto3) create_workforce. Pour les autres kits SDK spécifiques au langage, reportez-vous à la liste dans CreateWorkforce.

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

Créer une équipe de travail privée

Une fois que vous avez créé une main-d'œuvre privée dans la région AWS pour configurer et démarrer votre boucle humaine, vous pouvez créer une équipe de travail privée à l'aide de la fonction AWS SDK for Python (Boto3) create_workteam. Pour les autres kits SDK spécifiques au langage, reportez-vous à la liste dans 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" }, } ] )

Pour accéder à l'ARN de votre équipe de travail, procédez comme suit :

workteamArn = response["WorkteamArn"]

Répertorier les équipes de travail privées de votre compte

Si vous avez déjà créé une équipe de travail privée, vous pouvez répertorier toutes les équipes de travail dans une région AWS donnée de votre compte à l'aide de la fonction AWS SDK for Python (Boto3) list_workteams. Pour les autres kits SDK spécifiques au langage, reportez-vous à la liste dans ListWorkteams.

response = client.list_workteams()

Si votre compte comporte de nombreuses équipes de travail, vous voudrez peut-être utiliser MaxResults, SortBy et NameContains pour filtrer vos résultats.

Créer un flux de vérification humaine

Vous pouvez créer un flux de vérification humaine à l'aide de l’opération CreateFlowDefinition Amazon A2I. Avant de créer votre flux de vérification humaine, vous devez créer une interface utilisateur de tâche humaine. Vous pouvez faire ceci avec l’opération CreateHumanTaskUi.

Si vous utilisez Amazon A2I avec les intégrations Amazon Textract ou Amazon Rekognition, vous pouvez spécifier des conditions d'activation à l'aide d'un objet JSON.

Créer une interface utilisateur de tâche humaine

Si vous créez un flux de vérification humaine à utiliser avec les intégrations Amazon Textract ou Amazon Rekognition, vous devez utiliser et modifier le modèle de tâche d'employé préétabli. Pour toutes les intégrations personnalisées, vous pouvez utiliser votre propre modèle de tâche d'employé personnalisé. Utilisez le tableau suivant pour apprendre à créer une interface utilisateur de tâche humaine à l'aide d'un modèle de tâche d'employé pour les deux intégrations intégrées. Pour personnaliser cette demande, remplacez le modèle par le vôtre.

Amazon Textract – Key-value pair extraction

Pour en savoir plus sur ce modèle, veuillez consulter la section Exemple de modèle personnalisé pour 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

Pour en savoir plus sur ce modèle, veuillez consulter la section Exemple de modèle personnalisé pour 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

Voici un exemple de modèle qui peut être utilisé dans une intégration personnalisée. Ce modèle est utilisé dans cet ordinateur portable, pour démontrer une intégration personnalisée avec 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> """

À l'aide du modèle spécifié ci-dessus, vous pouvez créer un modèle à l'aide de la fonction AWS SDK for Python (Boto3) create_human_task_ui. Pour les autres kits SDK spécifiques au langage, reportez-vous à la liste dans CreateHumanTaskUi.

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

Cet élément de réponse contient l'ARN de l'interface utilisateur de tâche humaine. Enregistrez ceci comme suit :

humanTaskUiArn = response["HumanTaskUiArn"]

Créer un objet JSON pour spécifier les conditions d'activation

Pour les intégrations intégrées Amazon Textract et Amazon Rekognition, vous pouvez enregistrer les conditions d'activation dans un objet JSON et l'utiliser dans votre demande CreateFlowDefinition.

Ensuite, sélectionnez un onglet pour voir un exemple de conditions d'activation que vous pouvez utiliser pour ces intégrations intégrées. Pour plus d'informations sur les options de condition d'activation, veuillez consulter la section Schéma JSON pour les conditions d'activation de boucle humaine dans Amazon Augmented AI.

Amazon Textract – Key-value pair extraction

Cet exemple spécifie des conditions pour des clés spécifiques (telles que Mail address) dans le document. Si l’indice de confiance d'Amazon Textract dépasse les seuils définis ici, le document est soumis à vérification humaine, et les clés spécifiques à l'initiation de la boucle humaine sont envoyées à l’employé.

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

Les conditions d'activation de la boucle humaine utilisées ici sont adaptées à la modération du contenu Amazon Rekognition ; elles sont basées sur les seuils de confiance pour les étiquettes de modération Suggestive et 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 } } ] } ] } )

Créer un flux de vérification humaine

Cette section fournit un exemple de la demande CreateFlowDefinition AWS SDK for Python (Boto3) utilisant les ressources créées dans les sections précédentes. Pour les autres kits SDK spécifiques au langage, reportez-vous à la liste dans CreateFlowDefinition. Utilisez les onglets du tableau suivant pour voir les demandes de création d'un flux de vérification humaine pour les intégrations intégrées Amazon Textract et Amazon Rekognition.

Amazon Textract – Key-value pair extraction

Si vous utilisez l'intégration intégrée avec Amazon Textract, vous devez spécifier "AWS/Textract/AnalyzeDocument/Forms/V1" pour "AwsManagedHumanLoopRequestSource" dans 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://DOC-EXAMPLE-BUCKET/prefix/", }, RoleArn="arn:aws:iam::<account-number>:role/<role-name>", Tags=[ { "Key": "string", "Value": "string" }, ] )
Amazon Rekognition – Image moderation

Si vous utilisez l'intégration intégrée avec Amazon Rekognition, vous devez spécifier "AWS/Rekognition/DetectModerationLabels/Image/V3" pour "AwsManagedHumanLoopRequestSource" dans 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://DOC-EXAMPLE-BUCKET/prefix/", }, RoleArn="arn:aws:iam::<account-number>:role/<role-name>", Tags=[ { "Key": "string", "Value": "string" }, ] )
Custom Integration

Si vous utilisez une intégration personnalisée, excluez les paramètres suivants :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://DOC-EXAMPLE-BUCKET/prefix/", }, RoleArn="arn:aws:iam::<account-number>:role/<role-name>", Tags=[ { "Key": "string", "Value": "string" }, ] )

Une fois que vous avez créé un flux de vérification humaine, vous pouvez récupérer l'ARN de définition de flux à partir de la réponse :

humanReviewWorkflowArn = response["FlowDefinitionArn"]

Créer une boucle humaine

L'opération d'API que vous utilisez pour démarrer une boucle humaine dépend de l'intégration Amazon A2I que vous utilisez.

  • Si vous utilisez l'intégration intégrée Amazon Textract, vous utilisez l’opération AnalyzeDocument.

  • Si vous utilisez l'intégration intégrée Amazon Rekognition, vous utilisez l’opération DetectModerationLabels.

  • Si vous utilisez une intégration personnalisée, vous utiliserez l'opération StartHumanLoop.

Sélectionnez votre type de tâche dans le tableau suivant pour voir des exemples de demandes pour Amazon Textract et Amazon Rekognition à l'aide de l'outil AWS SDK for Python (Boto3).

Amazon Textract – Key-value pair extraction

L'exemple suivant utilise l'outil AWS SDK for Python (Boto3) pour appeler analyze_document dans la région us-west-2. Remplacez le texte en rouge et en italique par vos ressources. N’incluez le paramètre DataAttributes que si vous utilisez la main-d'œuvre Amazon Mechanical Turk. Pour plus d'informations, veuillez consulter la documentation analyze_document dans la référence d’API AWS SDK for Python (Boto).

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

Les boucles humaines ne sont créées que si la confiance d'Amazon Textract pour la tâche d'analyse des documents répond aux conditions d'activation que vous avez spécifiées dans votre flux de vérification humaine. Vous pouvez vérifier l’élément response pour déterminer si une boucle humaine a été créée. Pour voir tout ce qui est inclus dans cette réponse, veuillez consulter 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

L'exemple suivant utilise l'outil AWS SDK for Python (Boto3) pour appeler detect_moderation_labels dans la région us-west-2. Remplacez le texte en rouge et en italique par vos ressources. N’incluez le paramètre DataAttributes que si vous utilisez la main-d'œuvre Amazon Mechanical Turk. Pour plus d'informations, veuillez consulter la documentation detect_moderation_labelsdans la référence d’API AWS SDK for Python (Boto).

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

Les boucles humaines ne sont créées que si la confiance d'Amazon Rekognition pour une tâche de modération des images satisfait aux conditions d'activation que vous avez spécifiées dans votre flux de vérification humaine. Vous pouvez vérifier l’élément response pour déterminer si une boucle humaine a été créée. Pour voir tout ce qui est inclus dans cette réponse, veuillez consulter 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

L'exemple suivant utilise l'outil AWS SDK for Python (Boto3) pour appeler start_human_loop dans la région us-west-2. Remplacez le texte en rouge et en italique par vos ressources. N’incluez le paramètre DataAttributes que si vous utilisez la main-d'œuvre Amazon Mechanical Turk. Pour plus d'informations, veuillez consulter la documentation start_human_loop dans la référence d’API AWS SDK for Python (Boto).

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

Cet exemple stocke le contenu d’entrée dans la variable inputContentJson. Supposons que le contenu d'entrée contienne deux éléments : un texte de présentation et un ressenti (tel quePositive, Negative ouNeutral), et qu’il est formaté de la façon suivante :

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

Les clés initialValue et taskObject doivent correspondre aux clés utilisées dans les éléments liquides du modèle de tâche d'employé. Reportez-vous au modèle personnalisé dans Créer une interface utilisateur de tâche humaine pour voir un exemple.

Pour créer inputContentJson, procédez comme suit :

import json inputContentJson = json.dumps(inputContent)

Une boucle humaine démarre chaque fois que vous appelez start_human_loop. Pour vérifier l'état de votre boucle humaine, utilisez 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"]}")