Despliegue en Amazon Mechanical Turk

Amazon Mechanical Turk (MTurk) proporciona acceso a una fuerza laboral grande y bajo demanda para tareas de anotación. Potato se integra con MTurk a través del tipo de HIT ExternalQuestion: tu servidor de Potato actúa como la interfaz de anotación, y MTurk se encarga del reclutamiento de trabajadores, seguimiento de asignaciones y pagos. Esta guía cubre el proceso completo de configuración.

Requisitos Previos

1. Cuenta de AWS con MTurk habilitado
2. Cuenta de Requester en MTurk (producción o sandbox) en requester.mturk.com
3. Servidor de Potato accesible mediante una URL pública (se recomienda HTTPS)
4. Entorno Python con Potato instalado
5. Familiaridad básica con los conceptos de MTurk (HITs, Workers, Assignments)

Cómo Funciona la Integración

Potato no gestiona los HITs de MTurk directamente. En su lugar, la integración sigue este flujo:

1. Creas un HIT ExternalQuestion en MTurk que apunta a la URL de tu servidor de Potato
2. Un trabajador acepta el HIT en MTurk y es redirigido a tu servidor de Potato con parámetros de consulta (workerId, assignmentId, hitId, turkSubmitTo)
3. Potato usa el parámetro workerId para identificar al trabajador (mediante login.type: url_direct)
4. El trabajador completa la tarea de anotación en tu servidor de Potato
5. Al completar, Potato redirige al trabajador de vuelta al endpoint de envío de MTurk

Configuración

La clave de la integración con MTurk es establecer el tipo de login como url_direct con url_argument: workerId. Esto le dice a Potato que extraiga la identidad del trabajador del parámetro de consulta URL que MTurk pasa automáticamente.

login:
  type: url_direct
  url_argument: workerId

Esa es la única configuración específica de MTurk en Potato. Todo lo demás -- creación de HITs, calificaciones, pago, aprobación -- se gestiona en el lado de MTurk.

Ejemplo de Configuración 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
output_annotation_format: json

Configuración en MTurk

Paso 1: Inicia Tu Servidor de Potato

Lanza tu servidor de Potato en una máquina accesible públicamente:

potato start config.yaml -p 8080

Asegúrate de que el servidor sea accesible desde internet (p.ej., https://your-server.com:8080/).

Paso 2: Crea el XML de ExternalQuestion

MTurk usa un formato XML llamado ExternalQuestion para incrustar sitios web externos en un HIT. Crea el siguiente 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 el XML. MTurk sustituirá los marcadores ${...} con valores reales cuando un trabajador acepte el HIT.

Paso 3: Crea el HIT en MTurk

Puedes crear HITs a través de la Consola de Requester de MTurk o programáticamente usando el AWS SDK (boto3). La configuración del HIT como título, descripción, recompensa, duración y calificaciones se configura todo en el lado de MTurk, no en Potato.

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

Paso 4: Establece Calificaciones (en MTurk)

Las calificaciones de los trabajadores se configuran completamente en el lado de MTurk al crear tu HIT. Los filtros de calificación comunes incluyen:

• Tasa de aprobación: Requerir un porcentaje mínimo de aprobación de HITs (p.ej., 97%+)
• HITs aprobados: Requerir un número mínimo de HITs previamente aprobados (p.ej., 500+)
• Ubicación: Restringir a trabajadores de países específicos
• Masters: Usar los trabajadores Masters pre-evaluados de MTurk (se aplican tarifas más altas)
• Calificaciones personalizadas: Crear tus propias pruebas de calificación a través de la consola de MTurk

Manejo de Completación

Cuando un trabajador termina de anotar todos los elementos asignados, Potato necesita redirigirlo de vuelta a MTurk para que la asignación pueda ser enviada. MTurk pasa un parámetro URL turkSubmitTo que le dice a Potato dónde enviar la solicitud POST de completación.

El trabajador ve un botón "Submit HIT" después de completar la tarea. Al hacer clic, envía la asignación de vuelta a MTurk para tu revisión y aprobación.

Pruebas en el Sandbox de MTurk

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

Pruebas Locales

Puedes probar el flujo de parámetros URL localmente sin 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"

Cuando assignmentId es ASSIGNMENT_ID_NOT_AVAILABLE, el trabajador está previsualizando el HIT y aún no lo ha aceptado.

Gestión de HITs y Aprobaciones

La gestión de HITs -- monitorear progreso, aprobar o rechazar asignaciones, emitir bonificaciones -- se hace a través de las herramientas propias de MTurk:

• Consola de Requester de MTurk: Interfaz web para gestionar HITs, revisar asignaciones y comunicarse con trabajadores
• boto3 (AWS SDK para Python): Acceso programático para operaciones en lote

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

Cálculo de Costos

MTurk cobra tarifas además de la recompensa que pagas a los trabajadores:

• Tarifa base: 20% del monto de la recompensa
• Calificación Masters: 5% adicional
• 10+ asignaciones por HIT: 20% adicional

Ejemplo: Si pagas $0.50 por asignación con 100 asignaciones:

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

Mejores Prácticas

1. Comenzar con Sandbox: Siempre prueba el flujo completo en el sandbox antes de gastar dinero
2. Pago justo: Calcula una tarifa por hora (recompensa / tiempo estimado x 60) y apunta a al menos $12-15/hora
3. Descripciones claras de HITs: Títulos y descripciones bien escritos atraen mejores trabajadores
4. Aprobación rápida: Los trabajadores aprecian el pago rápido -- aprueba prontamente cuando la calidad es aceptable
5. Manejar rechazos con cuidado: Los rechazos afectan las tasas de aprobación de los trabajadores y tu reputación como requester
6. Usar HTTPS: Algunos navegadores bloquean contenido mixto; HTTPS asegura que el iframe funcione correctamente
7. Establecer hide_navbar: true: Evita que los trabajadores naveguen fuera de la tarea dentro de Potato
8. Monitorear tu servidor: Asegúrate de que tu servidor de Potato se mantenga activo durante la duración del HIT

Comparación: MTurk vs Prolific

Próximos Pasos

• Compara con la integración con Prolific
• Configura control de calidad
• Calcula acuerdo entre anotadores

Documentación completa de MTurk en /docs/deployment/mturk-integration. Para detalles de implementación, consulta la documentación fuente.