Integração com Crowdsourcing

Execute estudos do Potato no Prolific, no MTurk ou em qualquer painel que passe um ID de participante, com login direto por URL, códigos de conclusão e triagem por verificações de atenção.

O Potato coleta anotações de crowdsourcing lendo o ID do participante na URL para a qual a plataforma envia as pessoas e mostrando um código de conclusão no final. Esse padrão cobre o Prolific e o MTurk, e o provedor generic cobre qualquer outro painel que funcione da mesma forma.

Execução em uma porta aberta

Um trabalhador da plataforma precisa conseguir acessar o servidor, então execute-o em uma porta aberta para a internet:

bash

potato start your-project -p 8080

Os trabalhadores então chegam em https://your-server:8080/. Coloque um proxy reverso na frente dele para TLS, como descrito em Configuração de Produção.

Provedores de crowdsourcing

O bloco crowdsourcing indica a plataforma. O Prolific e o MTurk têm provedores próprios, e generic atende qualquer painel que passe um ID na URL e aceite um código de conclusão, como Besample, Positly, User Interviews, Testable Minds ou Cint:

yaml

login:
  type: url_direct
  url_argument: response_id        # must match id_param below
 
crowdsourcing:
  provider: generic                # generic | prolific | mturk
  generic:
    platform_label: "Besample"     # shown on the done-page return button
    id_param: response_id          # URL parameter carrying the participant ID
    capture_params: [study]        # extra URL params to record
    completion:
      code: "BSMP-4432"
      redirect_url: "https://besample.app/complete?rid={worker_id}&code={code}"
      failed_code: "BSMP-FAIL"     # optional, for blocked participants

redirect_url aceita os marcadores {code}, {worker_id}, {session_id}, {study_id} e qualquer nome listado em capture_params.

Uma configuração sem bloco crowdsourcing mantém o comportamento anterior, em que login.type: url_direct atende ao mesmo tempo chegadas no estilo do Prolific e no estilo do MTurk.

Prolific

Configuração mínima

Duas configurações bastam para executar um estudo no Prolific:

yaml

login:
  type: url_direct
  url_argument: PROLIFIC_PID   # the default
 
completion_code: "YOUR-PROLIFIC-CODE"

Os trabalhadores que chegam do Prolific entram com o seu PROLIFIC_PID, sem que uma senha seja pedida. Ao terminar, veem o código de conclusão e um botão para voltar ao Prolific.

A URL do estudo

Nas configurações do seu estudo no Prolific, defina a URL como:

text

https://your-server:8080/?PROLIFIC_PID={{%PROLIFIC_PID%}}&SESSION_ID={{%SESSION_ID%}}&STUDY_ID={{%STUDY_ID%}}

O Prolific substitui os valores reais. O Potato registra SESSION_ID e STUDY_ID junto com o ID do participante.

Redirecionamento na conclusão

yaml

completion_code: "YOUR-PROLIFIC-CODE"
auto_redirect_on_completion: true
auto_redirect_delay: 5000   # milliseconds

Sem o redirecionamento, a página final mostra o código com cópia por clique e um botão de retorno, que é o padrão mais seguro quando você quer que os trabalhadores guardem um registro do código.

Integração com a API do Prolific

Em estudos maiores, o Potato pode se comunicar com a API do Prolific, o que permite liberar as vagas ocupadas por trabalhadores que devolveram a tarefa ou esgotaram o tempo e pausar o estudo quando o servidor está sobrecarregado. Coloque as credenciais em um arquivo próprio:

yaml

# configs/prolific_config.yaml
token: "your-prolific-api-token"
study_id: "your-study-id"
max_concurrent_sessions: 30
workload_checker: true
workload_checker_period: 300

Depois, aponte a configuração principal para ele:

yaml

login:
  type: prolific
 
prolific:
  config_file_path: configs/prolific_config.yaml
 
completion_code: "YOUR-PROLIFIC-CODE"

workload_checker fica desligado a menos que você o ative. Com ele ativado, o Potato pausa o estudo quando os trabalhadores ativos ultrapassam max_concurrent_sessions e o retoma quando caem para 20% desse número, mas só se o próprio monitor tiver pausado o estudo. O Potato nunca retoma por conta própria um estudo que você pausou manualmente.

Recuperação de trabalho abandonado

Quando um envio volta como RETURNED, TIMED-OUT ou REJECTED, o Potato libera os itens atribuídos a esse trabalhador que ainda não foram anotados, para que outra pessoa possa pegá-los. As anotações que ele já concluiu são mantidas. instance_reclaim muda esse comportamento conforme o status:

yaml

instance_reclaim:
  enabled: true
  prolific:
    preserve_completed_annotations: true
    status_policies:
      TIMED-OUT:
        preserve_completed_annotations: true
      REJECTED:
        preserve_completed_annotations: false

Amazon Mechanical Turk

Configuração mínima

yaml

login:
  type: url_direct
  url_argument: workerId
 
completion_code: "COMPLETED"
 
hide_navbar: true
jumping_to_id_disabled: true

O HIT do tipo External Question

O MTurk envia os trabalhadores para o seu servidor por meio de uma External 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:8080/?workerId=${workerId}&amp;assignmentId=${assignmentId}&amp;hitId=${hitId}&amp;turkSubmitTo=${turkSubmitTo}</ExternalURL>
  <FrameHeight>800</FrameHeight>
</ExternalQuestion>

O Potato lê quatro parâmetros dessa URL:

Parâmetro	Descrição
`workerId`	O ID do trabalhador no MTurk, usado como nome de usuário
`assignmentId`	ID único para este par de trabalhador e HIT
`hitId`	O identificador do HIT
`turkSubmitTo`	Para onde o formulário de conclusão é enviado por POST

Inclua turkSubmitTo na URL. Sem ele, o botão de envio da página de conclusão não tem para onde mandar a atribuição.

Modo de pré-visualização

O MTurk envia assignmentId=ASSIGNMENT_ID_NOT_AVAILABLE enquanto um trabalhador pré-visualiza um HIT que ainda não aceitou. O Potato mostra uma página de pré-visualização em vez de iniciar a tarefa, e a atualiza a cada três segundos para que a tarefa comece assim que o HIT for aceito. O Sandbox e a produção diferem apenas no host para o qual turkSubmitTo aponta, então a mesma configuração funciona nos dois.

Integração com a API do MTurk

Com o boto3 instalado e credenciais da AWS que tenham permissões de solicitante do MTurk, o Potato pode listar as atribuições e aprová-las automaticamente:

yaml

# configs/mturk_config.yaml
aws_access_key_id: "YOUR_AWS_ACCESS_KEY"
aws_secret_access_key: "YOUR_AWS_SECRET_KEY"
sandbox: true
hit_id: "YOUR_HIT_ID"

yaml

login:
  type: url_direct
  url_argument: workerId
 
mturk:
  enabled: true
  config_file_path: configs/mturk_config.yaml

Mantenha esse arquivo fora do controle de versão e, em produção, prefira variáveis de ambiente.

Controle de Qualidade

Verificações de atenção

Itens com respostas conhecidas, misturados na fila:

yaml

attention_checks:
  enabled: true
  items_file: data/attention_checks.json
  frequency: 10
  min_response_time: 3.0
  failure_handling:
    warn_threshold: 2
    warn_message: "Please read items carefully before answering."
    block_threshold: 5
    block_message: "You have been blocked due to too many incorrect responses."

min_response_time detecta a falha a que o crowdsourcing está mais exposto, que é clicar mais rápido do que qualquer pessoa conseguiria ler o item.

Padrões ouro

Itens rotulados por especialistas medem a precisão, e não a atenção, e por padrão ficam silenciosos, para que os trabalhadores não recebam nenhum retorno que os ensine as respostas:

yaml

gold_standards:
  enabled: true
  items_file: data/gold_standards.json
  mode: mixed
  frequency: 20
  accuracy:
    min_threshold: 0.7
    evaluation_count: 5

Consulte Controle de Qualidade para ver os formatos dos itens e como ambos são relatados.

Páginas de conclusão personalizadas

A página de conclusão integrada cuida de um código e de um botão de retorno. Quando você precisar de mais do que isso, termine o estudo com uma página de surveyflow:

yaml

surveyflow:
  on: true
  order:
    - pre_annotation
    - post_annotation
  pre_annotation:
    - surveyflow/consent.jsonl
  post_annotation:
    - surveyflow/end.jsonl

A página final é um item pure_display que leva o link ou o texto de que você precisar:

json

{"id":"1","text":"Thanks for participating. Click below to complete the study.","schema":"pure_display","choices":["<a href=\"https://app.prolific.com/submissions/complete?cc=YOUR-CODE\" target=\"_blank\">Complete Study on Prolific</a>"]}

Exemplo completo: estudo no Prolific

yaml

annotation_task_name: "Sentiment Analysis Study"
task_dir: .
 
login:
  type: url_direct
  url_argument: PROLIFIC_PID
 
completion_code: "SENT2024"
auto_redirect_on_completion: false
 
hide_navbar: true
jumping_to_id_disabled: true
 
user_config:
  allow_all_users: true
 
assignment_strategy: random
max_annotations_per_user: 50
num_annotators_per_item: 3
 
phases:
  order:
    - consent
    - instructions
    - annotation
  consent:
    file: data/consent.html
  instructions:
    file: data/instructions.html
  annotation:
    type: annotation
 
attention_checks:
  enabled: true
  items_file: data/attention_checks.json
  frequency: 10
  failure_handling:
    warn_threshold: 2
    block_threshold: 5
 
data_files:
  - data/main.json
 
item_properties:
  id_key: id
  text_key: text
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment of this text?"
    labels:
      - Positive
      - Negative
      - Neutral
    sequential_key_binding: true
 
output_annotation_dir: annotation_output/
export_annotation_format: jsonl

Exemplo completo: HIT do MTurk

yaml

annotation_task_name: "Image Classification HIT"
task_dir: .
 
login:
  type: url_direct
  url_argument: workerId
 
completion_code: "TASK_COMPLETE"
 
hide_navbar: true
jumping_to_id_disabled: true
 
user_config:
  allow_all_users: true
 
assignment_strategy: random
max_annotations_per_user: 20
num_annotators_per_item: 3
 
data_files:
  - data/items.json
 
item_properties:
  id_key: id
  text_key: image_url
 
instance_display:
  fields:
    - key: image_url
      type: image
      label: "Image"
      display_options:
        max_width: 800
 
annotation_schemes:
  - annotation_type: radio
    name: category
    description: "What is shown in this image?"
    labels:
      - Cat
      - Dog
      - Bird
      - Other
    sequential_key_binding: true
 
output_annotation_dir: annotation_output/

Monitoramento do estudo

O painel administrativo em /admin informa as taxas de conclusão, o tempo por instância e os resultados das verificações de atenção enquanto o estudo está em andamento. Para acessá-lo é preciso a chave compartilhada admin_api_key ou um papel que inclua view_admin_dashboard:

yaml

admin_api_key: "your-shared-key"
 
rbac:
  enabled: true
  user_role_assignments:
    researcher@university.edu: admin

Exporte as anotações coletadas com a CLI de exportação:

bash

python -m potato.export -c config.yaml -f csv -o ./export/

Boas práticas

Faça um piloto primeiro: rode com alguns poucos trabalhadores antes de lançar em grande escala
Pague de forma justa: cronometre a tarefa você mesmo e defina o valor pela duração real
Escreva instruções claras: inclua exemplos e os casos extremos que você espera
Use verificações de atenção: detecte cedo quem clica sem ler, e não na análise
Adicione padrões ouro: atenção e precisão são medidas diferentes
Acompanhe o painel: problemas são baratos de corrigir no primeiro dia e caros no quinto
Defina os critérios de rejeição com antecedência: os trabalhadores devem conhecer o padrão antes de começar
Exporte regularmente: não espere o estudo encerrar

Leitura adicional

Integração com o MTurk: configuração detalhada do MTurk
Login sem senha: autenticação baseada em URL
Controle de Qualidade: verificações de atenção e padrões ouro
Gerenciamento de Usuários: listas de acesso, papéis e cotas

Para detalhes de implementação, consulte a documentação de origem, a referência do Prolific e a referência do MTurk.