Skip to content

MTurk 연동

Amazon Mechanical Turk에서 Potato 주석 작업을 실행합니다. HIT, 자격 테스트, 승인 워크플로, 보너스 지급, 주석자 품질 필터링을 구성합니다.

이 가이드에서는 Amazon Mechanical Turk(MTurk)에 Potato 주석 작업을 배포하는 방법을 설명합니다.

개요

Potato는 External Question HIT 유형을 통해 MTurk와 연동됩니다.

  1. Potato 서버를 가리키는 External Question HIT를 MTurk에서 생성합니다
  2. 작업자가 HIT를 클릭하면 Potato 서버로 리디렉션됩니다
  3. Potato가 URL에서 작업자 ID와 기타 매개변수를 추출합니다
  4. 작업자가 주석 작업을 수행합니다
  5. 완료 후 작업자는 "Submit HIT to MTurk"를 클릭합니다

URL 매개변수

MTurk는 External Question URL에 네 개의 매개변수를 전달합니다.

매개변수설명
workerId작업자의 고유 MTurk 식별자
assignmentId이 작업자-HIT 쌍에 대한 고유 ID
hitIdHIT 식별자
turkSubmitTo완료 양식을 POST로 전송할 URL

사전 요구 사항

서버 요구 사항

  1. 다음 조건을 갖춘 공개적으로 접근 가능한 서버:

    • 열린 포트(일반적으로 8080 또는 443)
    • HTTPS 권장(일부 브라우저에서는 필수)
    • 안정적인 인터넷 연결

  2. Potato가 설치된 Python 환경

MTurk 요구 사항

  1. MTurk Requester 계정: 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 템플릿을 사용하여 External Question 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 Sandbox에서 테스트합니다.

샌드박스 URL

서비스URL
Requesterhttps://requestersandbox.mturk.com
Workerhttps://workersandbox.mturk.com
API Endpointhttps://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인지 확인합니다

더 읽어보기

구현 세부 사항은 원본 문서를 참조하세요.