Gestion des utilisateurs

Gérez les annotateurs dans Potato avec les listes d'accès de user_config, la connexion directe par URL, les rôles et permissions RBAC, les quotas de travail par annotateur et les phases de formation.

Potato décide trois choses distinctes à propos d'une personne : si elle peut s'inscrire, ce qu'elle a le droit de faire une fois connectée et quelle quantité de travail elle reçoit. Chacune relève d'un bloc de configuration différent, et les confondre est la cause habituelle d'un annotateur qui peut se connecter mais ne reçoit jamais aucun élément.

Modes d'accès

Accès ouvert

Potato autorise l'auto-inscription par défaut, si bien qu'un nouvel annotateur crée lui-même son compte depuis la page de connexion :

yaml

user_config:
  allow_all_users: true

Accès restreint

Définissez allow_all_users: false et listez les adresses autorisées à s'inscrire. Personne d'autre ne peut créer de compte :

yaml

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

Les deux clés se placent sous user_config. Écrites au niveau supérieur, elles sont ignorées sans avertissement, ce qui donne une liste d'accès qui ne fait rien.

Authentification

Connexion par mot de passe

C'est le mode par défaut. Les annotateurs s'inscrivent avec une adresse e-mail et un mot de passe, que Potato stocke sous forme de hachage PBKDF2 salé propre à chaque utilisateur.

yaml

login:
  type: password

Connexion directe par argument d'URL

url_direct prend le nom d'utilisateur directement dans un paramètre d'URL et ne demande aucun mot de passe. C'est ainsi que sont gérés les participants qui arrivent d'une plateforme de crowdsourcing :

yaml

login:
  type: url_direct
  url_argument: PROLIFIC_PID

Les annotateurs arrivent alors sur http://your-server:8000/?PROLIFIC_PID=abc123 et sont connectés en tant que abc123.

url_argument accepte aussi une liste. Dans ce cas, le dossier de sortie de l'annotateur est nommé en joignant les valeurs :

yaml

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

Les trois types de connexion sont password, url_direct et prolific. Le dernier ajoute l'intégration de l'API Prolific à la connexion directe par URL. Voir Intégration du crowdsourcing pour la partie plateforme.

Désactiver le mot de passe ou le formulaire de connexion

Chaque annotateur se connecte sous un nom d'utilisateur, parce que Potato range les labels de chaque annotateur dans un dossier à son nom sous output_annotation_dir. Aucun réglage ne supprime cette étape. Deux réglages en retirent le mot de passe, et le second retire aussi le formulaire.

Avec require_password: false au niveau supérieur de la configuration, le formulaire de connexion ne demande qu'un nom d'utilisateur. Potato enregistre sur-le-champ un nom qu'il n'a jamais vu, et un nom qu'il connaît déjà ramène au travail de cet annotateur :

yaml

require_password: false

Toute personne qui tape un nom d'utilisateur existant reprend donc la session de cet annotateur. Ne désactivez le mot de passe que là où les annotateurs se font confiance ou là où l'URL de la tâche reste privée. Une liste d'utilisateurs s'applique toujours dans ce mode, et avec user_config.allow_all_users: false un nom absent de users est refusé. Pour supprimer aussi le formulaire, utilisez la connexion url_direct et envoyez à chaque annotateur un lien qui porte son nom d'utilisateur. Connexion sans mot de passe liste les backends d'authentification qui fonctionnent sans mot de passe.

Rôles et permissions

La clé d'administration partagée

admin_api_key est une clé unique et partagée, envoyée dans l'en-tête X-API-Key, qui contourne toutes les vérifications de permissions. Si elle n'est pas définie, Potato en génère une et l'écrit dans {task_dir}/admin_api_key.txt.

yaml

admin_api_key: "your-shared-key"

Contrôle d'accès basé sur les rôles

Avec un bloc rbac, des personnes désignées accèdent au tableau de bord d'administration en se connectant normalement, sans détenir la clé partagée :

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

Les permissions sont view_admin_dashboard, manage_assignment, adjudicate, export_data et annotate. Le rôle intégré admin possède les cinq, adjudicator possède adjudicate, export_data et annotate, et annotator possède annotate.

Les permissions d'un utilisateur sont l'union de tous les rôles qu'il détient. Sans aucun bloc rbac, seuls la clé partagée et la liste adjudication.adjudicator_users donnent un accès élevé. C'est ce qui permet aux projets écrits avant RBAC de continuer à fonctionner.

Charge de travail

Plafonds par annotateur

max_annotations_per_user fixe un seul nombre pour tout le monde :

yaml

max_annotations_per_user: 100

per_annotator_quota fixe des nombres différents pour des personnes différentes. Il accepte default, by_user et by_user_role, et rejette toute autre sous-clé au chargement au lieu de l'ignorer :

yaml

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

Le plafond se résout en consultant d'abord by_user, puis by_user_role, puis default. Les étiquettes de rôle viennent de user_roles :

yaml

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

Une étiquette définie ici ne sert qu'à la charge de travail. Elle ne confère des permissions que si elle nomme aussi un rôle dans rbac.roles, donc expert et novice restent de simples étiquettes de quota.

Annotateurs par élément

num_annotators_per_item indique combien de personnes voient chaque élément, et c'est ce qui décide si vous pourrez rapporter l'accord à la fin :

yaml

num_annotators_per_item: 3
min_annotators_per_instance: 2

max_annotations_per_item est un alias obsolète du même plafond. Si les deux sont définis avec des valeurs différentes, la configuration est refusée au chargement au lieu d'être résolue sans avertissement.

Stratégie d'attribution

yaml

assignment_strategy: random
random_seed: 1234

Les stratégies sont random, fixed_order, least_annotated, max_diversity, diversity_clustering, category_based, batch, priority, model_review, llm_confidence, psychometric et active_learning. random_seed vaut 1234 par défaut ; fixez-le lorsqu'une exécution doit être reproductible. Voir Attribution des tâches pour le rôle de chaque stratégie.

Qualifier les annotateurs

Une phase de formation présente aux annotateurs des éléments d'entraînement aux réponses connues avant la tâche réelle, et passing_criteria décide qui continue :

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

Voir Phase de formation pour le format des éléments et les options de retour.

Vérifier l'attention pendant la tâche

La formation filtre les personnes au départ. Les contrôles d'attention continuent de mesurer une fois le vrai travail commencé :

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

Voir Contrôle qualité pour les références étalons et le rapport d'accord.

Sessions

yaml

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

secret_key signe le cookie de session et peut aussi provenir de la variable d'environnement POTATO_SECRET_KEY. Sans elle, Potato génère une nouvelle clé à chaque démarrage, ce qui déconnecte tout le monde à chaque redémarrage.

session_timeout_minutes efface une session restée inactive pendant cette durée, et le décompte repart à chaque requête. Potato 2.11 est la première version qui l'applique, avec une valeur par défaut de 480 minutes. À 60, comme dans cet exemple, un annotateur qui s'absente une heure doit se reconnecter à son retour.

Exemple : configuration pour une équipe de recherche

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/

Exemple : configuration pour le 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/

Pour aller plus loin

Connexion sans mot de passe - Authentification par URL
Attribution des tâches - Contrôler la répartition des annotations
Intégration du crowdsourcing - Prolific, SONA et d'autres panels
Phase de formation - Qualifier les annotateurs avant la tâche

Pour les détails d'implémentation, consultez la documentation source et la référence des rôles et permissions.