Skip to content

Gestione Utenti

Gestisci gli annotatori in Potato con le liste di accesso di user_config, il login diretto tramite URL, i ruoli e permessi RBAC, le quote di lavoro per annotatore e le fasi di formazione.

Potato decide tre cose distinte su una persona: se può registrarsi, cosa può fare una volta entrata e quanto lavoro riceve. Ognuna è un blocco di configurazione diverso, e confonderli è la causa più comune di un annotatore che riesce ad accedere ma non riceve mai nessun elemento.

Modalità di accesso

Accesso aperto

Potato consente l'auto-registrazione per impostazione predefinita, quindi un nuovo annotatore crea da sé il proprio account dalla pagina di login:

yaml
user_config:
  allow_all_users: true

Accesso ristretto

Imposta allow_all_users: false ed elenca gli indirizzi autorizzati a registrarsi. Nessun altro può creare un account:

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

Entrambe le chiavi vanno sotto user_config. Scritte al livello superiore vengono ignorate senza alcun avviso, e il risultato è una lista di accesso che non fa nulla.

Autenticazione

Login con password

È l'impostazione predefinita. Gli annotatori si registrano con un indirizzo email e una password, che Potato memorizza come hash PBKDF2 con un salt distinto per ogni utente.

yaml
login:
  type: password

Login diretto con un argomento URL

url_direct prende il nome utente direttamente da un parametro dell'URL e non chiede alcuna password. È così che si gestiscono i partecipanti in arrivo dalle piattaforme di crowdsourcing:

yaml
login:
  type: url_direct
  url_argument: PROLIFIC_PID

Gli annotatori arrivano quindi su http://your-server:8000/?PROLIFIC_PID=abc123 e accedono come abc123.

url_argument accetta anche una lista. In questo caso la cartella di output dell'annotatore prende il nome dall'unione dei valori:

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

I tre tipi di login sono password, url_direct e prolific. L'ultimo aggiunge l'integrazione con l'API di Prolific al login diretto tramite URL. Per la parte relativa alla piattaforma, consulta Integrazione con il crowdsourcing.

Disattivare la password o il modulo di login

Ogni annotatore accede con un nome utente, perché Potato salva le etichette di ogni annotatore in una cartella con il suo nome dentro output_annotation_dir. Nessuna impostazione elimina questo passaggio. Due impostazioni tolgono la password, e la seconda toglie anche il modulo.

Con require_password: false al livello principale della configurazione, il modulo di login chiede solo un nome utente. Potato registra subito un nome che non ha mai visto, e un nome già noto riporta al lavoro di quell'annotatore:

yaml
require_password: false

Chi digita un nome utente esistente riprende quindi la sessione di quell'annotatore, perciò disattiva la password solo dove gli annotatori si fidano l'uno dell'altro o l'URL del task è privato. Un elenco di utenti continua a valere in questa modalità, e con user_config.allow_all_users: false un nome assente da users viene rifiutato. Per eliminare anche il modulo, usa il login url_direct e invia a ogni annotatore un link che contiene il suo nome utente. Accesso Senza Password elenca i backend di autenticazione che funzionano senza password.

Ruoli e permessi

La chiave di amministrazione condivisa

admin_api_key è un'unica chiave condivisa, inviata nell'header X-API-Key, che scavalca ogni controllo sui permessi. Se non è impostata, Potato ne genera una e la scrive in {task_dir}/admin_api_key.txt.

yaml
admin_api_key: "your-shared-key"

Controllo degli accessi basato sui ruoli

Con un blocco rbac, le persone indicate raggiungono la dashboard di amministrazione accedendo normalmente, senza possedere la chiave condivisa:

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

I permessi sono view_admin_dashboard, manage_assignment, adjudicate, export_data e annotate. Il ruolo predefinito admin li ha tutti e cinque, adjudicator ha adjudicate, export_data e annotate, e annotator ha annotate.

I permessi di un utente sono l'unione di tutti i ruoli che possiede. Senza alcun blocco rbac, solo la chiave condivisa e la lista adjudication.adjudicator_users concedono un accesso elevato. In questo modo i progetti scritti prima di RBAC continuano a funzionare.

Carico di lavoro

Limiti per annotatore

max_annotations_per_user imposta un unico numero per tutti:

yaml
max_annotations_per_user: 100

per_annotator_quota imposta numeri diversi per persone diverse. Accetta default, by_user e by_user_role, e rifiuta qualsiasi altra sottochiave al caricamento invece di ignorarla:

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

Il limite si determina consultando prima by_user, poi by_user_role e infine default. Le etichette di ruolo provengono da user_roles:

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

Qui un'etichetta serve solo per il carico di lavoro. Conferisce permessi solo se nomina anche un ruolo in rbac.roles, quindi expert e novice restano semplici etichette di quota.

Annotatori per elemento

num_annotators_per_item indica quante persone vedono ciascun elemento, ed è questo che decide se alla fine potrai riportare l'accordo:

yaml
num_annotators_per_item: 3
min_annotators_per_instance: 2

max_annotations_per_item è un alias deprecato dello stesso limite. Se entrambi sono impostati su valori diversi, la configurazione viene rifiutata al caricamento invece di essere risolta senza avviso.

Strategia di assegnazione

yaml
assignment_strategy: random
random_seed: 1234

Le strategie sono random, fixed_order, least_annotated, max_diversity, diversity_clustering, category_based, batch, priority, model_review, llm_confidence, psychometric e active_learning. random_seed vale 1234 per impostazione predefinita, quindi fissalo quando un'esecuzione deve essere riproducibile. Per sapere cosa fa ciascuna strategia, consulta Assegnazione dei task.

Qualificare gli annotatori

Una fase di formazione sottopone agli annotatori elementi di prova con risposte note prima del task vero e proprio, e passing_criteria decide chi prosegue:

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

Consulta Fase di formazione per il formato degli elementi e le opzioni di feedback.

Controllare l'attenzione durante il task

La formazione filtra le persone all'inizio. I controlli di attenzione continuano a misurare una volta avviato il lavoro vero e proprio:

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

Consulta Controllo qualità per i gold standard e il report sull'accordo.

Sessioni

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

secret_key firma il cookie di sessione e può provenire anche dalla variabile d'ambiente POTATO_SECRET_KEY. Senza di essa, Potato genera una nuova chiave a ogni avvio, e a ogni riavvio tutti vengono disconnessi.

session_timeout_minutes chiude una sessione rimasta inattiva per quel tempo, e il conteggio riparte a ogni richiesta. Potato 2.11 è la prima release che lo applica, con un default di 480 minuti. Con 60, come in questo esempio, un annotatore che si allontana per un'ora deve accedere di nuovo quando torna.

Esempio: configurazione per un gruppo di ricerca

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/

Esempio: configurazione per il 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/

Letture di approfondimento

Per i dettagli di implementazione, consulta la documentazione sorgente e il riferimento su ruoli e permessi.