Hugging Face Spaces : c'est quoi et comment s'en servir ?

#Hugging Face Spaces : c'est quoi exactement ?

Un Space est une petite application web hébergée par Hugging Face. Techniquement, c'est un dépôt git, comme ceux des modèles et des jeux de données du Hub : il contient le code de l'application, un fichier de dépendances et un README dont l'en-tête YAML décrit la configuration. À chaque commit poussé dans ce dépôt, Hugging Face reconstruit et redémarre l'application. Le visiteur, lui, ne voit qu'une page avec des champs, des boutons et un résultat.

Si vous découvrez Hugging Face, retenez la différence avec une page de modèle : la page de modèle contient des fichiers (poids, tokenizer, configuration) que vous téléchargez ; un Space exécute du code sur un serveur pour vous montrer ce que le modèle sait faire. Le guide « Hugging Face : c'est quoi, et comment s'en servir ? » couvre le Hub en général ; ici, on ne parle que des Spaces.

La documentation officielle propose trois types de Spaces, appelés SDK, à choisir à la création :

Gradio

Le cas le plus fréquent. Gradio est une bibliothèque Python qui génère une interface web à partir d'une fonction : une zone de texte en entrée, une image en sortie, etc. La plupart des démos de LLM et de modèles d'image sont des Spaces Gradio.

Docker

Le Space est construit à partir d'un Dockerfile. Il peut donc faire tourner n'importe quelle application web : une interface de chat complète, un serveur d'API, un outil écrit dans un autre langage que Python.

Static HTML

Une simple page HTML, CSS et JavaScript, sans serveur de calcul. Utile pour une documentation, une visualisation ou une démo qui tourne entièrement dans le navigateur.

Chaque Space a une adresse sur le Hub, de la forme huggingface.co/spaces/propriétaire/nom, et une adresse directe de l'application, de la forme propriétaire-nom.hf.space. Les Spaces peuvent être publics (code et application visibles par tous), protégés (code privé, application accessible) ou privés (réservés au propriétaire et à ses collaborateurs).

#Étape 1 : utiliser une démo dans le navigateur

Pour essayer un Space, aucun compte n'est nécessaire dans la plupart des cas. La page d'accueil des Spaces (huggingface.co/spaces) permet de chercher par mot-clé ou par tâche, et de trier par tendance ou par nombre de « likes ». Beaucoup de pages de modèles affichent aussi, dans la colonne de droite, la liste des Spaces qui utilisent ce modèle.

1. 01
   Repérer le bon Space

   Privilégiez les Spaces publiés par l'éditeur du modèle (le compte officiel de l'organisation) ou très suivis. Un Space récent d'un compte inconnu peut très bien fonctionner, mais vous ne savez pas ce que son code fait des données envoyées.
2. 02
   Lire l'état affiché

   En haut de la page, un badge indique l'état : en cours d'exécution (Running), en construction (Building), en sommeil (Sleeping), en pause ou en erreur. Un Space endormi se réveille à la visite, ce qui peut prendre un moment le temps que l'application redémarre.
3. 03
   Lancer une requête

   Remplissez les champs et validez. Sur un Space qui partage un GPU entre tous les visiteurs, une file d'attente peut s'afficher avant le traitement.
4. 04
   Vérifier ce que vous testez

   Ouvrez l'onglet Files pour lire le fichier principal (souvent app.py) et le README. Vous y verrez quel modèle est chargé, avec quelle précision (FP16, quantification 4 bits…) et quels paramètres. Une démo n'est pas toujours la version complète du modèle annoncé.

#Étape 2 : appeler un Space Gradio par API

Un Space Gradio n'est pas qu'une page web : il expose aussi une API. Le lien « Use via API », en bas de l'application, affiche les points d'entrée disponibles et des exemples de code. En Python, la bibliothèque officielle gradio_client permet d'appeler un Space comme une fonction, ce qui est pratique pour tester un modèle sur une série d'exemples sans cliquer à la main.

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()

Une fois les paramètres connus, la méthode client.predict() envoie une requête avec les arguments attendus et un api_name indiqué par view_api(). Les quotas et files d'attente du Space s'appliquent à ces appels comme aux visites dans le navigateur : ce n'est pas une solution pour traiter de gros volumes. Pour un Space privé ou pour être identifié (et profiter du quota ZeroGPU de votre compte), passez un jeton d'accès Hugging Face à Client().

#Étape 3 : dupliquer un Space

Dupliquer un Space crée une copie complète dans votre compte. C'est utile pour partir d'une démo existante et la modifier, ou pour disposer de votre propre instance sans partager la file d'attente avec tous les visiteurs. La manipulation se fait depuis le menu à trois points en haut à droite de la page, option « Duplicate this Space ».

1. 01
   Choisir le propriétaire et le nom

   La copie peut aller dans votre compte personnel ou dans une organisation où vous avez les droits d'écriture.
2. 02
   Régler la visibilité

   La copie est privée par défaut. Laissez-la privée si vous comptez y traiter vos propres données.
3. 03
   Choisir le matériel

   Par défaut, la copie tourne sur CPU Basic. Un GPU payant peut être choisi à ce moment ou plus tard dans les réglages (Settings).
4. 04
   Renseigner les secrets

   Les variables publiques du Space d'origine sont recopiées automatiquement. Les secrets (jetons, clés d'API) ne le sont jamais : l'interface vous avertit s'il faut les fournir. Sans eux, l'application peut démarrer puis échouer à la première requête.

Le matériel est facturé à l'heure au-delà de CPU Basic. La documentation donne par exemple 0,40 $ de l'heure pour une NVIDIA T4 small, au 26/10/2026 ; la grille complète et à jour est sur la page de tarifs de Hugging Face. Un Space payant peut être mis en pause depuis ses réglages : le temps en pause n'est pas facturé.

#Étape 4 : exécuter un Space Hugging Face en local

Puisque le code d'un Space public est lisible et clonable, vous pouvez le faire tourner sur votre propre machine. Deux méthodes existent : récupérer l'image Docker construite par Hugging Face, ou cloner le dépôt et lancer l'application vous-même.

#Méthode A : l'image Docker du Space

La documentation indique que l'on peut exécuter la plupart des Spaces avec Docker. Le bouton « Run with Docker », dans le menu en haut à droite de la page du Space, affiche la commande exacte à copier. Elle a généralement la forme suivante, avec l'image hébergée sur le registre registry.hf.space :

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

Copiez toujours la commande proposée par le bouton plutôt que de la reconstituer : le nom de l'image, la commande de démarrage et les éventuelles variables (option -e, par exemple pour un jeton HF_TOKEN) dépendent du Space. Certains Spaces exigent de se connecter au registre avec votre nom d'utilisateur Hugging Face et un jeton d'accès en guise de mot de passe :

docker login registry.hf.space

Pour qu'un conteneur utilise une carte NVIDIA, Docker a besoin du NVIDIA Container Toolkit sur la machine hôte, et l'option --gpus all doit être ajoutée à la commande docker run. Les images sont construites pour l'architecture x86_64 (linux/amd64) : sur un Mac Apple Silicon, elles passent par l'émulation, sans accès au GPU du Mac. Dans ce cas, la méthode B est en général plus adaptée.

#Méthode B : cloner le dépôt et lancer l'application

Le menu du Space propose aussi « Clone repository », en HTTPS ou en SSH. Pour un Space Gradio, la séquence classique consiste à cloner, créer un environnement Python isolé, installer les dépendances listées dans requirements.txt, puis lancer le fichier principal :

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 affiche ensuite l'adresse locale de l'interface, par défaut http://127.0.0.1:7860. Quelques points à vérifier avant de lancer :

En-tête du README

Les clés sdk_version, app_file et parfois python_version indiquent la version de Gradio, le fichier à lancer et la version de Python utilisées en ligne. Installer la même version de Gradio (pip install "gradio==X.Y.Z") évite bien des erreurs d'interface.

Fichiers volumineux

Un Space peut contenir des fichiers lourds stockés via le système de stockage du Hub. Si des fichiers apparaissent comme de petits pointeurs texte après le clonage, installez l'extension git recommandée par Hugging Face (git-xet ou Git LFS) et relancez le téléchargement.

Décorateur @spaces.GPU

Les Spaces ZeroGPU importent le module spaces et décorent leurs fonctions avec @spaces.GPU. La documentation précise que ce décorateur n'a aucun effet hors de ZeroGPU : il suffit d'installer le paquet spaces (pip install spaces) pour que le code s'exécute sur votre propre GPU.

Secrets

Si le code lit des variables d'environnement (os.getenv), définissez-les dans votre terminal avant de lancer app.py. Un modèle soumis à conditions d'accès demande un jeton Hugging Face associé à un compte qui a accepté la licence.

Pour un Space Docker, le dépôt cloné contient un Dockerfile : docker build puis docker run suffisent, en publiant le port déclaré par app_port dans le README (7860 par défaut).

#Limites des Hugging Face Spaces : calcul et confidentialité

Un Space est parfait pour une première impression. Pour un usage régulier, ses contraintes apparaissent vite. Celles qui suivent viennent de la documentation officielle consultée le 26/10/2026.

Matériel gratuit modeste

Le matériel par défaut, CPU Basic, offre 2 vCPU, 16 Go de RAM et 50 Go de disque, sans GPU. Un LLM de plusieurs milliards de paramètres y tourne lentement, quand il tient en mémoire.

Disque non persistant

Les 50 Go de disque sont effacés au redémarrage. Les fichiers déposés ou générés ne sont pas conservés, sauf stockage persistant configuré par le propriétaire.

Mise en sommeil

Sur le matériel gratuit, un Space inutilisé s'endort au bout d'un certain temps et doit redémarrer à la visite suivante. Le propriétaire peut aussi le mettre en pause, voire le supprimer : une démo disponible aujourd'hui peut disparaître demain.

Quotas ZeroGPU

Le temps GPU quotidien est limité par compte (voir plus haut) et une requête est par défaut limitée à 60 secondes de GPU, sauf durée plus longue fixée par l'auteur. Le quota se réinitialise 24 heures après la première utilisation.

Réseau restreint

Un Space ne peut sortir que par les ports 80, 443 et 8080. Une application qui doit joindre un service sur un autre port ne fonctionnera pas telle quelle.

Côté confidentialité, la règle est simple : tout ce que vous saisissez dans un Space est envoyé à un serveur qui exécute le code de quelqu'un d'autre. Ce code peut enregistrer les requêtes, les transmettre à une API tierce ou conserver les fichiers téléversés le temps de la session. Sur un Space public, vous pouvez le vérifier en lisant app.py ; sur un Space protégé, le code n'est pas visible. Ne collez donc dans une démo ni document client, ni donnée personnelle, ni code propriétaire, ni identifiant.

#Quand préférer l'exécution locale

Le bon réflexe consiste à se servir des Spaces pour décider, puis à passer en local pour travailler. Quelques situations où le local l'emporte nettement :

Données sensibles

Contrats, dossiers médicaux, code d'entreprise : avec un modèle local, rien ne quitte votre machine.

Usage quotidien ou en volume

Les quotas ZeroGPU et les files d'attente rendent un Space impropre à un usage soutenu. En local, la seule limite est votre matériel.

Besoin de stabilité

Un Space peut changer de modèle, de version ou disparaître. Un modèle téléchargé et figé donne des résultats reproductibles.

Intégration dans vos outils

Ollama expose une API locale sur http://localhost:11434, utilisable par Open WebUI, des scripts ou des automatisations, sans dépendre d'un service distant.

Pour un LLM, le passage au local ne se fait d'ailleurs pas forcément en clonant le Space. Beaucoup de démos chargent le modèle complet au format safetensors, en FP16 : les poids d'un modèle 7B occupent alors environ 14 Go, au-delà de la plupart des cartes grand public. La version quantifiée du même modèle au format GGUF, en Q4_K_M, demande environ 5 Go de VRAM et tourne sur une RTX 3060 12 Go. Le plus simple est souvent de noter le nom du modèle utilisé par le Space, puis de chercher sa version GGUF sur le Hub et de l'importer dans Ollama.

3B en Q4

environ 2 Go de VRAM

7B en Q4

environ 5 Go

14B en Q4

environ 9 Go (RTX 4070 12 Go)

32B en Q4

environ 19 Go (RTX 4090 24 Go ou Mac M4 Pro avec 24 à 48 Go de mémoire unifiée)

70B en Q4

environ 40 Go

#Dépannage

« Runtime error » sur la page

Le Space a planté au démarrage. L'onglet Logs, quand il est accessible, montre la cause. Si c'est le Space de quelqu'un d'autre, vous ne pouvez que patienter, chercher un autre Space ou signaler le problème dans l'onglet Community.

Message de quota GPU dépassé

Votre quota ZeroGPU du jour est épuisé. Connectez-vous si ce n'est pas fait, attendez la réinitialisation ou exécutez le modèle en local.

Erreur d'import après pip install

La version de Gradio ou d'une dépendance diffère de celle du Space. Alignez-vous sur sdk_version et python_version du README, dans un environnement virtuel neuf.

CUDA introuvable en local

Le code attend un GPU NVIDIA. Vérifiez que PyTorch a été installé avec la prise en charge CUDA, ou adaptez le code pour utiliser le CPU (ou mps sur Mac), au prix d'une exécution plus lente.

Image Docker refusée ou introuvable

Connectez-vous au registre avec docker login registry.hf.space, puis vérifiez que le nom de l'image correspond à celui donné par le bouton « Run with Docker ».

#Pour aller plus loin

Ce guide couvre les Spaces. Pour comprendre le Hub dans son ensemble, distinguer les formats de fichiers ou passer d'une démo à un modèle qui tourne chez vous, ces guides prennent le relais.