Implantando no Amazon Mechanical Turk

O Amazon Mechanical Turk (MTurk) oferece uma grande força de trabalho sob demanda para tarefas de anotação. O Potato se conecta ao MTurk pelo tipo de HIT ExternalQuestion: seu servidor Potato é a interface de anotação, e o MTurk cuida de recrutar trabalhadores, acompanhar as atribuições e pagá-los. Veja como montar tudo isso.

Pré-requisitos

1. Uma conta da AWS com o MTurk habilitado
2. Uma conta de Requester do MTurk (produção ou sandbox) em requester.mturk.com
3. Um servidor Potato acessível em uma URL pública (use HTTPS)
4. Um ambiente Python com o Potato instalado
5. Alguma familiaridade com os conceitos do MTurk (HITs, Workers, Assignments)

Como funciona a integração

O Potato não gerencia os HITs do MTurk diretamente. O fluxo é assim:

1. Você cria um HIT ExternalQuestion no MTurk que aponta para a URL do seu servidor Potato
2. Um trabalhador aceita o HIT no MTurk e é redirecionado para o seu servidor Potato com parâmetros de consulta (workerId, assignmentId, hitId, turkSubmitTo)
3. O Potato lê o parâmetro workerId para identificar o trabalhador (via login.type: url_direct)
4. O trabalhador realiza a tarefa de anotação no seu servidor Potato
5. Ao terminar, o Potato o redireciona de volta para o endpoint de envio do MTurk

Configuração

A integração com o MTurk se resume a uma coisa: defina o tipo de login como url_direct com url_argument: workerId. Isso diz ao Potato para extrair a identidade do trabalhador do parâmetro de consulta da URL que o MTurk passa automaticamente.

login:
  type: url_direct
  url_argument: workerId

Essa é a única configuração específica do MTurk no Potato. A criação de HITs, as qualificações, o pagamento e a aprovação acontecem todos do lado do MTurk.

Exemplo de configuração 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

Configurando no MTurk

Passo 1: Inicie seu servidor Potato

Inicie seu servidor Potato em uma máquina acessível publicamente:

potato start config.yaml -p 8080

Certifique-se de que o servidor seja acessível pela internet (por exemplo, https://your-server.com:8080/).

Passo 2: Crie o XML do ExternalQuestion

O MTurk incorpora sites externos em um HIT usando um formato XML chamado ExternalQuestion. Veja o XML de que você precisa:

<?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. O MTurk substitui os marcadores ${...} por valores reais quando um trabalhador aceita o HIT.

Passo 3: Crie o HIT no MTurk

Você pode criar HITs pelo Console de Requester do MTurk ou programaticamente com o AWS SDK (boto3). Configurações do HIT como título, descrição, recompensa, duração e qualificações ficam todas do lado do MTurk, não no 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']}")

Passo 4: Defina as qualificações (no MTurk)

Você define as qualificações dos trabalhadores do lado do MTurk ao criar o HIT. Filtros comuns:

• Taxa de aprovação: exija um percentual mínimo de aprovação de HITs, digamos 97% ou mais
• HITs aprovados: exija um número mínimo de HITs previamente aprovados, digamos 500 ou mais
• Localidade: limite a trabalhadores de países específicos
• Masters: use os trabalhadores Masters pré-avaliados do MTurk (isso custa mais)
• Qualificações personalizadas: crie seus próprios testes de qualificação pelo console do MTurk

Tratamento da conclusão

Quando um trabalhador termina todos os itens atribuídos, o Potato precisa redirecioná-lo de volta ao MTurk para que a atribuição seja enviada. O MTurk passa um parâmetro de URL turkSubmitTo que diz ao Potato para onde enviar a requisição POST de conclusão.

Depois de concluir a tarefa, o trabalhador vê um botão "Submit HIT". Ao clicar nele, a atribuição volta para o MTurk para sua revisão e aprovação.

Testando no Sandbox do MTurk

Teste tudo no Sandbox do MTurk antes de gastar dinheiro de verdade em produção.

Teste local

Você pode testar o fluxo de parâmetros de URL localmente, sem o 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 o assignmentId é ASSIGNMENT_ID_NOT_AVAILABLE, o trabalhador está pré-visualizando o HIT e ainda não o aceitou.

Gerenciando HITs e aprovações

Você gerencia os HITs pelas próprias ferramentas do MTurk, seja para acompanhar o progresso, aprovar ou rejeitar atribuições ou conceder bônus:

• Console de Requester do MTurk: uma interface web para gerenciar HITs, revisar atribuições e enviar mensagens aos trabalhadores
• boto3 (o AWS SDK para Python): acesso programático para operações em 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 custos

O MTurk cobra taxas além da recompensa que você paga aos trabalhadores:

• Taxa base: 20% do valor da recompensa
• Qualificação Masters: 5% adicionais
• 10 ou mais atribuições por HIT: 20% adicionais

Por exemplo, se você paga US$ 0,50 por atribuição em 100 atribuições:

• Custo base: 100 x US$ 0,50 x 1,20 = US$ 60,00
• Com Masters: 100 x US$ 0,50 x 1,25 = US$ 62,50

O que vale a pena fazer

1. Comece no sandbox. Rode o fluxo de trabalho inteiro ali antes de qualquer dinheiro trocar de mãos.
2. Pague de forma justa. Calcule a taxa por hora (recompensa / tempo estimado x 60) e mire em US$ 12 a US$ 15 por hora ou mais.
3. Escreva descrições claras de HIT. Bons títulos e descrições atraem trabalhadores melhores.
4. Aprove rápido. Os trabalhadores percebem o pagamento ágil, então aprove assim que a qualidade parecer boa.
5. Tenha cuidado com rejeições. Elas prejudicam a taxa de aprovação dos trabalhadores e a sua própria reputação como requester, então use-as com parcimônia.
6. Use HTTPS. Alguns navegadores bloqueiam conteúdo misto, e o HTTPS mantém o iframe funcionando.
7. Defina hide_navbar: true para que os trabalhadores não saiam da tarefa dentro do Potato.
8. Mantenha seu servidor no ar durante toda a vida do HIT.

MTurk vs Prolific

Para onde ir agora

• Compare isto com a integração com o Prolific
• Configure o controle de qualidade
• Calcule a concordância entre anotadores

Para todos os detalhes da configuração do MTurk, consulte a documentação de origem. Se você estiver tocando um esforço maior de crowdsourcing, o guia de crowdsourcing cobre o gerenciamento de trabalhadores e o monitoramento de qualidade entre plataformas.

Documentação completa do MTurk em /docs/deployment/mturk-integration.