Benutzerverwaltung

Annotatoren in Potato verwalten, mit Zugriffslisten in user_config, Direktanmeldung per URL, RBAC-Rollen und -Berechtigungen, Arbeitskontingenten pro Annotator und Trainingsphasen.

Potato entscheidet über eine Person drei getrennte Dinge: ob sie sich registrieren darf, was sie nach der Anmeldung tun darf und wie viel Arbeit sie bekommt. Jedes davon ist ein eigener Konfigurationsblock, und wer sie verwechselt, bekommt meist einen Annotator, der sich anmelden kann, aber nie ein Element erhält.

Zugriffsmodi

Offener Zugang

Potato erlaubt standardmäßig die Selbstregistrierung. Ein neuer Annotator legt sein Konto also selbst auf der Anmeldeseite an:

yaml

user_config:
  allow_all_users: true

Eingeschränkter Zugang

Setzen Sie allow_all_users: false und listen Sie die Adressen auf, die sich registrieren dürfen. Niemand sonst kann ein Konto anlegen:

yaml

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

Beide Schlüssel gehören unter user_config. Auf oberster Ebene werden sie stillschweigend ignoriert, und es entsteht eine Zugriffsliste, die nichts bewirkt.

Authentifizierung

Anmeldung mit Passwort

Das ist die Voreinstellung. Annotatoren registrieren sich mit einer E-Mail-Adresse und einem Passwort, das Potato als PBKDF2-Hash mit einem Salt pro Benutzer speichert.

yaml

login:
  type: password

Direktanmeldung über ein URL-Argument

url_direct übernimmt den Benutzernamen direkt aus einem URL-Parameter und fragt nach keinem Passwort. So werden Teilnehmende aus Crowdsourcing-Plattformen empfangen:

yaml

login:
  type: url_direct
  url_argument: PROLIFIC_PID

Annotatoren rufen dann http://your-server:8000/?PROLIFIC_PID=abc123 auf und sind als abc123 angemeldet.

url_argument akzeptiert auch eine Liste. In diesem Fall wird der Ausgabeordner des Annotators aus den zusammengefügten Werten benannt:

yaml

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

Die drei Anmeldetypen sind password, url_direct und prolific. Der letzte ergänzt die URL-Direktanmeldung um die Anbindung an die Prolific-API. Die Plattformseite beschreibt Crowdsourcing-Integration.

Passwort oder Anmeldeformular deaktivieren

Jeder Annotator meldet sich unter einem Benutzernamen an, weil Potato die Labels jedes Annotators in einem nach ihm benannten Ordner unter output_annotation_dir ablegt. Keine Einstellung entfernt diesen Schritt. Zwei Einstellungen nehmen das Passwort heraus, und die zweite entfernt auch das Formular.

Mit require_password: false auf der obersten Ebene der Konfiguration fragt das Anmeldeformular nur nach einem Benutzernamen. Einen Namen, den Potato noch nicht kennt, registriert es sofort, und mit einem bekannten Namen gelangt man zurück in die Arbeit dieses Annotators:

yaml

require_password: false

Wer einen vorhandenen Benutzernamen eintippt, setzt also die Sitzung dieses Annotators fort. Deaktivieren Sie das Passwort deshalb nur, wo die Annotatoren einander vertrauen oder die URL der Aufgabe privat ist. Eine Benutzerliste gilt in diesem Modus weiterhin, und mit user_config.allow_all_users: false wird ein Name abgelehnt, der nicht in users steht. Um auch das Formular wegzulassen, verwenden Sie die Anmeldung url_direct und schicken jedem Annotator einen Link, der seinen Benutzernamen enthält. Passwortloser Login führt die Authentifizierungs-Backends auf, die ohne Passwort laufen.

Rollen und Berechtigungen

Der gemeinsame Admin-Schlüssel

admin_api_key ist ein einzelner gemeinsamer Schlüssel, der im Header X-API-Key gesendet wird und jede Berechtigungsprüfung umgeht. Ist er nicht gesetzt, erzeugt Potato einen und schreibt ihn nach {task_dir}/admin_api_key.txt.

yaml

admin_api_key: "your-shared-key"

Rollenbasierte Zugriffskontrolle

Mit einem rbac-Block erreichen namentlich festgelegte Personen das Admin-Dashboard über eine normale Anmeldung, ohne den gemeinsamen Schlüssel zu besitzen:

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

Die Berechtigungen sind view_admin_dashboard, manage_assignment, adjudicate, export_data und annotate. Die eingebaute Rolle admin besitzt alle fünf, adjudicator besitzt adjudicate, export_data und annotate, und annotator besitzt annotate.

Die Berechtigungen eines Benutzers sind die Vereinigung aller Rollen, die er innehat. Ganz ohne rbac-Block verleihen nur der gemeinsame Schlüssel und die Liste adjudication.adjudicator_users erweiterten Zugriff. Deshalb funktionieren Projekte, die vor RBAC geschrieben wurden, weiterhin.

Arbeitslast

Obergrenzen pro Annotator

max_annotations_per_user legt eine einzige Zahl für alle fest:

yaml

max_annotations_per_user: 100

per_annotator_quota legt unterschiedliche Zahlen für unterschiedliche Personen fest. Es akzeptiert default, by_user und by_user_role und weist jeden anderen Unterschlüssel beim Laden zurück, statt ihn zu ignorieren:

yaml

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

Eine Obergrenze wird ermittelt, indem zuerst by_user, dann by_user_role und dann default geprüft wird. Die Rollenbezeichnungen stammen aus user_roles:

yaml

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

Eine Bezeichnung hier ist nur eine Bezeichnung für die Arbeitslast. Berechtigungen verleiht sie nur, wenn sie zugleich eine Rolle in rbac.roles benennt. expert und novice bleiben also reine Kontingentbezeichnungen.

Annotatoren pro Element

num_annotators_per_item gibt an, wie viele Personen jedes Element sehen, und davon hängt ab, ob Sie am Ende eine Übereinstimmung berichten können:

yaml

num_annotators_per_item: 3
min_annotators_per_instance: 2

max_annotations_per_item ist ein veralteter Alias für dieselbe Obergrenze. Werden beide auf unterschiedliche Werte gesetzt, wird die Konfiguration beim Laden abgelehnt, statt stillschweigend aufgelöst zu werden.

Zuweisungsstrategie

yaml

assignment_strategy: random
random_seed: 1234

Die Strategien sind random, fixed_order, least_annotated, max_diversity, diversity_clustering, category_based, batch, priority, model_review, llm_confidence, psychometric und active_learning. random_seed ist standardmäßig 1234. Legen Sie den Wert fest, wenn ein Lauf reproduzierbar sein muss. Was jede Strategie tut, steht unter Aufgabenzuweisung.

Annotatoren qualifizieren

Eine Trainingsphase legt Annotatoren vor der eigentlichen Aufgabe Übungselemente mit bekannten Antworten vor, und passing_criteria entscheidet, wer weitermacht:

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

Das Elementformat und die Feedback-Optionen beschreibt Trainingsphase.

Aufmerksamkeit während der Aufgabe prüfen

Das Training filtert Personen zu Beginn. Aufmerksamkeitsprüfungen messen weiter, sobald die eigentliche Arbeit läuft:

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

Goldstandards und Übereinstimmungsberichte beschreibt Qualitätskontrolle.

Sitzungen

yaml

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

secret_key signiert das Sitzungscookie und kann auch aus der Umgebungsvariablen POTATO_SECRET_KEY stammen. Ohne ihn erzeugt Potato bei jedem Start einen neuen Schlüssel, wodurch bei jedem Neustart alle abgemeldet werden.

session_timeout_minutes löscht eine Sitzung, die so lange inaktiv war, und die Uhr beginnt bei jeder Anfrage von vorn. Potato 2.11 ist das erste Release, das die Einstellung durchsetzt, mit einem Standardwert von 480 Minuten. Bei 60, wie in diesem Beispiel, muss sich ein Annotator, der eine Stunde weggeht, bei seiner Rückkehr erneut anmelden.

Beispiel: Einrichtung für ein Forschungsteam

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/

Beispiel: Einrichtung für 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/

Weiterführende Literatur

Passwortlose Anmeldung - URL-basierte Authentifizierung
Aufgabenzuweisung - Verteilung der Annotationen steuern
Crowdsourcing-Integration - Prolific, SONA und andere Panels
Trainingsphase - Annotatoren vor der Aufgabe qualifizieren

Implementierungsdetails finden Sie in der Quelldokumentation und in der Referenz zu Rollen und Berechtigungen.