Skip to content

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.

sudo apt install git-lfs
git lfs install

To upload files to the Hugging Face Hub, you need to sign up and log in to your Hugging Face account with:

huggingface-cli login

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:

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

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:

git clone <URL of Hugging Face Repo>

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 to https://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 to max_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. If None, will save to replay.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 as hf_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