Skip to content

Distribuire Potato su uno Space di Hugging Face

Esegui un task Potato in uno Space Docker di Hugging Face con potato deploy, con il backup delle annotazioni su un dataset privato ogni cinque minuti.

potato deploy up --provider huggingface esegue un task di annotazione in uno Space Docker di Hugging Face, con HTTPS su un indirizzo hf.space e nulla da configurare su un server. È adatto a una demo pubblica di un task e a un laboratorio i cui dati e modelli sono già sull'Hugging Face Hub. Il disco di uno Space viene cancellato a ogni riavvio, quindi Potato conserva le annotazioni in un dataset privato di Hugging Face che crea insieme allo Space. Esegue il backup delle annotazioni sul dataset ogni cinque minuti e le ripristina all'avvio dello Space. Questa pagina richiede Potato 2.10 o successivo e una configurazione che hai già eseguito con potato start.

Requisiti e limiti di uno Space

Gli Space di Potato sono Space Docker, e per creare uno Space Docker serve un piano Hugging Face a pagamento: PRO per un account personale, Team o Enterprise per un'organizzazione. Un account o un'organizzazione con il piano gratuito di Hugging Face esegue inoltre al massimo tre Space alla volta. Un quarto resta PAUSED e, a differenza di uno Space in sospensione, uno Space in pausa non si risveglia mai quando un visitatore lo apre.

Per uno studio che dura settimane con annotatori nominativi, una macchina virtuale come AWS Lightsail, Jetstream2 o Hetzner mantiene il disco tra un riavvio e l'altro, quindi i dati non dipendono da un backup. Uno Space è la scelta migliore quando le persone che vuoi raggiungere hanno già un account Hugging Face, o quando il task è una dimostrazione di cui puoi permetterti di perdere le annotazioni.

Configurare un token Hugging Face

Potato crea lo Space e il dataset con il tuo token Hugging Face. Crea un token con accesso in scrittura nelle impostazioni di Hugging Face, poi installa l'extra Hugging Face e metti il token nel tuo ambiente:

bash
pip install 'potato-annotation[huggingface]'
export HF_TOKEN=hf_...
potato deploy providers --verify

providers --verify stampa l'account a cui appartiene il token. Potato passa il token allo Space come secret dello Space, così il backup può scrivere sul dataset, e non lo inserisce mai in un commit nel repository dello Space.

Decidere chi può accedere

potato deploy non modifica le tue impostazioni di accesso, e uno Space pubblico può essere aperto da chiunque ne conosca l'indirizzo. Se la configurazione permette a chiunque di registrarsi, l'esecuzione di prova qui sotto segnala l'avviso D003, "Anyone who finds the URL can register and annotate." (Chiunque trovi l'URL può registrarsi e annotare.) Di solito la registrazione aperta va bene per una demo. Per annotatori nominativi, elencali sotto user_config.users con allow_all_users: false (Gestione delle password), oppure falli accedere con il loro account Hugging Face, che Potato supporta come provider integrato sotto authentication.providers (Autenticazione SSO e OAuth).

Controllare il piano e distribuire

Un'esecuzione di prova non crea nulla e stampa ciò che il deploy creerebbe:

bash
potato deploy up myproject/config.yaml --provider huggingface --dry-run

Il piano crea il dataset privato <account>/<name>-annotations, poi uno Space Docker <account>/<name>, imposta la chiave di sessione, la chiave di amministrazione e il token come secret dello Space e carica il tuo progetto con un Dockerfile e un README. Il Dockerfile parte dall'immagine Potato pubblicata per la versione che hai installato, quindi lo Space contiene solo i file del tuo progetto. --owner distribuisce sotto un'organizzazione, --private rende privato lo Space stesso e --name sostituisce il nome ricavato dal task.

Esegui il comando senza --dry-run e conferma il piano:

bash
potato deploy up myproject/config.yaml --provider huggingface

Il deploy attende che lo Space sia in esecuzione e stampa il suo indirizzo, https://<account>-<name>.hf.space, e il percorso del file della chiave di amministrazione, .potato/secrets.json accanto alla tua configurazione. La chiave di amministrazione apre la dashboard di amministrazione su /admin. Uno Space su hardware gratuito va in sospensione dopo 48 ore senza visitatori e si risveglia quando qualcuno lo apre, e ogni volta le annotazioni tornano dal dataset.

Chiudere lo studio

potato deploy pull scarica il dataset di backup, che contiene tutto ciò che lo Space ha salvato, invece di leggere lo Space stesso:

bash
potato deploy pull myproject/config.yaml
potato deploy destroy myproject/config.yaml

destroy elimina lo Space e lascia il dataset al suo posto, perché l'eliminazione di uno Space si annulla con un nuovo deploy, mentre quella delle annotazioni no. Quando il dataset non ti serve più, eliminalo dalla sua pagina delle impostazioni sull'Hub.

Distribuire senza backup

--demo distribuisce lo Space senza dataset, per una dimostrazione le cui annotazioni non contano. L'esecuzione di prova avvisa allora che tutto ciò che viene raccolto andrà perso al riavvio successivo. Senza dataset, pull legge lo Space in esecuzione tramite l'export di amministrazione, che funziona solo finché lo Space è attivo.

Risoluzione dei problemi

Un errore di pagamento alla creazione significa che l'account o l'organizzazione non ha un piano a pagamento. Gli Space Docker richiedono PRO per un account personale, oppure Team o Enterprise per un'organizzazione.

Lo Space è PAUSED quando un account con il piano gratuito esegue già tre Space. Metti in pausa un altro Space, poi riavvia questo dalla sua pagina delle impostazioni. Riavviare uno Space esistente non richiede un piano a pagamento.

Mancano annotazioni dopo una ricostruzione quando lo Space non è riuscito a ripristinarle dal dataset. Il log dello Space mostra una riga RESTORED quando il ripristino riesce, e la sua assenza di solito significa che il secret dello Space HF_TOKEN manca o non ha accesso in scrittura.

BUILD_ERROR è spiegato nel log di build su https://huggingface.co/spaces/<account>/<name>?logs=build.

Approfondimenti