Ihre Potato-Studie online stellen

Um eine Potato-Studie online zu stellen, führen Sie Ihre Aufgabe auf einem Computer aus, den Ihre Annotatoren über eine Webadresse erreichen, halten die Annotationen während der Studie sicher und laden die Annotationen am Ende herunter. Die IT Ihrer Einrichtung zu fragen und einen Deploy-Button zu klicken, den ein Kollege vorbereitet hat, sind die beiden Wege, die auf Ihrer Seite kein Terminal brauchen.

Eine Studie bereitzustellen (englisch deploy) bedeutet, die Potato-Aufgabe, die Sie gebaut haben, von Ihrem eigenen Computer auf einen Server zu bringen, einen Computer, der eingeschaltet und mit dem Internet verbunden bleibt. Annotatoren öffnen die Aufgabe dann von überall in einem Webbrowser, und Potato speichert jede Antwort auf dem Server, während die Annotatoren arbeiten. Die Vorschau des Study Designers führt Potato in Ihrem eigenen Browser aus, und niemand sonst kann diese Kopie erreichen. Eine im Designer gebaute Studie braucht weiterhin einen der folgenden Wege.

Jeder Weg beginnt mit demselben Projektordner. Im Study Designer speichert der Button Download project (.zip) die Datei config.yaml (die Datei, die Ihre Aufgabe beschreibt), eine Beispieldatendatei und eine README. Die Beispieldatei enthält drei Platzhalter-Items. Ersetzen Sie die Beispieldatei vor dem Bereitstellen durch Ihre eigenen Items, in dem Format, das Datenformate beschreibt.

Einen Weg wählen

Die Wege unterscheiden sich darin, wer die technische Arbeit erledigt, was der Server kostet und wie lange die Studie online bleiben kann. Die Kosten unten stammen aus den Preislisten der Hosts und aus den Schätzungen von Potato vom 04.11.2026, und die Wartezeiten sind grobe Richtwerte und keine Messungen:

Wenn Sie unsicher sind, beginnen Sie mit Ihrer IT. Ein Server innerhalb Ihrer Einrichtung hält die Daten auf Geräten, die Ihre Einrichtung ohnehin verwaltet, und die IT kann Sicherheitsupdates und Backups übernehmen.

Die IT oder das Forschungsrechenzentrum fragen

Viele Universitäten und Krankenhäuser betreiben einen Dienst für Forschungsrechnen, der Webanwendungen für Studien hostet. Für ein solches Team ist Potato eine gewöhnliche Webanwendung, und das Team kann mit einer einseitigen Zusammenfassung dessen beginnen, was Potato braucht.

1. Laden Sie das Projekt aus dem Study Designer herunter und ersetzen Sie die Beispieldatendatei durch Ihre Items.
2. Schicken Sie Ihrer IT den Projektordner und einen Link auf Server-Anforderungen von Potato für Ihre IT.
3. Sagen Sie dem Team, wer Ihre Annotatoren sind, wie viele teilnehmen und wie lange die Studie läuft.
4. Sagen Sie, wie sich Annotatoren anmelden sollen. Kolleginnen und Kollegen mit Konten der Einrichtung können Single Sign-on nutzen, die Anmeldung, die Ihre Einrichtung bereits betreibt, und externe Annotatoren können Benutzernamen nutzen, die Sie auflisten.
5. Sagen Sie, ob die Items oder die Antworten personenbezogene oder sensible Informationen enthalten, und nennen Sie das Ethikvotum, unter dem die Studie läuft.
6. Bitten Sie das Team um die Webadresse der Studie, um den Admin-Schlüssel, der das Admin-Dashboard von Potato öffnet, und um einen Plan für Backups und für die Übergabe der Daten an Sie, wenn die Studie endet.

Wenn die Adresse eintrifft, arbeiten Sie Bevor Sie Annotatoren einladen durch, bevor Sie die Adresse an irgendjemanden schicken.

Einen Deploy-Button klicken, den ein Kollege vorbereitet hat

Ein Deploy-Button ist ein Link auf der Seite eines Code-Repositorys, der eine Kopie einer Potato-Aufgabe auf den Servern eines Hosting-Unternehmens einrichtet, vollständig über Formulare in Ihrem Browser. Ein Kollege, der git und ein Terminal nutzt, erstellt den Button einmal aus einem Repository, das Ihren Projektordner enthält, mit dem Befehl potato deploy button. Potato lokal oder in der Cloud ausführen ist die Seite, die Sie diesem Kollegen schicken.

Der Button funktioniert mit drei Hosts, die unterschiedlich abrechnen:

• Render führt die Studie in einem kostenlosen Tarif ohne Zahlungsmittel aus. Ein kostenloser Render-Dienst schläft nach 15 Minuten ohne Besucher ein und braucht etwa eine Minute zum Aufwachen, wenn der nächste Annotator eintrifft.
• Heroku berechnet 7 $ pro Monat für den Server, den der Button erstellt. Heroku verlangt ein verifiziertes Konto, meist über eine Kreditkarte, bevor Sie eine App anlegen können.
• AWS betreibt einen Lightsail-Server für 12 $ pro Monat. Der AWS-Button liest die Aufgabe aus einem öffentlichen Repository, daher eignet er sich nur für Items, die öffentlich sein dürfen.

Render und Heroku löschen den Datenträger des Servers, sobald der Server neu startet. Der Button kopiert die Annotationen deshalb alle fünf Minuten in ein privates Dataset auf Hugging Face, einer Seite zum Teilen von Daten und Modellen, und kopiert die Annotationen zurück, sobald der Server startet. Sie nennen dieses Dataset beim Klicken, und das Dataset gehört zu Ihrem Konto.

Halten Sie vor dem Klicken drei Dinge bereit:

• ein Konto beim Host, Render oder Heroku;
• ein kostenloses Hugging-Face-Konto mit einem Zugriffstoken mit Schreibrecht, das Sie unter huggingface.co/settings/tokens erstellen; und
• Zugriff auf das Repository, wenn das Repository privat ist. Heroku bittet Sie bei einem privaten Repository, Ihr GitHub-Konto zu verknüpfen.

Stellen Sie dann bereit:

1. Klicken Sie den Button in der README des Repositorys und melden Sie sich beim Host an.
2. Geben Sie der App einen Namen. Der Name wird Teil der Webadresse der Studie.
3. Tippen Sie in POTATO_BACKUP_HF_REPO einen Dataset-Namen aus Ihrem Hugging-Face-Benutzernamen und einem Namen für die Studie ein, etwa your-username/my-study-annotations. Ist der Name neu, legt Potato das Dataset an und macht es privat.
4. Fügen Sie Ihr Hugging-Face-Token in HF_TOKEN ein. Lassen Sie jedes andere Feld auf dem Wert, den der Button eingetragen hat.
5. Starten Sie die Bereitstellung und warten Sie, bis der Host meldet, dass die App läuft. Öffnen Sie die Webadresse, die der Host anzeigt.
6. Suchen Sie den Admin-Schlüssel, ein Passwort, das der Host bei der Bereitstellung erzeugt hat. Auf Heroku ist der Schlüssel der Eintrag POTATO_ADMIN_API_KEY auf dem Tab Settings der App, und auf Render steht derselbe Eintrag auf der Seite Environment des Dienstes.
7. Öffnen Sie die Adresse der Studie mit angehängtem /admin und fügen Sie den Admin-Schlüssel ein, um das Admin-Dashboard zu öffnen.

Das Repository legt die Aufgabe, die Items und die Liste der Annotatoren fest. Schließen Sie die Aufgabe ab, bevor Sie klicken, denn jede spätere Änderung läuft über den Kollegen, der den Button erstellt hat. Halten Sie das Repository privat, es sei denn, die Items dürfen öffentlich sein.

Einen Link von Ihrem eigenen Computer freigeben

Ihr eigener Computer kann einen Pilotlauf für einen Nachmittag bedienen. Annotatoren öffnen einen temporären Weblink, die Annotationen landen in Ihrem Projektordner, und der Link funktioniert nicht mehr, wenn Sie den Befehl beenden. Dieser Weg braucht ein Terminal, ein Programm zum Eintippen von Befehlen. Auf einem Mac ist das Terminal (unter Programme, dann Dienstprogramme), unter Windows ist es PowerShell (suchen Sie im Startmenü nach „PowerShell“).

1. Installieren Sie Python 3.9 oder neuer von python.org/downloads. Unter Windows ist der Download der Python Install Manager. Auf einem Mac ist der Download das macOS-Installationsprogramm.

2. Öffnen Sie das Terminal und installieren Sie Potato. Auf einem Mac tippen Sie:

   bashKopieren

   python3 -m pip install potato-annotation

   Unter Windows tippen Sie:

   powershellKopieren

   py -m pip install potato-annotation

3. Entpacken Sie das Projekt, das Sie aus dem Study Designer heruntergeladen haben. Auf einem Mac doppelklicken Sie auf die .zip-Datei. Unter Windows klicken Sie mit der rechten Maustaste auf die Datei und wählen Alle extrahieren. Ersetzen Sie die Beispieldatendatei durch Ihre Items.

4. Wechseln Sie im Terminal in den Projektordner und starten Sie Potato. Der Ordnername unten ist ein Beispiel, verwenden Sie also den Namen Ihres eigenen Ordners. Auf einem Mac:

   bashKopieren

   cd ~/Downloads/my-task
   python3 -m potato start config.yaml

   Unter Windows:

   powershellKopieren

   cd $HOME\Downloads\my-task
   py -m potato start config.yaml

5. Öffnen Sie http://localhost:8000 in Ihrem Browser. Nur Ihr Computer kann diese Adresse erreichen. Drücken Sie Strg-C im Terminal, um Potato zu beenden.

6. Um andere Personen hineinzulassen, installieren Sie cloudflared, ein kostenloses Programm von Cloudflare, das kein Konto braucht. Auf einem Mac mit Homebrew führen Sie brew install cloudflared aus. Unter Windows laden Sie das Windows-Installationsprogramm von der Download-Seite von Cloudflare herunter.

7. Führen Sie potato share anstelle von potato start aus:

   bashKopieren

   python3 -m potato share config.yaml

   Unter Windows tippen Sie py -m potato share config.yaml. Potato zeigt an, wer sich anmelden kann, und fragt nach, bevor etwas veröffentlicht wird. Tippen Sie y, und Potato gibt einen https://-Link aus, den Sie an Ihre Annotatoren schicken.

Der Link funktioniert nur, solange der Befehl läuft. Das Schließen des Terminals, der Ruhezustand des Computers oder ein Netzwerkwechsel beenden den Link, und ein neuer Lauf gibt einen neuen Link aus. Manche Hochschulnetze sperren die trycloudflare.com-Links, die cloudflared erzeugt. Meldet ein Annotator einen gesperrten Link, nutzt potato share config.yaml --backend tailscale stattdessen Tailscale. Tailscale braucht ein kostenloses Konto. Meldet potato share No tunnel backend found, hat Potato cloudflared auf Ihrem Computer nicht gefunden, und die Meldung listet die Installationsbefehle auf.

Installation behandelt virtuelle Umgebungen und optionale Funktionen, und Potato lokal oder in der Cloud ausführen behandelt potato share ausführlicher.

Einen Server mit einem Befehl mieten

potato deploy up mietet einen Server bei einem Cloud-Unternehmen, besorgt ein HTTPS-Zertifikat (das Schloss in der Adressleiste des Browsers), lädt Ihren Projektordner hoch, startet die Studie und gibt die Webadresse aus. Der Befehl braucht die Einrichtung des Terminals aus den Schritten 1 bis 3 oben, ein Konto beim Cloud-Unternehmen und ein API-Token, einen passwortähnlichen Schlüssel, mit dem ein Programm in Ihrem Konto handeln darf. Die Anleitung jedes Hosts behandelt das Konto und das Token von Grund auf:

Jeder Host nimmt dieselben zwei Befehle, und die Anleitung für jeden Host nennt den Namen des Anbieters und den Installationsbefehl für den Host. Der erste Befehl zeigt den Plan und die monatlichen Kosten und erstellt nichts, und der zweite erstellt den Server, nachdem Sie bestätigt haben:

potato deploy up config.yaml --provider aws --dry-run
potato deploy up config.yaml --provider aws

Der Button Duplicate this Space von Hugging Face kopiert einen Space im Browser, aber die Kopie eines Potato-Space behält die Backup-Einstellungen des ursprünglichen Besitzers und verliert die Secrets des Originals. Stellen Sie einen Potato-Space stattdessen mit potato deploy up --provider huggingface bereit.

Bevor Sie Annotatoren einladen

Gehen Sie diese Liste einmal durch, sobald die Studie eine Webadresse hat, welchen Weg Sie auch genommen haben:

• Festlegen, wer sich anmelden darf. Die einfachste geschlossene Einrichtung ist eine Liste von Benutzernamen. Schalten Sie im Study Designer Allow All Users aus und fügen Sie jeden Annotator unter Authorized Users hinzu. Jeder aufgeführte Annotator wählt beim ersten Besuch bei der Registrierung ein Passwort, und Potato weist jeden ab, der nicht auf der Liste steht. Schicken Sie jedem Annotator den Benutzernamen direkt, denn die erste Person, die einen aufgeführten Benutzernamen registriert, besitzt dieses Konto. Für Konten der Einrichtung siehe SSO- und OAuth-Authentifizierung, für Crowdworker siehe Crowdsourcing-Integration. Mit eingeschaltetem Allow All Users kann jeder, der die Adresse findet, ein Konto anlegen. Behalten Sie diese Einstellung für öffentliche Demos.
• Wissen, wo die Annotationen liegen. Potato speichert die Antworten jedes Annotators, während dieser arbeitet, in einer Datei namens user_state.json in einem Ordner pro Annotator. Die Ordner liegen im Ausgabeordner, den die Konfiguration nennt und den der Study Designer output nennt. Auf Ihrem eigenen Computer liegt dieser Ordner in Ihrem Projektordner. Bei einer Bereitstellung per Button enthält das Hugging-Face-Dataset die Kopie, die einen Neustart übersteht. Auf einem gemieteten Server lädt potato deploy pull den Ordner herunter. Fragen Sie bei einem Server der Einrichtung die IT, wie der Server gesichert wird.
• Mit einem zweiten Browser testen. Öffnen Sie die Adresse der Studie in einem privaten Fenster, das heißt Inkognito in Chrome, Privates Fenster in Safari und Firefox und InPrivate in Edge. Fügen Sie der Liste einen Benutzernamen wie pilot-test hinzu, registrieren Sie sich mit diesem Namen und beantworten Sie drei Items. Schließen Sie das Fenster, melden Sie sich erneut an und prüfen Sie, ob die Antworten noch da sind. Öffnen Sie dann das Admin-Dashboard und prüfen Sie, ob der Test-Annotator erscheint. Probieren Sie die Adresse auf einem Smartphone aus, falls Annotatoren auf Smartphones arbeiten könnten.
• Den Admin-Schlüssel privat halten. Der Admin-Schlüssel öffnet das Admin-Dashboard unter /admin. Das Dashboard zeigt die Antworten jedes Annotators. Auf Ihrem eigenen Computer speichert Potato den Schlüssel in admin_api_key.txt im Projektordner, sobald Sie zum ersten Mal /admin öffnen.
• Die Einladung schreiben. Schicken Sie jedem Annotator die Adresse, den Benutzernamen, die Dauer der Aufgabe und die Kontaktperson für den Fall, dass etwas schiefgeht.

Ihre Ergebnisse abholen

Das Admin-Dashboard lädt die Ergebnisse ohne Terminal auf Ihren Computer herunter. Öffnen Sie /admin, geben Sie den Admin-Schlüssel ein und wählen Sie Publish Dataset. Wählen Sie unter Target die Option Local archive, setzen Sie Data format für eine Tabelle auf CSV und klicken Sie auf Publish. Ist das Archiv fertig, klicken Sie auf Download archive.

Das Archiv enthält die Antworten jedes Annotators, die Items und die per Mehrheitsentscheid kombinierten Labels. Eine README im Archiv nennt die Label-Anzahlen und die Übereinstimmung zwischen den Annotatoren. Annotatorennamen werden durch A1, A2 usw. ersetzt, es sei denn, Sie entfernen das Häkchen bei Anonymize annotators. Antworten aus Umfragen bleiben aus dem Archiv heraus, es sei denn, Sie setzen das Häkchen bei Include survey / phase responses, weil Umfrageantworten personenbezogene Informationen enthalten können.

Von einem Terminal aus schreibt python -m potato.export dieselben Annotationen in einen Ordner, in jedem der Exportformate von Potato:

python -m potato.export --config config.yaml --format csv --output results

Auf einem mit potato deploy up erstellten Server lädt potato deploy pull config.yaml alles herunter, was der Server gesammelt hat, einschließlich der Datenbanken.

Die Studie beenden, damit der Server keine Kosten mehr verursacht

Laden Sie die Ergebnisse herunter, bevor Sie etwas entfernen, und öffnen Sie den Download, um zu prüfen, dass die Antworten des letzten Annotators enthalten sind. Schalten Sie den Server dann so ab, wie es der Weg verlangt:

• Ihr eigener Computer. Drücken Sie Strg-C im Terminal. Es sind keine Kosten entstanden.
• Ihre IT. Sagen Sie dem Team, dass die Studie beendet ist, bitten Sie um eine Kopie des Ausgabeordners und fragen Sie, wie lange die Kopie auf dem Server aufbewahrt wird.
• Ein Deploy-Button. Löschen Sie die App auf dem Tab Settings der App bei Heroku oder den Dienst auf seiner Seite Settings bei Render. Das Hugging-Face-Dataset enthält eine vollständige Kopie der Annotationen. Wenn Sie das Backup nicht mehr brauchen, löschen Sie das Dataset auf der Einstellungsseite des Datasets.
• Ein gemieteter Server. Führen Sie potato deploy pull config.yaml aus, prüfen Sie den heruntergeladenen Ordner und führen Sie dann potato deploy destroy config.yaml aus. Potato weigert sich, einen Server zu zerstören, dessen Daten nie heruntergeladen wurden.

Häufige Fragen

Wie erstelle ich einen Potato-Server für meine Studie?

Sie erstellen einen Potato-Server, indem Sie Ihre Aufgabe auf einem Computer ausführen, den Ihre Annotatoren über eine Webadresse erreichen. Die IT Ihrer Einrichtung kann die Aufgabe für Sie ausführen, ein Kollege kann einen Deploy-Button vorbereiten, den Sie klicken, potato share kann einen Pilotlauf von Ihrem Laptop aus bedienen, und potato deploy up kann einen Server für Sie mieten. Die Tabelle unter Einen Weg wählen vergleicht die Wege nach Kosten und nach der Terminalarbeit, die jeder Weg braucht.

Wie installiere ich Potato auf meinem PC?

Installieren Sie Python 3.9 oder neuer von python.org und tippen Sie dann py -m pip install potato-annotation in PowerShell unter Windows oder python3 -m pip install potato-annotation im Terminal auf einem Mac. Nach der Installation startet py -m potato start config.yaml unter Windows oder python3 -m potato start config.yaml auf einem Mac eine Aufgabe. Installation behandelt die optionalen Funktionen.

In dieser Seite verwendete Begriffe

• Server. Ein Server ist ein Computer, der eingeschaltet und mit dem Internet verbunden bleibt, damit andere Personen ein Programm auf diesem Computer über einen Webbrowser nutzen können.
• URL oder Webadresse. Eine URL ist die Adresse, die Annotatoren eintippen oder anklicken, etwa https://my-study.example.edu. Eine Domain ist der Namensteil der Adresse, hier my-study.example.edu.
• HTTPS. HTTPS verschlüsselt alles zwischen dem Browser des Annotators und dem Server, auch Passwörter und Antworten. Browser zeigen bei einer HTTPS-Adresse ein Schloss.
• Port. Ein Port ist ein nummerierter Eingang eines Computers. Potato lauscht auf Port 8000, wenn die Konfiguration keinen anderen Port nennt, und die lokale Adresse http://localhost:8000 endet mit dieser Nummer.
• Terminal. Ein Terminal ist ein Programm zum Eintippen von Befehlen, auf einem Mac Terminal und unter Windows PowerShell genannt.
• Admin-Schlüssel. Der Admin-Schlüssel ist ein langes Passwort, das das Admin-Dashboard von Potato öffnet.
• API-Token. Ein API-Token ist ein passwortähnlicher Schlüssel, mit dem ein Programm, etwa der Deploy-Befehl von Potato, in Ihrem Konto bei einem Hosting-Unternehmen handeln darf.

Weiterführende Literatur

• Server-Anforderungen von Potato für Ihre IT, die Seite, die Sie Ihrer IT schicken
• Potato lokal oder in der Cloud ausführen, für jeden Host, Deploy-Buttons und Backups
• Einen Annotationsserver bereitstellen, um einen Host für eine lange Studie zu wählen
• Potato in Docker ausführen, für Server, die Container ausführen
• Admin-Dashboard, um den Fortschritt während der Studie zu verfolgen