ローカルでテンプレートを開発する外部アセットを使用する変数を追跡する Amazon Textract のカスタムテンプレートの例 Amazon Rekognition のカスタムテンプレートの例 Liquid を使用して自動化を追加するワーカータスクテンプレートをプレビューする

カスタムワーカータスクテンプレートを作成する

crowd HTML 要素は、質問したい内容に合わせて調整できるさまざまなタスクウィジェットとデザイン要素を提供するウェブコンポーネントです。これらの crowd 要素を使用してカスタムワーカーテンプレートを作成し、それを Amazon Augmented AI (Amazon A2I) の人間によるレビューワークフローと統合して、ワーカーコンソールと手順をカスタマイズできます。

Amazon A2I ユーザーが使用できるすべての HTML crowd 要素のリストについては、「Crowd HTML 要素のリファレンス」を参照してください。テンプレートの例については、60 AWS GitHubを超えるサンプルカスタムタスクテンプレートを含むリポジトリを参照してください。

ローカルでテンプレートを開発する

テンプレートによって入力データがどのように処理されるかをコンソールでテストする場合、次のコードを HTML ファイルの先頭に追加することによって、テンプレートの HTML およびカスタム要素のブラウザでのルックアンドフィールをテストできます。


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

これによって、カスタム HTML 要素のレンダリングに必要なコードがロードされます。このコードは、テンプレートのルックアンドフィールをコンソールではなく任意のエディタで作成する場合に使用します。

このコードでは、変数は解析されません。ローカルでの作成時には、それらを仮の内容で置き換えておくことができます。

外部アセットを使用する

Amazon Augmented AI カスタムテンプレートを使用すると、外部スクリプトやスタイルシートを埋め込むことができます。たとえば、次のヘッダーは、https://www.example.com/my-enhancement-styles.css にある stylesheet という名前の text/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 です。

変数を追跡する

カスタムテンプレートの作成時には、タスクやワーカーごとに異なる可能性のあるデータを表す変数を追加する必要があります。サンプルテンプレートの 1 つから開始する場合、そのテンプレートで既に使用されている変数を確実に把握する必要があります。

例えば、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> 要素の子要素には、2 つのリージョンを用意する必要があります。これらのリージョンで任意の 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 のカテゴリの下にボタンが作成されます。ユーザーがこのボタンを選択すると、すべてのカテゴリの選択が解除されて無効になります。ワーカーがこのボタンを再度選択すると、ユーザーがまたカテゴリを選択できるようになります。このボタンを選択した後にワーカーが [Submit] (送信) ボタンを選択してタスクを送信すると、そのタスクは空の配列を返します。

<crowd-rekognition-detect-moderation-labels> 要素の子要素には、2 つのリージョンを用意する必要があります。

<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 では、一重波括弧とパーセント記号で囲まれたテキストは、制御フローやイテレーションなどを実行する 1 つの手順またはタグになります。二重波括弧で囲まれたテキストは、値を出力する 1 つの変数またはオブジェクトです。次のリストには、テンプレート入力データの処理を自動化するのに便利な 2 種類の Liquid タグが含まれています。以下のタグタイプのいずれかを選択すると、Liquid のドキュメントにリダイレクトされます。

フロー制御: if/else、unless、case/when のようなプログラミングロジック演算子が含まれています。
イテレーション: FOR LOOP などのステートメントを使用して、コードのブロックを繰り返し実行できます。

例えば、次のコード例は Liquid の for タグを使用して for loop を作成する方法を示しています。この例では、Amazon Rekognition から返された moderationLabels をループ処理し、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; にならないようにします。

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 RenderUiTemplateRenderUiTemplateこのオペレーションは、 AWS CLI またはお好みの AWS SDK で使用できます。この API オペレーションでサポートされている言語固有の SDK に関するドキュメントについては、「RenderUiTemplate」の「See Also」セクションを参照してください。

前提条件

ワーカータスクテンプレートをプレビューするには、使用する AWS Identity and Access Management (IAM) ロール Amazon Resource Name (ARN) RoleArn、またはに、テンプレートが使用する S3 オブジェクトへのアクセス権限が必要です。ロールまたはユーザーを設定する方法については、「ワーカータスクテンプレートプレビューを有効にする」を参照してください。

`RenderUiTemplate` オペレーションを使用してワーカータスクテンプレートをプレビューするには

カスタムテンプレートをプレビューするために必要なポリシーをアタッチしたロールの RoleArn を指定します。
Task の Input パラメータで、テンプレートで定義されている変数の値を含む JSON オブジェクトを指定します。これらは、task.input.source 変数に代入される変数です。例えば、テンプレートで task.input.text という変数を定義する場合、JSON オブジェクトの変数は text: sample text のように指定できます。
UiTemplate の Content パラメータで、テンプレートを挿入します。

RenderUiTemplate を設定したら、任意の SDK または AWS CLI を使用して、テンプレートをレンダリングするリクエストを送信します。リクエストが成功した場合、レスポンスには、ワーカーの UI の HTML をレンダリングする Liquid テンプレートである RenderedContent が含まれます。

重要

テンプレートをプレビューするには、ユーザーインターフェイスでレンダリングされる Amazon S3 オブジェクトの読み取り権限を持つ IAM ロールが必要です。これらのアクセス許可を付与するために IAM ロールにアタッチできるサンプルポリシーについては、「ワーカータスクテンプレートプレビューを有効にする」を参照してください。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

ワーカータスクテンプレートを作成および削除する

適切なワーカー指示書の作成