Skip to content
Guides6 min read

Prolific에서 어노테이션 연구 진행하기

URL 직접 로그인, 완료 코드, 주의력 검사, API를 통한 제출 모니터링으로 Prolific에서 Potato 어노테이션 연구를 진행합니다.

Potato Team

Prolific의 연구 URL을 ?PROLIFIC_PID={{%PROLIFIC_PID%}}와 함께 Potato 서버로 지정하고, login.type: url_direct와 연구에 설정한 코드와 일치하는 completion_code를 설정하면, 각 참가자는 자신의 Prolific ID로 로그인하고 작업을 마치면 Prolific으로 돌아갑니다.

Prolific은 학술 연구를 위해 만들어진 참가자 풀이며, Potato가 가장 폭넓게 지원하는 크라우드소싱 플랫폼입니다. 이 가이드에서는 Potato에 필요한 구성, Prolific 쪽 연구 설정, 그리고 비용을 쓰기 전에 갖춰 둘 만한 품질 관리를 다룹니다.

연구자들이 어노테이션에 Prolific을 쓰는 이유

Prolific은 참가자를 선별하고 플랫폼을 통해 보수를 지급하므로, 크라우드소싱에서 보통 연구 예산을 잡아먹는 부분이 여러분의 서버 밖에서 처리됩니다. 최저 시급을 강제하고, 인구통계와 언어 기준으로 참가자를 필터링하며, 동의를 기록하기 때문에 레이블링 연구의 IRB 서류 작업이 줄어듭니다. 대신 응답당 비용이 Mechanical Turk보다 높으며, 그 플랫폼이 필요하다면 MTurk 배포 가이드에서 다룹니다.

시작하기 전에 필요한 것

  1. Prolific 연구자 계정.
  2. 공개 HTTPS URL이 있는 서버에서 실행 중인 Potato. 이 단계는 서버 배포 가이드에서 다룹니다.
  3. 데이터 파일, item_properties, 그리고 하나 이상의 어노테이션 스킴이 담긴 구성.

Potato에 필요한 구성

네 가지 설정으로 일반 Potato 프로젝트를 Prolific이 구동할 수 있는 프로젝트로 바꿀 수 있습니다. login.url_argument는 참가자의 Prolific ID를 담은 URL 매개변수의 이름을 지정하고, completion_code는 Prolific 연구에 설정한 코드와 일치해야 하며, 두 개의 리디렉션 키는 참가자를 완료 페이지에 남겨 두지 않고 Prolific으로 돌려보냅니다. 그 아래의 할당 키는 참가자 한 명에게 주어지는 작업량의 상한을 정하며, 이것이 연구 비용을 예측 가능하게 유지합니다.

yaml
annotation_task_name: "Sentiment Annotation Study"
task_description: "Classify the sentiment of short text snippets. This task takes about five minutes."
 
# Participants are logged in from the PROLIFIC_PID URL parameter
login:
  type: url_direct
  url_argument: PROLIFIC_PID
 
# Must match a completion code configured on the Prolific study
completion_code: "C1ABCDEF"
auto_redirect_on_completion: true
auto_redirect_delay: 5000
 
# Keep participants on task
hide_navbar: true
jumping_to_id_disabled: true
 
# Each participant labels 20 items; each item is labeled by 3 participants
assignment_strategy: random
max_annotations_per_user: 20
num_annotators_per_item: 3
 
data_files:
  - data/texts.json
 
item_properties:
  id_key: id
  text_key: text
 
output_annotation_dir: annotation_output/prolific-study/
export_annotation_format: jsonl
 
user_config:
  allow_all_users: true
  users: []
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment expressed in this text?"
    labels:
      - name: positive
      - name: neutral
      - name: negative
    sequential_key_binding: true
    label_requirement:
      required: true

num_annotators_per_item은 데이터를 어떻게 쓸지에 따라 정하세요. 일치도를 보고하거나 다수결 레이블을 취할 계획이라면 보통 3을 쓰고, 파일럿으로 작업이 잘 정의되어 있음을 확인한 뒤라면 1로도 충분합니다. 결과를 읽는 방법은 어노테이터 간 일치도 가이드에서 설명합니다.

Prolific에서 연구 설정하기

Prolific의 연구 양식에서 외부 연구 URL을 Potato 서버로 지정하고, 쿼리 문자열에 Prolific의 플레이스홀더를 넣습니다:

text
https://your-server.com/?PROLIFIC_PID={{%PROLIFIC_PID%}}&STUDY_ID={{%STUDY_ID%}}&SESSION_ID={{%SESSION_ID%}}

Prolific ID를 기록하는 방식을 묻는 질문에서 "I'll use URL parameters"를 선택한 다음, 구성의 completion_code와 일치하는 완료 코드를 연구에 설정합니다. STUDY_ID와 SESSION_ID는 나중에 추적할 수 있도록 참가자의 세션에 저장됩니다.

링크를 클릭한 참가자는 URL에 자신의 ID를 담은 채 Potato에 도착합니다. Potato는 그 ID로 비밀번호 없는 계정을 만들고, 여러분이 구성한 단계를 차례로 안내한 뒤, 작업이 끝나면 완료 코드와 함께 https://app.prolific.com/submissions/complete?cc=<code>로 연결되는 Return to Prolific 버튼을 보여 줍니다. auto_redirect_on_completion을 설정하면 auto_redirect_delay밀리초 후에 자동으로 리디렉션됩니다.

도메인은 app.prolific.com으로 쓰세요. 예전 도메인인 app.prolific.co는 더 이상 HTTPS를 제공하지 않으므로, 오래된 가이드에서 복사한 완료 URL은 작업을 마친 참가자를 작동하지 않는 페이지로 보냅니다.

동의, 안내, 종료 설문

대부분의 크라우드소싱 연구에는 어노테이션 페이지 외에 더 많은 것이 필요합니다. Potato의 phases 블록은 동의, 사전 선별, 안내, 연구 후 설문을 어노테이션 단계 앞뒤에 배치하며, 참가자는 여러분이 나열한 순서대로 이를 거칩니다:

yaml
phases:
  order: [consent, prestudy, instructions, annotation, poststudy]
 
  consent:
    type: consent
    file: surveyflow/consent.json
 
  prestudy:
    type: prestudy
    file: surveyflow/prescreening.json
 
  instructions:
    type: instructions
    file: surveyflow/instructions.html
 
  poststudy:
    type: poststudy
    file: surveyflow/demographics.json

이 블록을 위의 구성에 추가하세요. 필수 단계는 annotation 하나뿐이므로, 동의서가 필요 없는 연구는 나머지 항목을 모두 생략할 수 있습니다. 이전 프로젝트는 같은 설정을 surveyflow로 구성하는데, Potato는 이를 여전히 읽지만 새 프로젝트에는 더 이상 권장하지 않습니다.

주의력 검사

주의력 검사는 정답이 알려진 항목을 대기열에 섞어 두어, 주의를 기울이지 않는 참가자가 감지 가능한 오답을 내게 하는 것입니다. Potato는 이 항목을 여러분의 데이터가 아니라 별도 파일에서 불러오므로, 검사 항목은 데이터셋에 들어가지 않습니다:

yaml
attention_checks:
  enabled: true
  items_file: "data/attention_checks.json"
  frequency: 10
  min_response_time: 3.0
  failure_handling:
    warn_threshold: 2
    block_threshold: 5

이 블록을 위의 구성에 추가하세요. frequency: 10은 항목 10개마다 검사를 하나 넣고, min_response_time은 누구도 항목을 읽을 수 없을 만큼 빨리 도착한 응답을 내용과 상관없이 실패로 처리합니다. 시간은 서버에서 측정하며, 서버가 항목을 보낸 순간부터 저장을 받은 순간까지를 잽니다.

각 검사 항목에는 id, 참가자에게 보이는 텍스트, 그리고 스킴 이름별 기대 응답이 들어갑니다:

json
[
  {
    "id": "attn_001",
    "text": "Please select 'positive' for this item to verify you are reading carefully.",
    "expected_answer": {"sentiment": "positive"}
  }
]

block_threshold는 연구의 길이에 맞춰 설정하세요. 항목 20개짜리 작업에서 검사를 다섯 번 실패한 참가자는 애초에 어노테이션을 하고 있지 않았습니다. 반면 항목 300개에 걸쳐 다섯 번 실패한 참가자는 한동안 지쳐 있었을 수 있고, 그를 차단하면 나머지 작업을 잃게 됩니다.

진행 중인 연구 모니터링

login.type: prolific을 설정하고 prolific 블록을 추가하면, Potato는 이미 수행하는 URL 직접 로그인에 더해 Prolific API에 제출 상태를 주기적으로 조회합니다:

yaml
login:
  type: prolific
  url_argument: PROLIFIC_PID
 
prolific:
  config_file_path: configs/prolific_config.yaml
 
completion_code: "C1ABCDEF"

이 블록을 위의 구성에 추가하세요. 이 블록이 가리키는 파일에는 API 토큰이 들어 있으므로 버전 관리에서 제외하세요:

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

토큰을 구성하면 관리자 대시보드에 Prolific 패널이 추가됩니다. 이 패널에서 연구를 게시, 일시 중지, 중단하고, 제출을 승인하거나 거부하고, 보너스를 지급하고, 자리를 추가할 때의 비용을 미리 볼 수 있습니다. 작업량 모니터는 활성 참가자 수가 max_concurrent_sessions에 도달하면 연구를 일시 중지하고, 그 수가 최대치의 20% 아래로 떨어지면 재개합니다. 스스로 일시 중지한 연구만 재개하므로, Prolific에서 직접 일시 중지한 연구는 계속 중지된 상태로 남습니다.

중도에 이탈하는 참가자

참가자가 끝내지 않고 떠나면 Prolific은 그 제출을 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

이 블록을 위의 구성에 추가하세요. 이 구분은 의도적으로 설정할 가치가 있습니다. 시간 초과된 참가자는 대개 무언가에 방해받기 전까지 성실하게 어노테이션했지만, 거부된 참가자는 여러분이 보수를 지급하지 않기로 한 작업을 낸 것이며, 그 작업을 데이터셋에 남기면 거부의 의미가 약해집니다.

출력에 담기는 내용

Potato는 output_annotation_dir 아래에 어노테이터별 파일을 쓰고, export_annotation_format이 설정되어 있으면 <output_annotation_dir>/exports/<format>/ 아래에 주기적인 내보내기 파일도 씁니다. 내보낸 각 레코드에는 인스턴스, 어노테이터, 스킴 이름별 레이블이 담깁니다:

json
{"instance_id": "t_014", "user_id": "5f2c9a1b3d4e5f6a7b8c9d0e", "labels": {"sentiment": {"positive": "positive"}}, "spans": {}, "links": {}}

user_id는 참가자의 Prolific ID입니다. Potato가 그 사용자 이름으로 계정을 만들었기 때문이며, 덕분에 각 행을 Prolific 제출과 대조해 승인하거나 보너스를 지급할 수 있습니다. 데이터셋을 공개할 때는 이 열을 식별 가능한 데이터로 취급하세요.

먼저 파일럿 진행하기

전체 연구를 시작하기 전에 참가자 5~10명으로 먼저 진행하고, 완료율만 보지 말고 그들의 출력을 직접 읽으세요. 나중에 발견하면 비용이 큰 실패가 두 가지 있습니다. 첫째는 여러분이 직접 작업을 작성했기 때문에 보이지 않는 방식으로 모호한 안내이고, 둘째는 항목당 소요 시간이 추정치와 크게 다른 경우로, 이는 보수 단가가 어느 한쪽으로 잘못되었다는 뜻입니다.

연구 가격은 여러분의 소요 시간이 아니라 파일럿의 중앙값 소요 시간으로 정하세요. 연구 설명에 무엇을 적든 일부 참가자는 휴대폰으로 참여하므로, 인터페이스는 휴대폰 너비에서도 쓸 수 있게 유지하세요. 제출은 신속히 승인하세요. 사람들이 돈을 기다리고 있고, 여러분의 승인 소요 시간은 연구 참여를 고민하는 미래의 참가자에게도 보이기 때문입니다.

다음 단계

전체 레퍼런스는 이 사이트의 크라우드소싱 통합에 있으며, Potato 저장소의 Prolific 통합 문서는 대시보드 패널 뒤에 있는 관리자 API 엔드포인트를 다룹니다. 연구 생성, 자격 요건(qualification) 동기화, 유료 스크린아웃을 여러분의 코드에서 직접 처리해야 한다면 거기서 시작하세요.