Amazon Mechanical Turkへのデプロイ

Amazon Mechanical Turk（MTurk）は、アノテーションタスク向けに大規模なオンデマンドワーカープールへのアクセスを提供します。PotatoはExternalQuestion HITタイプを通じてMTurkと統合されます：Potatoサーバーがアノテーションインターフェースとして機能し、MTurkがワーカーの採用、割り当て追跡、および支払いを処理します。本ガイドでは、完全なセットアッププロセスを説明します。

前提条件

MTurkが有効化されたAWSアカウント
requester.mturk.comでのMTurkリクエスターアカウント（本番またはサンドボックス）
パブリックURL経由でアクセス可能なPotatoサーバー（HTTPS推奨）
PotatoがインストールされたPython環境
MTurkの基本概念（HIT、ワーカー、アサインメント）の理解

統合の仕組み

PotatoはMTurkのHITを直接管理しません。代わりに、統合は以下のフローに従います：

MTurk上でPotatoサーバーのURLを指すExternalQuestion HITを作成する
ワーカーがMTurkでHITを承諾し、クエリパラメータ（workerId、assignmentId、hitId、turkSubmitTo）付きでPotatoサーバーにリダイレクトされる
PotatoはworkerIdパラメータを使用してワーカーを識別する（login.type: url_direct経由）
ワーカーがPotatoサーバー上でアノテーションタスクを完了する
完了すると、PotatoがワーカーをMTurkの送信エンドポイントにリダイレクトする

設定

MTurk統合の鍵は、ログインタイプをurl_directに設定し、url_argument: workerIdとすることです。これにより、PotatoはMTurkが自動的に渡すURLクエリパラメータからワーカーのIDを抽出します。

yaml

login:
  type: url_direct
  url_argument: workerId

これがPotato内で唯一のMTurk固有の設定です。HITの作成、資格、支払い、承認など、その他すべてはMTurk側で管理されます。

完全な設定例

yaml

annotation_task_name: "Sentiment Classification"
task_description: "Classify the sentiment of short text snippets."
 
# MTurk login: extract worker ID from URL parameter
login:
  type: url_direct
  url_argument: workerId
 
# UI settings recommended for crowdsourcing
hide_navbar: true
jumping_to_id_disabled: true
 
# Assignment settings
assignment_strategy: random
max_annotations_per_user: 20
max_annotations_per_item: 3
 
# Data
data_files:
  - data/items.json
 
item_properties:
  id_key: id
  text_key: text
 
# Annotation scheme
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment of this text?"
    labels:
      - Positive
      - Negative
      - Neutral
 
# Output
output_annotation_dir: annotation_output
output_annotation_format: json

MTurkでのセットアップ

ステップ1：Potatoサーバーの起動

公開アクセス可能なマシンでPotatoサーバーを起動します：

bash

potato start config.yaml -p 8080

サーバーがインターネットからアクセス可能であることを確認してください（例：https://your-server.com:8080/）。

ステップ2：ExternalQuestion XMLの作成

MTurkはExternalQuestionと呼ばれるXML形式を使用して、外部ウェブサイトをHITに埋め込みます。以下のXMLを作成してください：

xml

<?xml version="1.0" encoding="UTF-8"?>
<ExternalQuestion xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2006-07-14/ExternalQuestion.xsd">
  <ExternalURL>https://your-server.com:8080/?workerId=${workerId}&amp;assignmentId=${assignmentId}&amp;hitId=${hitId}&amp;turkSubmitTo=${turkSubmitTo}</ExternalURL>
  <FrameHeight>800</FrameHeight>
</ExternalQuestion>

重要: XMLでは&の代わりに&を使用してください。MTurkはワーカーがHITを承諾した際に${...}プレースホルダーを実際の値に置換します。

ステップ3：MTurkでHITを作成する

MTurkリクエスターコンソールまたはプログラム的に**AWS SDK（boto3）**を使用してHITを作成できます。タイトル、説明、報酬、期間、資格などのHIT設定はすべてMTurk側で設定され、Potatoでは設定しません。

boto3（Python）を使用する場合

python

import boto3
 
# Use sandbox for testing
mturk = boto3.client(
    'mturk',
    region_name='us-east-1',
    endpoint_url='https://mturk-requester-sandbox.us-east-1.amazonaws.com'
)
 
# For production, omit endpoint_url or use:
# endpoint_url='https://mturk-requester.us-east-1.amazonaws.com'
 
question_xml = '''<?xml version="1.0" encoding="UTF-8"?>
<ExternalQuestion xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2006-07-14/ExternalQuestion.xsd">
  <ExternalURL>https://your-server.com:8080/?workerId=${workerId}&amp;assignmentId=${assignmentId}&amp;hitId=${hitId}&amp;turkSubmitTo=${turkSubmitTo}</ExternalURL>
  <FrameHeight>800</FrameHeight>
</ExternalQuestion>'''
 
response = mturk.create_hit(
    Title='Sentiment Classification Task',
    Description='Read short texts and classify their sentiment as positive, negative, or neutral.',
    Keywords='sentiment, classification, text, NLP',
    Reward='0.50',
    MaxAssignments=100,
    LifetimeInSeconds=86400,         # 1 day
    AssignmentDurationInSeconds=3600, # 1 hour
    AutoApprovalDelayInSeconds=604800, # 7 days
    Question=question_xml,
    QualificationRequirements=[
        {
            'QualificationTypeId': '000000000000000000L0',  # Approval rate
            'Comparator': 'GreaterThanOrEqualTo',
            'IntegerValues': [97]
        },
        {
            'QualificationTypeId': '00000000000000000040',  # Number approved
            'Comparator': 'GreaterThanOrEqualTo',
            'IntegerValues': [500]
        },
        {
            'QualificationTypeId': '00000000000000000071',  # Locale
            'Comparator': 'In',
            'LocaleValues': [
                {'Country': 'US'},
                {'Country': 'GB'},
                {'Country': 'CA'},
                {'Country': 'AU'}
            ]
        }
    ]
)
 
print(f"Created HIT: {response['HIT']['HITId']}")

ステップ4：資格の設定（MTurk側）

ワーカーの資格はすべてMTurk側でHITを作成する際に設定されます。一般的な資格フィルターには以下が含まれます：

承認率: 最低HIT承認率の要求（例：97%以上）
承認済みHIT数: 過去に承認されたHITの最低数の要求（例：500件以上）
地域: 特定の国のワーカーに制限
Masters: MTurkの事前審査済みMastersワーカーを使用（追加料金あり）
カスタム資格: MTurkコンソールから独自の資格テストを作成

完了処理

ワーカーが割り当てられたすべてのアイテムのアノテーションを完了すると、Potatoはワーカーをアサインメントの送信のためにMTurkにリダイレクトする必要があります。MTurkはturkSubmitTo URLパラメータを渡し、Potatoに完了POSTリクエストの送信先を指示します。

ワーカーはタスク完了後に「Submit HIT」ボタンを確認します。クリックすると、レビューと承認のためにMTurkにアサインメントが送信されます。

MTurkサンドボックスでのテスト

本番に移行する前に、必ずMTurkサンドボックスでセットアップをテストしてください。

サービス	URL
リクエスターサンドボックス	https://requestersandbox.mturk.com
ワーカーサンドボックス	https://workersandbox.mturk.com
APIエンドポイント（サンドボックス）	https://mturk-requester-sandbox.us-east-1.amazonaws.com

ローカルテスト

MTurkなしでURLパラメータのフローをローカルでテストできます：

bash

# Simulate a worker accessing your task
curl "http://localhost:8080/?workerId=TEST_WORKER&assignmentId=TEST_ASSIGN&hitId=TEST_HIT"
 
# Simulate the preview mode (before a worker accepts the HIT)
curl "http://localhost:8080/?workerId=TEST_WORKER&assignmentId=ASSIGNMENT_ID_NOT_AVAILABLE&hitId=TEST_HIT"

assignmentIdがASSIGNMENT_ID_NOT_AVAILABLEの場合、ワーカーはHITをプレビュー中であり、まだ承諾していません。

HITと承認の管理

HIT管理（進捗の監視、アサインメントの承認・却下、ボーナスの発行）はMTurk独自のツールで行います：

MTurkリクエスターコンソール: HITの管理、アサインメントのレビュー、ワーカーとのコミュニケーション用のWebインターフェース
boto3（AWS SDK for Python）: バッチ操作用のプログラムアクセス

python

# Example: List assignments for a HIT
assignments = mturk.list_assignments_for_hit(
    HITId='YOUR_HIT_ID',
    AssignmentStatuses=['Submitted']
)
 
# Approve an assignment
mturk.approve_assignment(AssignmentId='ASSIGNMENT_ID')
 
# Reject an assignment (use sparingly)
mturk.reject_assignment(
    AssignmentId='ASSIGNMENT_ID',
    RequesterFeedback='Did not complete all items.'
)

コスト計算

MTurkはワーカーに支払う報酬に加えて手数料を請求します：

基本手数料: 報酬額の20%
Masters資格: 追加5%の手数料
HIT当たり10件以上のアサインメント: 追加20%の手数料

例: アサインメント当たり$0.50で100件のアサインメントの場合：

基本コスト: 100 x $0.50 x 1.20 = $60.00
Masters使用時: 100 x $0.50 x 1.25 = $62.50

ベストプラクティス

サンドボックスから始める: お金を使う前に必ずサンドボックスで完全なワークフローをテストする
公正な報酬: 時給を計算し（報酬 / 推定時間 x 60）、少なくとも$12-15/時を目指す
明確なHIT説明: 適切に書かれたタイトルと説明は優れたワーカーを引き付ける
迅速な承認: ワーカーは迅速な支払いを評価する - 品質が許容範囲内であれば速やかに承認する
却下は慎重に: 却下はワーカーの承認率に影響し、リクエスターの評判にも影響する
HTTPSを使用する: 一部のブラウザは混合コンテンツをブロックする；HTTPSによりiframeが確実に動作する
hide_navbar: trueを設定する: ワーカーがPotato内でタスクから離れることを防ぐ
サーバーを監視する: HITの期間中、Potatoサーバーが稼働し続けることを確認する

比較：MTurk vs Prolific

項目	MTurk	Prolific
ワーカープール	大規模、多様	小規模、研究向け
品質	ばらつきがある	一般的に高い
価格	基本料金低い + 手数料	高いが透明性がある
セットアップ	より複雑	よりシンプル
最適な用途	大規模、予算重視	研究、品質重視
Potato設定	`url_argument: workerId`	`url_argument: PROLIFIC_PID`

次のステップ

Prolific統合と比較する
品質管理を設定する
アノテーター間一致度を計算する

MTurkの完全なドキュメントは/docs/deployment/mturk-integrationをご覧ください。実装の詳細については、ソースドキュメントを参照してください。