Skip to content

사용자 관리

Potato에서 주석 작업자를 관리합니다. user_config 접근 목록, URL 직접 로그인, RBAC 역할과 권한, 주석 작업자별 작업량 할당량, 교육 단계를 통한 선별을 다룹니다.

Potato는 한 사람에 대해 세 가지를 따로 결정합니다. 가입할 수 있는지, 로그인한 뒤 무엇을 할 수 있는지, 얼마나 많은 작업을 받는지입니다. 각각은 서로 다른 설정 블록이며, 이를 혼동하는 것이 로그인은 되는데 항목을 하나도 받지 못하는 주석 작업자가 생기는 흔한 원인입니다.

접근 모드

개방형 접근

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 세 가지이며, 마지막 유형은 URL 직접 로그인 위에 Prolific API 연동을 더합니다. 플랫폼 쪽 설정은 크라우드소싱 연동을 참조하세요.

역할과 권한

공유 관리자 키

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 역할은 다섯 가지 모두를 가지며, adjudicator는 adjudicate, export_data, annotate를, annotator는 annotate를 가집니다.

사용자의 권한은 그 사용자가 가진 모든 역할의 권한을 합친 것입니다. rbac 블록이 아예 없으면 상위 접근 권한을 주는 것은 공유 키와 adjudication.adjudicator_users 목록뿐이며, RBAC 이전에 작성된 프로젝트는 이 방식으로 계속 동작합니다.

작업량

주석 작업자별 상한

max_annotations_per_user는 모든 사람에게 하나의 숫자를 설정합니다.

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은 같은 상한의 더 이상 사용되지 않는(deprecated) 별칭입니다. 두 값을 서로 다르게 설정하면 조용히 한쪽으로 정리되지 않고 로드 시점에 거부됩니다.

할당 전략

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는 세션 쿠키에 서명하며, 대신 POTATO_SECRET_KEY 환경 변수로 제공할 수도 있습니다. 이 값이 없으면 Potato는 시작할 때마다 새 키를 생성하므로, 재시작할 때마다 모든 사람이 로그아웃됩니다.

예시: 연구팀 설정

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/

추가 자료

구현 세부 정보는 소스 문서와 역할 및 권한 참조를 참조하세요.