Guides4 min read
部署到 Amazon Mechanical Turk
在 MTurk 上執行 Potato 標註任務的分步說明，包括資格測試和審批工作流。
Potato Team
Amazon Mechanical Turk (MTurk) 提供了大規模的按需勞動力用於標註任務。Potato 通過 ExternalQuestion HIT 類型與 MTurk 整合：你的 Potato 伺服器作為標註介面，MTurk 負責工人招募、任務分配和支付。本指南涵蓋完整的設定過程。
前提條件
- 已啟用 MTurk 的 AWS 賬號
- MTurk 請求者賬號（生產或沙箱環境）：requester.mturk.com
- 可通過公共 URL 訪問的 Potato 伺服器（推薦使用 HTTPS）
- 安裝了 Potato 的 Python 環境
- 基本瞭解 MTurk 概念（HIT、Worker、Assignment）
整合工作原理
Potato 不直接管理 MTurk HIT。整合流程如下：
- 你在 MTurk 上建立指向 Potato 伺服器 URL 的 ExternalQuestion HIT
- 工人在 MTurk 上接受 HIT 後被重定向到你的 Potato 伺服器，帶有查詢參數（
workerId、assignmentId、hitId、turkSubmitTo） - Potato 使用
workerId參數識別工人（通過login.type: url_direct） - 工人在 Potato 伺服器上完成標註任務
- 完成後，Potato 將工人重定向回 MTurk 的提交端點
配置
MTurk 整合的關鍵是將登入類型設定為 url_direct，url_argument 設為 workerId。這告訴 Potato 從 MTurk 自動傳遞的 URL 查詢參數中提取工人身份。
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
export_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}&assignmentId=${assignmentId}&hitId=${hitId}&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}&assignmentId=${assignmentId}&hitId=${hitId}&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 內導航離開任務 - 監控你的伺服器：確保 Potato 伺服器在 HIT 持續期間保持執行
對比：MTurk vs Prolific
| 方面 | MTurk | Prolific |
|---|---|---|
| 工人池 | 大，多樣化 | 較小，研究導向 |
| 品質 | 參差不齊 | 通常較高 |
| 定價 | 較低基礎價 + 費用 | 較高，透明 |
| 設定 | 更復雜 | 更簡單 |
| 最適合 | 大規模，預算 | 研究，品質 |
| Potato 配置 | url_argument: workerId | url_argument: PROLIFIC_PID |
下一步
- 與 Prolific 整合進行對比
- 設定品質控制
- 計算標註者間一致性