Skip to content

Démarrage rapide

Lancez Potato en moins de 5 minutes. Installez-le avec pip, écrivez une configuration YAML, démarrez le serveur et annotez votre premier jeu de données sans écrire de code.

Ce guide vous mène d'une installation neuve à l'annotation de données en moins de 5 minutes. Il montre comment écrire une tâche vous-même. L'autre façon de commencer consiste à décrire l'étude à un agent de programmation et à laisser potato-skill la concevoir et la construire, ce que couvre Démarrage rapide avec un agent de programmation.

Potato en cinq étapes : installer, configurer, lancer le serveur, annoter dans le navigateur et exporterPotato en cinq étapes

Prérequis

  • Python 3.9 ou supérieur
  • Le gestionnaire de paquets pip
  • Un terminal

Installation

Nous recommandons d'installer Potato dans un environnement virtuel pour éviter tout conflit avec le Python du système :

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

Vérifiez l'installation :

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

Vous devriez voir s'afficher 2.10.3. Depuis la version 2.9, potato --version indique le même numéro, et y ajoute le commit lorsque vous l'exécutez depuis une copie locale du dépôt.

Créez votre premier projet

1. Créez un répertoire de projet

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

2. Créez votre fichier de données

Créez un dossier data et, à l'intérieur, un fichier appelé 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."}
]

Potato accepte aussi .jsonl (un objet JSON par ligne), .csv et .tsv pour data_files. Indiquez un fichier avec l'extension correspondante et Potato choisit le lecteur d'après celle-ci.

3. Créez votre configuration

Créez un fichier appelé config.yaml dans votre répertoire de projet :

Bac à sable des chemins : Tous les chemins relatifs de votre configuration (comme data_files ou output_annotation_dir) sont résolus par rapport à task_dir et doivent rester à l'intérieur. Les chemins qui se résolvent hors de task_dir sont rejetés pour empêcher la traversée de répertoires.

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

Astuce : Vous pouvez valider votre configuration sans lancer le serveur complet grâce à la Preview CLI. C'est le moyen le plus rapide de repérer les fautes de frappe avant de commencer à annoter.

4. Démarrez le serveur

bash
potato start config.yaml -p 8000

Forme longue équivalente :

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

Si le port 8000 est déjà utilisé, choisissez-en un autre avec -p 8001. Pour arrêter le serveur, appuyez sur Ctrl+C dans le terminal.

Premier lancement plus rapide : Ajoutez --debug pour contourner complètement l'écran de connexion pendant vos essais : potato start config.yaml --debug.

5. Ouvrez votre navigateur

Accédez à http://localhost:8000. Vous verrez un écran de connexion avec un seul champ username. Saisissez n'importe quoi (par exemple alice) et cliquez sur Continue, et vous pouvez annoter.

Chaque fois que vous sélectionnez une étiquette et cliquez sur Next, votre annotation est enregistrée automatiquement. Il n'y a pas de bouton « enregistrer » distinct.

Où vont vos annotations

Potato écrit l'état de chaque utilisateur au fil de l'annotation :

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

user_state.json contient l'état d'annotation complet de cet utilisateur. Pour produire un fichier plat consolidé couvrant tous les annotateurs, lancez la CLI d'export de Potato, que décrit la documentation de l'export. Lancez python -m potato.export --list-formats pour voir tous les formats qu'elle enregistre.

Problèmes courants au premier lancement

  • Address already in use. Le port 8000 est occupé. Utilisez -p 8001 (ou n'importe quel port libre).
  • KeyError: 'description'. Il manque à un schéma radio (ou similaire) son champ obligatoire description. Chaque schéma en a besoin d'un.
  • Path ... is outside the task directory. Un chemin data_files ou output_annotation_dir sort de task_dir. Gardez tout dans le dossier du projet, ou définissez task_dir comme un chemin absolu qui les contient.
  • La page de connexion affiche un champ de mot de passe. Vous avez oublié require_password: false, ou vous êtes sur un onglet du navigateur mis en cache. Redémarrez le serveur et forcez le rechargement de la page.

Foire aux questions

Les questions ci-dessous portent sur l'installation de Potato, son exécution dans Docker et la vérification d'une configuration avant que les annotateurs ne la voient.

Comment installer Potato ?

Installez-le depuis PyPI avec pip install potato-annotation, sous Python 3.9 ou supérieur. L'installer dans un environnement virtuel tient les dépendances de Potato à l'écart du Python du système, et potato --version confirme l'installation en affichant le numéro de version.

Peut-on exécuter Potato dans Docker ?

Oui. Potato publie une image préconstruite, ghcr.io/davidjurgens/potato, sur GitHub Container Registry. Le dossier de votre projet est monté dans le conteneur sur /app et le serveur écoute sur le port 7860 à l'intérieur, si bien qu'une seule image sert pour toutes les tâches. Définissez POTATO_SECRET_KEY pour que les sessions des annotateurs survivent à un redémarrage. Déployer Potato sur un serveur donne la commande docker run complète.

Comment vérifier une configuration Potato avant que les annotateurs ne la voient ?

Lancez potato validate config.yaml --strict, qui vérifie la configuration comme le fait le serveur au démarrage et transforme les avertissements, par exemple une clé non reconnue, en échecs. potato preview config.yaml montre ensuite ce que déclare la configuration et affiche l'interface dans un navigateur, ce qui vous permet de voir la tâche comme la verra un annotateur avant que quiconque ne se connecte.

Et ensuite ?

Outils et utilitaires

Une fois à l'aise avec les bases, consultez ces outils pratiques :