Module 6 — Exemples préremplis et mise en cache

Un utilisateur qui arrive sur une démonstration inconnue passe environ trois secondes à décider s'il essaie ou s'il ferme l'onglet. Si l'interface est vide, il faut deviner quoi taper, ce que peut faire le modèle et quel type d'entrée l'intéresse. Les exemples préremplis répondent à ces trois questions d'un coup, en un clic. Sur toutes les démonstrations publiques de Hugging Face, ce sont eux qui pilotent l'engagement, bien plus que la qualité du modèle lui-même.

examples, une liste de listes

Le paramètre examples de gr.Interface accepte une liste, où chaque élément est lui-même une liste correspondant aux entrées de la fonction, dans l'ordre. Pour une fonction à une seule entrée texte, on écrit examples=[["Bonjour"], ["Comment allez-vous ?"]]. Pour une fonction à deux entrées (texte + curseur), on écrit examples=[["résumé court", 0.3], ["résumé détaillé", 0.9]].

Gradio affiche ces exemples sous forme de boutons cliquables juste sous les composants d'entrée. Un clic remplit les entrées avec les valeurs de l'exemple, mais n'appelle pas la fonction par défaut : l'utilisateur voit la question, la lit, puis clique sur « Envoyer » s'il veut la réponse. Ce délai supplémentaire est intentionnel, il donne à l'utilisateur le contrôle du moment de l'appel.

Pour un composant image ou audio, l'exemple est un chemin de fichier, absolu ou relatif au dossier de lancement. examples=[["chats/persan.jpg"], ["chiens/labrador.jpg"]] charge ces images depuis un sous-dossier. Le sous-dossier doit être livré avec la démonstration, ce qui compte pour la publication sur un espace Hugging Face au module 9.

Exemples pour gr.ChatInterface

Le composant conversationnel a son propre paramètre examples, qui prend une liste de chaînes — puisqu'un chat a une seule entrée de type texte. Ces chaînes s'affichent sous forme de suggestions au-dessus de la zone de saisie tant que la conversation est vide, et disparaissent dès le premier message. C'est l'endroit idéal pour inviter l'utilisateur à essayer trois questions représentatives de ce que l'assistant sait bien faire.

import gradio as gr

def repondre(message, historique):
    return f"Je réfléchis à : {message}"

demo = gr.ChatInterface(
    fn=repondre,
    type="messages",
    title="Assistant démo",
    examples=[
        "Résume-moi le premier chapitre du Petit Prince en trois phrases.",
        "Explique la différence entre TCP et UDP à un étudiant de première année.",
        "Traduis en anglais : 'La météo est douce pour la saison.'",
    ],
)
demo.launch()

Choisir des exemples qui montrent les limites

C'est la partie contre-intuitive du module. Un ensemble d'exemples qui ne montre que des réussites trompe l'utilisateur, qui essaie ensuite un cas légèrement plus complexe et se sent floué. Un ensemble qui inclut un exemple aux limites du modèle — assez difficile pour que la réponse soit imparfaite mais restée compréhensible — informe l'utilisateur sur les frontières réelles, et augmente sa confiance dans la démonstration.

Pour un classificateur d'images entraîné sur ImageNet, trois exemples types fonctionnent bien : une image typique (un labrador de face, cadrage propre, éclairage neutre) qui donne un résultat parfait ; une image ambiguë (un chien-loup) qui donne trois catégories de probabilité proche ; une image hors domaine (une facture, un schéma) qui donne des probabilités faibles réparties sur des catégories improbables. L'utilisateur comprend en trois clics ce que le modèle sait et ne sait pas faire.

Pour un assistant conversationnel, la même logique s'applique : une question factuelle sur laquelle il excelle, une question de raisonnement sur laquelle il fait une erreur légère, une question ambiguë qu'il refuse gracieusement (« pouvez-vous préciser ? »). Trois exemples suffisent, cinq est presque toujours trop, dix noient l'utilisateur dans le choix.

cache_examples : payer au démarrage plutôt qu'au clic

Sur les démonstrations lourdes — un modèle qui met vingt secondes à répondre — même le premier exemple donne une mauvaise impression : l'utilisateur clique, attend, et voit son premier essai se traîner. Gradio propose de précalculer les exemples au démarrage avec cache_examples=True. Au lancement de la démonstration, la fonction est appelée sur chaque exemple, les sorties sont stockées, et un clic sur un exemple affiche immédiatement le résultat mis en cache, sans réappeler la fonction.

Le coût est déplacé du premier clic vers le démarrage. Un modèle qui met vingt secondes par exemple, avec cinq exemples, ajoute une minute cinquante au temps de lancement de la démonstration. Sur un espace Hugging Face gratuit qui se met en veille au bout de dix minutes d'inactivité et se réveille au premier appel, ce délai est ajouté à la première visite, ce qui reste en pratique meilleur que d'attendre l'appel lui-même.

demo = gr.Interface(
    fn=classer,
    inputs=gr.Image(type="pil"),
    outputs=gr.Label(num_top_classes=3),
    examples=[
        ["exemples/chien.jpg"],
        ["exemples/chat.jpg"],
        ["exemples/facture.jpg"],
    ],
    cache_examples=True,
)

Sur un gr.ChatInterface, le paramètre s'appelle cache_examples également et fonctionne exactement de la même manière : chaque exemple est envoyé au modèle au démarrage, et la réponse est mémorisée jusqu'au prochain redémarrage.

Quand ne pas mettre en cache

Trois cas commandent de laisser cache_examples=False (la valeur par défaut). D'abord, quand la fonction est non déterministe (sampling activé, température non nulle) : le résultat mis en cache figerait une réponse aléatoire, ce qui trompe l'utilisateur qui s'attend à voir la vraie sortie du modèle. Ensuite, quand la fonction lit une ressource externe qui change (base de données, API météo), auquel cas la réponse en cache devient obsolète. Enfin, quand la fonction consomme un budget (appels payants à une API), auquel cas précalculer cinq exemples toutes les nuit pour rien coûte de l'argent.

Sur un assistant conversationnel branché sur une API payante, cache_examples=False est presque toujours le bon choix, quitte à afficher les exemples et à laisser l'utilisateur payer le premier appel réel. Sur un classificateur local déterministe, cache_examples=True est presque toujours gagnant.

Les exemples sont livrés avec le code

Les fichiers d'exemples (images, audios) doivent être présents dans l'arborescence lancée. Sur un espace Hugging Face, cela veut dire les commiter dans le dépôt du Space. Un chemin qui pointe vers un fichier absent produit un exemple invisible ou un FileNotFoundError au premier clic, selon la version. Vérifier la liste des fichiers avant git push.

En résumé

• examples=[[...], [...]] (une liste par appel de fonction) pose des boutons cliquables sous les entrées ; le clic remplit les entrées mais n'appelle pas la fonction, laissant le contrôle à l'utilisateur.
• Sur gr.ChatInterface, examples=["..."] (liste de chaînes) affiche des suggestions au-dessus de la saisie tant que la conversation est vide.
• Choisir trois exemples : un cas typique (réussite), un cas limite (réponse imparfaite compréhensible), un cas hors domaine (refus gracieux) informe honnêtement l'utilisateur sur les frontières du modèle.
• cache_examples=True précalcule au démarrage : gagnant pour un modèle local déterministe, à éviter pour une API payante ou une fonction non déterministe.

Le module suivant regarde ce qui se passe quand plusieurs utilisateurs cliquent en même temps : la file d'attente et les limites de concurrence.