Hugging Face Spaces: cosa sono e come usarli ?

#Hugging Face Spaces: che cos'è esattamente?

Uno Space è una piccola applicazione web ospitata da Hugging Face. Tecnicamente è un repository git, come quelli dei modelli e dei dataset dell'Hub: contiene il codice dell'applicazione, un file delle dipendenze e un README la cui intestazione YAML descrive la configurazione. A ogni commit inviato a questo repository, Hugging Face ricompila e riavvia l'applicazione. Il visitatore, invece, vede solo una pagina con campi, pulsanti e un risultato.

Se stai scoprendo Hugging Face, tieni a mente la differenza con una pagina di modello: la pagina di modello contiene file (pesi, tokenizer, configurazione) che scarichi; uno Space esegue codice su un server per mostrarti cosa sa fare il modello. La guida « Hugging Face: c'est quoi, et comment s'en servir? » copre l'Hub in generale; qui si parla solo degli Spaces.

La documentazione ufficiale propone tre tipi di Spaces, chiamati SDK, da scegliere al momento della creazione:

Gradio

Il caso più frequente. Gradio è una libreria Python che genera un'interfaccia web a partire da una funzione: una casella di testo in input, un'immagine in output, ecc. La maggior parte delle demo di LLM e di modelli di immagini sono Spaces Gradio.

Docker

Lo Space è costruito a partire da un Dockerfile. Può quindi eseguire qualsiasi applicazione web: un'interfaccia di chat completa, un server API, uno strumento scritto in un linguaggio diverso da Python.

Static HTML

Una semplice pagina HTML, CSS e JavaScript, senza server di calcolo. Utile per una documentazione, una visualizzazione o una demo che gira interamente nel browser.

Ogni Space ha un indirizzo sull'Hub, nella forma huggingface.co/spaces/proprietario/nome, e un indirizzo diretto dell'applicazione, nella forma proprietario-nome.hf.space. Gli Space possono essere pubblici (codice e applicazione visibili a tutti), protetti (codice privato, applicazione accessibile) o privati (riservati al proprietario e ai suoi collaboratori).

#Passo 1: usare una demo nel browser

Per provare uno Space, nella maggior parte dei casi non serve nessun account. La home page degli Spaces (huggingface.co/spaces) permette di cercare per parola chiave o per task e di ordinare per tendenza o per numero di «like». Molte pagine dei modelli mostrano anche, nella colonna di destra, l'elenco degli Spaces che usano quel modello.

1. 01
   Individuare lo Space giusto

   Preferisci gli Space pubblicati dall'editore del modello (l'account ufficiale dell'organizzazione) o molto seguiti. Uno Space recente di un account sconosciuto può funzionare benissimo, ma non sai cosa fa il suo codice con i dati inviati.
2. 02
   Leggere lo stato visualizzato

   In cima alla pagina, un badge indica lo stato: in esecuzione (Running), in costruzione (Building), in sospensione (Sleeping), in pausa o in errore. Uno Space sospeso si riattiva alla visita, il che può richiedere un po' di tempo, finché l'applicazione non si riavvia.
3. 03
   Lanciare una richiesta

   Compila i campi e conferma. Su uno Space che condivide una GPU tra tutti i visitatori, prima dell'elaborazione può comparire una coda d'attesa.
4. 04
   Verificare cosa stai provando

   Apri la scheda Files per leggere il file principale (spesso app.py) e il README. Vedrai quale modello viene caricato, con quale precisione (FP16, quantizzazione a 4 bit…) e con quali parametri. Una demo non è sempre la versione completa del modello annunciato.

#Passaggio 2: chiamare uno Space Gradio tramite API

Uno Space Gradio non è solo una pagina web: espone anche un'API. Il link «Use via API», in fondo all'applicazione, mostra gli endpoint disponibili ed esempi di codice. In Python, la libreria ufficiale gradio_client permette di chiamare uno Space come una funzione, il che è comodo per provare un modello su una serie di esempi senza cliccare a mano.

pip install gradio_client

from gradio_client import Client

# Remplacez par l'identifiant du Space (propriétaire/nom)
client = Client("proprietaire/nom-du-space")

# Affiche les points d'entrée et leurs paramètres
client.view_api()

Una volta noti i parametri, il metodo client.predict() invia una richiesta con gli argomenti previsti e un api_name indicato da view_api(). Le quote e le code dello Space si applicano a queste chiamate come alle visite dal browser: non è una soluzione per elaborare grandi volumi. Per uno Space privato o per essere identificato (e sfruttare la quota ZeroGPU del tuo account), passa un token di accesso Hugging Face a Client().

#Passaggio 3: duplicare uno Space

Duplicare uno Space crea una copia completa nel tuo account. È utile per partire da una demo esistente e modificarla, oppure per avere una tua istanza senza condividere la coda con tutti i visitatori. L'operazione si esegue dal menu a tre puntini in alto a destra nella pagina, opzione «Duplicate this Space».

1. 01
   Scegliere il proprietario e il nome

   La copia può finire nel tuo account personale o in un'organizzazione in cui hai i permessi di scrittura.
2. 02
   Impostare la visibilità

   La copia è privata per impostazione predefinita. Lasciala privata se intendi elaborarci i tuoi dati.
3. 03
   Scegliere l'hardware

   Per impostazione predefinita, la copia gira su CPU Basic. Una GPU a pagamento può essere scelta in quel momento o più tardi nelle impostazioni (Settings).
4. 04
   Inserire i secret

   Le variabili pubbliche dello Space di origine vengono copiate automaticamente. I secret (token, chiavi API) non lo sono mai: l'interfaccia ti avvisa se devi fornirli. Senza di essi, l'applicazione può avviarsi e poi fallire alla prima richiesta.

Oltre il CPU Basic, l'hardware viene fatturato a ore. La documentazione indica ad esempio 0,40 $ all'ora per una NVIDIA T4 small, al 26/10/2026; il listino completo e aggiornato si trova nella pagina dei prezzi di Hugging Face. Uno Space a pagamento può essere messo in pausa dalle sue impostazioni: il tempo in pausa non viene fatturato.

#Passo 4: eseguire uno Space Hugging Face in locale

Dato che il codice di uno Space pubblico è leggibile e clonabile, puoi eseguirlo sulla tua macchina. Ci sono due metodi: scaricare l'immagine Docker creata da Hugging Face, oppure clonare il repository e avviare l'applicazione da solo.

#Metodo A: l'immagine Docker dello Space

La documentazione indica che la maggior parte degli Space si può eseguire con Docker. Il pulsante «Run with Docker», nel menu in alto a destra della pagina dello Space, mostra il comando esatto da copiare. In genere ha la forma seguente, con l'immagine ospitata sul registry registry.hf.space:

docker run -it -p 7860:7860 --platform=linux/amd64 \
  registry.hf.space/proprietaire-nom-du-space:latest python app.py

Copia sempre il comando proposto dal pulsante invece di ricostruirlo: il nome dell'immagine, il comando di avvio e le eventuali variabili (opzione -e, ad esempio per un token HF_TOKEN) dipendono dallo Space. Alcuni Space richiedono di accedere al registry con il tuo nome utente Hugging Face e un token di accesso al posto della password:

docker login registry.hf.space

Perché un container usi una scheda NVIDIA, Docker ha bisogno del NVIDIA Container Toolkit sulla macchina host, e l'opzione --gpus all va aggiunta al comando docker run. Le immagini sono compilate per l'architettura x86_64 (linux/amd64): su un Mac Apple Silicon passano per l'emulazione, senza accesso alla GPU del Mac. In questo caso, il metodo B è in genere più adatto.

#Metodo B: clonare il repository e avviare l'applicazione

Il menu dello Space propone anche «Clone repository», in HTTPS o in SSH. Per uno Space Gradio, la sequenza classica consiste nel clonare, creare un ambiente Python isolato, installare le dipendenze elencate in requirements.txt, poi avviare il file principale:

git clone https://huggingface.co/spaces/proprietaire/nom-du-space
cd nom-du-space
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install gradio
python app.py

Gradio mostra poi l'indirizzo locale dell'interfaccia, per impostazione predefinita http://127.0.0.1:7860. Alcuni punti da verificare prima dell'avvio:

Intestazione del README

Le chiavi sdk_version, app_file e a volte python_version indicano la versione di Gradio, il file da avviare e la versione di Python usate online. Installare la stessa versione di Gradio (pip install "gradio==X.Y.Z") evita molti errori di interfaccia.

File di grandi dimensioni

Uno Space può contenere file pesanti salvati tramite il sistema di archiviazione dell'Hub. Se dopo la clonazione alcuni file appaiono come piccoli puntatori di testo, installa l'estensione git consigliata da Hugging Face (git-xet o Git LFS) e rilancia il download.

Decoratore @spaces.GPU

Gli Space ZeroGPU importano il modulo spaces e decorano le loro funzioni con @spaces.GPU. La documentazione precisa che questo decoratore non ha alcun effetto al di fuori di ZeroGPU: basta installare il pacchetto spaces (pip install spaces) perché il codice venga eseguito sulla tua GPU.

Secrets

Se il codice legge variabili d'ambiente (os.getenv), definiscile nel terminale prima di avviare app.py. Un modello soggetto a condizioni di accesso richiede un token Hugging Face associato a un account che ha accettato la licenza.

Per uno Space Docker, il repository clonato contiene un Dockerfile: bastano docker build e poi docker run, pubblicando la porta dichiarata da app_port nel README (7860 per impostazione predefinita).

#Limiti degli Hugging Face Spaces: calcolo e riservatezza

Uno Space è perfetto per una prima impressione. Per un uso regolare, i suoi limiti emergono in fretta. Quelli che seguono provengono dalla documentazione ufficiale consultata il 26/10/2026.

Hardware gratuito modesto

L'hardware predefinito, CPU Basic, offre 2 vCPU, 16 GB di RAM e 50 GB di disco, senza GPU. Un LLM da diversi miliardi di parametri ci gira lentamente, quando entra in memoria.

Disco non persistente

I 50 GB di disco vengono cancellati al riavvio. I file caricati o generati non vengono conservati, salvo uno storage persistente configurato dal proprietario.

Sospensione

Sull'hardware gratuito, uno Space inutilizzato va in sospensione dopo un certo tempo e deve riavviarsi alla visita successiva. Il proprietario può anche metterlo in pausa, o addirittura eliminarlo: una demo disponibile oggi può sparire domani.

Quote ZeroGPU

Il tempo GPU giornaliero è limitato per account (vedi sopra) e una richiesta è limitata per impostazione predefinita a 60 secondi di GPU, salvo una durata più lunga fissata dall'autore. La quota si azzera 24 ore dopo il primo utilizzo.

Rete limitata

Uno Space può comunicare verso l'esterno solo tramite le porte 80, 443 e 8080. Un'applicazione che deve raggiungere un servizio su un'altra porta non funzionerà così com'è.

Sul fronte della riservatezza, la regola è semplice: tutto ciò che inserisci in uno Space viene inviato a un server che esegue il codice di qualcun altro. Questo codice può registrare le richieste, trasmetterle a un'API di terze parti o conservare i file caricati per la durata della sessione. Su uno Space pubblico puoi verificarlo leggendo app.py; su uno Space protetto il codice non è visibile. Quindi non incollare in una demo documenti dei clienti, dati personali, codice proprietario o credenziali.

#Quando preferire l'esecuzione locale

La cosa giusta da fare è usare gli Spaces per decidere, poi passare al locale per lavorare. Alcune situazioni in cui il locale vince nettamente:

Dati sensibili

Contratti, cartelle cliniche, codice aziendale: con un modello locale, nulla lascia il tuo computer.

Uso quotidiano o su grandi volumi

Le quote ZeroGPU e le code di attesa rendono uno Space inadatto a un uso intensivo. In locale, l'unico limite è il tuo hardware.

Esigenza di stabilità

Uno Space può cambiare modello, versione o scomparire. Un modello scaricato e congelato dà risultati riproducibili.

Integrazione nei tuoi strumenti

Ollama espone un'API locale su http://localhost:11434, utilizzabile da Open WebUI, script o automazioni, senza dipendere da un servizio remoto.

Per un LLM, del resto, il passaggio al locale non avviene necessariamente clonando lo Space. Molte demo caricano il modello completo in formato safetensors, in FP16: i pesi di un modello 7B occupano quindi circa 14 GB, oltre la capacità della maggior parte delle schede consumer. La versione quantizzata dello stesso modello in formato GGUF, in Q4_K_M, richiede circa 5 GB di VRAM e gira su una RTX 3060 da 12 GB. Spesso la cosa più semplice è annotare il nome del modello usato dallo Space, poi cercarne la versione GGUF sull'Hub e importarla in Ollama.

3B in Q4

circa 2 GB di VRAM

7B in Q4

circa 5 GB

14B in Q4

circa 9 GB (RTX 4070 12 GB)

32B in Q4

circa 19 GB (RTX 4090 24 GB o Mac M4 Pro con 24-48 GB di memoria unificata)

70B in Q4

circa 40 GB

#Risoluzione dei problemi

«Runtime error» sulla pagina

Lo Space si è bloccato all'avvio. La scheda Logs, quando è accessibile, mostra la causa. Se è lo Space di qualcun altro, puoi solo aspettare, cercare un altro Space o segnalare il problema nella scheda Community.

Messaggio di quota GPU superata

La tua quota ZeroGPU giornaliera è esaurita. Accedi se non l'hai ancora fatto, attendi il reset o esegui il modello in locale.

Errore di import après pip install

La versione di Gradio o di una dipendenza è diversa da quella dello Space. Allineati a sdk_version e python_version del README, in un ambiente virtuale nuovo.

CUDA non trovato in locale

Il codice si aspetta una GPU NVIDIA. Verifica che PyTorch sia stato installato con il supporto CUDA, oppure adatta il codice per usare la CPU (o mps su Mac), a costo di un'esecuzione più lenta.

Immagine Docker rifiutata o non trovata

Accedi al registry con docker login registry.hf.space, poi verifica che il nome dell'immagine corrisponda a quello indicato dal pulsante «Run with Docker».

#Per approfondire

Questa guida riguarda gli Space. Per capire l'Hub nel suo insieme, distinguere i formati dei file o passare da una demo a un modello che gira sul tuo computer, queste guide ti accompagnano oltre.