Module 9 — Publication sur un espace Hugging Face

Une démonstration qui vit sur votre poste ne survit pas à sa fermeture. Une démonstration qui vit sur un lien gradio.live ne dépasse pas 72 heures. Pour une démonstration publique, stable, avec une URL propre, une histoire git et un matériel adapté, l'écosystème naturel est Hugging Face Spaces : un service qui héberge gratuitement des démonstrations Gradio, Streamlit ou statiques, avec une intégration native de la bibliothèque gradio. Ce module décrit tout le circuit, de la création à la mise en veille.

Ce qu'est un Space

Un espace Hugging Face est un dépôt git particulier, hébergé sur huggingface.co, dont le contenu est déployé automatiquement sur une URL du type https://huggingface.co/spaces/votre_pseudo/nom_de_l_espace. Le déploiement est déclenché à chaque git push : la plateforme lit le fichier README.md, y trouve le SDK à utiliser (Gradio, Streamlit, Docker, statique), installe les dépendances de requirements.txt, puis exécute app.py. En cinq minutes en moyenne, votre démonstration est en ligne.

Le matériel par défaut est un CPU avec 16 Gio de RAM, gratuit et illimité en durée, mais avec des restrictions : mise en veille au bout de 48 heures d'inactivité, redémarrage lent, pas de GPU. Pour tout ce qui exige un GPU (modèles de langage locaux, diffusion d'images, modèles audio lourds), il faut passer à un matériel payant, décrit plus bas.

Créer l'espace en trois clics

Depuis la page d'accueil de Hugging Face, la création d'un espace se fait via New Space. Trois choix comptent. Le propriétaire (votre compte ou une organisation à laquelle vous appartenez). Le nom (qui devient l'URL, donc court, sans espace, sans caractère spécial : assistant-fr-demo plutôt que Assistant Français Démonstration V2 Final). Le SDK (choisir « Gradio »). Le formulaire propose aussi le matériel, la licence et une visibilité privée ou publique.

Une fois l'espace créé, Hugging Face vous montre l'URL de clonage git. Sur votre poste, un git clone https://huggingface.co/spaces/votre_pseudo/nom_de_l_espace récupère un dépôt vide avec un README.md initial que la plateforme a préparé. Toute votre démonstration se place dans ce dépôt local, avec un git push qui déploie.

Les fichiers requis, ni plus ni moins

Un espace Gradio minimal contient exactement trois fichiers.

app.py : le fichier Python que la plateforme exécute. Une seule contrainte : il doit se terminer par un demo.launch(). Aucun paramètre n'est nécessaire — pas de server_port, pas de server_name, pas de share=True. La plateforme s'occupe du serveur pour vous, et un paramètre inattendu peut casser le déploiement.

requirements.txt : la liste des dépendances Python à installer, une par ligne. Une bonne pratique est de figer les versions (gradio==4.44.0, transformers==4.44.2) pour éviter qu'une mise à jour d'une bibliothèque casse la démonstration silencieusement le jour où la plateforme redémarre l'environnement.

README.md : un fichier Markdown classique, préfixé par un frontmatter YAML que Hugging Face lit pour configurer l'espace. Le frontmatter par défaut ressemble à ceci :

---
title: Assistant francophone
emoji: "L"
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.44.0
app_file: app.py
pinned: false
---

sdk_version doit correspondre à la version de gradio listée dans requirements.txt, sinon la plateforme installe silencieusement une autre version. app_file permet de renommer app.py en autre chose si vous le souhaitez.

Les secrets : jamais dans le code

Les clés d'API et autres secrets se déposent dans les Settings de l'espace, section Repository secrets. Chaque secret est une variable clé-valeur ; à l'exécution, la plateforme l'expose dans os.environ de votre app.py. Le code de la démonstration lit os.environ["OPENAI_API_KEY"] exactement comme sur votre poste avec une variable d'environnement locale.

Un git push d'un fichier .env ou d'une clé en dur dans app.py est la faute la plus fréquente et la plus coûteuse des débutants sur Spaces. Un dépôt public expose la clé immédiatement, elle est indexée par des scrapers en quelques minutes, et vous découvrez le lendemain une facture d'appels API frauduleux. Le git est irréversible ; réinitialiser l'historique ne suffit pas ; il faut révoquer la clé chez le fournisseur d'API.

Le matériel : gratuit ou payant

Le matériel se change en un clic dans les Settings, section Space hardware. Les paliers actuels vont du CPU basic (gratuit, 16 Gio RAM, 2 vCPU) à divers GPU (T4 small 40 USD par mois, A10G small 108 USD par mois, A100 large plusieurs milliers). Un modèle de langage de la taille de Mistral 7B tient sur un T4 ; un modèle de 13 milliards de paramètres exige un A10G ; un modèle plus grand nécessite un A100.

Deux options intelligentes pour maîtriser le coût. Sleep after met l'espace en veille au bout de N minutes d'inactivité (par défaut 48 heures, mais on peut descendre à quelques minutes). Zero GPU est un mode récent où plusieurs espaces se partagent un pool de GPU : le GPU n'est réservé qu'au moment d'un appel, ce qui divise la facture par cinq à dix pour une démonstration à trafic modéré. C'est l'option à privilégier pour un projet perso qui reçoit quelques dizaines de visiteurs par jour.

La mise en veille : le comportement à comprendre

Un espace en veille consomme zéro ressource, mais le premier visiteur suivant paie un temps de réveil de trente secondes à deux minutes. Gradio le sait et affiche pendant ce temps une page « Space is starting » avec un décompte. L'utilisateur non prévenu croit à un site cassé ; l'utilisateur prévenu attend.

Pour un espace de démonstration publique, deux stratégies coexistent. Payer un peu (5 USD par mois pour un CPU permanent, l'option Persistent storage) pour ne jamais dormir, et servir instantanément. Ou vivre avec la mise en veille en assumant le temps de réveil, éventuellement en avertissant l'utilisateur dans le titre de la démonstration (« Le premier appel après une période d'inactivité peut prendre une minute »). Pour un espace lié à une candidature ou une publication scientifique, la première option est presque toujours la bonne.

Intégrer la démonstration dans un site externe

Un espace publié peut être intégré dans une page web tierce via un iframe de style :

<iframe
  src="https://votre_pseudo-nom_de_l_espace.hf.space"
  width="850"
  height="600"
  allow="microphone; camera"
></iframe>

L'URL utilisée n'est pas celle de la page du Space, mais celle du serveur de la démonstration (nom_de_l_espace.hf.space). Cette URL est indiquée dans la page du Space, sous « Embed this Space ». L'attribut allow autorise l'accès au micro et à la caméra pour les démonstrations audio ou vidéo, ce qui n'est pas activé par défaut par le navigateur.

Un README.md bien rédigé est le meilleur porte-parole

La section prose du README.md — celle sous le frontmatter — s'affiche sur la page du Space avant que l'utilisateur clique sur « Try it ». C'est votre argumentaire de démonstration : que fait ce modèle ? Sur quelles données a-t-il été entraîné ? Quelles sont ses limites ? Combien de temps prend une inférence ? Ces informations rassurent et pré-répondent à toutes les questions que le formulaire de retour ne posera jamais.

En résumé

• Un espace Hugging Face est un dépôt git qui se déploie à chaque git push ; trois fichiers suffisent (app.py, requirements.txt, README.md avec frontmatter YAML).
• app.py se termine par demo.launch() sans paramètre ; les secrets se déposent dans Settings > Repository secrets et se lisent avec os.environ, jamais dans le code.
• Le matériel par défaut est CPU gratuit ; passer à Zero GPU est l'option la plus économique pour une démonstration GPU à trafic modéré ; un A10G ou A100 est facturé au mois.
• La mise en veille par défaut économise les ressources mais fait payer un réveil de 30 s à 2 min au premier visiteur ; à assumer explicitement dans le titre ou à éviter en passant à un espace persistant.

Le module 10 est le projet fil rouge complet : assistant conversationnel diffusé, avec exemples, file d'attente, collecte de retours, coût et limites, publié sur un espace Hugging Face.