Sviluppo locale

Installa ed esegui Potato in locale per sviluppo e test. Copre l'installazione con pip, la configurazione, l'avvio del server e la risoluzione dei problemi di avvio più comuni.

Metti in funzione Potato sulla tua macchina locale per lo sviluppo e il testing.

Prerequisiti

Python 3.9 o superiore
Gestore di pacchetti pip
Git (opzionale, per clonare esempi)

Installazione

Con pip (consigliato)

bash

pip install potato-annotation

Dal sorgente

bash

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

Con dipendenze opzionali

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

Metti l'extra tra virgolette, così la shell non interpreta le parentesi quadre come un pattern glob. all esclude di proposito vision, perché quel gruppo installa torch e nulla nell'uso predefinito ne ha bisogno.

Avvio rapido

1. Crea un file di configurazione

Crea 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 è la radice rispetto a cui si risolvono tutti gli altri percorsi relativi, e Potato si rifiuta di leggere al di fuori di essa. Impostarla su . tiene la configurazione, il file di dati e la directory di output in un'unica cartella, ed è questo che permette di spostare il progetto su un server in seguito.

2. Prepara dati di esempio

Crea 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. Avvia il server

bash

potato start config.yaml

4. Accedi all'interfaccia

Apri il tuo browser su http://localhost:8000

Modalità di sviluppo

Modalità debug

La modalità debug attiva i log dettagliati, disattiva il timeout di inattività della sessione e apre le pagine di amministrazione senza chiave per le richieste che arrivano dalla tua macchina. La pagina di login resta, e --debug-phase (più sotto) la salta:

bash

potato start config.yaml --debug

Non attivare mai la modalità debug su un server in produzione. Un tunnel o un reverse proxy sulla stessa macchina che non aggiunge alcuna intestazione di inoltro fa sembrare locale ogni chiamante, e --debug-phase fa entrare ogni visitatore come lo stesso debug_user. Le versioni di Potato dalla 2.8.2 alla 2.11.0 si rifiutano di avviarsi in modalità debug sull'indirizzo predefinito 0.0.0.0, quindi con quelle versioni aggiungi --host 127.0.0.1.

Log di debug

Scegli quale parte dell'applicazione produce i log:

bash

potato start config.yaml --debug-log server

I valori accettati sono all, ui, server e none. Usa ui quando la pagina di annotazione si comporta in modo anomalo e server quando un elemento non si carica.

Output dettagliato

Visualizza tutta l'attività del server:

bash

potato start config.yaml --verbose

Saltare a una fase

Con --debug attivo, salta il login e passa direttamente alla fase su cui stai lavorando invece di ripercorrere consenso e istruzioni a ogni riavvio:

bash

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

Struttura delle directory

Layout di progetto consigliato:

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

Sono obbligatori solo config.yaml e il file di dati. Potato include i propri template, quindi imposta site_dir e aggiungi una cartella templates/ solo quando li sostituisci, e fai puntare site_file a un file specifico con cui renderizzare la pagina di annotazione.

Testare la tua configurazione

Valida la configurazione

Controlla la configurazione come la controlla il server all'avvio, prima di sprecarci un avvio:

bash

potato validate config.yaml

Aggiungi --strict perché gli avvisi, come una chiave non riconosciuta, facciano fallire l'esecuzione invece di essere stampati e lasciarla passare.

Modalità anteprima

Mostra cosa dichiara una configurazione e renderizzala in un browser senza avviare un server completo:

bash

potato preview config.yaml

Gli screenshot richiedono l'extra per il browser headless, pip install "potato-annotation[preview]":

bash

potato preview config.yaml --screenshot preview.png

Problemi comuni

Porta già in uso

bash

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

Oppure impostala in config.yaml, e l'opzione -p la sovrascrive:

yaml

port: 8080

File di dati non trovato

Assicurati che i percorsi siano relativi alla posizione del file di configurazione:

yaml

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

I percorsi si risolvono rispetto a task_dir, e Potato si rifiuta di caricare un file al di fuori di essa, quindi sposta i dati sotto la directory del task invece di puntare a un percorso assoluto altrove sulla macchina.

Permesso negato

Controlla i permessi dei file:

bash

chmod 755 annotations/
chmod 644 data/*.json

Più utenti in locale

Per testare scenari multi-utente:

yaml

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

url_direct legge il nome utente direttamente dall'URL e non chiede alcuna password, quindi puoi aprire due profili del browser e annotare come due persone senza registrare account:

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

Reimposta le annotazioni

Potato scrive una directory per annotatore sotto output_annotation_dir, ognuna con il user_state.json di quella persona:

bash

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

Rimuovere la directory di un utente rimuove le sue assegnazioni insieme alle sue risposte, quindi una nuova esecuzione riassegna gli elementi da zero.

Variabili d'ambiente

Configura tramite l'ambiente:

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

Senza POTATO_SECRET_KEY, Potato genera una chiave di firma casuale a ogni avvio, e questo disconnette tutti a ogni riavvio.

Utilizzo con ambienti virtuali

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

Integrazione IDE

VS Code

Installa l'estensione YAML per il supporto dei file di configurazione:

json

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

Le configurazioni scaricate dal Designer di studi hanno già quello schema su una riga # yaml-language-server:, quindi vengono validate nell'editor senza questa impostazione.

PyCharm

Crea una configurazione di esecuzione:

Add → Python
Script: potato
Parametri: start config.yaml
Directory di lavoro: il percorso del tuo progetto

Prossimi passi

Basi della configurazione - Scopri tutte le opzioni di configurazione
Formati di dati - Comprendi la struttura dei dati
Configurazione di produzione - Distribuisci per uso reale