Интеграция с краудсорсингом

Исследования Potato на Prolific, SONA, CloudResearch Connect или любой панели, которая передаёт идентификатор участника: вход по URL, коды завершения и проверки внимательности.

Potato собирает краудсорсинговую разметку так: считывает идентификатор участника из URL, по которому платформа отправляет людей, а в конце показывает код завершения. Для Prolific, пулов участников SONA, CloudResearch Connect, Clickworker и Microworkers есть свои провайдеры, а провайдер generic подходит для любой другой панели, которая работает так же. Amazon Mechanical Turk закрылся 30 сентября 2026 года, поэтому исследование, которое шло там, нужно перенести на одну из этих платформ, а раздел «Перенос исследования с MTurk» ниже перечисляет шаги.

Запуск на открытом порту

Исполнитель должен иметь доступ к серверу, поэтому запускайте сервер на порту, открытом в интернет:

bash

potato start your-project -p 8080

Тогда исполнители попадают на https://your-server:8080/. Для TLS поставьте перед сервером обратный прокси, как описано в разделе Production-настройка.

Краудпровайдеры

Блок crowdsourcing задаёт платформу. У Prolific, SONA, Connect, Clickworker и Microworkers есть собственные провайдеры, а generic обслуживает любую панель, которая передаёт идентификатор в URL и принимает код завершения, например 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.

Каждый провайдер считывает идентификатор участника из параметра URL, названного в login.url_argument, поэтому держите login.type: url_direct рядом с блоком crowdsourcing и задайте в url_argument значение id_param провайдера. Вход url_direct к тому же отключает запрос пароля. Конфигурация без блока crowdsourcing сохраняет прежнее поведение, при котором идентификатор считывает один только вход, и минимальная настройка 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 вместе с идентификатором участника.

Перенаправление по завершении

yaml

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

Без перенаправления страница завершения показывает код, который копируется по щелчку, и кнопку возврата. Это более надёжный вариант по умолчанию, если вы хотите, чтобы у исполнителей остался код.

Интеграция с API Prolific

В крупных исследованиях Potato может обращаться к API Prolific: так он освобождает места, занятые исполнителями, которые вернули задание или не уложились во время, и приостанавливает исследование, когда сервер перегружен. Учётные данные храните в отдельном файле:

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

Пулы участников SONA

SONA Systems ведёт пулы участников, через которые многие университеты выставляют зачёт по учебным курсам. SONA вставляет в URL исследования уникальный код для каждого участника, и Potato использует этот код как идентификатор участника:

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, передавая идентификатор участника в participantId и, по желанию, assignmentId и projectId. Potato записывает все три. Завершение — это фиксированный код или перенаправление на URL завершения, указанный в настройках проекта Connect:

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 не обращается к REST API Connect, поэтому одобрения и бонусы оформляются в Connect.

Clickworker

Заказы внешних опросов на Clickworker отправляют исполнителей на ваш 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"

Провайдер может также отправлять уведомление о завершении, которое запускает оплату через API площадки Clickworker. Эта обратная отправка экспериментальная, потому что её контракт не удалось сверить с публичной документацией, и она остаётся выключенной, пока в конфигурации не задано experimental: true рядом с postback_url.

Microworkers

Кампании на Microworkers просят каждого исполнителя вставить в ответ проверочный код, который называется VCODE, чтобы подтвердить, что работа выполнена. Potato выводит VCODE каждого исполнителя из HMAC над идентификаторами исполнителя и кампании, поэтому один и тот же исполнитель всегда получает один и тот же код, никто не может угадать код без секрета, а метод провайдера 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 закрылся навсегда 30 сентября 2026 года и больше не принимает HIT и не присылает исполнителей. Провайдер mturk в Potato и вход через workerId по-прежнему загружаются, поэтому архивная конфигурация MTurk запускается, но ни один исполнитель до неё не доберётся. Страница Интеграция с MTurk сохраняет подробности для тех, кто разбирается в конфигурации старого исследования.

Перенос исследования с MTurk

Большая часть конфигурации исследования на MTurk переносится без изменений, потому что проверки внимательности, эталонные примеры, обучение, назначение объектов и квоты работают одинаково на всех платформах. Перенос занимает пять шагов:

Выберите платформу. Prolific и CloudResearch Connect набирают участников из общей исследовательской аудитории, SONA обслуживает собственный пул университета, а Clickworker и Microworkers — открытые краудплатформы микрозадач, которым нужен более строгий контроль качества.
Измените вход. Оставьте login.type: url_direct и замените в login.url_argument значение workerId на параметр идентификатора новой платформы (PROLIFIC_PID, sona_code, participantId, worker_id или mw_id).
Замените блоки платформы. Удалите блок mturk, потому что, пока этот блок есть, Potato по-прежнему запускает свой клиент API MTurk, и добавьте блок crowdsourcing новой платформы с этой страницы.
Замените HIT. Создайте исследование или проект на новой платформе, направьте его внешний URL на ваш сервер, поставив в ссылку заполнитель идентификатора платформы, и задайте код завершения или перенаправление, которые выдаст платформа.
Сохраните контроль качества. Оставьте 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/

Что почитать дальше

Как провести краудсорсинговое исследование - Набор участников, оплата и контроль качества
Интеграция с MTurk - Что изменилось после закрытия MTurk
Вход без пароля - Аутентификация по URL
Контроль качества - Проверки внимательности и эталонные примеры
Управление пользователями - Списки доступа, роли и квоты

Подробности реализации — в исходной документации, справочнике по Prolific и обзоре платформ.

Интеграция с краудсорсингом

Запуск на открытом порту

Краудпровайдеры

Prolific

Минимальная настройка

Провайдер Prolific

URL исследования

Перенаправление по завершении

Интеграция с API Prolific

Возврат брошенной работы

Пулы участников SONA

CloudResearch Connect

Clickworker

Microworkers

Amazon Mechanical Turk (закрыт)

Перенос исследования с MTurk

Контроль качества

Проверки внимательности

Эталонные примеры

Собственные страницы завершения

Полный пример: исследование на Prolific

Наблюдение за исследованием

Рекомендации

Что почитать дальше