MTurk 연동

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

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

개요

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

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

URL 매개변수

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

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

사전 요구 사항

서버 요구 사항

다음 조건을 갖춘 공개적으로 접근 가능한 서버:
- 열린 포트(일반적으로 8080 또는 443)
- HTTPS 권장(일부 브라우저에서는 필수)
- 안정적인 인터넷 연결
Potato가 설치된 Python 환경

MTurk 요구 사항

MTurk Requester 계정: requester.mturk.com에서 가입합니다
자금이 충전된 계정: 프로덕션을 위해 자금을 추가합니다(샌드박스는 무료입니다)

빠른 시작

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에서는 & 대신 &를 사용합니다.

구성 레퍼런스

필수 설정

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
Requester	https://requestersandbox.mturk.com
Worker	https://workersandbox.mturk.com
API Endpoint	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']}")

모범 사례

작업 설계

명확한 지침: 상세한 예시를 제공합니다
합리적인 시간: 작업자를 서두르게 하지 마세요
공정한 보수: 최소한 최저임금 수준(시간당 $12-15)
적절한 분량: HIT당 5~15분이 이상적입니다

품질 관리

자격 테스트: 작업자를 사전에 선별합니다
주의 확인: 검증 문항을 포함합니다
중복: 항목당 여러 작업자(3명 이상 권장)
샘플 검토: 일부를 수동으로 확인합니다

기술적 사항

예외 상황 처리: 작업자가 새로 고침하거나 뒤로 갈 수 있습니다
진행 상황 저장: 가능하면 자동 저장합니다
부드러운 오류 처리: 유용한 오류 메시지를 표시합니다

문제 해결

작업자가 수락 후 미리보기 페이지를 보는 경우

assignmentId 매개변수가 올바르게 전달되는지 확인합니다
미리보기 페이지는 자동으로 새로 고쳐집니다. 작업자에게 잠시 기다리도록 안내하세요

제출 버튼이 작동하지 않는 경우

브라우저 콘솔에서 오류를 확인합니다
turkSubmitTo 매개변수가 있는지 확인합니다
CORS 또는 혼합 콘텐츠 문제를 확인합니다

작업자가 로그인할 수 없는 경우

login.url_argument가 workerId로 설정되어 있는지 확인합니다
login.type이 url_direct인지 확인합니다

자주 묻는 질문

아래 질문에서는 Potato가 Mechanical Turk와 연결되는 방식과 샌드박스에서 작업을 테스트하는 방법을 다룹니다.

Potato는 Amazon Mechanical Turk와 어떻게 연동되나요?

External Question HIT를 통해 연동됩니다. Potato 서버를 가리키는 HIT를 MTurk에서 생성하면, MTurk는 각 작업자를 URL에 workerId, assignmentId, hitId, turkSubmitTo를 붙여 그 서버로 보냅니다. Potato는 이 매개변수를 읽고 주석 작업을 실행하며, 마지막에 표시되는 "Submit HIT to MTurk" 버튼으로 assignment를 MTurk에 반환합니다.

MTurk 샌드박스에서 Potato 작업을 테스트하려면 어떻게 하나요?

requestersandbox.mturk.com의 Requester 샌드박스에서 Potato 서버의 URL로 External Question HIT를 생성한 다음, workersandbox.mturk.com에서 작업자로서 해당 HIT를 수락합니다. 그 전에 테스트용 workerId, assignmentId, hitId 값을 붙여 서버 URL에 요청하면 매개변수 처리를 로컬에서 확인할 수 있고, assignmentId를 ASSIGNMENT_ID_NOT_AVAILABLE로 설정하면 미리보기 모드를 테스트할 수 있습니다.

더 읽어보기

크라우드소싱 연동 - 일반적인 크라우드소싱 설정
품질 관리 - 주의 확인 및 골드 스탠다드
작업 할당 - 할당 전략

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