# Widgets

## Qu'est-ce qu'un widget ?

De nombreux dépôts de modèles disposent d’un widget permettant à quiconque d’exécuter des inférences directement dans le navigateur. Ces widgets sont propulsés par les [Inference Providers](https://huggingface.co/docs/inference-providers), qui offrent aux développeurs un accès unifié et simplifié à des centaines de modèles de machine learning, soutenu par nos partenaires d’inférence serverless.

Voici quelques exemples de modèles populaires actuels :

- [DeepSeek V3](https://huggingface.co/deepseek-ai/DeepSeek-V3-0324) - Modèle conversationnel à poids ouverts de pointe
- [Flux Kontext](https://huggingface.co/black-forest-labs/FLUX.1-Kontext-dev) - Modèle transformer à poids ouverts pour l'édition d'images
- [Détection NSFW de Falconsai](https://huggingface.co/Falconsai/nsfw_image_detection) - Modération du contenu d'images
- [Chatterbox de ResembleAI](https://huggingface.co/ResembleAI/chatterbox) - Modèle open source de synthèse vocale de qualité production.

Vous pouvez explorer d'autres modèles et leurs widgets sur la [page des modèles](https://huggingface.co/models?inference_provider=all&sort=trending) ou les essayer de manière interactive dans le [Inference Playground](https://huggingface.co/playground).

## Activer un widget

Les widgets sont affichés lorsque le modèle est hébergé par au moins un fournisseur d'inférence, garantissant ainsi des performances et une fiabilité optimales pour l'inférence du modèle. Les fournisseurs choisissent et contrôlent de manière autonome les modèles qu'ils déploient.

Le type de widget affiché (texte vers image, reconnaissance vocale automatique, etc.) est déduit du `pipeline_tag` du modèle, un tag spécial que le Hub tente de calculer automatiquement pour tous les modèles. La seule exception concerne le widget `conversational`, qui est affiché sur tous les modèles dont le `pipeline_tag` est soit `text-generation`, soit `image-text-to-text`. Nous avons choisi d’exposer **un seul** widget par modèle, par simplicité.

Pour certaines bibliothèques, telles que `transformers`, le type de modèle peut être inféré automatiquement à partir des fichiers de configuration (`config.json`). L'architecture peut déterminer le type : par exemple, `AutoModelForTokenClassification` correspond à `token-classification`. Si cela vous intéresse, vous pouvez consulter le pseudo-code dans [ce gist](https://gist.github.com/julien-c/857ba86a6c6a895ecd90e7f7cab48046).

Pour la plupart des autres cas d'utilisation, nous utilisons les étiquettes du modèle pour déterminer le type de tâche du modèle. Par exemple, si `tag: text-classification` figure dans les [métadonnées de la carte du modèle](./model-cards), le `pipeline_tag` déduit sera `text-classification`.

**Vous pouvez toujours remplacer manuellement le type de votre pipeline avec `pipeline_tag: xxx` dans les [métadonnées de la carte de modèle](./model-cards#model-card-metadata).** (Vous pouvez également utiliser l’éditeur de métadonnées pour ce faire).

### Comment puis-je contrôler l'exemple d'entrée du widget de mon modèle ?

Vous pouvez spécifier l’entrée du widget dans la section métadonnées de la carte du modèle :

```yaml
widget:
  - text: "This new restaurant has amazing food and great service!"
    example_title: "Positive Review"
  - text: "I'm really disappointed with this product. Poor quality and overpriced."
    example_title: "Negative Review"
  - text: "The weather is nice today."
    example_title: "Neutral Statement"
```

Vous pouvez fournir plusieurs exemples d’entrée. Dans le menu déroulant des exemples du widget, ils apparaîtront sous la forme `Example 1`, `Example 2`, etc. Facultativement, vous pouvez également fournir `example_title`.

```yaml
widget:
  - text: "Is this review positive or negative? Review: Best cast iron skillet you will ever buy."
    example_title: "Sentiment analysis"
  - text: "Barack Obama nominated Hilary Clinton as his secretary of state on Monday. He chose her because she had ..."
    example_title: "Coreference resolution"
  - text: "On a shelf, there are five books: a gray book, a red book, a purple book, a blue book, and a black book ..."
    example_title: "Logic puzzles"
  - text: "The two men running to become New York City's next mayor will face off in their first debate Wednesday night ..."
    example_title: "Reading comprehension"
```

De plus, vous pouvez spécifier des exemples d’entrées non textuels dans les métadonnées de la carte du modèle. Consultez [ici](./models-widgets-examples) pour obtenir la liste complète des formats d’entrée d’exemple pour tous les types de widgets. Pour les types de widgets vision & audio, fournissez des exemples d’entrées avec `src` plutôt que `text`.

Par exemple, permettre aux utilisateurs de choisir parmi deux fichiers audio d’exemple pour les tâches de reconnaissance vocale automatique en :

```yaml
widget:
  - src: https://example.org/somewhere/speech_samples/sample1.flac
    example_title: Speech sample 1
  - src: https://example.org/somewhere/speech_samples/sample2.flac
    example_title: Speech sample 2
```

Notez que vous pouvez également inclure des fichiers d'exemple dans votre dépôt de modèle et les utiliser comme suit :

```yaml
widget:
  - src: https://huggingface.co/username/model_repo/resolve/main/sample1.flac
    example_title: Custom Speech Sample 1
```

Mais encore plus pratique, si le fichier se trouve dans le dépôt de modèle correspondant, vous pouvez simplement utiliser le nom du fichier ou le chemin du fichier dans le dépôt :

```yaml
widget:
  - src: sample1.flac
    example_title: Custom Speech Sample 1
```

ou s'il était imbriqué dans le dépôt :

```yaml
widget:
  - src: nested/directory/sample1.flac
```

Nous fournissons des exemples d’entrées pour certaines langues et la plupart des types de widgets dans le fichier [default-widget-inputs.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/tasks/src/default-widget-inputs.ts). Si certains exemples manquent, nous accueillons avec plaisir les PR de la communauté pour les ajouter !

## Exemples de sorties

En complément des exemples d’entrées, pour chaque exemple de widget, vous pouvez également décrire de manière facultative la sortie correspondante du modèle, directement dans la propriété `output`.

Cela est utile lorsque le modèle n'est pas encore pris en charge par les Inference Providers, afin que la page du modèle puisse toujours présenter son fonctionnement et les résultats qu'il produit.

Par exemple, pour un modèle [automatic-speech-recognition](./models-widgets-examples#automatic-speech-recognition) :

```yaml
widget:
  - src: sample1.flac
    output:
      text: "Hello my name is Julien"
```

La propriété `output` doit être un dictionnaire YAML représentant le format de sortie des Inference Providers.

Pour un modèle qui génère du texte, consultez l’exemple ci-dessus.

Pour un modèle qui sort des étiquettes (comme un modèle de [text-classification](./models-widgets-examples#text-classification) par exemple), la sortie doit ressembler à ceci :

```yaml
widget:
  - text: "I liked this movie"
    output:
      - label: POSITIVE
        score: 0.8
      - label: NEGATIVE
        score: 0.2
```

Enfin, pour un modèle qui génère une image, un audio ou tout autre type d’actif, la sortie doit inclure une propriété `url` pointant vers un nom de fichier ou un chemin dans le dépôt, ou vers une URL distante. Par exemple, pour un modèle texte-vers-image :

```yaml
widget:
  - text: "picture of a futuristic tiger, artstation"
    output:
      url: images/tiger.jpg
```

Nous pouvons également afficher les exemples de sortie dans l’interface utilisateur Hugging Face, par exemple pour un modèle texte-vers-image afin d’afficher une galerie de générations d’images impressionnantes.

## Disponibilité des widgets et prise en charge des fournisseurs

Tous les modèles ne disposent pas de widgets. La disponibilité des widgets dépend de :

1. **Prise en charge des tâches** : la tâche du modèle doit être prise en charge par au moins un fournisseur du réseau Inference Providers
2. **Disponibilité des fournisseurs** : au moins un fournisseur doit servir le modèle spécifique
3. **Configuration du modèle** : le modèle doit disposer de métadonnées et de fichiers de configuration appropriés

Pour consulter la liste complète des tâches prises en charge, consultez [notre page de documentation dédiée](https://huggingface.co/docs/inference-providers/tasks/index).

La liste de tous les fournisseurs et des tâches qu’ils prennent en charge est disponible dans [cette page de documentation](https://huggingface.co/docs/inference-providers/index#partners).

Pour les modèles sans support de fournisseur, vous pouvez toujours mettre en avant les fonctionnalités à l'aide de [sorties d'exemple](#example-outputs) dans votre carte de modèle.

Vous pouvez également cliquer sur _Demander le support du fournisseur_ directement sur la page du modèle pour encourager les fournisseurs à servir le modèle, s'il y a suffisamment d'intérêt de la part de la communauté.

## Explorer les modèles avec l’Inference Playground

Avant d'intégrer des modèles dans vos applications, vous pouvez les tester de manière interactive avec le [Inference Playground](https://huggingface.co/playground). Le playground vous permet de :

- Testez différents [modèles de complétion de chat](https://huggingface.co/models?inference_provider=all&sort=trending&other=conversational) avec des invites personnalisées
- Comparer les réponses de différents modèles
- Expérimentez avec des paramètres d'inférence tels que la température, le nombre maximal de jetons, et plus encore
- Trouvez le modèle parfait pour votre cas d'usage spécifique

Le playground utilise la même infrastructure Inference Providers que celle qui alimente les widgets, vous pouvez donc vous attendre à des performances et des capacités similaires lorsque vous intégrez les modèles dans vos propres applications.