Hugging Face Spaces

Hugging Face Spaces hébergent des applications de machine learning. Il en existe plus de 1 million aujourd'hui ; chaque Space est un dépôt git. Cette compétence couvre la création, la construction, le débogage et la maintenance de ces applications.

0. Se préparer

Avant toute chose :

1. Vérifiez que la CLI hf est installée : which hf. Sinon, pip install -U huggingface_hub.
2. Vérifiez que l'utilisateur est connecté : hf auth whoami. Sinon, demandez-lui d'exécuter ! hf auth login dans cette session — il aura besoin d'un token avec droits d'écriture depuis https://huggingface.co/settings/tokens.
3. Notez les drapeaux canPay et isPro de whoami — ils contrôlent les choix de hardware ci-dessous.

La compétence hf-cli enseigne à un agent chaque commande hf et est le compagnon recommandé de celle-ci. Installez-la avec hf skills add hf-cli (ajoutez --claude --global pour installer aussi pour Claude Code, au niveau utilisateur).

1. Ce qu'est un Space

Un Space est un dépôt git avec trois SDK possibles :

• Gradio — la plupart des Spaces. Python, itération rapide, supporte ZeroGPU.
• Docker — conteneur arbitraire. À utiliser quand vous avez besoin d'une pile non-Python ou d'un template pré-construit (Streamlit, Argilla, Shiny, etc. — liste complète sur https://huggingface.co/docs/hub/spaces-sdks-docker). Ne supporte pas ZeroGPU.
• Static — HTML pur, ou un projet React/Svelte/Vue compilé au déploiement. À utiliser pour le ML côté navigateur (transformers.js / WebGPU / WebAssembly / onnxruntime-web), les pages de projet, les rapports interactifs, ou les Spaces qui orchestrent d'autres Spaces. Aucun hardware nécessaire.

Niveaux de hardware

Gratuit, aucun coût pour le créateur : cpu-basic et zero-a10g (ZeroGPU). Les Spaces Static sont aussi gratuits et n'ont pas besoin de hardware.

cpu-basic — 2 vCPU / 16 GB. Pour la visualisation de données, les Spaces proxy API, les petits modèles limités par CPU.

ZeroGPU (zero-a10g) — allocation GPU dynamique par requête sur NVIDIA RTX PRO 6000 Blackwell (sm_120). Deux tailles : large (demi MIG, 48 GB, 1× quota) et xlarge (complet, 96 GB, 2× quota). Gratuit pour le créateur du Space ; les visiteurs consomment leur propre quota quotidien (~5 min gratuit / 40 min Pro / 60 min Enterprise). Gradio uniquement, PyTorch en priorité. Requiert que le créateur soit sur un plan PRO / Team / Enterprise.

GPU dédié (T4, L4, A10G, L40S, A100, H200) — facturé au créateur du Space à l'heure. Liste + tarifs : hf spaces hardware. Seul le créateur peut les attacher, et seulement si canPay=True. À utiliser quand ZeroGPU ne convient vraiment pas — modèle principal non-PyTorch avec initialisation lourde, inférence très long contexte sur grand modèle, etc.

Si un utilisateur non-PRO a un cas d'usage qui nécessite ZeroGPU, vous pouvez toujours le construire : créez un Space cpu-basic, codez l'app pour ZeroGPU, poussez-la, puis demandez une subvention communautaire. Voir references/grants.md.

Pour la référence officielle : https://huggingface.co/docs/hub/spaces-overview

2. Chercher une démo existante d'abord

Avant de décider comment construire quoi que ce soit, cherchez des réalisations antérieures :

hf spaces search "<nom du modèle ou tâche>" --sdk gradio --limit 10

Si quelqu'un a construit un Space similaire, lisez son app.py et requirements.txt — cela vous donne le pattern fonctionnel. Économise beaucoup d'itération à l'aveugle. Mentionnez à l'utilisateur ce que vous avez trouvé avant de vous engager dans une approche.

3. Décider du SDK et du hardware

Respectez d'abord la demande explicite de l'utilisateur. S'il a été vague :

• Par défaut pour une démo ML publique : Gradio + ZeroGPU. Utilisez ceci sauf si quelque chose ci-dessous s'applique.
• Le seul chemin d'inférence du modèle est non-PyTorch (ONNX / TF / JAX / vLLM comme le modèle PRINCIPAL, avec initialisation lourde) : GPU dédié.
  • Mais : les outils non-torch marginaux (un petit préprocesseur ONNX, un utilitaire TF) dans un pipeline torch-main vont bien sur ZeroGPU. Le hijack ne patche que torch ; initialisez la lib non-torch dans @spaces.GPU et payez le court coût d'initialisation par appel.
• Modèle minuscule / limité par CPU, ou Space proxy API : cpu-basic (gratuit hardware ne s'applique pas à Gradio).
• ML côté navigateur ou page de projet : Static.
• Conteneur avec pile non-Python : Docker.

Sourcer le modèle

• Dépôt GitHub — clonez localement pour lire la structure. S'il a déjà une démo Gradio, le chemin minimal viable est de l'adapter sur ZeroGPU (voir references/zerogpu.md). Sinon : lisez le README + le code d'inférence, privilégiez le chemin PyTorch, estimez la VRAM (bf16 ≈ params_B × 2 GB ; 48 GB tient ≤24B params en bf16, ou beaucoup plus avec quantification — voir references/zerogpu.md pour la quantification sur ZeroGPU).
• Dépôt de modèle HF — lisez son README, suivez tout GitHub lié.
• Paper / blog post — cherchez une implémentation officielle ou non-officielle. Ne réimplémentez pas sauf si c'est trivial ou si l'utilisateur le demande explicitement.
• Demande vague — cherchez d'abord dans Spaces ; présentez les résultats.

Si le modèle ne rentre vraiment pas, vérifiez les Inference Providers comme alternative : voir references/inference-providers.md. Cela évite d'héberger le modèle du tout.

4. Créer le Space

hf repos create <namespace>/<name> --type space --space-sdk <gradio|docker|static> \
    [--flavor zero-a10g|cpu-basic|<paid-flavor>] \
    [--secrets KEY=val] [--env KEY=val] \
    --public|--private|--protected \
    --exist-ok

• --space-sdk est obligatoire.
• --flavor sélectionne le hardware. zero-a10g est l'identifiant (legacy) pour ZeroGPU. Omettez pour cpu-basic. Exécutez hf spaces hardware pour la liste payante complète et les tarifs.
• Visibilité : --public (tout le monde peut voir), --private (vous seul), --protected (l'app est accessible mais le dépôt git / onglet Files est privé).
• --secrets KEY=val devient une variable d'environnement dans le Space et n'est pas visible aux visiteurs. À utiliser pour les clés API, les tokens de dépôt gated (HF_TOKEN=hf_…), etc. Peut aussi être défini plus tard via hf spaces secrets set <id> KEY=val.
• --env KEY=val est visible aux visiteurs — utilisez uniquement pour la configuration non-sensible (GRADIO_SSR_MODE=false, PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True, etc.).

Note : hardware: dans le YAML du README est silencieusement ignoré — le hardware ne se configure que via --flavor à la création, ou plus tard via hf spaces settings <id> --hardware <name>.

5. Construire l'app

Le Space existe maintenant sur https://huggingface.co/spaces/<namespace>/<name> mais il est vide.

README.md frontmatter

Toujours requis :

---
title: ...
emoji: 🚀                # choisissez quelque chose de représentatif
colorFrom: blue          # red|yellow|green|blue|indigo|purple|pink|gray (seulement ceux-ci)
colorTo: indigo
sdk: gradio              # gradio | docker | static
sdk_version: 6.15.1      # latest stable sauf si vous avez une raison*
app_file: app.py         # gradio only (docker / static utilisent Dockerfile / index.html)
short_description: ...   # ≤ 60 caractères (le serveur rejette les plus longs)
python_version: "3.12"   # ZeroGPU supporte officiellement 3.10.13 et 3.12.12
startup_duration_timeout: 30m   # par défaut ; augmentez à 1h pour les gros LLM / lourds téléchargements
---

* Raisons d'utiliser une Gradio plus ancienne : un composant personnalisé la verrouille, ou vous adaptez une démo existante et ne voulez pas réécrire pour les breaking changes 5.x→6.x. Si vous avez besoin d'une 5.x, choisissez 5.50.0 (la dernière de la série ; supporte toujours les composants personnalisés).

Toutes les options de frontmatter : https://huggingface.co/docs/hub/spaces-config-reference

App Gradio ZeroGPU minimale

import spaces           # DOIT venir avant torch / diffusers / transformers
import torch
import gradio as gr
from diffusers import DiffusionPipeline

pipe = DiffusionPipeline.from_pretrained("<repo>", torch_dtype=torch.bfloat16).to("cuda")

@spaces.GPU(duration=60)
def generate(prompt):
    return pipe(prompt).images[0]

gr.Interface(fn=generate, inputs=gr.Text(), outputs=gr.Image()).launch()

Trois règles — traitement complet dans references/zerogpu.md :

1. import spaces avant torch / tout import touchant CUDA. Il monkey-patche torch.cuda.* ; une fois que CUDA est initialisé dans le processus principal, c'est trop tard.
2. Chargez le modèle à la portée du module, .to("cuda") immédiatement. ZeroGPU intercepte l'appel, empile les poids sur disque, et les diffuse en VRAM au premier appel @spaces.GPU. Le chargement paresseux dans le décorateur coûte à chaque utilisateur.
3. Décorez la fonction que Gradio utilise. Estimez duration au pire cas réaliste (plus petit = priorité plus haute en queue et vérification de quota plus stricte). Pour un runtime dépendant de l'entrée, passez une fonction callable.

requirements.txt

Version courte :

• Ne listez PAS : gradio, spaces, huggingface_hub (préinstallés et gérés par la plateforme ; les verrouiller cause des échecs de résolution ou casse silencieusement le runtime ZeroGPU).
• Listez si vous les utilisez : torchvision, torchaudio (non préinstallés), plus tout le reste (diffusers, transformers, accelerate, sentencepiece, …).
• ZeroGPU n'accepte que torch 2.8.0, 2.9.1, 2.10.0, 2.11.0. Par défaut, laissez torch sans verrouillage (le runtime préinstalle la dernière version). Verrouillez seulement quand une dépendance le force.
• Pour les wheels d'extensions CUDA pré-compilées (flash_attn, xformers, pytorch3d, nvdiffrast, diff_gaussian_rasterization, torchmcubes) : utilisez les wheels Blackwell pré-compilées sur https://huggingface.co/datasets/multimodalart/zerogpu-blackwell-wheels/tree/main/wheels. Mapping complet + mises en garde dans references/requirements.md.

Profondeur par SDK

• Patterns Gradio (thèmes, gr.Examples, streaming, composants HTML personnalisés, gr.Server) : references/gradio.md.
• Docker : https://huggingface.co/docs/hub/spaces-sdks-docker. Exemples : hf spaces list --filter docker.
• Static : https://huggingface.co/docs/hub/spaces-sdks-static. Pour les SPA construites, définissez app_build_command: npm run build et app_file: dist/index.html dans le frontmatter.
• Spécifiques ZeroGPU (sémantique du décorateur, dimensionnement, AoTI, générateurs, concurrence, pickle / gr.State au-delà de la limite du worker) : references/zerogpu.md — lisez ceci quand le Space cible ZeroGPU.

6. Itérer sur le Space, pas localement

Essayez de construire un candidat à la sortie à partir de la quête de l'utilisateur localement et poussez-le — puis utilisez l'URL en direct comme votre boucle de test. L'environnement du Space est le seul qui compte ; n'essayez pas de tester localement. python3 -m py_compile app.py est le maximum d'vérification locale qui vaut la peine d'être faite avant de pousser.

Une fois poussé, choisissez le mécanisme de mise à jour le moins cher pour chaque changement — rechargement à chaud pour les édits Python pur, hf upload pour les fichiers que le rechargement à chaud ne peut pas toucher, reconstruction complète seulement quand requirements.txt / Dockerfile / le frontmatter du README ont vraiment changé. Échelle complète + pièges (empoisonnement du rechargement à chaud usine redémarrage complet, lag runtime.sha, etc.) dans references/debugging.md.

7. Vérifier

Ne faites pas confiance à RUNNING seul — l'app peut être en cours d'exécution mais cassée. Quatre étapes, dans l'ordre :

A. En vie ? Étape + hardware :

hf spaces info <ns>/<name> --expand runtime

B. Logs propres après le démarrage ? Lisez le log d'exécution pour confirmer que le démarrage s'est terminé sans avertissements ou fallbacks silencieux :

hf spaces logs <ns>/<name> --tail 200

Cherchez l'achèvement du chargement du modèle, aucun avertissement d'import, aucun message "falling back to CPU" / downgrade dtype, aucun RUNNING masquant une app à moitié cassée.

C. L'API répond réellement. Avec les logs toujours en queue dans un autre terminal (hf spaces logs <ns>/<name> --follow), appelez le endpoint :

from gradio_client import Client, handle_file
import os
c = Client("<ns>/<name>", token=os.environ["HF_TOKEN"], httpx_kwargs={"timeout": 600})
print(c.view_api())                    # découvrez les endpoints — ne devinez pas
result = c.predict(..., api_name="/generate")

D. Renichez la sortie ET les logs. HTTP 200 ≠ sortie correcte. Vérifiez les deux :

head = open(result, "rb").read(16)
# glTF / \x89PNG / RIFF…WEBP / RIFF…WAVE / [4:8]==b"ftyp" → png/jpg/webp/wav/mp4

Et regardez le log d'exécution émis pendant l'appel — les fallbacks silencieux (modèle changeant de taille, dépendance optionnelle manquante, downgrade dtype) ne s'affichent que là.

Patterns de smoke-test complets (endpoints streaming, Spaces gated OAuth, routes personnalisées gr.Server) : references/debugging.md.

8. Stockage permanent (buckets)

Les Spaces sont sans état — /data est effacé au redémarrage. Si le Space doit persister les uploads utilisateur, les générations, les logs, ou interagir avec un magasin long-terme, montez un bucket :

hf buckets create <ns>/<bucket-name>                                          # --private optionnel
hf spaces volumes set <ns>/<space> -v hf://buckets/<ns>/<bucket-name>:/data   # lecture-écriture sur /data

Les buckets sont du stockage payant ; vérifiez canPay et confirmez avec l'utilisateur. Patterns complets (lecture rapide / écriture durable, URLs de bucket public, anti-pattern model-cache) : references/buckets.md.

9. Quand les choses cassent

Ordre des opérations :

1. Lisez les logs : hf spaces logs <id> --build --follow (erreur de construction) ou hf spaces logs <id> --follow (erreur d'exécution). Trouvez la première erreur, pas la dernière.
2. Grep references/known-errors.md pour la chaîne d'erreur. Vérifiez si c'est un problème connu avant d'essayer votre propre correction — la plupart des erreurs courantes ZeroGPU / Gradio / dépendances ont un correctif de 1–2 lignes là.
3. Itérez en utilisant l'échelon le moins cher de references/debugging.md. La grande majorité des problèmes se résout avec la lecture des logs + des boucles de smoke-test ; le mode dev interactif + SSH est un dernier recours brutal.

Si vous résolvez une erreur qui n'était pas dans la liste known-errors, suggérez à l'utilisateur de la PR vers cette compétence pour que les futures exécutions en bénéficient.

Index de référence