Hugging Face 🤗 Hub¶
Sample Factory has integrations with 🤗 Hugging Face Hub to push models with evaluation results and training metrics to the hub.
Setting Up¶
The Hugging Face Hub requires git lfs
to download model files.
To upload files to the Hugging Face Hub, you need to sign up and log in to your Hugging Face account with:
As part of the huggingface-cli login
, you should generate a token with write access at https://huggingface.co/settings/tokens
Downloading Models¶
Using the load_from_hub Scipt¶
To download a model from the Hugging Face Hub to use with Sample-Factory, use the load_from_hub
script:
The command line arguments are:
-
-r
: The repo ID for the HF repository to download. The repo ID should be in the format<username>/<repo_name>
-
-d
: An optional argument to specify the directory to save the experiment to. Defaults to./train_dir
which will save the repo to./train_dir/<repo_name>
Download Model Repository Directly¶
Hugging Face repositories can be downloaded directly using git clone
:
Using Downloaded Models with Sample Factory¶
After downloading the model, you can run the models in the repo with the enjoy script corresponding to your environment. For example, if you are downloading a mujoco-ant
model, it can be run with:
python -m sf_examples.mujoco.enjoy_mujoco --algo=APPO --env=mujoco_ant --experiment=<repo_name> --train_dir=./train_dir
Note, you may have to specify the --train_dir
if your local train_dir has a different path than the one in the config.json
Uploading Models¶
Using enjoy.py¶
You can upload your models to the Hub using your environment's enjoy
script with the --push_to_hub
flag. Uploading using enjoy
can also generate evaluation metrics and a replay video.
The evaluation metrics are generated by running your model on the specified environment for a number of episodes and reporting the mean and std reward of those runs.
Other relevant command line arguments are:
-
--hf_repository
: The repository to push to. Must be of the form<username>/<repo_name>
. The model will be saved tohttps://huggingface.co/<username>/<repo_name>
-
--max_num_episodes
: Number of episodes to evaluate on before uploading. Used to generate evaluation metrics. It is recommended to use multiple episodes to generate an accurate mean and std. -
--max_num_frames
: Number of frames to evaluate on before uploading. An alternative tomax_num_episodes
-
--no_render
: A flag that disables rendering and showing the environment steps. It is recommended to set this flag to speed up the evaluation process.
You can also save a video of the model during evaluation to upload to the hub with the --save_video
flag
-
--video_frames
: The number of frames to be rendered in the video. Defaults to -1 which renders an entire episode -
--video_name
: The name of the video to save as. IfNone
, will save toreplay.mp4
in your experiment directory
Also, you can include information in the Hugging Face Hub model card for how to train and enjoy using this model. These parameters are optional:
-
--train_script
: The module path for training this model -
--enjoy_script
: The module path for enjoying this model
For example:
python -m sf_examples.mujoco.enjoy_mujoco --algo=APPO --env=mujoco_ant --experiment=<repo_name> --train_dir=./train_dir --max_num_episodes=10 --push_to_hub --hf_repository=<username>/<hf_repo_name> --save_video --no_render --enjoy_script=sf_examples.mujoco.enjoy_mujoco --train_script=sf_examples.mujoco.train_mujoco
Using the push_to_hub Script¶
If you want to upload without generating evaluation metrics or a replay video, you can use the push_to_hub
script:
python -m sample_factory.huggingface.push_to_hub -r <hf_username>/<hf_repo_name> -d <experiment_dir_path>
The command line arguments are:
-
-r
: The repo_id to save on HF Hub. This is the same ashf_repository
in the enjoy script and must be in the form<hf_username>/<hf_repo_name>
-
-d
: The full path to your experiment directory to upload
The optional arguments of --train_script
and --enjoy_script
can also be used. See the above section for more details