部署到 Amazon Mechanical Turk

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
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 内导航离开任务
监控你的服务器：确保 Potato 服务器在 HIT 持续期间保持运行

对比：MTurk vs Prolific

方面	MTurk	Prolific
工人池	大，多样化	较小，研究导向
质量	参差不齐	通常较高
定价	较低基础价 + 费用	较高，透明
设置	更复杂	更简单
最适合	大规模，预算	研究，质量
Potato 配置	`url_argument: workerId`	`url_argument: PROLIFIC_PID`

下一步

与 Prolific 集成进行对比
设置质量控制
计算标注者间一致性

完整 MTurk 文档请参阅 /docs/deployment/mturk-integration。更多实现细节请参阅源文档。