Hugging Face 🤗 Hub¶
Sample Factory has integrations with 🤗 Hugging Face Hub to push models with evaluation results and training metrics to the hub.
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
Using the load_from_hub Scipt¶
To download a model from the Hugging Face Hub to use with Sample-Factory, use the
The command line arguments are:
-r: The repo ID for the HF repository to download. The repo ID should be in the format
-d: An optional argument to specify the directory to save the experiment to. Defaults to
./train_dirwhich will save the repo to
Download Model Repository Directly¶
Hugging Face repositories can be downloaded directly using
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:
Note, you may have to specify the
--train_dir if your local train_dir has a different path than the one in the
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 to
--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 to
--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
--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. If
None, will save to
replay.mp4in 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
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
The command line arguments are:
-r: The repo_id to save on HF Hub. This is the same as
hf_repositoryin the enjoy script and must be in the form
-d: The full path to your experiment directory to upload
The optional arguments of
--enjoy_script can also be used. See the above section for more details