Integração com o MTurk

Este guia fornece instruções para implantar tarefas de anotação do Potato no Amazon Mechanical Turk (MTurk).

Visão geral

O Potato se integra ao MTurk por meio do tipo de HIT External Question:

1. Você cria um HIT do tipo External Question no MTurk apontando para o seu servidor Potato
2. Os trabalhadores clicam no seu HIT e são redirecionados para o seu servidor Potato
3. O Potato extrai o ID do trabalhador e outros parâmetros da URL
4. Os trabalhadores realizam a tarefa de anotação
5. Ao concluir, os trabalhadores clicam em "Submit HIT to MTurk"

Parâmetros de URL

O MTurk passa quatro parâmetros para a URL da sua External Question:

Pré-requisitos

Requisitos do servidor

1. Servidor acessível publicamente com:

   • Porta aberta (normalmente 8080 ou 443)
   • HTTPS recomendado (obrigatório para alguns navegadores)
   • Conexão de internet estável

2. Ambiente Python com o Potato instalado

Requisitos do MTurk

1. Conta de Requester no MTurk: Cadastre-se em requester.mturk.com
2. Conta com fundos: Adicione fundos para produção (o sandbox é gratuito)

Início rápido

Passo 1: Criar sua configuração do 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

Passo 2: Iniciar seu 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

Passo 3: Criar seu HIT no MTurk

Crie um HIT do tipo External Question usando este modelo 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: Use & em vez de & no XML.

Referência de configuração

Configurações obrigatórias

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

Configurações recomendadas

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"

Testes no Sandbox

Sempre teste no MTurk Sandbox antes de ir para produção.

URLs do Sandbox

Testes locais

Teste os parâmetros de URL do 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"

Integração com a API do MTurk (opcional)

Para recursos avançados, habilite a integração com a API do MTurk:

pip install boto3

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

Habilite na sua configuração principal:

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

Criar HITs programaticamente

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

Boas práticas

Design das tarefas

1. Instruções claras: Forneça exemplos detalhados
2. Tempo razoável: Não apresse os trabalhadores
3. Pagamento justo: No mínimo o equivalente ao salário mínimo (US$ 12-15/hora)
4. Duração gerenciável: 5 a 15 minutos por HIT é o ideal

Controle de qualidade

1. Testes de qualificação: Filtre os trabalhadores previamente
2. Verificações de atenção: Inclua perguntas de verificação
3. Redundância: Vários trabalhadores por item (3 ou mais recomendados)
4. Revisar amostras: Verifique manualmente um subconjunto

Aspectos técnicos

1. Lidar com casos extremos: Os trabalhadores podem recarregar ou voltar
2. Salvar progresso: Salvamento automático, se possível
3. Erros tratados com elegância: Mostre mensagens de erro úteis

Solução de problemas

Os trabalhadores veem a página de prévia após aceitar

• Verifique se o parâmetro assignmentId está sendo passado corretamente
• A página de prévia se atualiza automaticamente; peça aos trabalhadores que aguardem

O botão de envio não funciona

• Verifique o console do navegador em busca de erros
• Verifique se o parâmetro turkSubmitTo está presente
• Verifique problemas de CORS ou de conteúdo misto

Os trabalhadores não conseguem fazer login

• Verifique se login.url_argument está definido como workerId
• Certifique-se de que login.type seja url_direct

Leitura adicional

• Integração de crowdsourcing - Configuração geral de crowdsourcing
• Controle de qualidade - Verificações de atenção e padrões de referência
• Atribuição de tarefas - Estratégias de atribuição

Para detalhes de implementação, consulte a documentação de origem.