Gerenciamento de Usuários

Gerencie anotadores no Potato com listas de acesso em user_config, login direto por URL, papéis e permissões RBAC, cotas de trabalho por anotador e fases de treinamento.

O Potato decide três coisas diferentes sobre uma pessoa: se ela pode se cadastrar, o que ela pode fazer depois de entrar e quanto trabalho ela recebe. Cada uma é um bloco de configuração diferente, e confundi-los é a causa mais comum de um anotador que consegue fazer login mas nunca recebe nenhum item.

Modos de acesso

Acesso aberto

O Potato permite o autocadastro por padrão, então um novo anotador cria a própria conta na página de login:

yaml

user_config:
  allow_all_users: true

Acesso restrito

Defina allow_all_users: false e liste os endereços autorizados a se cadastrar. Ninguém mais consegue criar uma conta:

yaml

user_config:
  allow_all_users: false
  users:
    - alice@example.com
    - bob@example.com
    - researcher@university.edu

As duas chaves ficam dentro de user_config. Escritas no nível superior, elas são ignoradas sem aviso, e o resultado é uma lista de acesso que não faz nada.

Autenticação

É o padrão. Os anotadores se cadastram com um e-mail e uma senha, que o Potato armazena como um hash PBKDF2 com salt próprio de cada usuário.

yaml

login:
  type: password

url_direct pega o nome de usuário diretamente de um parâmetro da URL e não pede senha. É assim que são tratados os participantes que chegam de plataformas de crowdsourcing:

yaml

login:
  type: url_direct
  url_argument: PROLIFIC_PID

Os anotadores então chegam em http://your-server:8000/?PROLIFIC_PID=abc123 e entram como abc123.

url_argument também aceita uma lista. Nesse caso, a pasta de saída do anotador recebe o nome formado pela junção dos valores:

yaml

login:
  type: url_direct
  url_argument:
    - PROLIFIC_PID
    - STUDY_ID
    - SESSION_ID

Os três tipos de login são password, url_direct e prolific. O último acrescenta a integração com a API do Prolific ao login direto por URL. Consulte Integração com crowdsourcing para a parte da plataforma.

Papéis e permissões

A chave de administração compartilhada

admin_api_key é uma única chave compartilhada, enviada no cabeçalho X-API-Key, que ignora todas as verificações de permissão. Quando não é definida, o Potato gera uma e a grava em {task_dir}/admin_api_key.txt.

yaml

admin_api_key: "your-shared-key"

Controle de acesso baseado em papéis

Com um bloco rbac, pessoas designadas chegam ao painel administrativo fazendo login normalmente, sem ter a chave compartilhada:

yaml

rbac:
  enabled: true
 
  # Custom roles, merged over the built-in ones
  roles:
    lead: [view_admin_dashboard, export_data, annotate]
 
  # Assign roles to specific users
  user_role_assignments:
    carol@example.com: admin
    dave@example.com: lead
 
  # Map an SSO claim to a role
  sso_role_mapping:
    "org:my-github-org": adjudicator

As permissões são view_admin_dashboard, manage_assignment, adjudicate, export_data e annotate. O papel embutido admin tem as cinco, adjudicator tem adjudicate, export_data e annotate, e annotator tem annotate.

As permissões de um usuário são a união de todos os papéis que ele tem. Sem nenhum bloco rbac, apenas a chave compartilhada e a lista adjudication.adjudicator_users concedem acesso elevado. É assim que projetos escritos antes do RBAC continuam funcionando.

Carga de trabalho

Limites por anotador

max_annotations_per_user define um único número para todos:

yaml

max_annotations_per_user: 100

per_annotator_quota define números diferentes para pessoas diferentes. Aceita default, by_user e by_user_role, e rejeita qualquer outra subchave no carregamento em vez de ignorá-la:

yaml

per_annotator_quota:
  default: 50
  by_user:
    alice@example.com: 200
  by_user_role:
    expert: 150
    novice: 40

O limite é determinado consultando primeiro by_user, depois by_user_role e por fim default. Os rótulos de papel vêm de user_roles:

yaml

user_roles:
  alice@example.com: expert
  bob@example.com: novice

Aqui um rótulo serve apenas para a carga de trabalho. Ele só concede permissões se também nomear um papel em rbac.roles, então expert e novice continuam sendo apenas rótulos de cota.

Anotadores por item

num_annotators_per_item é quantas pessoas veem cada item, e é isso que decide se você poderá relatar a concordância no final:

yaml

num_annotators_per_item: 3
min_annotators_per_instance: 2

max_annotations_per_item é um alias obsoleto para o mesmo limite. Se os dois forem definidos com valores diferentes, a configuração é recusada no carregamento em vez de ser resolvida sem aviso.

Estratégia de atribuição

yaml

assignment_strategy: random
random_seed: 1234

As estratégias são random, fixed_order, least_annotated, max_diversity, diversity_clustering, category_based, batch, priority, model_review, llm_confidence, psychometric e active_learning. random_seed tem 1234 como padrão, então fixe o valor quando uma execução precisar ser reproduzível. Consulte Atribuição de tarefas para saber o que cada estratégia faz.

Qualificação de anotadores

Uma fase de treinamento apresenta aos anotadores itens de prática com respostas conhecidas antes da tarefa real, e passing_criteria decide quem continua:

yaml

training:
  enabled: true
  data_file: data/training.json
  passing_criteria:
    min_correct: 8
    max_mistakes: 2
    max_mistakes_per_question: 1
  allow_retry: true
  failure_action: block

Consulte Fase de treinamento para o formato dos itens e as opções de feedback.

Verificação de atenção durante a tarefa

O treinamento filtra as pessoas no início. As verificações de atenção continuam medindo depois que o trabalho real começa:

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

Consulte Controle de qualidade para padrões-ouro e relatórios de concordância.

Sessões

yaml

secret_key: "a-long-random-string"
session_timeout_minutes: 60
persist_sessions: true
session_lifetime_days: 7

secret_key assina o cookie de sessão e também pode vir da variável de ambiente POTATO_SECRET_KEY. Sem ela, o Potato gera uma nova chave a cada inicialização, o que desconecta todo mundo a cada reinício.

Exemplo: configuração para uma equipe de pesquisa

yaml

annotation_task_name: "Sentiment Annotation"
task_dir: .
 
user_config:
  allow_all_users: false
  users:
    - researcher1@university.edu
    - researcher2@university.edu
    - student1@university.edu
    - student2@university.edu
 
rbac:
  enabled: true
  user_role_assignments:
    researcher1@university.edu: admin
 
user_roles:
  researcher1@university.edu: expert
  student1@university.edu: novice
 
per_annotator_quota:
  default: 200
  by_user_role:
    expert: 300
    novice: 120
 
num_annotators_per_item: 2
assignment_strategy: least_annotated
 
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/

Exemplo: configuração para crowdsourcing

yaml

annotation_task_name: "Sentiment Annotation Study"
task_dir: .
 
login:
  type: url_direct
  url_argument: PROLIFIC_PID
 
completion_code: "POTATO2024"
 
user_config:
  allow_all_users: true
 
max_annotations_per_user: 50
num_annotators_per_item: 3
assignment_strategy: random
 
hide_navbar: true
jumping_to_id_disabled: true
 
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
 
output_annotation_dir: annotation_output/

Leitura complementar

Login sem senha - Autenticação baseada em URL
Atribuição de tarefas - Controle da distribuição das anotações
Integração com crowdsourcing - Configuração do Prolific e do MTurk
Fase de treinamento - Qualificação de anotadores antes da tarefa

Para detalhes de implementação, consulte a documentação original e a referência de papéis e permissões.

Gerenciamento de Usuários

Modos de acesso

Acesso aberto

Acesso restrito

Autenticação

Login com senha

Login direto com um argumento de URL

Papéis e permissões

A chave de administração compartilhada

Controle de acesso baseado em papéis

Carga de trabalho

Limites por anotador

Anotadores por item

Estratégia de atribuição

Qualificação de anotadores

Verificação de atenção durante a tarefa

Sessões

Exemplo: configuração para uma equipe de pesquisa

Exemplo: configuração para crowdsourcing

Leitura complementar