Mettere online il tuo studio Potato

Per mettere online uno studio Potato, esegui il tuo task su un computer che i tuoi annotatori possono raggiungere tramite un indirizzo web, metti al sicuro le annotazioni mentre lo studio è in corso e scarichi le annotazioni alla fine. Rivolgersi al team IT della tua istituzione e cliccare un pulsante di deploy preparato da un collega sono i due percorsi che non richiedono alcun terminale da parte tua.

Distribuire uno studio significa spostare il task Potato che hai costruito dal tuo computer a un server, un computer che resta acceso e connesso a internet. Gli annotatori aprono poi il task in un browser da qualsiasi luogo, e Potato salva ogni risposta sul server mentre gli annotatori lavorano. L'anteprima dello Study Designer esegue Potato dentro il tuo browser, e nessun altro può raggiungere quella copia. Uno studio costruito nel Designer ha comunque bisogno di uno dei percorsi qui sotto.

Ogni percorso parte dalla stessa cartella del progetto. Nello Study Designer, il pulsante Download project (.zip) salva config.yaml (il file che descrive il tuo task), un file di dati di esempio e un README. Il file di esempio contiene tre item segnaposto. Sostituisci il file di esempio con i tuoi item prima del deploy, nel formato descritto in Formati di Dati.

Scegliere un percorso

I percorsi differiscono per chi svolge il lavoro tecnico, per quanto costa il server e per quanto a lungo lo studio può restare online. I costi qui sotto vengono dai listini degli host e dalle stime di Potato al 2026-11-04, e le attese sono indicazioni approssimative, non misurazioni:

Se non sei sicuro, comincia dal tuo team IT. Un server dentro la tua istituzione mantiene i dati su apparecchiature che l'istituzione già gestisce, e il team IT può occuparsi degli aggiornamenti di sicurezza e dei backup.

Rivolgersi al team IT o di calcolo per la ricerca

Molte università e molti ospedali hanno un servizio di calcolo per la ricerca che ospita applicazioni web per gli studi. Per un team di questo tipo, Potato è una normale applicazione web, e il team può partire da un riepilogo di una pagina di ciò di cui Potato ha bisogno.

1. Scarica il progetto dallo Study Designer e sostituisci il file di dati di esempio con i tuoi item.
2. Invia al tuo team IT la cartella del progetto e un link a Requisiti del server Potato per il tuo team IT.
3. Dì al team chi sono i tuoi annotatori, quanti parteciperanno e quanto dura lo studio.
4. Indica come gli annotatori devono accedere. I colleghi con account istituzionali possono usare il single sign-on, l'accesso che la tua istituzione già gestisce, e gli annotatori esterni possono usare i nomi utente che elenchi.
5. Indica se gli item o le risposte contengono informazioni personali o sensibili, e nomina l'approvazione etica con cui si svolge lo studio.
6. Chiedi al team l'indirizzo web dello studio, la chiave di amministrazione che apre la dashboard di amministrazione di Potato e un piano per i backup e per consegnarti i dati quando lo studio finisce.

Quando arriva l'indirizzo, segui Prima di invitare gli annotatori prima di inviare l'indirizzo a chiunque.

Cliccare un pulsante di deploy preparato da un collega

Un pulsante di deploy è un link sulla pagina di un repository di codice che configura una copia di un task Potato sui server di un'azienda di hosting, interamente tramite moduli nel tuo browser. Un collega che usa git e un terminale crea il pulsante una sola volta, da un repository che contiene la cartella del tuo progetto, con il comando potato deploy button. Eseguire Potato in locale o nel cloud è la pagina da inviare a quel collega.

Il pulsante funziona con tre host, che applicano costi diversi:

• Render esegue lo studio su un piano gratuito senza metodo di pagamento. Un servizio Render gratuito va in sospensione dopo 15 minuti senza visitatori e impiega circa un minuto a riattivarsi quando arriva il prossimo annotatore.
• Heroku addebita $7 al mese per il server che il pulsante crea. Heroku richiede un account verificato, di solito tramite una carta di credito, prima che tu possa creare un'app.
• AWS esegue un server Lightsail a $12 al mese. Il pulsante AWS legge il task da un repository pubblico, quindi il pulsante AWS è adatto solo a item che possono essere pubblici.

Render e Heroku cancellano il disco del server ogni volta che il server si riavvia. Il pulsante copia quindi le annotazioni ogni cinque minuti su un dataset privato di Hugging Face, un sito per condividere dati e modelli, e ricopia le annotazioni ogni volta che il server parte. Dai tu il nome a quel dataset quando clicchi, e il dataset appartiene al tuo account.

Prima di cliccare, prepara tre cose:

• un account sull'host, Render o Heroku;
• un account Hugging Face gratuito, con un token di accesso che abbia il permesso di scrittura, creato su huggingface.co/settings/tokens; e
• l'accesso al repository, se il repository è privato. Heroku ti chiede di collegare il tuo account GitHub per un repository privato.

Poi fai il deploy:

1. Clicca il pulsante nel README del repository e accedi all'host.
2. Dai un nome all'app. Il nome diventa parte dell'indirizzo web dello studio.
3. In POTATO_BACKUP_HF_REPO, scrivi un nome di dataset composto dal tuo nome utente Hugging Face e da un nome per lo studio, come your-username/my-study-annotations. Quando il nome è nuovo, Potato crea il dataset e lo rende privato.
4. Incolla il tuo token Hugging Face in HF_TOKEN. Lascia ogni altro campo al valore che il pulsante ha inserito.
5. Avvia il deploy e attendi che l'host segnali che l'app è in esecuzione. Apri l'indirizzo web che l'host mostra.
6. Trova la chiave di amministrazione, una password che l'host ha generato durante il deploy. Su Heroku la chiave è la voce POTATO_ADMIN_API_KEY nella scheda Settings dell'app, e su Render la stessa voce si trova nella pagina Environment del servizio.
7. Apri l'indirizzo dello studio con /admin aggiunto alla fine e incolla la chiave di amministrazione per aprire la dashboard di amministrazione.

Il repository fissa il task, gli item e l'elenco degli annotatori. Completa il task prima di cliccare, perché qualsiasi modifica successiva passa dal collega che ha creato il pulsante. Mantieni il repository privato a meno che gli item possano essere pubblici.

Condividere un link dal tuo computer

Il tuo computer può servire un pilota per un pomeriggio. Gli annotatori aprono un link web temporaneo, le annotazioni finiscono nella cartella del tuo progetto, e il link smette di funzionare quando chiudi il comando. Il percorso richiede un terminale, un programma in cui si digitano comandi, che è Terminal su un Mac (in Applicazioni, poi Utility) e PowerShell su Windows (cerca "PowerShell" nel menu Start).

1. Installa Python 3.9 o successivo da python.org/downloads. Su Windows, il download è il Python install manager. Su un Mac, il download è l'installer per macOS.

2. Apri il terminale e installa Potato. Su un Mac, scrivi:

   bashCopia

   python3 -m pip install potato-annotation

   Su Windows, scrivi:

   powershellCopia

   py -m pip install potato-annotation

3. Decomprimi il progetto che hai scaricato dallo Study Designer. Su un Mac, fai doppio clic sul file .zip. Su Windows, fai clic con il tasto destro sul file e scegli Extract All. Sostituisci il file di dati di esempio con i tuoi item.

4. Sposta il terminale nella cartella del progetto e avvia Potato. Il nome della cartella qui sotto è un esempio, quindi usa il nome della tua cartella. Su un Mac:

   bashCopia

   cd ~/Downloads/my-task
   python3 -m potato start config.yaml

   Su Windows:

   powershellCopia

   cd $HOME\Downloads\my-task
   py -m potato start config.yaml

5. Apri http://localhost:8000 nel tuo browser. Solo il tuo computer può raggiungere quell'indirizzo. Premi Ctrl-C nel terminale per fermare Potato.

6. Per far entrare altre persone, installa cloudflared, un programma gratuito di Cloudflare che non richiede un account. Su un Mac con Homebrew, esegui brew install cloudflared. Su Windows, scarica l'installer per Windows dalla pagina dei download di Cloudflare.

7. Esegui potato share al posto di potato start:

   bashCopia

   python3 -m potato share config.yaml

   Su Windows, scrivi py -m potato share config.yaml. Potato stampa chi potrà accedere e chiede conferma prima di pubblicare qualsiasi cosa. Scrivi y, e Potato stampa un link https:// da inviare ai tuoi annotatori.

Il link funziona solo finché il comando è in esecuzione. Chiudere il terminale, mettere il computer in sospensione o cambiare rete interrompe il link, e una nuova esecuzione stampa un nuovo link. Alcune reti universitarie bloccano i link trycloudflare.com che cloudflared crea. Se un annotatore segnala un link bloccato, potato share config.yaml --backend tailscale usa invece Tailscale. Tailscale richiede un account gratuito. Se potato share segnala No tunnel backend found, Potato non ha trovato cloudflared sul tuo computer, e il messaggio elenca i comandi di installazione.

Installazione tratta gli ambienti virtuali e le funzioni opzionali, e Eseguire Potato in locale o nel cloud tratta potato share in modo più dettagliato.

Noleggiare un server con un solo comando

potato deploy up noleggia un server da un'azienda cloud, ottiene un certificato HTTPS (il lucchetto nella barra degli indirizzi del browser), carica la cartella del tuo progetto, avvia lo studio e stampa l'indirizzo web. Il comando richiede la configurazione del terminale dei passaggi da 1 a 3 qui sopra, un account presso l'azienda cloud e un token API, una chiave simile a una password che permette a un programma di agire sul tuo account. La guida di ogni host tratta l'account e il token fin dall'inizio:

Ogni host accetta gli stessi due comandi, e la guida di ciascun host indica il nome del provider e il comando di installazione per quell'host. Il primo comando mostra il piano e il costo mensile e non crea nulla, e il secondo crea il server dopo la tua conferma:

potato deploy up config.yaml --provider aws --dry-run
potato deploy up config.yaml --provider aws

Il pulsante Duplicate this Space di Hugging Face copia uno Space nel browser, ma la copia di uno Space Potato mantiene le impostazioni di backup del proprietario originale e perde i segreti dell'originale. Distribuisci invece uno Space Potato con potato deploy up --provider huggingface.

Prima di invitare gli annotatori

Segui questa lista una volta che lo studio ha un indirizzo web, qualunque percorso tu abbia seguito:

• Decidi chi può accedere. La configurazione chiusa più semplice è un elenco di nomi utente. Nello Study Designer, disattiva Allow All Users e aggiungi ogni annotatore sotto Authorized Users. Ogni annotatore elencato sceglie una password al momento della registrazione alla prima visita, e Potato rifiuta chiunque non sia nell'elenco. Invia a ogni annotatore direttamente il nome utente, perché la prima persona che registra un nome utente elencato diventa titolare di quell'account. Per gli account istituzionali, vedi Autenticazione SSO e OAuth, e per i crowdworker vedi Integrazione con il crowdsourcing. Con Allow All Users attivo, chiunque trovi l'indirizzo può creare un account. Riserva quell'impostazione alle demo pubbliche.
• Sappi dove si trovano le annotazioni. Potato salva le risposte di ogni annotatore mentre l'annotatore lavora, in un file chiamato user_state.json dentro una cartella per annotatore. Le cartelle stanno nella cartella di output che la configurazione nomina, che lo Study Designer chiama output. Sul tuo computer, quella cartella è dentro la cartella del progetto. In un deploy con pulsante, il dataset Hugging Face contiene la copia che sopravvive a un riavvio. Su un server a noleggio, potato deploy pull scarica la cartella. Su un server istituzionale, chiedi all'IT come viene fatto il backup del server.
• Prova con un secondo browser. Apri l'indirizzo dello studio in una finestra privata, che è Incognito in Chrome, Private Window in Safari e Firefox, e InPrivate in Edge. Aggiungi all'elenco un nome utente come pilot-test, registrati con quel nome e rispondi a tre item. Chiudi la finestra, accedi di nuovo e controlla che le risposte ci siano ancora. Poi apri la dashboard di amministrazione e controlla che l'annotatore di prova compaia. Prova l'indirizzo su un telefono se gli annotatori potrebbero lavorare da telefono.
• Mantieni privata la chiave di amministrazione. La chiave di amministrazione apre la dashboard di amministrazione su /admin. La dashboard mostra le risposte di ogni annotatore. Sul tuo computer, Potato salva la chiave in admin_api_key.txt nella cartella del progetto la prima volta che apri /admin.
• Scrivi l'invito. Invia a ogni annotatore l'indirizzo, il nome utente, quanto dura il task e a chi rivolgersi quando qualcosa non funziona.

Ottenere i risultati

La dashboard di amministrazione scarica i risultati sul tuo computer senza alcun terminale. Apri /admin, inserisci la chiave di amministrazione e scegli Publish Dataset. Sotto Target, scegli Local archive, imposta Data format su CSV per un foglio di calcolo e clicca Publish. Quando l'archivio è pronto, clicca Download archive.

L'archivio contiene le risposte di ogni annotatore, gli item e le etichette combinate a maggioranza. Un README nell'archivio riporta il numero di etichette e l'accordo tra gli annotatori. I nomi degli annotatori vengono sostituiti con A1, A2 e così via, a meno che tu deselezioni Anonymize annotators. Le risposte ai sondaggi restano fuori dall'archivio a meno che tu selezioni Include survey / phase responses, perché le risposte ai sondaggi possono contenere informazioni personali.

Da un terminale, python -m potato.export scrive le stesse annotazioni in una cartella, in uno qualsiasi dei formati di esportazione di Potato:

python -m potato.export --config config.yaml --format csv --output results

Su un server creato con potato deploy up, potato deploy pull config.yaml scarica tutto ciò che il server ha raccolto, database compresi.

Chiudere lo studio perché il server smetta di costare

Scarica i risultati prima di rimuovere qualsiasi cosa, e apri il download per controllare che le risposte dell'ultimo annotatore ci siano. Poi spegni il server nel modo richiesto dal percorso:

• Il tuo computer. Premi Ctrl-C nel terminale. Non è stato addebitato nulla.
• Il tuo team IT. Comunica al team che lo studio è finito, chiedi una copia della cartella di output e chiedi per quanto tempo verrà conservata la copia sul server.
• Un pulsante di deploy. Elimina l'app dalla scheda Settings dell'app su Heroku, oppure elimina il servizio dalla sua pagina Settings su Render. Il dataset Hugging Face contiene una copia completa delle annotazioni. Quando non ti serve più il backup, elimina il dataset dalla pagina delle impostazioni del dataset.
• Un server a noleggio. Esegui potato deploy pull config.yaml, controlla la cartella scaricata e poi esegui potato deploy destroy config.yaml. Potato rifiuta di distruggere un server i cui dati non sono mai stati scaricati.

Domande frequenti

Come creo un server Potato per il mio studio?

Crei un server Potato eseguendo il tuo task su un computer che i tuoi annotatori possono raggiungere tramite un indirizzo web. Il team IT della tua istituzione può eseguire il task per te, un collega può preparare un pulsante di deploy che clicchi tu, potato share può servire un pilota dal tuo portatile e potato deploy up può noleggiare un server per te. La tabella sotto Scegliere un percorso confronta i percorsi per costo e per il lavoro da terminale che ciascuno richiede.

Come installo Potato sul mio PC?

Installa Python 3.9 o successivo da python.org, poi scrivi py -m pip install potato-annotation in PowerShell su Windows, oppure python3 -m pip install potato-annotation in Terminal su un Mac. Dopo l'installazione, py -m potato start config.yaml su Windows o python3 -m potato start config.yaml su un Mac avvia un task. Installazione tratta le funzioni opzionali.

Parole usate in questa pagina

• Server. Un server è un computer che resta acceso e connesso a internet, così altre persone possono usare un programma del computer tramite un browser web.
• URL, o indirizzo web. Un URL è l'indirizzo che gli annotatori digitano o cliccano, come https://my-study.example.edu. Un dominio è la parte del nome dell'indirizzo, qui my-study.example.edu.
• HTTPS. HTTPS cifra tutto ciò che passa tra il browser dell'annotatore e il server, comprese password e risposte. I browser mostrano un lucchetto per un indirizzo HTTPS.
• Porta. Una porta è un punto di ingresso numerato di un computer. Potato resta in ascolto sulla porta 8000 a meno che la configurazione nomini un'altra porta, e l'indirizzo locale http://localhost:8000 termina con quel numero.
• Terminale. Un terminale è un programma in cui si digitano comandi, chiamato Terminal su un Mac e PowerShell su Windows.
• Chiave di amministrazione. La chiave di amministrazione è una lunga password che apre la dashboard di amministrazione di Potato.
• Token API. Un token API è una chiave simile a una password che permette a un programma, come il comando di deploy di Potato, di agire sul tuo account presso un'azienda di hosting.

Ulteriori letture

• Requisiti del server Potato per il tuo team IT, la pagina da inviare al tuo team IT
• Eseguire Potato in locale o nel cloud, per ogni host, i pulsanti di deploy e i backup
• Distribuire un server di annotazione, per scegliere un host per uno studio lungo
• Eseguire Potato in Docker, per i server che eseguono container
• Dashboard di Amministrazione, per seguire l'avanzamento mentre lo studio è in corso