Skip to content

MTurk 整合

在 Amazon Mechanical Turk 上部署標註任務。

本指南提供在 Amazon Mechanical Turk (MTurk) 上部署 Potato 標註任務的說明。

概述

Potato 通過外部問題 HIT 類型與 MTurk 整合：

  1. 你在 MTurk 上建立一個指向 Potato 伺服器的外部問題 HIT
  2. 工作者點選你的 HIT 並被重定向到你的 Potato 伺服器
  3. Potato 從 URL 中提取工作者 ID 和其他參數
  4. 工作者完成標註任務
  5. 完成後，工作者點選"提交 HIT 到 MTurk"

URL 參數

MTurk 向你的外部問題 URL 傳遞四個參數：

參數描述
workerId工作者的唯一 MTurk 識別符號
assignmentId該工作者-HIT 對的唯一 ID
hitIdHIT 識別符號
turkSubmitTo完成表單應 POST 到的 URL

前提條件

伺服器要求

  1. 可公開訪問的伺服器，需要：

    • 開放埠（通常為 8080 或 443）
    • 建議使用 HTTPS（某些瀏覽器必需）
    • 穩定的網路連線

  2. 安裝了 Potato 的 Python 環境

MTurk 要求

  1. MTurk 請求者賬戶：在 requester.mturk.com 註冊
  2. 已充值賬戶：生產環境需要充值（沙盒免費）

快速開始

步驟 1：建立 Potato 配置

yaml
# mturk_task.yaml
annotation_task_name: "Sentiment Classification"
task_description: "Classify the sentiment of short text snippets."
 
# MTurk login configuration
login:
  type: url_direct
  url_argument: workerId
 
# Optional completion code
completion_code: "TASK_COMPLETE"
 
# Crowdsourcing settings
hide_navbar: true
jumping_to_id_disabled: true
assignment_strategy: random
max_annotations_per_user: 10
max_annotations_per_item: 3
 
# Data files
data_files:
  - data/items.json
 
# Annotation scheme
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment of this text?"
    labels:
      - positive
      - neutral
      - negative

步驟 2：啟動伺服器

bash
# Start the server
potato start mturk_task.yaml -p 8080
 
# Or with HTTPS (recommended)
potato start mturk_task.yaml -p 443 --ssl-cert cert.pem --ssl-key key.pem

步驟 3：在 MTurk 上建立 HIT

使用以下 XML 模板建立外部問題 HIT：

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 中使用 &amp; 代替 &。

配置參考

必需設定

yaml
login:
  type: url_direct      # Required: enables URL-based authentication
  url_argument: workerId  # Required: MTurk uses 'workerId' parameter

推薦設定

yaml
hide_navbar: true           # Prevent workers from skipping
jumping_to_id_disabled: true
assignment_strategy: random
max_annotations_per_user: 10
max_annotations_per_item: 3
task_description: "Brief description for the preview page."
completion_code: "YOUR_CODE"

在沙盒中測試

在上線生產環境之前，務必在 MTurk 沙盒中進行測試。

沙盒 URL

服務URL
請求者https://requestersandbox.mturk.com
工作者https://workersandbox.mturk.com
API 端點https://mturk-requester-sandbox.us-east-1.amazonaws.com

本地測試

本地測試 MTurk URL 參數：

bash
# Test normal workflow
curl "http://localhost:8080/?workerId=TEST_WORKER&assignmentId=TEST_ASSIGNMENT&hitId=TEST_HIT"
 
# Test preview mode
curl "http://localhost:8080/?workerId=TEST_WORKER&assignmentId=ASSIGNMENT_ID_NOT_AVAILABLE&hitId=TEST_HIT"

MTurk API 整合（可選）

對於高階功能，啟用 MTurk API 整合：

bash
pip install boto3

建立 configs/mturk_config.yaml：

yaml
aws_access_key_id: "YOUR_ACCESS_KEY"
aws_secret_access_key: "YOUR_SECRET_KEY"
sandbox: true  # Set to false for production
hit_id: "YOUR_HIT_ID"

在主配置中啟用：

yaml
mturk:
  enabled: true
  config_file_path: configs/mturk_config.yaml

以程式設計方式建立 HIT

python
import boto3
 
mturk = boto3.client(
    'mturk',
    region_name='us-east-1',
    endpoint_url='https://mturk-requester-sandbox.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='Classify the sentiment of short text snippets.',
    Keywords='sentiment, classification, text',
    Reward='0.50',
    MaxAssignments=100,
    LifetimeInSeconds=86400,
    AssignmentDurationInSeconds=3600,
    AutoApprovalDelayInSeconds=604800,
    Question=question_xml
)
 
print(f"Created HIT: {response['HIT']['HITId']}")

最佳實踐

任務設計

  1. 清晰的說明：提供詳細示例
  2. 合理的時間：不要催促工作者
  3. 公平的報酬：至少等同最低工資（$12-15/小時）
  4. 適當的長度：每個 HIT 5-15 分鐘為理想

品質控制

  1. 資格測試：預先篩選工作者
  2. 注意力檢查：包含驗證問題
  3. 冗餘標註：每個項目多個工作者（建議 3+）
  4. 抽樣檢查：人工檢查一部分

技術方面

  1. 處理邊界情況：工作者可能會重新整理或返回
  2. 儲存進度：儘可能自動儲存
  3. 優雅的錯誤處理：顯示有幫助的錯誤資訊

故障排除

工作者接受後仍看到預覽頁面

  • 驗證 assignmentId 參數是否正確傳遞
  • 預覽頁面會自動重新整理；請工作者稍等

提交按鈕不起作用

  • 檢查瀏覽器控制台的錯誤資訊
  • 驗證 turkSubmitTo 參數是否存在
  • 檢查 CORS 或混合內容問題

工作者無法登入

  • 驗證 login.url_argument 設定為 workerId
  • 確保 login.type 為 url_direct

延伸閱讀

有關實現細節，請參閱原始碼文件。