Développement local

Installez et lancez Potato en local pour le développement et les tests. Couvre l'installation via pip, la configuration, le démarrage du serveur et le diagnostic des problèmes de démarrage courants.

Faites tourner Potato sur votre machine pour développer et tester.

Prérequis

Python 3.9 ou version supérieure
Le gestionnaire de paquets pip
Git (facultatif, pour cloner les exemples)

Installation

Avec pip (recommandé)

bash

pip install potato-annotation

Depuis les sources

bash

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

Avec les dépendances facultatives

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]"

Mettez l'extra entre guillemets pour que le shell ne lise pas les crochets comme un motif glob. all exclut volontairement vision, car ce groupe installe torch et rien dans l'usage par défaut n'en a besoin.

Démarrage rapide

1. Créer un fichier de configuration

Créez 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 est la racine par rapport à laquelle tous les autres chemins relatifs sont résolus, et Potato refuse de lire en dehors. En le fixant à ., la configuration, le fichier de données et le répertoire de sortie restent dans un même dossier, ce qui permet de déplacer le projet vers un serveur plus tard.

2. Préparer des données d'exemple

Créez 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. Démarrer le serveur

bash

potato start config.yaml

4. Ouvrir l'interface

Rendez-vous sur http://localhost:8000 dans votre navigateur.

Mode développement

Mode debug

Le mode debug active la journalisation verbeuse, désactive le délai d'inactivité des sessions et ouvre les pages d'administration sans clé pour les requêtes venant de votre propre machine. La page de connexion reste en place, et --debug-phase (ci-dessous) permet de la passer :

bash

potato start config.yaml --debug

N'activez jamais le mode debug sur un serveur déployé. Un tunnel ou un proxy inverse sur la même machine qui n'ajoute aucun en-tête de transfert fait passer chaque appelant pour local, et --debug-phase connecte chaque visiteur sous le même debug_user. Les versions 2.8.2 à 2.11.0 de Potato refusent de démarrer en mode debug sur l'adresse par défaut 0.0.0.0 ; sur ces versions, ajoutez donc --host 127.0.0.1.

Journalisation de débogage

Choisissez quelle partie de l'application produit des journaux :

bash

potato start config.yaml --debug-log server

Les valeurs acceptées sont all, ui, server et none. Utilisez ui quand la page d'annotation se comporte mal et server quand un élément ne se charge pas.

Sortie verbeuse

Voir toute l'activité du serveur :

bash

potato start config.yaml --verbose

Aller directement à une phase

Avec --debug activé, passez la connexion et allez directement à la phase sur laquelle vous travaillez au lieu de parcourir le consentement et les instructions à chaque redémarrage :

bash

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

Arborescence

Organisation de projet recommandée :

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

Seuls config.yaml et le fichier de données sont obligatoires. Potato fournit ses propres gabarits, donc ne définissez site_dir et n'ajoutez un dossier templates/ que si vous les remplacez, et faites pointer site_file vers un fichier précis pour rendre la page d'annotation avec celui-ci.

Tester votre configuration

Valider la configuration

Vérifiez la configuration comme le serveur la vérifie au démarrage, avant d'y consacrer un démarrage :

bash

potato validate config.yaml

Ajoutez --strict pour que les avertissements, par exemple une clé non reconnue, fassent échouer l'exécution au lieu d'être affichés sans bloquer.

Mode aperçu

Affichez ce que déclare une configuration et rendez-la dans un navigateur sans démarrer un serveur complet :

bash

potato preview config.yaml

Les captures d'écran nécessitent l'extra du navigateur headless, pip install "potato-annotation[preview]" :

bash

potato preview config.yaml --screenshot preview.png

Problèmes courants

Port déjà utilisé

bash

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

Ou définissez-le dans config.yaml, l'option -p le remplaçant alors :

yaml

port: 8080

Fichier de données introuvable

Les chemins doivent être relatifs à l'emplacement du fichier de configuration :

yaml

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

Les chemins sont résolus par rapport à task_dir, et Potato refuse de charger un fichier situé en dehors. Déplacez donc les données sous le répertoire de la tâche plutôt que de pointer vers un chemin absolu ailleurs sur la machine.

Permission refusée

Vérifiez les permissions des fichiers :

bash

chmod 755 annotations/
chmod 644 data/*.json

Plusieurs utilisateurs en local

Pour tester des scénarios multi-utilisateurs :

yaml

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

url_direct lit le nom d'utilisateur directement dans l'URL et ne demande aucun mot de passe. Vous pouvez donc ouvrir deux profils de navigateur et annoter comme deux personnes sans créer de comptes :

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

Réinitialiser les annotations

Potato écrit un répertoire par annotateur sous output_annotation_dir, chacun contenant le user_state.json de la personne :

bash

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

Supprimer le répertoire d'un utilisateur supprime ses attributions en même temps que ses réponses, donc une nouvelle exécution réattribue les éléments depuis le début.

Variables d'environnement

Configuration par l'environnement :

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

Sans POTATO_SECRET_KEY, Potato génère une clé de signature aléatoire à chaque démarrage, ce qui déconnecte tout le monde à chaque redémarrage.

Utilisation avec des environnements virtuels

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

Intégration avec l'IDE

VS Code

Installez l'extension YAML pour la prise en charge du fichier de configuration :

json

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

Les configurations téléchargées depuis le Concepteur d'études portent déjà ce schéma sur une ligne # yaml-language-server:, elles sont donc validées dans l'éditeur sans ce réglage.

PyCharm

Créez une configuration d'exécution :

Add → Python
Script : potato
Paramètres : start config.yaml
Répertoire de travail : le chemin de votre projet

Étapes suivantes

Bases de la configuration - Toutes les options de configuration
Formats de données - Comprendre la structure des données
Mise en production - Déployer pour un usage réel