Skip to content

Guida rapida

Avvia Potato in meno di 5 minuti. Installalo con pip, scrivi una configurazione YAML, avvia il server e annota il tuo primo dataset senza scrivere codice.

Questa guida ti porta da un'installazione nuova all'annotazione dei dati in meno di 5 minuti. Mostra come scrivere un task da solo. L'altro modo per iniziare è descrivere lo studio a un agente di programmazione e lasciare che potato-skill lo progetti e lo costruisca, come spiega Guida rapida con un agente di programmazione.

Potato in cinque passi: installa, configura, avvia il server, annota nel browser ed esportaPotato in cinque passi

Prerequisiti

  • Python 3.7 o versione superiore
  • Il gestore di pacchetti pip
  • Un terminale

Installazione

Consigliamo di installare Potato in un ambiente virtuale, così non entra in conflitto con il Python di sistema:

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

Verifica l'installazione:

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

Dovresti vedere stampato 2.9.1. Dalla versione 2.9, potato --version riporta lo stesso numero e aggiunge il commit quando esegui Potato da un checkout.

Crea il tuo primo progetto

1. Crea una directory di progetto

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

2. Crea il file di dati

Crea una cartella data e al suo interno un file chiamato 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."}
]

Per data_files Potato accetta anche .jsonl (un oggetto JSON per riga), .csv e .tsv. Indica un file con l'estensione corrispondente e Potato sceglie il lettore in base a essa.

3. Crea la configurazione

Crea un file chiamato config.yaml nella directory del progetto:

Sandbox dei percorsi: tutti i percorsi relativi nella configurazione (come data_files o output_annotation_dir) vengono risolti rispetto a task_dir e devono restare al suo interno. I percorsi che si risolvono fuori da task_dir vengono rifiutati per impedire il path traversal.

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

Suggerimento: puoi validare la configurazione senza avviare il server completo usando la Preview CLI. È il modo più rapido per trovare gli errori di battitura prima di iniziare ad annotare.

4. Avvia il server

bash
potato start config.yaml -p 8000

Forma estesa equivalente:

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

Se la porta 8000 è già in uso, scegline un'altra con -p 8001. Per fermare il server, premi Ctrl+C nel terminale.

Primo avvio più rapido: aggiungi --debug per saltare del tutto la schermata di login mentre fai prove: potato start config.yaml --debug.

5. Apri il browser

Vai su http://localhost:8000. Vedrai una schermata di login con un solo campo username. Scrivi un nome qualsiasi (per esempio alice), fai clic su Continue e sei pronto ad annotare.

Ogni volta che selezioni un'etichetta e fai clic su Next, l'annotazione viene salvata automaticamente. Non c'è un pulsante "salva" separato.

Dove finiscono le annotazioni

Potato scrive lo stato di ogni utente mentre annoti:

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

user_state.json contiene lo stato completo delle annotazioni di quell'utente. Per produrre un unico file piatto con tutti gli annotatori, esegui la CLI di esportazione di Potato, descritta nella documentazione sull'esportazione. Esegui python -m potato.export --list-formats per vedere tutti i formati che registra.

Problemi comuni al primo avvio

  • Address already in use. La porta 8000 è occupata. Usa -p 8001 (o qualsiasi porta libera).
  • KeyError: 'description'. A uno schema radio (o simile) manca il campo obbligatorio description. Ogni schema ne ha bisogno.
  • Path ... is outside the task directory. Un percorso in data_files o output_annotation_dir esce da task_dir. Tieni tutto dentro la cartella del progetto, oppure imposta task_dir su un percorso assoluto che li contenga.
  • La pagina di login mostra un campo password. Hai dimenticato require_password: false, oppure stai usando una scheda del browser con la cache. Riavvia il server e forza il ricaricamento della pagina.

Domande frequenti

Le domande seguenti riguardano l'installazione di Potato, la sua esecuzione in Docker e il controllo di una configurazione prima che gli annotatori la vedano.

Come si installa Potato?

Installalo da PyPI con pip install potato-annotation, su Python 3.7 o versione superiore. Installarlo in un ambiente virtuale tiene le dipendenze di Potato separate dal Python di sistema, e potato --version conferma l'installazione stampando il numero di versione.

Si può eseguire Potato in Docker?

Sì. Potato pubblica un'immagine precompilata, ghcr.io/davidjurgens/potato, su GitHub Container Registry. La cartella del tuo progetto viene montata nel container in /app e il server resta in ascolto sulla porta 7860 al suo interno, quindi una sola immagine serve per ogni task. Imposta POTATO_SECRET_KEY perché le sessioni degli annotatori sopravvivano a un riavvio. Mettere online Potato su un server riporta il comando docker run completo.

Come si controlla una configurazione di Potato prima che la vedano gli annotatori?

Esegui potato validate config.yaml --strict, che controlla la configurazione come fa il server all'avvio e trasforma gli avvisi, per esempio una chiave non riconosciuta, in errori. potato preview config.yaml mostra poi ciò che la configurazione dichiara e visualizza l'interfaccia in un browser, così vedi il task come lo vedrà un annotatore prima che chiunque effettui l'accesso.

Cosa c'è dopo?

Strumenti e utilità

Quando hai preso confidenza con le basi, consulta questi strumenti utili: