Skip to content

Schnellstart

Potato in weniger als 5 Minuten zum Laufen bringen. Mit pip installieren, eine YAML-Konfiguration schreiben, den Server starten und den ersten Datensatz annotieren, ohne Code zu schreiben.

Diese Anleitung führt Sie in weniger als 5 Minuten von einer frischen Installation bis zur Annotation von Daten. Sie zeigt, wie Sie eine Aufgabe selbst schreiben. Der andere Weg zum Start besteht darin, die Studie einem Coding-Agenten zu beschreiben und potato-skill sie entwerfen und aufbauen zu lassen. Das behandelt Schnellstart mit einem Coding-Agenten.

Potato in fünf Schritten: installieren, konfigurieren, den Server starten, im Browser annotieren und exportierenPotato in fünf Schritten

Voraussetzungen

  • Python 3.9 oder höher
  • Der Paketmanager pip
  • Ein Terminal

Installation

Wir empfehlen, Potato in einer virtuellen Umgebung zu installieren, damit es nicht mit dem System-Python kollidiert:

bash
python -m venv potato-env
source potato-env/bin/activate   # Windows: potato-env\Scripts\activate
pip install potato-annotation

Prüfen Sie die Installation:

bash
python -c "import potato; print(potato.__version__)"

Es sollte 2.12.1 ausgegeben werden. Ab Version 2.9 meldet potato --version dieselbe Nummer und ergänzt den Commit, wenn Sie Potato aus einem Checkout ausführen.

Erstes Projekt erstellen

1. Projektverzeichnis anlegen

bash
mkdir my-annotation-task
cd my-annotation-task

2. Datendatei erstellen

Erstellen Sie einen Ordner data und darin eine Datei namens data.json:

bash
mkdir data
json
[
  {"id": "1", "text": "I love this product! It's amazing."},
  {"id": "2", "text": "This is the worst experience ever."},
  {"id": "3", "text": "It's okay, nothing special."}
]

Für data_files akzeptiert Potato außerdem .jsonl (ein JSON-Objekt pro Zeile), .csv und .tsv. Verweisen Sie auf eine Datei mit der passenden Endung, und Potato wählt anhand der Endung den Reader.

3. Konfiguration erstellen

Erstellen Sie eine Datei namens config.yaml in Ihrem Projektverzeichnis:

Pfad-Sandbox: Alle relativen Pfade in Ihrer Konfiguration (etwa data_files oder output_annotation_dir) werden relativ zu task_dir aufgelöst und müssen innerhalb dieses Verzeichnisses bleiben. Pfade, die außerhalb von task_dir landen, werden abgewiesen, um Path Traversal zu verhindern.

yaml
annotation_task_name: "Sentiment Analysis"
 
# All relative paths below are resolved against task_dir.
task_dir: "."
 
# Data configuration
data_files:
  - "data/data.json"
 
# Tell Potato which fields in each record to use.
# id_key = unique identifier; text_key = the text shown to annotators.
item_properties:
  id_key: id
  text_key: text
 
# Where per-user annotation state is stored (relative to task_dir).
output_annotation_dir: "annotation_output/"
 
# Also write a periodic flat export, because the per-user state files are
# awkward to analyze. No exporter is named "json", so use "jsonl".
export_annotation_format: "jsonl"
 
# Annotation scheme
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment of this text?"   # required for radio schemes
    labels:
      - Positive
      - Negative
      - Neutral
 
# Skip password authentication so anyone can log in with just a username.
require_password: false

Tipp: Mit der Preview CLI können Sie Ihre Konfiguration validieren, ohne den vollständigen Server zu starten. So finden Sie Tippfehler am schnellsten, bevor Sie mit der Annotation beginnen.

4. Server starten

bash
potato start config.yaml -p 8000

Gleichwertige Langform:

bash
python -m potato start config.yaml -p 8000

Ist Port 8000 bereits belegt, wählen Sie mit -p 8001 einen anderen. Um den Server zu beenden, drücken Sie im Terminal Ctrl+C.

Schnellerer erster Start: Fügen Sie --debug --debug-phase=annotation hinzu, um beim Ausprobieren die Anmelde- und die Einwilligungsseite zu überspringen: potato start config.yaml --debug --debug-phase=annotation. Jede besuchende Person wird dann als ein gemeinsamer debug_user angemeldet, verwenden Sie das also nur auf Ihrem eigenen Rechner.

5. Browser öffnen

Öffnen Sie http://localhost:8000. Sie sehen einen Anmeldebildschirm mit einem einzigen Feld username. Geben Sie einen beliebigen Namen ein (z. B. alice) und klicken Sie auf Continue. Danach können Sie annotieren.

Jedes Mal, wenn Sie ein Label auswählen und auf Next klicken, wird Ihre Annotation automatisch gespeichert. Einen eigenen Speichern-Button gibt es nicht.

Wo Ihre Annotationen landen

Potato schreibt den Zustand pro Benutzer, während Sie annotieren:

text
my-annotation-task/
├── config.yaml
├── data/
│   └── data.json
└── annotation_output/              # created automatically
    └── alice/
        └── user_state.json         # one folder per username

user_state.json enthält den vollständigen Annotationszustand dieses Benutzers. Um eine zusammengeführte, flache Datei über alle Annotatoren hinweg zu erzeugen, führen Sie die Export-CLI von Potato aus, die in der Export-Dokumentation beschrieben ist. Mit python -m potato.export --list-formats sehen Sie jedes Format, das sie registriert.

Häufige Probleme beim ersten Start

  • Address already in use. Port 8000 ist belegt. Verwenden Sie -p 8001 (oder einen anderen freien Port).
  • KeyError: 'description'. Einem Radio-Schema (oder einem ähnlichen Schema) fehlt das Pflichtfeld description. Jedes Schema braucht eines.
  • Path ... is outside the task directory. Ein Pfad in data_files oder output_annotation_dir verlässt task_dir. Legen Sie alles in den Projektordner, oder setzen Sie task_dir auf einen absoluten Pfad, der diese Dateien enthält.
  • Die Anmeldeseite zeigt ein Passwortfeld. Sie haben require_password: false vergessen, oder Sie sind in einem zwischengespeicherten Browser-Tab. Starten Sie den Server neu und laden Sie die Seite ohne Cache neu.

Häufige Fragen

Die folgenden Fragen behandeln die Installation von Potato, den Betrieb in Docker und die Prüfung einer Konfiguration, bevor Annotatoren sie sehen.

Wie installiere ich Potato?

Installieren Sie Potato aus PyPI mit pip install potato-annotation, unter Python 3.9 oder höher. Eine Installation in einer virtuellen Umgebung hält die Abhängigkeiten von Potato vom System-Python getrennt, und potato --version bestätigt die Installation, indem es die Versionsnummer ausgibt.

Kann ich Potato in Docker ausführen?

Ja. Potato veröffentlicht ein vorgefertigtes Image, ghcr.io/davidjurgens/potato, in der GitHub Container Registry. Ihr Projektordner wird unter /app in den Container eingebunden, und der Server lauscht darin auf Port 7860, sodass ein einziges Image jede Aufgabe bedient. Setzen Sie POTATO_SECRET_KEY, damit die Sitzungen der Annotatoren einen Neustart überstehen. Potato auf einem Server bereitstellen enthält den vollständigen docker run-Befehl.

Wie prüfe ich eine Potato-Konfiguration, bevor Annotatoren sie sehen?

Führen Sie potato validate config.yaml --strict aus. Der Befehl prüft die Konfiguration so, wie es der Server beim Start tut, und macht aus Warnungen, etwa zu einem unbekannten Schlüssel, Fehler. potato preview config.yaml zeigt anschließend, was die Konfiguration deklariert, und rendert die Oberfläche im Browser, sodass Sie die Aufgabe so sehen, wie ein Annotator sie sehen wird, bevor sich jemand anmeldet.

Nächste Schritte

Werkzeuge und Hilfsprogramme

Sobald Sie mit den Grundlagen vertraut sind, finden Sie hier nützliche Werkzeuge: