Lokale Entwicklung

Potato lokal für Entwicklung und Tests installieren und ausführen. Behandelt die Installation mit pip, die Konfiguration, den Serverstart und die Fehlersuche bei häufigen Startproblemen.

Bringen Sie Potato auf Ihrem lokalen Rechner für Entwicklung und Tests zum Laufen.

Voraussetzungen

Python 3.9 oder höher
pip-Paketmanager
Git (optional, zum Klonen von Beispielen)

Installation

Mit pip (empfohlen)

bash

pip install potato-annotation

Aus dem Quellcode

bash

git clone https://github.com/davidjurgens/potato.git
cd potato
pip install -e .

Mit optionalen Abhängigkeiten

bash

# Local speech-to-text and diarization for transcript projects
pip install "potato-annotation[transcribe]"
 
# Hosted model providers for AI support and active learning
pip install "potato-annotation[ai]"
 
# Everything except the multi-gigabyte server-side vision stack
pip install "potato-annotation[all]"

Setzen Sie das Extra in Anführungszeichen, damit die Shell die eckigen Klammern nicht als Glob-Muster liest. all lässt vision bewusst weg, weil diese Gruppe torch installiert und nichts in der Standardnutzung es braucht.

Schnellstart

1. Konfigurationsdatei erstellen

Erstellen Sie config.yaml:

yaml

annotation_task_name: "My First Annotation Task"
task_dir: "."
port: 8000
 
data_files:
  - data.json
 
item_properties:
  id_key: id
  text_key: text
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment?"
    labels:
      - Positive
      - Negative
      - Neutral
 
output_annotation_dir: "annotations/"

task_dir ist das Stammverzeichnis, gegen das alle anderen relativen Pfade aufgelöst werden, und Potato verweigert das Lesen außerhalb davon. Wenn Sie es auf . setzen, liegen Konfiguration, Datendatei und Ausgabeverzeichnis in einem Ordner. Genau das macht es möglich, das Projekt später auf einen Server zu verschieben.

2. Beispieldaten vorbereiten

Erstellen Sie data.json:

json

[
  {"id": "1", "text": "I love this product!"},
  {"id": "2", "text": "This is terrible."},
  {"id": "3", "text": "It's okay, nothing special."}
]

3. Server starten

bash

potato start config.yaml

4. Auf die Oberfläche zugreifen

Öffnen Sie Ihren Browser unter http://localhost:8000

Entwicklungsmodus

Debug-Modus

Der Debug-Modus schaltet ausführliche Protokollierung ein, schaltet das Inaktivitäts-Timeout der Sitzung ab und öffnet die Admin-Seiten ohne Schlüssel für Anfragen von Ihrem eigenen Rechner. Die Anmeldeseite bleibt, und --debug-phase (unten) überspringt sie:

bash

potato start config.yaml --debug

Aktivieren Sie den Debug-Modus nie auf einem produktiv eingesetzten Server. Ein Tunnel oder Reverse Proxy auf demselben Rechner, der keinen Weiterleitungs-Header hinzufügt, lässt jeden Aufrufer lokal erscheinen, und --debug-phase meldet jede besuchende Person als denselben debug_user an. Potato 2.8.2 bis 2.11.0 verweigern den Start im Debug-Modus auf der Standardadresse 0.0.0.0; fügen Sie bei diesen Versionen deshalb --host 127.0.0.1 hinzu.

Debug-Protokollierung

Wählen Sie, welche Seite der Anwendung protokolliert:

bash

potato start config.yaml --debug-log server

Die zulässigen Werte sind all, ui, server und none. Verwenden Sie ui, wenn sich die Annotationsseite fehlerhaft verhält, und server, wenn ein Item nicht lädt.

Ausführliche Ausgabe

Alle Serveraktivitäten anzeigen:

bash

potato start config.yaml --verbose

Direkt zu einer Phase springen

Mit aktiviertem --debug überspringen Sie die Anmeldung und springen direkt zu der Phase, an der Sie arbeiten, statt sich bei jedem Neustart durch Einwilligung und Anleitung zu klicken:

bash

potato start config.yaml --debug --debug-phase annotation

Verzeichnisstruktur

Empfohlenes Projektlayout:

text

my-annotation-project/
├── config.yaml           # Main configuration, inside task_dir
├── data/
│   ├── training.json     # Practice items for the training phase
│   └── main.json         # Annotation data
├── annotations/          # output_annotation_dir
├── media/                # media_directory, served at /media/
└── templates/            # site_dir, if you override the default templates

Nur config.yaml und die Datendatei sind erforderlich. Potato bringt eigene Templates mit. Setzen Sie site_dir und legen Sie einen Ordner templates/ also nur an, wenn Sie diese ersetzen, und lassen Sie site_file auf eine bestimmte Datei zeigen, mit der die Annotationsseite gerendert werden soll.

Konfiguration testen

Konfiguration validieren

Prüfen Sie die Konfiguration so, wie der Server sie beim Start prüft, bevor Sie einen Serverstart daran verschwenden:

bash

potato validate config.yaml

Fügen Sie --strict hinzu, damit Warnungen, etwa ein unbekannter Schlüssel, den Lauf fehlschlagen lassen, statt nur ausgegeben zu werden und durchzugehen.

Vorschaumodus

Zeigen Sie an, was eine Konfiguration deklariert, und rendern Sie sie im Browser, ohne einen vollständigen Server zu starten:

bash

potato preview config.yaml

Screenshots benötigen das Extra für den Headless-Browser, pip install "potato-annotation[preview]":

bash

potato preview config.yaml --screenshot preview.png

Häufige Probleme

Port bereits in Verwendung

bash

# Use a different port
potato start config.yaml -p 8080

Oder legen Sie ihn in config.yaml fest. Die Option -p überschreibt diesen Wert dann:

yaml

port: 8080

Datendatei nicht gefunden

Stellen Sie sicher, dass Pfade relativ zum Speicherort der Konfigurationsdatei sind:

yaml

# If data is in a subdirectory
data_files:
  - data/main.json

Pfade werden gegen task_dir aufgelöst, und Potato verweigert das Laden einer Datei außerhalb davon. Verschieben Sie die Daten also in das Aufgabenverzeichnis, statt auf einen absoluten Pfad an anderer Stelle auf dem Rechner zu verweisen.

Zugriff verweigert

Dateiberechtigungen prüfen:

bash

chmod 755 annotations/
chmod 644 data/*.json

Mehrere Benutzer lokal

Für das Testen von Mehrbenutzerszenarien:

yaml

user_config:
  allow_all_users: true
 
login:
  type: url_direct
  url_argument: user_id

url_direct liest den Benutzernamen direkt aus der URL und fragt nach keinem Passwort. So können Sie zwei Browserprofile öffnen und als zwei Personen annotieren, ohne Konten zu registrieren:

http://localhost:8000/?user_id=annotator1
http://localhost:8000/?user_id=annotator2

Annotationen zurücksetzen

Potato schreibt unter output_annotation_dir ein Verzeichnis pro Annotator, das jeweils die user_state.json dieser Person enthält:

bash

# Remove one annotator's work
rm -rf annotations/annotator1
 
# Or clear every annotator
rm -rf annotations/*
 
# Restart server
potato start config.yaml

Wenn Sie das Verzeichnis eines Benutzers löschen, verschwinden seine Zuweisungen zusammen mit seinen Antworten, sodass ein neuer Lauf die Items von Grund auf neu zuweist.

Umgebungsvariablen

Über die Umgebung konfigurieren:

bash

# Keeps sessions valid across restarts; required for OAuth
export POTATO_SECRET_KEY="$(python3 -c 'import secrets; print(secrets.token_hex(32))')"
 
# Fixes the shared admin key instead of letting Potato generate one per task
export POTATO_ADMIN_API_KEY="your-admin-key"
 
potato start config.yaml

Ohne POTATO_SECRET_KEY erzeugt Potato bei jedem Start einen zufälligen Signaturschlüssel, wodurch bei jedem Neustart alle abgemeldet werden.

Mit virtuellen Umgebungen verwenden

venv

bash

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

Conda

bash

conda create -n potato python=3.10
conda activate potato
pip install potato-annotation

IDE-Integration

VS Code

Installieren Sie die YAML-Erweiterung für die Unterstützung von Konfigurationsdateien:

json

// settings.json
{
  "yaml.schemas": {
    "https://potatoannotator.readthedocs.io/en/latest/schemas/potato-config.schema.json": "config.yaml"
  }
}

Konfigurationen, die aus dem Studien-Designer heruntergeladen werden, tragen dieses Schema bereits in einer # yaml-language-server:-Zeile und werden deshalb auch ohne diese Einstellung im Editor validiert.

PyCharm

Richten Sie eine Ausführungskonfiguration ein:

Add → Python
Skript: potato
Parameter: start config.yaml
Arbeitsverzeichnis: Ihr Projektpfad

Nächste Schritte

Konfigurationsgrundlagen - Alle Konfigurationsoptionen kennenlernen
Datenformate - Die Datenstruktur verstehen
Produktionseinrichtung - Für den echten Einsatz bereitstellen