Integración con Amazon Mechanical Turk

Esta guía proporciona instrucciones para desplegar tareas de anotación de Potato en Amazon Mechanical Turk (MTurk).

Descripción General

Potato se integra con MTurk a través del tipo de HIT External Question:

1. Creas un HIT de tipo External Question en MTurk apuntando a tu servidor Potato
2. Los trabajadores hacen clic en tu HIT y son redirigidos a tu servidor Potato
3. Potato extrae el ID del trabajador y otros parámetros de la URL
4. Los trabajadores completan la tarea de anotación
5. Al finalizar, los trabajadores hacen clic en "Submit HIT to MTurk"

Parámetros de URL

MTurk pasa cuatro parámetros a la URL de tu External Question:

Requisitos Previos

Requisitos del Servidor

1. Servidor accesible públicamente con:

   • Puerto abierto (típicamente 8080 o 443)
   • HTTPS recomendado (requerido para algunos navegadores)
   • Conexión a internet estable

2. Entorno Python con Potato instalado

Requisitos de MTurk

1. Cuenta de Requester en MTurk: Regístrate en requester.mturk.com
2. Cuenta con fondos: Agrega fondos para producción (el sandbox es gratuito)

Inicio Rápido

Paso 1: Crear tu Configuración de Potato

# 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

Paso 2: Iniciar tu Servidor

# 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

Paso 3: Crear tu HIT en MTurk

Crea un HIT de tipo External Question usando esta plantilla 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>

Importante: Usa & en lugar de & en XML.

Referencia de Configuración

Configuración Requerida

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

Configuración Recomendada

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"

Pruebas en Sandbox

Siempre prueba en el MTurk Sandbox antes de pasar a producción.

URLs del Sandbox

Pruebas Locales

Prueba los parámetros de URL de MTurk localmente:

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

Integración con la API de MTurk (Opcional)

Para funciones avanzadas, habilita la integración con la API de MTurk:

pip install boto3

Crea configs/mturk_config.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"

Habilítalo en tu configuración principal:

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

Crear HITs Programáticamente

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

Mejores Prácticas

Diseño de Tareas

1. Instrucciones claras: Proporciona ejemplos detallados
2. Tiempo razonable: No apresures a los trabajadores
3. Pago justo: Al menos el equivalente al salario mínimo ($12-15/hora)
4. Duración manejable: 5-15 minutos por HIT es ideal

Control de Calidad

1. Pruebas de calificación: Filtra a los trabajadores de antemano
2. Verificaciones de atención: Incluye preguntas de verificación
3. Redundancia: Múltiples trabajadores por elemento (se recomiendan 3+)
4. Revisar muestras: Verifica manualmente un subconjunto

Aspectos Técnicos

1. Manejo de casos extremos: Los trabajadores pueden recargar o retroceder
2. Guardar progreso: Autoguardar si es posible
3. Errores elegantes: Muestra mensajes de error útiles

Solución de Problemas

Los Trabajadores Ven la Página de Vista Previa Después de Aceptar

• Verifica que el parámetro assignmentId se esté pasando correctamente
• La página de vista previa se actualiza automáticamente; pide a los trabajadores que esperen

El Botón de Envío no Funciona

• Revisa la consola del navegador en busca de errores
• Verifica que el parámetro turkSubmitTo esté presente
• Verifica problemas de CORS o contenido mixto

Los Trabajadores no Pueden Iniciar Sesión

• Verifica que login.url_argument esté configurado como workerId
• Asegúrate de que login.type sea url_direct

Lectura Adicional

• Integración de crowdsourcing - Configuración general de crowdsourcing
• Control de calidad - Verificaciones de atención y estándares de oro
• Asignación de tareas - Estrategias de asignación

Para detalles de implementación, consulta la documentación fuente.