Leitfäden8 Min. Lesezeit

Annotationsstudien auf Prolific durchführen

Eine Potato-Annotationsstudie auf Prolific durchführen, mit Login direkt über die URL, Abschlusscode, Aufmerksamkeitstests und Überwachung der Einreichungen über die API.

Potato Team20. Januar 2026

Richte die Studien-URL von Prolific mit ?PROLIFIC_PID={{%PROLIFIC_PID%}} auf deinen Potato-Server, setze login.type: url_direct und einen completion_code, der mit dem Code der Studie übereinstimmt, und jede teilnehmende Person wird unter ihrer eigenen Prolific-ID angemeldet und nach dem Abschluss zu Prolific zurückgeschickt.

Prolific ist ein Teilnehmendenpool, der für akademische Studien gebaut ist, und die Crowdsourcing-Plattform, die Potato am vollständigsten unterstützt. Dieser Leitfaden behandelt die Konfiguration, die Potato braucht, die Studieneinstellungen auf der Prolific-Seite und die Qualitätskontrolle, die stehen sollte, bevor du Geld ausgibst.

Warum Forschende Prolific für Annotation nutzen

Prolific prüft seine Teilnehmenden vorab und bezahlt sie über die Plattform, sodass die Teile des Crowdsourcings, die sonst das Budget einer Studie aufzehren, außerhalb deines Servers erledigt werden. Die Plattform schreibt einen Mindeststundensatz vor, filtert Teilnehmende nach demografischen und sprachlichen Kriterien und dokumentiert die Einwilligung, was den IRB-Papierkram für eine Labeling-Studie verkürzt. Mechanical Turk, mit dem Prolific meist verglichen wurde, ist am 30. September 2026 geschlossen worden, und eine Studie von MTurk umziehen beschreibt den Wechsel für Studien, die dort liefen.

Was du vor dem Start brauchst

Ein Forschendenkonto bei Prolific.
Potato auf einem Server mit öffentlicher HTTPS-URL. Der Leitfaden zum Server-Deployment behandelt diesen Schritt.
Eine Konfiguration mit deinen Datendateien, item_properties und mindestens einem Annotationsschema.

Die Konfiguration, die Potato braucht

Vier Einstellungen machen aus einem gewöhnlichen Potato-Projekt eines, das Prolific steuern kann. login.url_argument benennt den URL-Parameter, der die Prolific-ID der teilnehmenden Person trägt, completion_code muss mit einem in der Prolific-Studie konfigurierten Code übereinstimmen, und die beiden Weiterleitungsschlüssel schicken Teilnehmende zu Prolific zurück, statt sie auf einer Abschlussseite stehen zu lassen. Die Zuweisungsschlüssel darunter begrenzen, wie viel Arbeit eine einzelne Person bekommt, und das hält die Kosten einer Studie planbar.

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

Lege num_annotators_per_item danach fest, was du mit den Daten vorhast. Drei ist die übliche Wahl, wenn du Übereinstimmung berichten oder ein Mehrheitslabel bilden willst, und eins reicht, sobald ein Pilot gezeigt hat, dass die Aufgabe klar definiert ist. Der Leitfaden zur Inter-Annotator-Übereinstimmung erklärt, wie du das Ergebnis liest.

Die Studie bei Prolific einrichten

Trage im Studienformular von Prolific als externe Studien-URL deinen Potato-Server ein, mit den Platzhaltern von Prolific im Query-String:

text

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

Wähle bei der Frage, wie Prolific-IDs erfasst werden, "I'll use URL parameters" und konfiguriere dann in der Studie einen Abschlusscode, der mit completion_code in deiner Konfiguration übereinstimmt. STUDY_ID und SESSION_ID werden für die spätere Nachverfolgung in der Sitzung der teilnehmenden Person gespeichert.

Wer auf den Link klickt, kommt mit der eigenen ID in der URL bei Potato an. Potato legt unter dieser ID ein Konto ohne Passwort an, führt die Person durch die Phasen, die du konfiguriert hast, und zeigt nach dem Abschluss den Abschlusscode mit einem Return to Prolific-Button, der auf https://app.prolific.com/submissions/complete?cc=<code> verlinkt. Ist auto_redirect_on_completion gesetzt, erfolgt die Weiterleitung nach auto_redirect_delay Millisekunden von selbst.

Schreibe die Domain als app.prolific.com. Die ältere Domain app.prolific.co liefert kein HTTPS mehr aus, sodass eine aus einem älteren Leitfaden kopierte Abschluss-URL Teilnehmende nach getaner Arbeit auf eine tote Seite schickt.

Einwilligung, Anleitungen und Abschlussbefragungen

Die meisten Crowdsourcing-Studien brauchen mehr als die Annotationsseite. Der phases-Block von Potato legt Einwilligung, Vorauswahl, Anleitung und eine Befragung nach der Studie um die Annotationsphase herum, und Teilnehmende durchlaufen sie in der Reihenfolge, in der du sie aufführst:

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

Füge diesen Block der Konfiguration oben hinzu. Die Phase annotation ist die einzige Pflichtphase, sodass eine Studie ohne Einwilligungsformular alle anderen Einträge weglassen kann. Ältere Projekte konfigurieren dasselbe über surveyflow, das Potato weiterhin liest, für neue Projekte aber nicht mehr empfiehlt.

Aufmerksamkeitstests

Ein Aufmerksamkeitstest ist ein Item mit bekannter richtiger Antwort, das in die Warteschlange gemischt wird, damit eine unaufmerksame Person eine erkennbar falsche Antwort abgibt. Potato lädt diese Tests aus einer eigenen Datei statt aus deinen Daten, sodass sie nicht in deinem Datensatz landen:

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

Füge diesen Block der Konfiguration oben hinzu. frequency: 10 fügt alle zehn Items einen Test ein, und min_response_time wertet eine Antwort als nicht bestanden, die schneller eintrifft, als irgendjemand das Item lesen könnte, egal was sie enthält. Die Uhr läuft auf dem Server, von dem Moment, in dem er das Item gesendet hat, bis zu dem Moment, in dem er die Speicherung empfangen hat.

Jedes Test-Item trägt eine ID, den Text, den die teilnehmende Person sieht, und die erwartete Antwort für jedes Schema nach Namen:

json

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

Stimme block_threshold auf die Länge deiner Studie ab. Wer in einer Aufgabe mit 20 Items fünf Tests nicht besteht, hat nie wirklich annotiert; wer fünf über 300 Items hinweg nicht besteht, war vielleicht eine Zeit lang müde, und eine Sperre kostet dich den Rest dieser Arbeit.

Eine laufende Studie überwachen

Setze login.type: prolific und füge einen prolific-Block hinzu, dann fragt Potato zusätzlich zum Login direkt über die URL, den es ohnehin durchführt, die Prolific-API nach dem Status der Einreichungen ab:

yaml

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

Füge diesen Block der Konfiguration oben hinzu. Die Datei, auf die er verweist, enthält das API-Token, halte sie also aus der Versionsverwaltung heraus:

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

Mit konfiguriertem Token bekommt das Admin-Dashboard ein Prolific-Panel, das die Studie veröffentlicht, pausiert und beendet, Einreichungen annimmt oder ablehnt, Boni auszahlt und vorab die Kosten zusätzlicher Plätze anzeigt. Der Auslastungsmonitor pausiert die Studie, wenn die Zahl aktiver Teilnehmender max_concurrent_sessions erreicht, und setzt sie fort, wenn sie unter 20 % dieses Maximums fällt. Er setzt nur eine Studie fort, die er selbst pausiert hat, sodass eine Studie, die du in Prolific von Hand pausierst, pausiert bleibt.

Teilnehmende, die abbrechen

Prolific meldet eine Einreichung als RETURNED, TIMED-OUT oder REJECTED, wenn jemand ohne Abschluss aussteigt. Potato gibt die diesen Personen zugewiesenen Items frei, damit andere sie übernehmen können, und behält die Annotationen, die sie bereits abgeschlossen hatten. Nutze instance_reclaim, wenn der Grund bestimmen soll, was mit dieser abgeschlossenen Arbeit geschieht:

yaml

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

Füge diesen Block der Konfiguration oben hinzu. Diese Unterscheidung solltest du bewusst festlegen. Wer in ein Timeout gelaufen ist, hat meist ehrlich annotiert, bis etwas dazwischenkam, während eine abgelehnte Person Arbeit abgeliefert hat, die du nicht bezahlen wolltest, und diese Arbeit im Datensatz zu behalten, untergräbt die Ablehnung.

Was die Ausgabe enthält

Potato schreibt Dateien pro annotierender Person unter output_annotation_dir und, wenn export_annotation_format gesetzt ist, einen periodischen Export unter <output_annotation_dir>/exports/<format>/. Jeder exportierte Datensatz enthält die Instanz, die annotierende Person und die Labels nach Schemaname:

json

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

Die user_id ist die Prolific-ID der teilnehmenden Person, weil das der Benutzername ist, unter dem Potato sie angelegt hat, und darüber kannst du eine Zeile einer Prolific-Einreichung zuordnen, um sie anzunehmen oder einen Bonus zu zahlen. Behandle diese Spalte als identifizierende Daten, wenn du den Datensatz veröffentlichst.

Zuerst einen Pilot durchführen

Lass 5 bis 10 Teilnehmende arbeiten, bevor du die vollständige Studie startest, und lies ihre Ausgabe, statt nur auf ihre Abschlussquote zu schauen. Zwei Fehler werden teuer, wenn du sie erst hinterher entdeckst. Der erste ist eine Anleitung, die auf eine Weise mehrdeutig ist, die du nicht siehst, weil du die Aufgabe selbst geschrieben hast, und der zweite ist eine Zeit pro Item, die weit von deiner Schätzung abweicht, was bedeutet, dass deine Vergütung in die eine oder andere Richtung falsch liegt.

Kalkuliere den Preis der Studie aus der Medianzeit des Pilots statt aus deiner eigenen. Halte die Oberfläche in Handybreite benutzbar, weil manche Teilnehmende am Handy sitzen werden, egal was in der Studienbeschreibung steht. Nimm Einreichungen zügig an, weil Menschen auf das Geld warten und weil deine Annahmezeit für künftige Teilnehmende sichtbar ist, die entscheiden, ob sie deine Studie übernehmen.

Nächste Schritte

Ziehe eine alte Studie von Mechanical Turk um
Richte die Qualitätskontrolle genauer ein
Berechne die Inter-Annotator-Übereinstimmung für das Ergebnis

Die vollständige Referenz findest du unter Crowdsourcing-Integration auf dieser Website, und die Dokumentation zur Prolific-Integration im Potato-Repository behandelt die Admin-API-Endpunkte hinter dem Dashboard-Panel. Fang dort an, wenn du Studienerstellung, Qualifikationsabgleich oder bezahlte Screen-outs aus deinem eigenen Code heraus steuern willst.