Skip to content

眾包整合

在 Prolific、SONA、CloudResearch Connect 或任何傳遞參與者 ID 的樣本平臺上執行 Potato 研究，支援 URL 登入、完成碼和注意力檢查。

Potato 從平臺把人送來的那個 URL 裡讀出參與者 ID，再在結束時顯示一個完成碼，眾包標註就是這樣收集的。Prolific、SONA 被試池、CloudResearch Connect、Clickworker 和 Microworkers 各有一個提供方，而 generic 提供方覆蓋任何以同樣方式工作的其他樣本平臺。Amazon Mechanical Turk 已於 2026 年 9 月 30 日關閉，所以原先在那裡執行的研究必須遷到上述平臺之一，下文“把研究遷出 MTurk”一節列出了具體步驟。

在開放埠上執行

眾包工作者必須能訪問到伺服器，所以要把它跑在對網際網路開放的埠上：

bash
potato start your-project -p 8080

工作者隨後會到達 https://your-server:8080/。在它前面放一個反向代理來處理 TLS，做法見生產環境部署。

眾包提供方

crowdsourcing 塊指明平臺。Prolific、SONA、Connect、Clickworker 和 Microworkers 有各自專用的提供方，而 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                # or prolific, sona, connect, clickworker, microworkers
  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 中列出的任何名稱。

每個提供方都從 login.url_argument 所指定的 URL 參數裡讀取參與者 ID，所以要在 crowdsourcing 塊旁邊保留 login.type: url_direct，並把 url_argument 設成該提供方的 id_param。關掉密碼提示的也是 url_direct 登入。不帶 crowdsourcing 塊的配置保持舊有行為，只靠登入本身讀取 ID，下面 Prolific 的基本設定用的就是這種方式。

Prolific

基本設定

兩項設定就能跑一個 Prolific 研究：

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

從 Prolific 過來的工作者會以其 PROLIFIC_PID 登入，不會被要求輸入密碼。他們做完後會看到完成碼和一個返回 Prolific 的按鈕。

Prolific 提供方

prolific 提供方為沒有完成任務的參與者加了第二個碼。被注意力檢查攔下的參與者，或者沒通過培訓階段的參與者，拿到的是 failed_code 而不是完成碼：

yaml
login:
  type: url_direct
  url_argument: PROLIFIC_PID
 
crowdsourcing:
  provider: prolific
  prolific:
    completion:
      code: "C1ABCDEF"          # defaults to the top-level completion_code
      failed_code: "C1FAILED"   # optional

研究 URL

在 Prolific 的研究設定裡，把 URL 設為：

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

Prolific 會代入真實值。Potato 會把 SESSION_ID 和 STUDY_ID 與參與者 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 預設關閉，要自己開啟。開啟後，當活躍工作者超過 max_concurrent_sessions 時 Potato 會暫停研究，等人數降到該數值的 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

SONA 被試池

SONA Systems 運營著許多大學用來發放課程學分的被試池。SONA 會在研究 URL 裡為每位參與者放入一個唯一程式碼，Potato 就把這個程式碼當作參與者 ID：

yaml
login:
  type: url_direct
  url_argument: sona_code
 
crowdsourcing:
  provider: sona
  sona:
    hostname: yourdept.sona-systems.com
    experiment_id: 123
    credit_token: your-credit-token   # both from the client-side completion URL on SONA's study information page
    id_param: sona_code               # the default; must match login.url_argument

在 SONA 裡把研究 URL 設為 https://your-server.com/?sona_code=%SURVEY_CODE%。參與者做完後，Potato 會通過 SONA 的伺服器端學分介面自行發放學分，參與者不必再點連結回到 SONA。如果這次呼叫失敗，完成頁會改為顯示 SONA 的客戶端學分連結。每次發放都會記錄在參與者的狀態裡，所以重新整理完成頁絕不會重複發放學分。

CloudResearch Connect

Connect 通過它的 Project Link 把參與者送到外部研究，參與者 ID 放在 participantId 裡，另外可選地帶上 assignmentId 和 projectId。Potato 會把這三項都記錄下來。完成方式可以是一個固定的完成碼，也可以是跳轉到 Connect 項目設定中顯示的完成 URL：

yaml
login:
  type: url_direct
  url_argument: participantId
 
crowdsourcing:
  provider: connect
  connect:
    completion:
      code: "ABC123"
      # or: redirect_url: "https://connect.cloudresearch.com/participant/project/<id>/complete"

Potato 不呼叫 Connect 的 REST API，所以審批和獎金都在 Connect 裡處理。

Clickworker

Clickworker 的外部問卷訂單會帶著工作者的 ID 把人送到你的 URL，完成情況則對照你上傳到 Clickworker 的完成碼來核驗：

yaml
login:
  type: url_direct
  url_argument: worker_id
 
crowdsourcing:
  provider: clickworker
  clickworker:
    id_param: worker_id      # the default
    completion:
      code: "CW-DONE-01"

該提供方還可以傳送一條完成通知，通過 Clickworker 的平臺市場 API 觸發付款。這個回傳功能是實驗性的，因為它的介面約定無法對照公開文件核實；除非配置裡在 postback_url 旁邊設定了 experimental: true，否則它一直處於關閉狀態。

Microworkers

Microworkers 的任務活動會要求每位工作者貼上回一個叫 VCODE 的驗證碼，以證明自己已經做完。Potato 用工作者 ID 和活動 ID 計算出的 HMAC 來生成每位工作者的 VCODE，因此同一位工作者總是拿到同一個碼，沒有金鑰的人猜不出碼來，而提供方的 verify_vcode 方法會重新計算出碼來核驗一次提交：

yaml
login:
  type: url_direct
  url_argument: mw_id
 
crowdsourcing:
  provider: microworkers
  microworkers:
    id_param: mw_id                        # matches {{MW_ID}} in the campaign URL
    capture_params: [campaign_id, slot_id]
    vcode_secret: "keep-this-private"
    vcode_prefix: "mw-"                    # optional

在 Microworkers 上把活動 URL 設為 https://your-server.com/?mw_id={{MW_ID}}&campaign_id={{CAMP_ID}}&slot_id={{SLOT_ID}}。Microworkers 是一個開放的微任務眾包人群，所以要搭配下文的注意力檢查和黃金標準一起使用。

Amazon Mechanical Turk（已關閉）

Amazon Mechanical Turk 已於 2026 年 9 月 30 日永久關閉，不再接受 HIT，也不再輸送工作者。Potato 的 mturk 提供方和 workerId 登入仍能載入，所以歸檔的 MTurk 配置還能啟動，但不會有任何工作者訪問到它。MTurk 整合頁面保留了相關細節，供閱讀舊研究配置的人參考。

把研究遷出 MTurk

MTurk 研究的配置大部分可以原樣沿用，因為注意力檢查、黃金標準、培訓、分配和配額在每個平臺上的工作方式都一樣。遷移分五步：

  1. 選定平臺。 Prolific 和 CloudResearch Connect 招募一般的研究人群，SONA 服務於大學自己的被試池，而 Clickworker 和 Microworkers 是開放的微任務眾包人群，需要更嚴格的品質控制。
  2. 修改登入。 保留 login.type: url_direct，把 login.url_argument 從 workerId 改成新平臺的 ID 參數（PROLIFIC_PID、sona_code、participantId、worker_id 或 mw_id）。
  3. 替換平臺塊。 刪除 mturk 塊，因為只要這個塊還在，Potato 就仍會啟動它的 MTurk API 客戶端；然後從本頁加入新平臺的 crowdsourcing 塊。
  4. 替換 HIT。 在新平臺上建立研究或項目，把它的外部 URL 指向你的伺服器，並在連結裡帶上該平臺的 ID 佔位符，再設定平臺給你的完成碼或跳轉地址。
  5. 保留品質控制。 attention_checks、gold_standards 和培訓階段維持原樣，這樣結果仍可與 MTurk 的資料相比較。

品質控制

注意力檢查

已知答案的條目，混進佇列中：

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

監控研究進展

研究執行期間，/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/

最佳實踐

  1. 先做小規模試跑 - 大規模上線前先找少數幾位工作者跑一遍
  2. 給足報酬 - 自己計時做一遍任務，按真實耗時定價
  3. 把說明寫清楚 - 附上例子和你預料到的邊界情況
  4. 用注意力檢查 - 儘早抓出亂點的人，而不是等到分析階段
  5. 加上黃金標準 - 注意力和準確率是兩種不同的測量
  6. 盯住面板 - 問題在第一天修起來很便宜，到第五天就很貴
  7. 事先定好拒收標準 - 工作者應當在開工前就知道標準
  8. 定期匯出 - 不要等到研究結束才導

延伸閱讀

實現細節見源文件、Prolific 參考和平臺調研。