Skip to content

ユーザー管理

Potatoでアノテーターを管理します。user_configのアクセスリスト、URLダイレクトログイン、RBACのロールと権限、アノテーターごとの作業量クォータ、トレーニングによる選別を扱います。

Potatoは1人のユーザーについて3つのことを別々に決めます。登録できるかどうか、ログイン後に何をしてよいか、どれだけの作業が割り当てられるかです。それぞれ別の設定ブロックで指定します。ログインはできるのにアイテムが1件も届かないアノテーターが生じる原因は、たいていこれらの取り違えです。

アクセスモード

オープンアクセス

Potatoはデフォルトで自己登録を許可しているため、新しいアノテーターはログインページから自分でアカウントを作成します：

yaml
user_config:
  allow_all_users: true

制限付きアクセス

allow_all_users: false を設定し、登録を許可するアドレスを列挙します。それ以外の人はアカウントを作成できません：

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

どちらのキーも user_config の下に置きます。トップレベルに書くと何の警告もなく無視され、何の効果もないアクセスリストになってしまいます。

認証

パスワードログイン

これがデフォルトです。アノテーターはメールアドレスとパスワードで登録し、Potatoはパスワードをユーザーごとにソルトを付けたPBKDF2ハッシュとして保存します。

yaml
login:
  type: password

URL引数によるダイレクトログイン

url_direct はユーザー名をURLパラメータから直接取得し、パスワードを求めません。クラウドソーシング経由で来るアノテーターはこの方式で扱います：

yaml
login:
  type: url_direct
  url_argument: PROLIFIC_PID

アノテーターは http://your-server:8000/?PROLIFIC_PID=abc123 にアクセスし、abc123 としてログインします。

url_argument はリストも受け付けます。その場合、アノテーターの出力フォルダ名は各値を連結したものになります：

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

ログインタイプは password、url_direct、prolific の3つです。prolific はURLダイレクトログインにProlific APIとの連携を加えたものです。プラットフォーム側の設定はクラウドソーシング統合を参照してください。

パスワードまたはログインフォームを無効にする

Potato は各アノテーターのラベルを output_annotation_dir の下にあるその人の名前のフォルダに保存するため、アノテーターは必ずユーザー名でサインインします。この手順をなくす設定はありません。パスワードをなくす設定は2つあり、2つ目はフォームもなくします。

設定の最上位に require_password: false を書くと、ログインフォームはユーザー名だけを尋ねます。Potato は初めて見る名前をその場で登録し、見たことのある名前はそのアノテーターの作業にそのまま戻します：

yaml
require_password: false

そのため、既存のユーザー名を入力した人はそのアノテーターのセッションを引き継ぎます。パスワードを無効にするのは、アノテーター同士が信頼し合っている場合か、タスクの URL が非公開の場合に限ってください。このモードでもユーザー名簿は有効で、user_config.allow_all_users: false のときは users にない名前が拒否されます。フォームもなくすには url_direct ログインを使い、各アノテーターにユーザー名を含むリンクを送ります。パスワードなしで動く認証バックエンドはパスワードなしログインにまとめています。

ロールと権限

共有管理キー

admin_api_key は X-API-Key ヘッダーで送る単一の共有キーで、すべての権限チェックを迂回します。未設定の場合、Potatoがキーを生成して {task_dir}/admin_api_key.txt に書き出します。

yaml
admin_api_key: "your-shared-key"

ロールベースのアクセス制御

rbac ブロックを置くと、指定した人は共有キーを持たなくても、通常のログインで管理ダッシュボードにアクセスできます：

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

権限は view_admin_dashboard、manage_assignment、adjudicate、export_data、annotate です。組み込みの admin ロールは5つすべてを持ち、adjudicator は adjudicate、export_data、annotate を、annotator は annotate を持ちます。

ユーザーの権限は、そのユーザーが持つすべてのロールの権限の和集合です。rbac ブロックがまったくない場合、上位のアクセス権を与えるのは共有キーと adjudication.adjudicator_users リストだけです。RBAC導入前に書かれたプロジェクトはこの仕組みによってそのまま動き続けます。

作業量

アノテーターごとの上限

max_annotations_per_user は全員に共通の1つの数値を設定します：

yaml
max_annotations_per_user: 100

per_annotator_quota は人によって異なる数値を設定します。受け付けるのは default、by_user、by_user_role で、それ以外のサブキーは無視せず、読み込み時にエラーとして拒否します：

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

上限は by_user、by_user_role、default の順に参照して決まります。ロールラベルは user_roles から取得します：

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

ここでのラベルは作業量のためのラベルにすぎません。rbac.roles のロール名とも一致する場合にだけ権限を与えるので、expert と novice はクォータ用のラベルのままで、それ以上の意味は持ちません。

アイテムごとのアノテーター数

num_annotators_per_item は各アイテムを何人が見るかを決めます。最後に一致度を報告できるかどうかはこの値で決まります：

yaml
num_annotators_per_item: 3
min_annotators_per_instance: 2

max_annotations_per_item は同じ上限の非推奨エイリアスです。両方を異なる値に設定すると、黙ってどちらかに解決されるのではなく、読み込み時に拒否されます。

割り当て戦略

yaml
assignment_strategy: random
random_seed: 1234

戦略は random、fixed_order、least_annotated、max_diversity、diversity_clustering、category_based、batch、priority、model_review、llm_confidence、psychometric、active_learning です。random_seed のデフォルトは1234なので、実行を再現可能にする必要があるときは固定してください。各戦略の動作はタスク割り当てを参照してください。

アノテーターの選別

トレーニングフェーズでは、本番のタスクの前に正解が分かっている練習アイテムをアノテーターに提示し、passing_criteria によって誰が先に進めるかを決めます：

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

アイテムの形式とフィードバックのオプションはトレーニングフェーズを参照してください。

タスク中の注意チェック

トレーニングは開始時に人を選別します。注意チェックは本番の作業が始まった後も測定を続けます：

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

ゴールドスタンダードと一致度の報告については品質管理を参照してください。

セッション

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

secret_key はセッションCookieに署名します。代わりに環境変数 POTATO_SECRET_KEY から与えることもできます。設定しない場合、Potatoは起動するたびに新しいキーを生成するため、再起動のたびに全員がログアウトされます。

session_timeout_minutes は、その時間アイドル状態が続いたセッションを消去します。時間はリクエストのたびにリセットされます。この設定が実際に適用されるのはPotato 2.11が最初のリリースで、デフォルトは480分です。この例のように60にすると、1時間席を外したアノテーターは、戻ったときに再ログインが必要になります。

例：研究チームのセットアップ

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/

例：クラウドソーシングのセットアップ

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/

関連資料

実装の詳細については、ソースドキュメントとロールと権限のリファレンスを参照してください。