# Utiliser sample-factory sur Hugging Face

[`sample-factory`](https://github.com/alex-petrenko/sample-factory) est une base de code pour l'apprentissage par renforcement asynchrone à haut débit. Elle intègre le Hugging Face Hub pour partager des modèles avec leurs résultats d'évaluation et leurs métriques d'entraînement.

## Explorer sample-factory dans le Hub

Vous pouvez trouver les modèles `sample-factory` en filtrant à gauche de la [page des modèles](https://huggingface.co/models?library=sample-factory).

Tous les modèles du Hub sont dotés de fonctionnalités utiles :
1. Une carte de modèle générée automatiquement, avec une description, une configuration d'entraînement et plus encore.
2. Balises de métadonnées qui aident à la découvrabilité.
3. Résultats d'évaluation à comparer avec d'autres modèles.
4. Un widget vidéo où vous pouvez voir votre agent en action.

## Installer la bibliothèque
Pour installer la bibliothèque `sample-factory`, vous devez installer le package :

`pip install sample-factory`

SF est connu pour fonctionner sur Linux et MacOS. Il n'existe pas de prise en charge de Windows à ce stade.

## Chargement des modèles depuis le Hub
### Utilisation de load_from_hub

Pour télécharger un modèle depuis le Hugging Face Hub afin de l'utiliser avec Sample-Factory, utilisez le script `load_from_hub` :

```
python -m sample_factory.huggingface.load_from_hub -r <HuggingFace_repo_id> -d <train_dir_path>
```

Les arguments de ligne de commande sont :

- `-r` : l’identifiant du dépôt HF à partir duquel effectuer le téléchargement. L’identifiant du dépôt doit être au format `<username>/<repo_name>`
- `-d` : argument facultatif pour spécifier le répertoire dans lequel enregistrer l'expérience. Par défaut, `./train_dir`, ce qui enregistre le dépôt dans `./train_dir/<repo_name>`

### Télécharger directement le dépôt de modèle

Les dépôts Hugging Face peuvent être téléchargés directement à l'aide de `git clone` :

```
git clone git@hf.co:<Name of HuggingFace Repo> # example: git clone git@hf.co:bigscience/bloom
```

## Utilisation des modèles téléchargés avec Sample-Factory

Après avoir téléchargé le modèle, vous pouvez exécuter les modèles du dépôt à l'aide du script enjoy correspondant à votre environnement. Par exemple, si vous téléchargez un modèle `mujoco-ant`, il peut être exécuté avec :

```
python -m sf_examples.mujoco.enjoy_mujoco --algo=APPO --env=mujoco_ant --experiment=<repo_name> --train_dir=./train_dir
```

Notez que vous devrez peut-être spécifier `--train_dir` si le chemin de votre train_dir local est différent de celui indiqué dans `cfg.json`

## Partager vos modèles
### En utilisant push_to_hub

Si vous souhaitez téléverser sans générer de métriques d'évaluation ni de vidéo de rejeu, vous pouvez utiliser le script `push_to_hub` :

```
python -m sample_factory.huggingface.push_to_hub -r <hf_username>/<hf_repo_name> -d <experiment_dir_path>
```

Les arguments de ligne de commande sont :

- `-r` : le repo_id à enregistrer sur HF Hub. C'est identique à `hf_repository` dans le script enjoy et doit être au format `<hf_username>/<hf_repo_name>`
- `-d` : le chemin complet vers votre répertoire d'expérience à téléverser

### Utilisation de enjoy.py

Vous pouvez téléverser vos modèles sur le Hub à l’aide du script `enjoy` de votre environnement avec le drapeau `--push_to_hub`. Le téléversement via `enjoy` peut également générer des métriques d’évaluation et une vidéo de rejouage.

Les métriques d'évaluation sont générées en exécutant votre modèle dans l'environnement spécifié pendant un certain nombre d'épisodes et en signalant la récompense moyenne et l'écart-type de ces exécutions.

Les autres arguments de ligne de commande pertinents sont :

- `--hf_repository` : Le dépôt vers lequel pousser. Doit être de la forme `<username>/<repo_name>`. Le modèle sera enregistré sur `https://huggingface.co/<username>/<repo_name>`
- `--max_num_episodes` : Nombre d'épisodes à évaluer avant le téléversement. Utilisé pour générer des métriques d'évaluation. Il est recommandé d'utiliser plusieurs épisodes pour générer une moyenne et un écart-type précis.
- `--max_num_frames` : Nombre de frames à évaluer avant le téléversement. Alternative à `max_num_episodes`
- `--no_render` : un drapeau qui désactive le rendu et l’affichage des étapes de l’environnement. Il est recommandé de définir ce drapeau pour accélérer le processus d’évaluation.

Vous pouvez également enregistrer une vidéo du modèle pendant l'évaluation pour la téléverser sur le hub à l'aide du drapeau `--save_video`

- `--video_frames` : Le nombre d'images à rendre dans la vidéo. La valeur par défaut est -1, ce qui rend l'épisode entier
- `--video_name` : Le nom sous lequel enregistrer la vidéo. Si `None`, la vidéo sera enregistrée sous `replay.mp4` dans votre répertoire d'expérimentation

Par exemple :

```
python -m sf_examples.mujoco_examples.enjoy_mujoco --algo=APPO --env=mujoco_ant --experiment=<repo_name> --train_dir=./train_dir --max_num_episodes=10 --push_to_hub --hf_username=<username> --hf_repository=<hf_repo_name> --save_video --no_render
```