# π₀-FAST (Pi0-FAST)

π₀-FAST, sürekli robot eylemlerini modellemek için otoregresif bir sonraki token tahminini kullanan **genel robot kontrolü için bir Görsel-Dil-Eylem modelidir**.

## Model Genel Bakış

π₀-FAST, Görüntü-Dil Modellerinin gücünü, **FAST (Frequency-space Action Sequence Tokenization)** adlı yeni bir eylem tokenizasyonu yaklaşımıyla birleştirir. Bu sayede, standart binned tabanlı ayrıklaştırma ile imkânsız olan, son derece çevik görevlerde otoregresif VLA'ların eğitimi mümkün hale gelirken, π₀ gibi difüzyon tabanlı yaklaşımlara kıyasla **5 kata kadar daha hızlı** eğitim yapılabilir.

<img
  src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/lerobot-pifast.png"
  alt="An overview of Pi0-FAST"
  width="85%"
/>

### Neden FAST?

Robot eylem tokenizasyonu için standart yaklaşımlar, basit boyut başına ve zaman adımı başına binişleme şemaları kullanır. Basit davranışlar için kabul edilebilir olsa da, hassasiyet ve yüksek frekanslı kontrol gerektiren karmaşık ve çevik beceriler için bu yöntem hızla işlevini yitirir.

FAST, sinyal işleme tekniklerini kullanarak eylem dizilerini sıkıştırarak bu sorunu çözer; bu da dil token'ları gibi otoregresif olarak tahmin edilebilen yoğun bir eylem token'ı dizisiyle sonuçlanır.

### FAST Tokenizasyonun Çalışma Şekli

FAST belirleyici, eylem dizilerini aşağıdaki adımlar aracılığıyla sıkıştırır:

1. **Normalize**: `H` ufku ve `D` eylem boyutuna sahip, `(H, D)` şeklinde sürekli bir eylem parçası alın. Desteklenen normalizasyon yöntemlerinden biriyle normalizasyon yapın (aykırı değerleri ele almak için Quantiles önerilir).

2. **Discrete Cosine Transform (DCT)**: DCT'yi (scipy aracılığıyla) her eylem boyutuna ayrı ayrı uygulayın. DCT, görüntü ve ses kodeklerinde (JPEG, MP3) yaygın olarak kullanılan bir sıkıştırma algoritmasıdır.

3. **Kantizasyon**: Her eylem boyutu için önemsiz katsayıları yuvarlayıp kaldırarak seyrek bir frekans matrisi oluşturur.

4. **Flatten**: Matrisi, düşük frekanslı bileşenler başta olacak şekilde 1B vektöre dönüştürür.

5. **Byte Pair Encoding (BPE)**: DCT katsayılarını yoğun eylem jetonlarına sıkıştırmak için bir BPE jetonlaştırıcı eğitin; bu, önceki jetonlaştırma yaklaşımlarına kıyasla tipik olarak **10x sıkıştırma** sağlar.

Bu yaklaşım, bu FAST tokenlarını tahmin etmesi için eğitilerek **mevcut herhangi bir VLM**'yi bir VLA'ya dönüştürebilir.

## Kurulum Gereksinimleri

1. LeRobot'u [Yükleme Kılavuzumuz](./installation)’u takip ederek yükleyin.
2. π₀-FAST bağımlılıklarını yüklemek için şunu çalıştırın:

   ```bash
   pip install -e ".[pi]"
   ```

## Özel Bir FAST Sözcük Üretici Eğitimi

FAST tokenizer için iki seçeneğiniz var:

1. **Önceden eğitilmiş belirteç ayrıştırıcısını kullanın**: `lerobot/fast-action-tokenizer` belirteç ayrıştırıcısı, 1M+ gerçek robot eylem dizisi üzerinde eğitilmiştir ve genel amaçlı bir belirteç ayrıştırıcısı olarak çalışır.

2. **Kendi tokenizörünüzü eğitin**: Belirli veri setinizde maksimum performans için, tokenizörü kendi verileriniz üzerinde ince ayarlayabilirsiniz.

### Kendi Tokenizer'ınızı Eğitme

```bash
lerobot-train-tokenizer \
    --repo_id "user/my-lerobot-dataset" \
    --action_horizon 10 \
    --encoded_dims "0:6" \
    --vocab_size 1024 \
    --scale 10.0 \
    --normalization_mode QUANTILES \
    --output_dir "./my_fast_tokenizer" \
    --push_to_hub true \
    --hub_repo_id "username/my-action-tokenizer"
```

### Önemli Tokenizer Parametreleri

| Parametre              | Açıklama                                                                       | Varsayılan      |
| ---------------------- | --------------------------------------------------------------------------------- | ------------ |
| `--repo_id`            | LeRobot veri seti deposu kimliği                                                     | Zorunlu     |
| `--action_horizon`     | Her parçadaki gelecek eylemlerin sayısı                                            | `10`         |
| `--encoded_dims`       | Kodlanacak virgülle ayrılmış boyut aralıkları (ör., `"0:6,7:23"`)                   | `"0:6,7:23"` |
| `--vocab_size`         | BPE sözlük boyutu                                                               | `1024`       |
| `--scale`              | Kantizasyon için DCT ölçekleme faktörü                                               | `10.0`       |
| `--normalization_mode` | Normalizasyon modu (`MEAN_STD`, `MIN_MAX`, `QUANTILES`, `QUANTILE10`, `IDENTITY`) | `QUANTILES`  |
| `--sample_fraction`    | Her bölümde örneklenmesi gereken parça oranı                                          | `0.1`        |

## Kullanım

LeRobot'ta π₀-FAST'ı kullanmak için politika türünü şu şekilde belirtin:

```python
policy.type=pi0_fast
```

## Eğitim

π₀-FAST'ı eğitmek için LeRobot eğitim betiğini kullanabilirsiniz:

```bash
lerobot-train \
    --dataset.repo_id=your_dataset \
    --policy.type=pi0_fast \
    --output_dir=./outputs/pi0fast_training \
    --job_name=pi0fast_training \
    --policy.pretrained_path=lerobot/pi0fast-base \
    --policy.dtype=bfloat16 \
    --policy.gradient_checkpointing=true \
    --policy.chunk_size=10 \
    --policy.n_action_steps=10 \
    --policy.max_action_tokens=256 \
    --steps=100000 \
    --batch_size=4 \
    --policy.device=cuda
```

### Temel Eğitim Parametreleri

| Parametre                              | Açıklama                                        | Varsayılan                         |
| -------------------------------------- | -------------------------------------------------- | ------------------------------- |
| `--policy.gradient_checkpointing=true` | Eğitim sırasında bellek kullanımını önemli ölçüde azaltır | `false`                         |
| `--policy.dtype=bfloat16`              | Verimlilik için karma hassasiyetli eğitim kullanın        | `float32`                       |
| `--policy.chunk_size`                  | Tahmin edilecek eylem adımı sayısı (eylem ufku) | `50`                            |
| `--policy.n_action_steps`              | Yürütülecek eylem adım sayısı                  | `50`                            |
| `--policy.max_action_tokens`           | Eylem parçası başına maksimum FAST jetonu sayısı     | `256`                           |
| `--policy.action_tokenizer_name`       | Kullanılacak FAST tokenizer                              | `lerobot/fast-action-tokenizer` |
| `--policy.compile_model=true`          | Daha hızlı eğitim için torch.compile'i etkinleştirin           | `false`                         |
| `--policy.optimizer_fused=true`        | Füzyonlu AdamW kullanılır; devam ettirme sırasında yok sayılır                 | `None`                          |

## Çıkarım

### Hızlı Çıkarım İçin KV-Önbellekleme

π₀-FAST, LLM çıkarımında yaygın olarak kullanılan bir optimizasyon olan **KV-caching** özelliğini destekler. Bu yöntem, dikkat mekanizmasından gelen anahtar-değer çiftlerini önbelleğe alarak otoregresif çözümleme sırasında gereksiz hesaplamaların önüne geçer.

```python
# KV-caching is enabled by default
policy.use_kv_cache=true
```

### Çıkarım Örneği

```python
from lerobot.policies.pi0_fast import PI0FastPolicy, PI0FastConfig

# Load the policy
policy = PI0FastPolicy.from_pretrained("your-model-path")

# During inference
actions = policy.predict_action_chunk(batch)
```

## Model Mimarisi

π₀-FAST, PaliGemma tabanlı bir mimari kullanır:

- **Görüntü Kodlayıcı**: Görüntü anlama için SigLIP görüntü kulesi
- **Dil Modeli**: Dil talimatlarını işleme ve eylem jetonlarını tahmin etme için Gemma 2B

Model, girdi olarak görüntüleri, metin talimatlarını ve robot durumunu alır ve sürekli eylemlere geri çözümlenen ayrık FAST jetonlarını çıktı olarak üretir.

## Yapılandırma Seçenekleri

| Parametre            | Açıklama                                     | Varsayılan    |
| -------------------- | ----------------------------------------------- | ---------- |
| `paligemma_variant`  | VLM omurga varyantı (`gemma_300m`, `gemma_2b`) | `gemma_2b` |
| `max_state_dim`      | Maksimum durum vektörü boyutu (dolgulu)         | `32`       |
| `max_action_dim`     | Maksimum eylem vektörü boyutu (dolgulu)        | `32`       |
| `temperature`        | Örnekleme sıcaklığı (açgözlü için 0.0)           | `0.0`      |
| `max_decoding_steps` | Maksimum çözümleme adımları                          | `256`      |
| `use_kv_cache`       | Daha hızlı çıkarım için KV önbellekleme etkinleştirin          | `true`     |

## π₀ ile karşılaştırma

| Özellik               | π₀                        | π₀-FAST                      |
| --------------------- | ------------------------- | ---------------------------- |
| Eylem Temsili | Flow Matching (Difüzyon) | Otomatik Geri Dönüşlü Jetonlar (FAST) |
| Eğitim Hızı        | 1x                        | **5 kat daha hızlı**                |
| Çeviklik             | Yüksek                      | Yüksek                         |
| Çıkarım Yöntemi      | İteratif Gürültü Azaltma       | Otomatik Geri Dönüşlü Çözümleme      |
| KV-Önbellekleme            | N/A                       | Destekleniyor                    |

## π₀Fast sonuçlarını yeniden üretme

LeRobot uygulamasını kullanarak π₀Fast sonuçlarını LIBERO benchmark'unda yeniden üretiyoruz. LeRobot PiFast temel modelini [lerobot/pi0fast-base](https://huggingface.co/lerobot/pi0fast-base) alıp, [HuggingFace LIBERO veri seti](https://huggingface.co/datasets/HuggingFaceVLA/libero) ile 8 H100 GPU üzerinde 256 batch boyutu ve bfloat16 ile ek 40k adım boyunca ince ayar yapıyoruz.

İnce ayarlanmış model burada bulunabilir:

- **π₀Fast LIBERO**: [lerobot/pi0fast-libero](https://huggingface.co/lerobot/pi0fast-libero)

Aşağıdaki eğitim komutuyla:

```bash
lerobot-train \
  --dataset.repo_id=lerobot/libero \
  --output_dir=outputs/libero_pi0fast \
  --job_name=libero_pi0fast \
  --policy.path=lerobot/pi0fast-base \
  --policy.dtype=bfloat16 \
  --steps=100000 \
  --save_freq=20000 \
  --batch_size=4 \
  --policy.device=cuda \
  --policy.scheduler_warmup_steps=4000 \
  --policy.scheduler_decay_steps=100000 \
  --policy.scheduler_decay_lr=1e-5 \
  --policy.gradient_checkpointing=true \
  --policy.chunk_size=10 \
  --policy.n_action_steps=10 \
  --policy.max_action_tokens=256 \
  --policy.empty_cameras=1
```

Ardından, finetuned modeli LeRobot LIBERO uygulamasını kullanarak aşağıdaki komutu çalıştırarak değerlendiririz:

```bash
tasks="libero_object,libero_spatial,libero_goal,libero_10"
lerobot-eval \
  --policy.path=lerobot/pi0fast-libero \
  --policy.max_action_tokens=256 \
  --env.type=libero \
  --policy.gradient_checkpointing=false \
  --env.task=${tasks} \
  --eval.batch_size=1 \
  --eval.n_episodes=1 \
  --rename_map='{"observation.images.image":"observation.images.base_0_rgb","observation.images.image2":"observation.images.left_wrist_0_rgb"}'
```

**Not:** Orijinal OpenPI uygulamasına benzer şekilde `n_action_steps=10` değerini ayarladık.

### Sonuçlar

LIBERO benchmark üzerinde aşağıdaki sonuçları elde ediyoruz:

| Model       | LIBERO Uzamsal | LIBERO Nesne | LIBERO Hedef | LIBERO 10 | Ortalama  |
| ----------- | -------------- | ------------- | ----------- | --------- | -------- |
| **π₀-fast** | 70.0           | 100.0         | 100.0       | 60.0      | **82.5** |

Videolar dahil olmak üzere tam değerlendirme çıktı klasörü [burada](https://drive.google.com/drive/folders/1HXpwPTRm4hx6g1sF2P7OOqGG0TwPU7LQ?usp=sharing) mevcuttur.

## Lisans

Bu model, orijinal [OpenPI deposu](https://github.com/Physical-Intelligence/openpi) ile tutarlı olarak **Apache 2.0 Lisansı**'na uyar.

## Referanslar

- [FAST: Verimli Robot Eylem Tokenizasyonu](https://www.physicalintelligence.company/research/fast) - Physical Intelligence Blog
- [OpenPI Deposu](https://github.com/Physical-Intelligence/openpi) - Orijinal uygulama
- [Hugging Face'ta FAST Tokenizer](https://huggingface.co/physical-intelligence/fast) - Ön eğitilmiş tokenizer