Mettere online un task su Amazon Mechanical Turk

Amazon Mechanical Turk (MTurk) ti mette a disposizione una forza lavoro numerosa e disponibile su richiesta per i task di annotazione. Potato si aggancia a MTurk tramite gli HIT di tipo ExternalQuestion: il tuo server Potato fa da interfaccia di annotazione, mentre MTurk si occupa di reclutare i worker, tenere traccia degli assignment e pagarli. Ecco come si mette in piedi il tutto.

Requisiti

1. Un account AWS con MTurk abilitato
2. Un account MTurk Requester (in produzione o in sandbox) su requester.mturk.com
3. Un server Potato raggiungibile a un URL pubblico (usa HTTPS)
4. Un ambiente Python con Potato installato
5. Una certa familiarità con i concetti di MTurk (HIT, Worker, Assignment)

Come funziona l'integrazione

Potato non gestisce direttamente gli HIT di MTurk. Il flusso è questo:

1. Crei su MTurk un HIT di tipo ExternalQuestion che punta all'URL del tuo server Potato
2. Un worker accetta l'HIT su MTurk e viene reindirizzato al tuo server Potato con dei parametri nella query string (workerId, assignmentId, hitId, turkSubmitTo)
3. Potato legge il parametro workerId per identificare il worker (tramite login.type: url_direct)
4. Il worker svolge il task di annotazione sul tuo server Potato
5. Quando ha finito, Potato lo rimanda all'endpoint di invio di MTurk

Configurazione

L'integrazione con MTurk si riduce a una cosa sola: impostare il tipo di login su url_direct con url_argument: workerId. Così Potato sa di dover ricavare l'identità del worker dal parametro che MTurk passa in automatico nell'URL.

login:
  type: url_direct
  url_argument: workerId

È l'unica impostazione specifica per MTurk in Potato. Creazione degli HIT, qualificazioni, pagamenti e approvazioni avvengono tutti dal lato MTurk.

Esempio di configurazione completa

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

Configurazione dal lato MTurk

Passo 1: avvia il server Potato

Avvia il server Potato su una macchina raggiungibile pubblicamente:

potato start config.yaml -p 8080

Assicurati che il server sia raggiungibile da internet (per esempio https://your-server.com:8080/).

Passo 2: prepara l'XML di ExternalQuestion

MTurk incorpora i siti esterni dentro un HIT usando un formato XML chiamato ExternalQuestion. L'XML che ti serve è questo:

<?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>

Importante: nell'XML usa & al posto di &. MTurk sostituisce i segnaposto ${...} con i valori reali nel momento in cui un worker accetta l'HIT.

Passo 3: crea l'HIT su MTurk

Puoi creare gli HIT dalla MTurk Requester Console oppure a livello di codice con l'AWS SDK (boto3). Impostazioni come titolo, descrizione, compenso, durata e qualificazioni stanno tutte dal lato MTurk, non in Potato.

Con boto3 (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']}")

Passo 4: imposta le qualificazioni (su MTurk)

Le qualificazioni dei worker si impostano dal lato MTurk quando crei l'HIT. I filtri più usati:

• Tasso di approvazione: richiedi una percentuale minima di HIT approvati, per esempio il 97% o più
• HIT approvati: richiedi un numero minimo di HIT già approvati, per esempio 500 o più
• Locale: limita ai worker di determinati paesi
• Masters: usa i worker Masters già selezionati da MTurk (costano di più)
• Qualificazioni personalizzate: crea i tuoi test di qualificazione dalla console MTurk

Gestione del completamento

Quando un worker finisce tutti gli elementi che gli sono stati assegnati, Potato deve rimandarlo a MTurk perché l'assignment venga inviato. MTurk passa un parametro turkSubmitTo nell'URL che dice a Potato dove mandare la richiesta POST di completamento.

Finito il task, al worker compare un pulsante «Submit HIT». Cliccandolo, l'assignment torna a MTurk per la tua revisione e approvazione.

Fare le prove nella MTurk Sandbox

Prova tutto quanto nella MTurk Sandbox prima di spendere soldi veri in produzione.

Prove in locale

Il flusso dei parametri nell'URL puoi provarlo in locale, senza MTurk:

# 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"

Quando assignmentId vale ASSIGNMENT_ID_NOT_AVAILABLE, il worker sta guardando l'anteprima dell'HIT e non l'ha ancora accettato.

Gestire HIT e approvazioni

Gli HIT si gestiscono con gli strumenti di MTurk, che si tratti di seguire l'avanzamento, approvare o rifiutare gli assignment o erogare bonus:

• MTurk Requester Console: un'interfaccia web per gestire gli HIT, rivedere gli assignment e scrivere ai worker
• boto3 (l'AWS SDK per Python): accesso programmatico per le operazioni in blocco

# 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.'
)

Calcolo dei costi

MTurk applica delle commissioni che si aggiungono al compenso che paghi ai worker:

• Commissione base: 20% dell'importo del compenso
• Qualificazione Masters: un 5% in più
• 10 o più assignment per HIT: un 20% in più

Per esempio, se paghi $0.50 per assignment su 100 assignment:

• Costo base: 100 x $0.50 x 1.20 = $60.00
• Con i Masters: 100 x $0.50 x 1.25 = $62.50

Cose che conviene fare

1. Parti dalla sandbox. Fai girare lì tutto il flusso prima che passi del denaro.
2. Paga in modo equo. Calcola la tariffa oraria (compenso / tempo stimato x 60) e punta a $12-$15 all'ora o più.
3. Scrivi descrizioni chiare degli HIT. Titoli e descrizioni fatti bene attirano worker migliori.
4. Approva in fretta. I worker notano chi paga in tempi rapidi, quindi approva appena la qualità ti sembra a posto.
5. Vai cauto con i rifiuti. Abbassano il tasso di approvazione dei worker e la tua reputazione da requester, quindi usali con parsimonia.
6. Usa HTTPS. Alcuni browser bloccano i contenuti misti, e con HTTPS l'iframe continua a funzionare.
7. Imposta hide_navbar: true così i worker non possono allontanarsi dal task dentro Potato.
8. Tieni il server acceso per tutta la vita dell'HIT.

MTurk e Prolific a confronto

Dove andare da qui

• Confronta questo approccio con l'integrazione con Prolific
• Imposta il controllo di qualità
• Calcola l'accordo tra annotatori

Per tutti i dettagli sulla configurazione di MTurk, vedi la documentazione sorgente. Se stai portando avanti un progetto di crowdsourcing più grande, la guida al crowdsourcing tratta la gestione dei worker e il monitoraggio della qualità sulle varie piattaforme.

Documentazione completa su MTurk in Integrazione MTurk.