# Sử dụng sample-factory trên Hugging Face

[`sample-factory`](https://github.com/alex-petrenko/sample-factory) là một mã nguồn cho học tăng cường bất đồng bộ thông lượng cao. Nó có các tích hợp với Hugging Face Hub để chia sẻ các mô hình kèm theo kết quả đánh giá và các chỉ số huấn luyện.

## Khám phá sample-factory trên Hub

Bạn có thể tìm các mô hình `sample-factory` bằng cách lọc ở phía bên trái của [trang models](https://huggingface.co/models?library=sample-factory).

Tất cả các model trên Hub đều đi kèm với các tính năng hữu ích:
1. Thẻ mô tả mô hình được tạo tự động, bao gồm phần mô tả, cấu hình huấn luyện và nhiều thông tin khác.
2. Các thẻ metadata giúp tăng khả năng tìm kiếm.
3. Kết quả đánh giá để so sánh với các mô hình khác.
4. Một widget video cho phép bạn xem agent của mình thực hiện.

## Cài đặt thư viện
Để cài đặt thư viện `sample-factory`, bạn cần cài đặt gói:

`pip install sample-factory`

SF được biết là hoạt động trên Linux và MacOS. Hiện tại chưa có hỗ trợ cho Windows.

## Tải mô hình từ Hub
### Sử dụng load_from_hub

Để tải một mô hình từ Hugging Face Hub về sử dụng với Sample-Factory, hãy dùng script `load_from_hub`:

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

Các đối số dòng lệnh là:

- `-r`: ID của kho cho kho HF để tải xuống. ID kho phải ở định dạng `<username>/<repo_name>`
- `-d`: Một đối số tùy chọn để chỉ định thư mục lưu trữ thí nghiệm. Mặc định là `./train_dir`, sẽ lưu kho vào `./train_dir/<repo_name>`

### Tải trực tiếp kho lưu trữ mô hình

Các kho lưu trữ Hugging Face có thể được tải xuống trực tiếp bằng `git clone`:

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

## Sử dụng các Mô hình đã Tải xuống với Sample-Factory

Sau khi tải xuống mô hình, bạn có thể chạy các mô hình trong kho bằng script enjoy tương ứng với môi trường của bạn. Ví dụ, nếu bạn tải xuống một mô hình `mujoco-ant`, nó có thể được chạy bằng:

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

Lưu ý, bạn có thể phải chỉ định `--train_dir` nếu đường dẫn của train_dir cục bộ khác với đường dẫn trong `cfg.json`

## Chia sẻ các mô hình của bạn
### Sử dụng push_to_hub

Nếu bạn muốn tải lên mà không tạo các chỉ số đánh giá hoặc video phát lại, bạn có thể sử dụng script `push_to_hub`:

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

Các đối số dòng lệnh là:

- `-r`: repo_id để lưu trên HF Hub. Đây giống với `hf_repository` trong script enjoy và phải ở dạng `<hf_username>/<hf_repo_name>`
- `-d`: Đường dẫn đầy đủ đến thư mục thử nghiệm của bạn để tải lên

### Sử dụng enjoy.py

Bạn có thể tải mô hình của mình lên Hub bằng cách sử dụng script `enjoy` của môi trường với cờ `--push_to_hub`. Việc tải lên bằng `enjoy` cũng có thể tạo ra các chỉ số đánh giá và một video phát lại.

Các chỉ số đánh giá được tạo ra bằng cách chạy mô hình của bạn trong môi trường đã chỉ định qua một số lượng episode nhất định và báo cáo phần thưởng trung bình và độ lệch chuẩn của các lần chạy đó.

Các đối số dòng lệnh liên quan khác là:

- `--hf_repository`: Kho lưu trữ để đẩy lên. Phải có dạng `<username>/<repo_name>`. Mô hình sẽ được lưu vào `https://huggingface.co/<username>/<repo_name>`
- `--max_num_episodes`: Số lượng episodes để đánh giá trước khi tải lên. Được sử dụng để tạo các chỉ số đánh giá. Khuyến nghị sử dụng nhiều episodes để tạo ra giá trị trung bình và độ lệch chuẩn chính xác.
- `--max_num_frames`: Số khung hình cần đánh giá trước khi tải lên. Một phương án thay thế cho `max_num_episodes`
- `--no_render`: Một cờ để tắt việc render và hiển thị các bước của môi trường. Khuyến nghị đặt cờ này để tăng tốc quá trình đánh giá.

Bạn cũng có thể lưu video của mô hình trong quá trình đánh giá để tải lên hub bằng cờ `--save_video`

- `--video_frames`: Số khung hình sẽ được render trong video. Mặc định là -1, render toàn bộ một episode
- `--video_name`: Tên của video cần lưu. Nếu là `None`, video sẽ được lưu thành `replay.mp4` trong thư mục thử nghiệm của bạn

Ví dụ:

```
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
```