# FastWAM

FastWAM, robot kontrolü için bir Dünya Eylem Modeli politikasıdır. LeRobot entegrasyonu, FastWAM'i standart politika API'si üzerinden açığa çıkarır; böylece `policy.type=fastwam` ile yapılandırılabilir, `lerobot-train` ile eğitilebilir ve LeRobot önceden eğitilmiş politika arayüzü üzerinden yüklenebilir.

## Model Genel Bakış

FastWAM, eğitim sırasında video modellemeyi korurken, çıkarım sırasında gelecekteki gözlemleri iteratif olarak üretmek yerine doğrudan eylem tahmini kullanır. Bu LeRobot politikası, FastWAM eylem modelini sarmalar, LeRobot topluluklarını FastWAM eğitim örneklerine uyarlar ve normalizasyon ile eylem son işlemesi için standart işlemci hattını sağlar.

Uygulama, varsayılan olarak görsel dünya modeli bileşenlerini `Wan-AI/Wan2.2-TI2V-5B` modelinden başlatır ve `[batch, action_horizon, action_dim]` biçiminde eylem parçacıklarını tahmin eder.

### LeRobot Entegrasyonunun Kapsamı

- LeRobot üzerinden standart `policy.type=fastwam` yapılandırması
- Görsel, durum, eylem ve dil görevi toplu uyarlama
- `select_action` ve `predict_action_chunk` ile eylem parçası çıkarımı
- LeRobot politika API'leri üzerinden checkpoint kaydetme/yükleme
- Yapılandırılabilir LIBERO gripper eylemi son işleme

## Kurulum Gereksinimleri

LeRobot'u kaynak kodundan kurun, ardından FastWAM bağımlılıklarını kurun:

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

Bu, `pyproject.toml` dosyasından FastWAM policy ekini yükler: `transformers`, `diffusers`, `ftfy` ve `regex`, ayrıca LeRobot'un temel bağımlılıkları.

LIBERO değerlendirmesi için, benchmark bağımlılıklarını da yükleyin:

```bash
pip install -e ".[fastwam,libero]"
```

Bu komut, her iki ek paketi de yükler. Yukarıdaki FastWAM bağımlılıklarının yanı sıra `libero` ek paketi, LeRobot veri seti bağımlılıklarını, Linux üzerinde `hf-libero` ve `scipy` paketlerini yükler.

FastWAM, Wan2.2 TI2V omurgasını kullanır. Varsayılan model kimliği şudur:

```python
policy.model_id=Wan-AI/Wan2.2-TI2V-5B
```

## Veri Gereksinimleri

FastWAM, aşağıdaki özelliklere sahip bir LeRobot veri seti bekler:

- genişlikleri `policy.image_size[1]` değerine birleşen bir veya daha fazla görsel gözlem
- `policy.proprio_dim` `None` değilse `observation.state`
- `action`
- veri seti görev alanı aracılığıyla bir dil görevi talimatı veya önceden hesaplanmış `context` ve `context_mask` tensörleri

Varsayılan görsel yapılandırma, `(3, 224, 448)` biçimine sahip `observation.images.image` adında tek bir görüntü özelliğidir. Veri seti iki kamera kullanıyorsa, `policy.input_features` yapılandırmasını, yüksekliklerinin `224` ile eşleşmesi ve genişliklerinin toplamının `448` olması şeklinde ayarlayın.

## Kullanım

Şu şekilde yeni bir FastWAM politikası oluşturun:

```bash
lerobot-train \
  --dataset.repo_id=your-org/your-dataset \
  --policy.type=fastwam \
  --policy.action_dim=7 \
  --policy.proprio_dim=8 \
  --policy.action_horizon=32 \
  --policy.n_action_steps=10 \
  --policy.image_size='[224,448]' \
  --output_dir=./outputs/fastwam_training \
  --job_name=fastwam_training \
  --steps=300000 \
  --batch_size=8 \
  --policy.device=cuda
```

Mevcut bir LeRobot biçiminde kontrol noktasını LIBERO-10 üzerinde şu komutla değerlendirin:

```bash
lerobot-eval \
  --policy.path=lerobot/fastwam_libero_uncond_2cam224 \
  --policy.device=cuda \
  --policy.dtype=float32 \
  --policy.n_action_steps=10 \
  --env.type=libero \
  --env.task=libero_10 \
  --env.observation_height=224 \
  --env.observation_width=224 \
  --eval.batch_size=1 \
  --eval.n_episodes=50 \
  --seed=0 \
  --env.episode_length=600
```

`libero_goal`, `libero_spatial` ve `libero_object` için `--env.episode_length=300` kullanın.

Bu checkpoint `VISUAL: IDENTITY` ön işleme kullanır. FastWAM, görüntüleri model içinde `[-1, 1]` aralığına yeniden ölçekler; bu nedenle ön işleyicide görüntü normalizasyonu uygulanırsa görüntüler iki kez normalize edilmiş olur.

Gerçek robot dağıtımı için aynı kontrol noktası yolunu kullanın:

```bash
lerobot-rollout \
  --robot.type=so101_follower \
  --robot.port=/dev/ttyACM0 \
  --policy.path=your-org/fastwam-real-robot
```

## Yapılandırma Notları

### Görsel Özellikleri

`policy.image_size`, birleştirilmiş FastWAM görüntü tensörünün `(height, width)` biçimindeki boyutudur. Yapılandırılan her görüntü özelliğinin şekli `(3, height, camera_width)` olmalı ve tüm kamera genişliklerinin toplamı yapılandırılan genişliğe eşit olmalıdır.

### Eylem Parçalama

`policy.action_horizon`, eğitim sırasında denetlenen ve çıkarım sırasında tahmin edilen gelecek eylem sayısını kontrol eder. `policy.n_action_steps`, politika yeni bir blok tahmin etmeden önce kaç eylemin tüketileceğini kontrol eder. `policy.n_action_steps`, `policy.action_horizon` değerinden küçük veya eşit olmalıdır.

### Göreceli Eylemler

FastWAM varsayılan olarak mutlak eylemleri tahmin eder. `policy.use_relative_actions=true` ile mevcut `observation.state` değerinden sapmaları tahmin eder; bu nedenle `policy.proprio_dim` ayarlanmalıdır. `policy.relative_exclude_joints` içinde adları belirtilen eklemeler (varsayılan `["gripper"]`) mutlak olarak kalır. Önce `--operation.chunk_size` parametresini `policy.action_horizon` değerine ayarlayarak veri seti istatistiklerini göreli uzayda yeniden hesaplayın (bkz. [π₀.₅ göreli eylemler](./pi05#relative-actions)):

```bash
lerobot-train \
  --dataset.repo_id=your-org/your-dataset \
  --policy.type=fastwam \
  --policy.use_relative_actions=true \
  --policy.relative_exclude_joints='["gripper"]' \
  ...
```

Göreceli eylemler mevcut olmadan önce kaydedilen kontrol noktaları, örneğin `lerobot/fastwam_base`, bu seçenekle onlardan ince ayar yapılırken göreceli-eylem işlemci adımlarını eklenir. Bu yalnızca ince ayar sırasında geçerlidir: değerlendirme ve dağıtım, kontrol noktasıyla birlikte kaydedilen işlemcileri olduğu gibi kullanır.

### Metin Kodlayıcı Cihazı

Donmuş UMT5-XXL metin kodlayıcı yaklaşık 11 GB yer kaplar. `policy.text_encoder_device=cpu` onu GPU dışında tutar: istemler CPU üzerinde kodlanır ve gömceler `policy.device` adresine taşınır. Çıkarım sırasında kodlanmış görev, `policy.reset()` çağrılana kadar önbelleğe alınır; bu sayede daha yavaş olan CPU kodlama işlemi her parça için değil, her bölüm için yalnızca bir kez çalışır. Eğitimde ise her parti kodlandığı için CPU yerleşimi her adımı yavaşlatır.

### Wan Bileşenleri

FastWAM, yapılandırılmış Wan model dizininden veya Hugging Face Hub model kimliğinden Wan VAE, video DiT, metin kodlayıcı ve belirteç oluşturucuyu yükler. `save_pretrained` tarafından kaydedilen LeRobot biçimindeki FastWAM denetim noktaları, `from_pretrained` tarafından gereken yerel Wan bileşen dosyalarını da kopyalar.

### Dikkat Arka Ucu

FastWAM'ın DiT'si, tüm dikkat işlemleri için PyTorch'un `scaled_dot_product_attention` (SDPA) bileşenini kullanır. FlashAttention **kullanmaz**: Mixture-of-Transformers (MoT) yönlendirmesi, FlashAttention varlen API'sinin ifade edemediği, keyfi boolean `[query, key]` dikkat maskeleri gerektirir. Bu nedenle `flash-attn` paketinin yüklenmesi, FastWAM yolunda herhangi bir etkiye sahip değildir. (SDPA'nın kendisinin, PyTorch'un kendi flash / memory-efficient / math çekirdeğini içsel olarak seçebileceğini unutmayın — bu, `flash-attn` paketiyle ilgisizdir.)

### Derlenmiş Eylem Çıkarımı

FastWAM, tekrarlanan çıkarım adımlarında Python ve CUDA çekirdek başlatma yükünü azaltmak için video ön-doldurma ve önbelleğe alınmış eylem gürültü azaltma grafiklerini derleyebilir:

```bash
--policy.compile_action_infer=true
```

Seçenek varsayılan olarak devre dışıdır. İlk eylem tahmini, mevcut girdi biçimleri için bir grafik derler ve bu nedenle daha yavaştır; aynı biçimlere sahip sonraki tahminler bu grafiği yeniden kullanır. Biçim değişiklikleri yeniden derlemeyi tetikleyebilir. Desteklenmeyen PyTorch veya hızlandırıcı yapılandırmalarında acil yol (eager path) kullanılabilir kalmaya devam eder.

### LIBERO Eylem Anahtarı

FastWAM LIBERO checkpoint'leri, orijinal FastWAM değerlendirme hattında kullanılan kavrama eylem sözleşmesiyle uyumlu olmak için varsayılan olarak `policy.toggle_action_dimensions=[-1]` kullanır:

```bash
--policy.toggle_action_dimensions='[-1]'
```

## Sonuçlar

LIBERO üzerinde [`lerobot/fastwam_libero_uncond_2cam224`](https://huggingface.co/lerobot/fastwam_libero_uncond_2cam224) ile değerlendirildi:

| Suite          | Başarı oranı | n_episodes |
| -------------- | -----------: | ---------: |
| libero_spatial |        97.6% |        500 |
| libero_object  |        99.0% |        500 |
| libero_goal    |        95.0% |        500 |
| libero_10      |        94.0% |        500 |
| **ortalama**    |    **96.4%** |       2000 |

Yeniden üretin: `lerobot-eval --policy.path=lerobot/fastwam_libero_uncond_2cam224 --policy.device=cuda --policy.dtype=float32 --policy.n_action_steps=10 --env.type=libero --env.task=libero_spatial --env.observation_height=256 --env.observation_width=256 --eval.batch_size=1 --eval.n_episodes=50 --seed=0 --env.episode_length=300` (1x H20 140 GB).

## Referanslar

- [Fast-WAM makalesi](https://arxiv.org/abs/2603.16666)
- [Fast-WAM proje sayfası](https://yuantianyuan01.github.io/FastWAM/)
- [Fast-WAM kodu](https://github.com/yuantianyuan01/FastWAM)
- [Yayınlanan upstream denetim noktaları](https://huggingface.co/yuanty/fastwam)
- [Wan2.2 TI2V 5B](https://huggingface.co/Wan-AI/Wan2.2-TI2V-5B)

## Atıf

```bibtex
@article{yuan2026fastwam,
  title = {Fast-WAM: Do World Action Models Need Test-time Future Imagination?},
  author = {Tianyuan Yuan and Zibin Dong and Yicheng Liu and Hang Zhao},
  journal = {arXiv preprint arXiv:2603.16666},
  year = {2026},
  url = {https://arxiv.org/abs/2603.16666}
}
```