创建自定义工作人员任务模板 - Amazon SageMaker
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

创建自定义工作人员任务模板

Crowd HTML 元素 是提供多种任务小部件和设计元素的 Web 组件,您可以根据您要提出的问题定制这些组件。您可以使用这些 crowd 元素创建自定义工作人员模板,并将其与 Amazon Augmented AI (Amazon A2I) 人工审核工作流集成,以自定义工作人员控制台和说明。

有关可供 Amazon A2I 用户使用的所有 HTML crowd 元素的列表,请参阅 Crowd HTML 元素参考。要查看模板示例,请参阅 AWS Github 存储库,其中包含 60 多个示例自定义任务模板。

在本地开发模板

在控制台中测试模板将如何处理传入数据时,您可以通过在 HTML 文件的顶部添加以下代码,在浏览器中测试模板的 HTML 和自定义元素的外观。

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

这会加载必要的代码来呈现自定义 HTML 元素。如果您希望在常用编辑器而非在控制台中开发您的模板的外观,则使用此代码。

此代码不会解析您的变量。您可能希望在本地开发时将它们替换示例内容。

使用外部资产

Amazon Augmented AI 自定义模板允许您嵌入外部脚本和样式表。例如,以下标题将位于 text/cssstylesheet 样式表名称 https://www.example.com/my-enhancement-styles.css 嵌入自定义模板中。

<script src="https://www.example.com/my-enhancment-script.js"></script> <link rel="stylesheet" type="text/css" href="https://www.example.com/my-enhancement-styles.css">

如果您遇到错误,请确保您的原始服务器随资产一起发送正确的 MIME 类型和编码标头。

例如,对于远程脚本,MIME 和编码类型为:application/javascript;CHARSET=UTF-8

对于远程样式表,MIME 和编码类型为:text/css;CHARSET=UTF-8

跟踪您的变量

构建自定义模板时,您必须向其中添加变量,用于表示可能在不同任务之间或者在不同工作人员之间更改的数据片段。如果您以其中一个示例模板开始,您需要确保您知道它已经使用的变量。

例如,对于将 Augmented AI 人工审核循环与 Amazon Textract 文本审核任务集成的自定义模板,使用 {{ task.input.selectedAiServiceResponse.blocks }} 作为初始值输入数据。对于 Amazon Augmented AI (Amazon A2I) 与 Amazon Rekognition 的集成,请使用 {{ task.input.selectedAiServiceResponse.moderationLabels }}。对于自定义任务类型,您需要确定任务类型的输入参数。使用指定 {{ task.input.customInputValuesForStartHumanLoop}} 的位置customInputValuesForStartHumanLoop

Amazon Textract 的自定义模板示例

所有自定义模板都以 <crowd-form> </crowd-form> 元素开始和结束。与标准 HTML <form> 元素类似,所有格式代码都应位于这些元素之间。

对于 Amazon Textract 文档分析任务,请使用 <crowd-textract-analyze-document> 元素。它使用以下属性:

  • src – 指定要注释的图像文件的 URL。

  • initialValue – 为工作人员 UI 中的属性设置初始值。

  • blockTypes(必需)– 确定工作人员可以执行的分析类型。当前仅支持 KEY_VALUE_SET

  • keys(必需)– 指定工作人员可以添加的新密钥和关联的文本值。

  • no-key-edit(必需)– 防止工作人员编辑通过 initialValue 传递的注释的键。

  • no-geometry-edit – 防止工作人员编辑通过 initialValue 传递的注释的多边形。

对于 <crowd-textract-analyze-document> 元素的子元素,您必须有两个区域。您可以在这些区域中使用任意 HTML 和 CSS 元素。

  • <full-instructions> – 工具中的 View full instructions (查看完整说明) 链接中提供的说明。您可以将此项留空,但我们建议您提供完整的说明以获得更好结果。

  • <short-instructions> – 工具侧栏中显示的任务的简要描述。您可以将此项留空,但我们建议您提供完整的说明以获得更好结果。

Amazon Textract 模板类似于以下内容。

<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"> <style> .instructions { white-space: pre-wrap; } .instructionsImage { display: inline-block; max-width: 100%; } </style> <p class='instructions'>Choose a key-value block to highlight the corresponding key-value pair in the document. If it is a valid key-value pair, review the content for the value. If the content is incorrect, correct it. The text of the value is incorrect, correct it. <img class='instructionsImage' src="https://example-site/correct-value-text.png" /> A wrong value is identified, correct it. <img class='instructionsImage' src="https://example-site/correct-value.png" /> If it is not a valid key-value relationship, choose No. <img class='instructionsImage' src="https://example-site/not-a-key-value-pair.png" /> If you can’t find the key in the document, choose Key not found. <img class='instructionsImage' src="https://example-site/key-is-not-found.png" /> If the content of a field is empty, choose Value is blank. <img class='instructionsImage' src="https://example-site/value-is-blank.png" /> <b>Examples</b> Key and value are often displayed next to or below to each other. Key and value displayed in one line. <img class='instructionsImage' src="https://example-site/sample-key-value-pair-1.png" /> Key and value displayed in two lines. <img class='instructionsImage' src="https://example-site/sample-key-value-pair-2.png" /> If the content of the value has multiple lines, enter all the text without a line break. Include all value text even if it extends beyond the highlight box. <img class='instructionsImage' 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 的自定义模板示例

所有自定义模板都以 <crowd-form> </crowd-form> 元素开始和结束。与标准 HTML <form> 元素类似,所有格式代码都应位于这些元素之间。对于 Amazon Rekognition 自定义任务模板,请使用 <crowd-rekognition-detect-moderation-labels> 元素。此元素支持以下属性:

  • categories – 字符串数组 对象数组(每个对象都具有 name 字段)。

    • 如果类别作为对象提供,则以下情况适用:

      • 显示的类别是 name 字段的值。

      • 返回的答复包含任何选定类别的完整 对象。

    • 如果类别作为字符串提供,则以下情况适用:

      • 返回的答复是选择的所有字符串的数组。

  • exclusion-category – 通过设置此属性,您可以在 UI 中的类别下创建一个按钮。当用户按下按钮时,将取消选择并禁用所有类别。如果工作人员再次按下按钮,您将重新允许用户选择类别。如果工作人员在您按下按钮之后,通过选择“提交”按钮提交任务,则该任务将返回一个空数组。

对于 <crowd-rekognition-detect-moderation-labels> 元素的子元素,您必须有两个区域。

  • <full-instructions> – 工具中的 View full instructions (查看完整说明) 链接中提供的说明。您可以将此项留空,但我们建议您提供完整的说明以获得更好结果。

  • <short-instructions> – 工具侧栏中显示的任务的简要描述。您可以将此项留空,但我们建议您提供完整的说明以获得更好结果。

使用这些元素的模板类似于如下所示。

<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>Graphic Male Nudity</b> Visuals depicting full frontal male nudity, often close ups <b>Graphic Female Nudity</b> Visuals depicting full frontal female nudity, often close ups <b>Sexual Activity</b> Visuals depicting various types of explicit sexual activities and pornography <b>Illustrated Nudity or Sexual Activity</b> Visuals depicting animated or drawn sexual activity, nudity, or pornography <b>Adult Toys</b> Visuals depicting adult toys, often in a marketing context <b>Female Swimwear or Underwear</b> Visuals depicting female person wearing only swimwear or underwear <b>Male Swimwear Or Underwear</b> Visuals depicting male person wearing only swimwear or underwear <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, such as deep cut dresses <b>Graphic Violence or Gore</b> Visuals depicting prominent blood or bloody injuries <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 <b>Self Injury</b> Visuals depicting self-inflicted cutting on the body, typically in distinctive patterns using sharp objects <b>Emaciated Bodies</b> Visuals depicting extremely malnourished human bodies <b>Corpses</b> Visuals depicting human dead bodies <b>Hanging</b> Visuals depicting death by hanging</p> </short-instructions> <full-instructions header="Instructions"></full-instructions> </crowd-rekognition-detect-moderation-labels> </crowd-form>

使用 Liquid 添加自动化功能

自定义模板系统使用 Liquid 实现自动化。Liquid 是开源内联标记语言。有关更多信息和文档,请参阅 Liquid 主页

在 Liquid 中,单大括号和百分比符号之间的文本是执行控制流程或迭代等操作的指令或标签。双大括号之间的文本是一个变量或用于输出变量值的对象。以下列表包含两种类型的 Liquid 标签,您可能会发现这些标签对于自动执行模板输入数据处理非常有用。如果您选择以下标签类型之一,则将重定向到 Liquid 文档。

  • 控制流程:包括 if/elseunless和 等编程逻辑运算符case/when

  • Iteration (迭代):使您能够使用类似于 的语句为循环重复运行代码块。

    例如,以下代码示例演示如何使用 Liquid for 标签创建适用于 循环的 。此示例循环访问从 moderationLabels 返回Amazon Rekognition的 moderationLabels ,并显示name属性parentName和 以供工作人员查看:

    {% for label in task.input.selectedAiServiceResponse.moderationLabels %} { name: &quot;{{ label.name }}&quot;, parentName: &quot;{{ label.parentName }}&quot;, }, {% endfor %}

使用变量筛选条件

除了标准 Liquid 筛选条件和操作之外, Amazon Augmented AI (Amazon A2I) 还提供了额外的筛选条件。您可以在变量名称之后放置竖线 (|) 字符,然后指定筛选条件名称,从而应用筛选条件。要链接过滤条件,请使用以下格式。

{{ <content> | <filter> | <filter> }}

自动转义和显式转义

默认情况下,输入将进行 HTML 转义,以防止在变量文本和 HTML 之间产生混淆。您可以明确添加 escape 筛选条件,使其对于读取正在进行转义的模板源的用户更显而易见。

escape_once

escape_once 可确保您的代码已经转义,而不会再次重新转义。例如,确保 &amp; 不会成为 &amp;amp;

skip_autoescape

skip_autoescape当您的内容要用作 HTML 时, 很有用。例如,您可能在边界框的完整说明中有一些文本段落和一些图像。

注意

请谨慎使用 skip_autoescape。对于模板,最佳实践是避免使用 skip_autoescape 传递功能代码或标记,除非您绝对确信您对正传递的内容具有严格的控制。如果您传递用户输入,您可能会让您的工作线程遭受跨站点脚本攻击。

to_json

to_json 对您提供给 JavaScript 对象表示法 (JSON) 的数据进行编码。如果您提供了一个对象,它会对该对象进行序列化。

grant_read_access

grant_read_access 获取 Amazon Simple Storage Service (Amazon S3) URI 并将其编码为 HTTPS URL(具有针对该资源的短期访问令牌)。这样,就可以向工作人员显示存储在 S3 存储桶中但原本无法公开访问的照片、音频或视频对象。

例 to_json 和 grant_read_access 筛选条件示例

输入

auto-escape: {{ "Have you read 'James & the Giant Peach'?" }} explicit escape: {{ "Have you read 'James & the Giant Peach'?" | escape }} explicit escape_once: {{ "Have you read 'James &amp; the Giant Peach'?" | escape_once }} skip_autoescape: {{ "Have you read 'James & the Giant Peach'?" | skip_autoescape }} to_json: {{ jsObject | to_json }} grant_read_access: {{ "s3://examplebucket/myphoto.png" | grant_read_access }}

输出

auto-escape: Have you read &#39;James &amp; the Giant Peach&#39;? explicit escape: Have you read &#39;James &amp; the Giant Peach&#39;? explicit escape_once: Have you read &#39;James &amp; the Giant Peach&#39;? skip_autoescape: Have you read 'James & the Giant Peach'? to_json: { "point_number": 8, "coords": [ 59, 76 ] } grant_read_access: https://s3.amazonaws.com/examplebucket/myphoto.png?<access token and other params>

例 自动化分类模板的示例。

要自动执行此简单文本分类示例,请包括 Liquid 标签 {{ task.input.source }}。此示例使用 crowd-classifier 元素。

<script src="https://assets.crowd.aws/crowd-html-elements.js"></script> <crowd-form> <crowd-classifier name="tweetFeeling" categories="['positive', 'negative', 'neutral', 'cannot determine']" header="Which term best describes this tweet?" > <classification-target> {{ task.input.source }} </classification-target> <full-instructions header="Analyzing a sentiment"> Try to determine the feeling the author of the tweet is trying to express. If none seems to match, choose "other." </full-instructions> <short-instructions> Pick the term that best describes the sentiment of the tweet. </short-instructions> </crowd-classifier> </crowd-form>

预览工作人员任务模板

要预览自定义工作人员任务模板,请使用 SageMaker RenderUiTemplate 操作。您可以将 RenderUiTemplate 操作与 AWS CLI 或您的常用 AWS 开发工具包结合使用。有关此 API 操作的受支持的语言特定开发工具包的文档See Also请使用 的 RenderUiTemplate 部分。

先决条件

要预览工作人员任务模板,您使用的 AWS Identity and Access Management (IAM) 角色 Amazon 资源名称 (ARN) 或 RoleArn 必须有权访问模板使用的 S3 对象。要了解如何配置角色或用户,请参阅启用工作人员任务模板预览

要使用 RenderUiTemplate 操作预览工作人员任务模板,请执行以下操作:

  1. 提供附加了所需策略的角色的 RoleArn 以预览自定义模板。

  2. Input Task 参数中,提供一个 JSON 对象,其中包含模板中定义的变量的值。这些变量用于替换 task.input.source 变量。例如,如果您在模板中定义了 task.input.text,则可以在 JSON 对象中以 "text": "sample text" 格式提供变量。

  3. 在 的 Content 参数中UiTemplate,插入您的模板。

配置了 RenderUiTemplate 之后,请使用首选开发工具包或 AWS CLI 提交请求以呈现模板。如果您的请求成功,响应将包括 RenderedContent,这是一个呈现工作人员 UI 的 HTML 的 Liquid 模板。

重要

要预览模板,您需要有权读取在用户界面上呈现的 IAM 对象的 Amazon S3 角色。有关可附加到 IAM 角色以授予这些权限的示例策略,请参阅启用工作人员任务模板预览