# Hugging Face'ta sample-factory kullanımı

[`sample-factory`](https://github.com/alex-petrenko/sample-factory), yüksek verimli asenkron pekiştirmeli öğrenme için bir kod tabanıdır. Hugging Face Hub ile entegrasyonları sayesinde değerlendirme sonuçları ve eğitim metrikleriyle birlikte modelleri paylaşmanızı sağlar.

## Hub'da sample-factory'yi keşfetme

[modeller sayfasının](https://huggingface.co/models?library=sample-factory) sol tarafında filtreleyerek `sample-factory` modellerini bulabilirsiniz.

Hub'daki tüm modeller, kullanışlı özelliklerle birlikte gelir:
1. Açıklama, eğitim yapılandırması ve daha fazlasını içeren otomatik olarak oluşturulmuş bir model kartı.
2. Keşfedilebilirliği artırmaya yardımcı olan meta etiketler.
3. Diğer modellerle karşılaştırma için değerlendirme sonuçları.
4. Ajanınızın performansını izleyebileceğiniz bir video widget'ı.

## Kütüphaneyi yükleyin
`sample-factory` kütüphanesini yüklemek için paketi yüklemeniz gerekir:

`pip install sample-factory`

SF'nin Linux ve MacOS üzerinde çalıştığı bilinmektedir. Şu anda Windows desteği bulunmamaktadır.

## Hub'dan modelleri yükleme
### load_from_hub kullanılarak

Sample-Factory ile kullanmak üzere Hugging Face Hub'dan bir model indirmek için `load_from_hub` betiğini kullanın:

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

Komut satırı argümanları şunlardır:

- `-r`: İndirme yapılacak HF deposunun depo kimliği. Depo kimliği `<username>/<repo_name>` biçiminde olmalıdır.
- `-d`: Deneyin kaydedileceği dizini belirtmek için isteğe bağlı bir argüman. Varsayılan olarak `./train_dir` kullanılır ve bu, repoyu `./train_dir/<repo_name>` konumuna kaydeder.

### Model Deposunu Doğrudan İndir

Hugging Face depoları doğrudan `git clone` kullanılarak indirilebilir:

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

## Örnek-Fabrika ile İndirilen Modelleri Kullanma

Modeli indirdikten sonra, repodaki modelleri ortamınıza karşılık gelen enjoy betiğiyle çalıştırabilirsiniz. Örneğin, `mujoco-ant` modelini indiriyorsanız, şu şekilde çalıştırılabilir:

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

Not: Yerel train_dir yolunuz, `cfg.json` içindeki yoldan farklıysa `--train_dir` parametresini belirtmeniz gerekebilir.

## Modellerinizi paylaşma
### push_to_hub kullanılarak

Değerlendirme metrikleri veya bir yeniden oynatma videosu oluşturmadan yüklemek istiyorsanız, `push_to_hub` betiğini kullanabilirsiniz:

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

Komut satırı argümanları şunlardır:

- `-r`: HF Hub üzerinde kaydedilecek repo_id. Bu, enjoy betiğindeki `hf_repository` ile aynıdır ve `<hf_username>/<hf_repo_name>` biçiminde olmalıdır
- `-d`: Yüklemek için deney dizininizin tam yolu

### enjoy.py kullanımı

Modellerinizi, ortamınızın `enjoy` betiğini `--push_to_hub` bayrağıyla kullanarak Hub'a yükleyebilirsiniz. `enjoy` ile yükleme işlemi ayrıca değerlendirme metrikleri ve bir oynatma videosu da oluşturabilir.

Değerlendirme metrikleri, modelinizin belirtilen ortamda belirli sayıda bölüm (episode) boyunca çalıştırılması ve bu çalıştırmaların ortalama ve standart sapma ödülünün raporlanmasıyla üretilir.

Diğer ilgili komut satırı argümanları şunlardır:

- `--hf_repository`: İtme yapılacak depo. Biçimi `<username>/<repo_name>` olmalıdır. Model, `https://huggingface.co/<username>/<repo_name>` adresine kaydedilecektir.
- `--max_num_episodes`: Yüklemeye başlamadan önce değerlendirilecek bölüm sayısı. Değerlendirme metriklerini üretmek için kullanılır. Doğru bir ortalama ve standart sapma üretmek için birden fazla bölüm kullanılması önerilir.
- `--max_num_frames`: Yüklemeye başlamadan önce değerlendirilecek kare sayısı. `max_num_episodes`'nin bir alternatifi
- `--no_render`: Ortam adımlarını görüntülemeyi ve render etmeyi devre dışı bırakan bir bayraktır. Değerlendirme sürecini hızlandırmak için bu bayrağın ayarlanması önerilir.

Değerlendirme sırasında modelin videosunu da `--save_video` bayrağıyla kaydederek hub'a yükleyebilirsiniz

- `--video_frames`: Videoda oluşturulacak kare sayısı. Varsayılan olarak -1'dir ve tüm bölümü oluşturur
- `--video_name`: Kaydedilecek videonun adı. `None` ise, deney dizininizde `replay.mp4` olarak kaydedilir

Örneğin:

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