크라우드소싱 연동

Prolific, MTurk 또는 참가자 ID를 전달하는 모든 패널에서 Potato 연구를 실행합니다. URL 직접 로그인, 완료 코드, 주의 확인 기반 선별을 지원합니다.

Potato는 플랫폼이 참가자를 보내는 URL에서 참가자 ID를 읽고, 마지막에 완료 코드를 보여 주는 방식으로 크라우드소싱 주석을 수집합니다. 이 방식으로 Prolific과 MTurk를 지원하며, 같은 방식으로 동작하는 다른 패널은 generic 제공자가 담당합니다.

공개 포트에서 실행하기

크라우드 작업자가 서버에 접속할 수 있어야 하므로, 인터넷에 열린 포트에서 실행합니다.

bash

potato start your-project -p 8080

그러면 작업자는 https://your-server:8080/으로 접속합니다. TLS를 위해 앞단에 리버스 프록시를 두세요. 방법은 프로덕션 설정에 설명되어 있습니다.

크라우드 제공자

crowdsourcing 블록은 플랫폼을 지정합니다. Prolific과 MTurk에는 전용 제공자가 있고, generic은 URL로 ID를 전달하고 완료 코드를 받는 모든 패널을 처리합니다. Besample, Positly, User Interviews, Testable Minds, Cint 등이 여기에 해당합니다.

yaml

login:
  type: url_direct
  url_argument: response_id        # must match id_param below
 
crowdsourcing:
  provider: generic                # generic | prolific | mturk
  generic:
    platform_label: "Besample"     # shown on the done-page return button
    id_param: response_id          # URL parameter carrying the participant ID
    capture_params: [study]        # extra URL params to record
    completion:
      code: "BSMP-4432"
      redirect_url: "https://besample.app/complete?rid={worker_id}&code={code}"
      failed_code: "BSMP-FAIL"     # optional, for blocked participants

redirect_url은 자리 표시자 {code}, {worker_id}, {session_id}, {study_id}와 capture_params에 나열한 모든 이름을 받습니다.

crowdsourcing 블록이 없는 구성은 이전 동작을 유지하며, 이때 login.type: url_direct는 Prolific 방식과 MTurk 방식의 접속을 동시에 처리합니다.

Prolific

최소 설정

Prolific 연구는 두 가지 설정으로 실행됩니다.

yaml

login:
  type: url_direct
  url_argument: PROLIFIC_PID   # the default
 
completion_code: "YOUR-PROLIFIC-CODE"

Prolific에서 온 작업자는 비밀번호 입력 없이 자신의 PROLIFIC_PID로 로그인됩니다. 작업을 마치면 완료 코드와 Prolific으로 돌아가는 버튼이 표시됩니다.

연구 URL

Prolific 연구 설정에서 URL을 다음과 같이 지정합니다.

text

https://your-server:8080/?PROLIFIC_PID={{%PROLIFIC_PID%}}&SESSION_ID={{%SESSION_ID%}}&STUDY_ID={{%STUDY_ID%}}

Prolific이 실제 값으로 바꿔 넣습니다. Potato는 참가자 ID와 함께 SESSION_ID와 STUDY_ID를 기록합니다.

완료 시 리디렉션

yaml

completion_code: "YOUR-PROLIFIC-CODE"
auto_redirect_on_completion: true
auto_redirect_delay: 5000   # milliseconds

리디렉션을 쓰지 않으면 완료 페이지에 클릭하여 복사할 수 있는 코드와 돌아가기 버튼이 표시됩니다. 작업자가 코드를 따로 기록해 두기를 원한다면 이쪽이 더 안전한 기본값입니다.

Prolific API 연동

규모가 큰 연구에서는 Potato가 Prolific API와 통신할 수 있습니다. 이를 통해 반환되었거나 시간이 초과된 작업자가 차지하던 자리를 풀어 주고, 서버가 바쁠 때 연구를 일시 중지할 수 있습니다. 자격 증명은 별도 파일에 둡니다.

yaml

# configs/prolific_config.yaml
token: "your-prolific-api-token"
study_id: "your-study-id"
max_concurrent_sessions: 30
workload_checker: true
workload_checker_period: 300

그런 다음 메인 구성에서 그 파일을 가리킵니다.

yaml

login:
  type: prolific
 
prolific:
  config_file_path: configs/prolific_config.yaml
 
completion_code: "YOUR-PROLIFIC-CODE"

workload_checker는 직접 켜지 않으면 꺼져 있습니다. 켜 두면 Potato는 활성 작업자 수가 max_concurrent_sessions를 넘을 때 연구를 일시 중지하고, 그 수의 20%까지 떨어지면 다시 시작합니다. 단, 모니터가 직접 연구를 일시 중지한 경우에만 다시 시작합니다. 사용자가 수동으로 일시 중지한 연구는 자동으로 다시 시작되지 않습니다.

방치된 작업 회수

제출이 RETURNED, TIMED-OUT, REJECTED 상태로 돌아오면, Potato는 해당 작업자에게 할당되었지만 아직 주석이 달리지 않은 항목을 풀어 다른 사람이 맡을 수 있게 합니다. 이미 완료한 주석은 유지됩니다. instance_reclaim으로 이 동작을 상태별로 바꿀 수 있습니다.

yaml

instance_reclaim:
  enabled: true
  prolific:
    preserve_completed_annotations: true
    status_policies:
      TIMED-OUT:
        preserve_completed_annotations: true
      REJECTED:
        preserve_completed_annotations: false

Amazon Mechanical Turk

최소 설정

yaml

login:
  type: url_direct
  url_argument: workerId
 
completion_code: "COMPLETED"
 
hide_navbar: true
jumping_to_id_disabled: true

External Question HIT

MTurk는 External Question을 통해 작업자를 서버로 보냅니다.

xml

<?xml version="1.0" encoding="UTF-8"?>
<ExternalQuestion xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2006-07-14/ExternalQuestion.xsd">
  <ExternalURL>https://your-server:8080/?workerId=${workerId}&amp;assignmentId=${assignmentId}&amp;hitId=${hitId}&amp;turkSubmitTo=${turkSubmitTo}</ExternalURL>
  <FrameHeight>800</FrameHeight>
</ExternalQuestion>

Potato는 이 URL에서 네 가지 매개변수를 읽습니다.

매개변수	설명
`workerId`	작업자의 MTurk ID로, 사용자 이름으로 사용됩니다
`assignmentId`	이 작업자와 HIT 조합의 고유 ID
`hitId`	HIT 식별자
`turkSubmitTo`	완료 양식을 POST로 보내는 위치

URL에 turkSubmitTo를 포함하세요. 이 값이 없으면 완료 페이지의 제출 버튼이 과제(assignment)를 보낼 곳이 없습니다.

미리보기 모드

작업자가 아직 수락하지 않은 HIT를 미리 보는 동안 MTurk는 assignmentId=ASSIGNMENT_ID_NOT_AVAILABLE을 보냅니다. Potato는 작업을 시작하는 대신 미리보기 페이지를 보여 주고 3초마다 새로 고치므로, HIT가 수락되면 바로 작업이 시작됩니다. 샌드박스와 프로덕션은 turkSubmitTo가 가리키는 호스트만 다르므로 같은 구성이 양쪽에서 모두 동작합니다.

MTurk API 연동

boto3가 설치되어 있고 MTurk 요청자(requester) 권한이 있는 AWS 자격 증명이 있으면, Potato는 과제 목록을 조회하고 자동으로 승인할 수 있습니다.

yaml

# configs/mturk_config.yaml
aws_access_key_id: "YOUR_AWS_ACCESS_KEY"
aws_secret_access_key: "YOUR_AWS_SECRET_KEY"
sandbox: true
hit_id: "YOUR_HIT_ID"

yaml

login:
  type: url_direct
  url_argument: workerId
 
mturk:
  enabled: true
  config_file_path: configs/mturk_config.yaml

이 파일은 버전 관리에 포함하지 말고, 프로덕션에서는 환경 변수를 사용하는 편이 좋습니다.

품질 관리

주의 확인

정답이 알려진 항목을 대기열에 섞어 넣습니다.

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

min_response_time은 크라우드소싱이 가장 취약한 실패 유형, 즉 누구도 항목을 읽을 수 없을 만큼 빠르게 클릭하며 넘어가는 행동을 잡아냅니다.

골드 스탠다드

전문가가 레이블을 단 항목은 주의력이 아니라 정확도를 측정합니다. 기본적으로 아무 피드백도 표시하지 않으므로, 작업자가 피드백을 통해 정답을 익히는 일이 없습니다.

yaml

gold_standards:
  enabled: true
  items_file: data/gold_standards.json
  mode: mixed
  frequency: 20
  accuracy:
    min_threshold: 0.7
    evaluation_count: 5

항목 형식과 두 가지가 보고되는 방식은 품질 관리를 참고하세요.

사용자 정의 완료 페이지

기본 완료 페이지는 코드와 돌아가기 버튼을 처리합니다. 그 이상이 필요하면 대신 surveyflow 페이지로 연구를 마무리하세요.

yaml

surveyflow:
  on: true
  order:
    - pre_annotation
    - post_annotation
  pre_annotation:
    - surveyflow/consent.jsonl
  post_annotation:
    - surveyflow/end.jsonl

종료 페이지는 필요한 링크나 텍스트를 담은 pure_display 항목입니다.

json

{"id":"1","text":"Thanks for participating. Click below to complete the study.","schema":"pure_display","choices":["<a href=\"https://app.prolific.com/submissions/complete?cc=YOUR-CODE\" target=\"_blank\">Complete Study on Prolific</a>"]}

전체 예시: Prolific 연구

yaml

annotation_task_name: "Sentiment Analysis Study"
task_dir: .
 
login:
  type: url_direct
  url_argument: PROLIFIC_PID
 
completion_code: "SENT2024"
auto_redirect_on_completion: false
 
hide_navbar: true
jumping_to_id_disabled: true
 
user_config:
  allow_all_users: true
 
assignment_strategy: random
max_annotations_per_user: 50
num_annotators_per_item: 3
 
phases:
  order:
    - consent
    - instructions
    - annotation
  consent:
    file: data/consent.html
  instructions:
    file: data/instructions.html
  annotation:
    type: annotation
 
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
 
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/
export_annotation_format: jsonl

전체 예시: MTurk HIT

yaml

annotation_task_name: "Image Classification HIT"
task_dir: .
 
login:
  type: url_direct
  url_argument: workerId
 
completion_code: "TASK_COMPLETE"
 
hide_navbar: true
jumping_to_id_disabled: true
 
user_config:
  allow_all_users: true
 
assignment_strategy: random
max_annotations_per_user: 20
num_annotators_per_item: 3
 
data_files:
  - data/items.json
 
item_properties:
  id_key: id
  text_key: image_url
 
instance_display:
  fields:
    - key: image_url
      type: image
      label: "Image"
      display_options:
        max_width: 800
 
annotation_schemes:
  - annotation_type: radio
    name: category
    description: "What is shown in this image?"
    labels:
      - Cat
      - Dog
      - Bird
      - Other
    sequential_key_binding: true
 
output_annotation_dir: annotation_output/

연구 모니터링

/admin의 관리자 대시보드는 연구가 진행되는 동안 완료율, 인스턴스당 시간, 주의 확인 결과를 보여 줍니다. 여기에 접근하려면 공유 admin_api_key 또는 view_admin_dashboard 권한이 있는 역할이 필요합니다.

yaml

admin_api_key: "your-shared-key"
 
rbac:
  enabled: true
  user_role_assignments:
    researcher@university.edu: admin

수집한 주석은 내보내기 CLI로 내보냅니다.

bash

python -m potato.export -c config.yaml -f csv -o ./export/

모범 사례

먼저 파일럿을 실행하세요: 대규모로 시작하기 전에 소수의 작업자로 실행해 보세요
공정하게 지급하세요: 작업 시간을 직접 재고 실제 소요 시간을 기준으로 보수를 정하세요
명확한 지침을 작성하세요: 예시와 예상되는 예외 사례를 포함하세요
주의 확인을 사용하세요: 읽지 않고 클릭하는 행동을 분석 단계가 아니라 초기에 잡아내세요
골드 스탠다드를 추가하세요: 주의력과 정확도는 서로 다른 측정값입니다
대시보드를 지켜보세요: 문제는 첫날 고치면 비용이 적고 닷새째 고치면 비용이 큽니다
거부 기준을 미리 정하세요: 작업자는 시작하기 전에 기준을 알아야 합니다
정기적으로 내보내세요: 연구가 끝날 때까지 기다리지 마세요

추가 자료

MTurk 연동: 자세한 MTurk 설정
비밀번호 없는 로그인: URL 기반 인증
품질 관리: 주의 확인과 골드 스탠다드
사용자 관리: 접근 목록, 역할, 할당량

구현 세부 정보는 소스 문서, Prolific 참조 문서, MTurk 참조 문서를 참조하세요.