# FastWAM

FastWAM est une politique de modèle d’action-monde pour le contrôle de robots. L’intégration LeRobot expose FastWAM via l’API standard des politiques, ce qui permet de le configurer avec `policy.type=fastwam`, de l’entraîner avec `lerobot-train` et de le charger via l’interface de politique préentraînée de LeRobot.

## Aperçu du modèle

FastWAM conserve la modélisation vidéo pendant l’entraînement, mais utilise une prédiction directe des actions au moment de l’inférence au lieu de générer itérativement des observations futures. Cette politique LeRobot encapsule le modèle d’action FastWAM, adapte les lots LeRobot aux échantillons d’entraînement FastWAM et fournit le pipeline de processeur standard pour la normalisation et le post-traitement des actions.

L'implémentation initialise par défaut les composants du modèle de monde visuel à partir de `Wan-AI/Wan2.2-TI2V-5B` et prédit des blocs d'actions de forme `[batch, action_horizon, action_dim]`.

### Ce que couvre l'intégration LeRobot

- Configuration standard `policy.type=fastwam` via LeRobot
- Adaptation par lots pour les tâches d'image, d'état, d'action et de langage
- Inférence par morceaux d'actions via `select_action` et `predict_action_chunk`
- Sauvegarde/chargement de points de contrôle via les API de politique LeRobot
- Post-traitement configurable des actions de la pince LIBERO

## Prérequis d'installation

Installez LeRobot à partir du code source, puis installez les dépendances de FastWAM :

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

Cela installe les dépendances supplémentaires de la politique FastWAM depuis `pyproject.toml` : `transformers`, `diffusers`, `ftfy` et `regex`, ainsi que les dépendances de base de LeRobot.

Pour l'évaluation LIBERO, installez également les dépendances du benchmark :

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

Cela installe les deux extras. En plus des dépendances FastWAM ci-dessus, l’extra `libero` installe les dépendances du jeu de données LeRobot, `hf-libero` sur Linux, et `scipy`.

FastWAM utilise le backbone Wan2.2 TI2V. L'identifiant de modèle par défaut est :

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

## Exigences en matière de données

FastWAM s'attend à un jeu de données LeRobot avec :

- une ou plusieurs observations visuelles dont les largeurs concaténées correspondent à `policy.image_size[1]`
- `observation.state` lorsque `policy.proprio_dim` n'est pas `None`
- `action`
- une instruction de tâche linguistique via le champ de tâche du jeu de données, ou des tenseurs `context` et `context_mask` précalculés

La configuration visuelle par défaut est une caractéristique d’image nommée `observation.images.image` de forme `(3, 224, 448)`. Si le jeu de données utilise deux caméras, configurez `policy.input_features` afin que leurs hauteurs correspondent à `224` et que la somme de leurs largeurs soit égale à `448`.

## Utilisation

Créez une nouvelle politique FastWAM avec :

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

Évaluer un point de contrôle existant au format LeRobot sur LIBERO-10 avec :

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

Pour `libero_goal`, `libero_spatial` et `libero_object`, utilisez `--env.episode_length=300`.

Ce point de contrôle utilise le prétraitement `VISUAL: IDENTITY`. FastWAM redimensionne les images vers `[-1, 1]` à l’intérieur du modèle, de sorte qu’appliquer la normalisation d’images dans le préprocesseur les normaliserait deux fois.

Pour le déploiement sur un robot réel, utilisez le même chemin de point de contrôle :

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

## Notes de configuration

### Caractéristiques d'image

`policy.image_size` est la taille du tenseur d'image FastWAM concaténé, sous la forme `(height, width)`. Chaque fonction d'image configurée doit avoir la forme `(3, height, camera_width)`, et la somme de toutes les largeurs de caméra doit correspondre à la largeur configurée.

### Chunking d'actions

`policy.action_horizon` contrôle le nombre d’actions futures supervisées pendant l’entraînement et prédites lors de l’inférence. `policy.n_action_steps` contrôle le nombre d’actions consommées avant que la politique ne prédise un nouveau bloc. `policy.n_action_steps` doit être inférieur ou égal à `policy.action_horizon`.

### Actions relatives

FastWAM prédit des actions absolues par défaut. Avec `policy.use_relative_actions=true`, il prédit à la place des décalages par rapport à l'`observation.state` actuel, de sorte que `policy.proprio_dim` doit être défini. Les articulations nommées dans `policy.relative_exclude_joints` (par défaut `["gripper"]`) restent absolues. Recalculez d'abord les statistiques du jeu de données dans l'espace relatif, avec `--operation.chunk_size` défini sur `policy.action_horizon` (voir [actions relatives π₀.₅](./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"]' \
  ...
```

Les points de contrôle enregistrés avant l’existence des actions relatives, tels que `lerobot/fastwam_base`, se voient ajouter les étapes du processeur d’actions relatives lors de l’ajustement fin à partir d’eux avec cette option. Cela ne s’applique qu’au moment de l’ajustement fin : l’évaluation et le déroulement utilisent les processeurs enregistrés avec le point de contrôle tels qu’ils sont.

### Appareil de l'encodeur de texte

L’encodeur de texte UMT5-XXL gelé occupe environ 11 Go. `policy.text_encoder_device=cpu` le maintient hors du GPU : les prompts sont encodés sur le CPU et les embeddings sont déplacés vers `policy.device`. Pendant l’inférence, la tâche encodée est mise en cache jusqu’à `policy.reset()`, de sorte que l’encodage CPU, plus lent, n’est exécuté qu’une fois par épisode plutôt qu’une fois par chunk. L’entraînement encode chaque lot, ce qui ralentit donc chaque étape avec un placement sur CPU.

### Composants de Wan

FastWAM charge le VAE Wan, le DiT vidéo, l’encodeur de texte et le tokenizer à partir du répertoire du modèle Wan configuré ou de l’identifiant de modèle Hugging Face Hub. Les points de contrôle FastWAM au format LeRobot enregistrés par `save_pretrained` copient également les fichiers locaux des composants Wan nécessaires à `from_pretrained`.

### Backend d'attention

Le DiT de FastWAM utilise `scaled_dot_product_attention` (SDPA) de PyTorch pour toutes les attentions. Il n'**utilise pas** FlashAttention : son routage Mixture-of-Transformers (MoT) nécessite des masques d'attention booléens arbitraires `[query, key]`, que l'API varlen de FlashAttention ne peut pas exprimer. L'installation du package `flash-attn` n'a donc aucun effet sur le chemin FastWAM. (Notez que SDPA lui-même peut toujours sélectionner en interne le noyau flash / memory-efficient / math de PyTorch — cela est sans rapport avec le package `flash-attn`.)

### Inférence d'actions compilées

FastWAM peut compiler ses graphes de préremplissage vidéo et de débruitage d’actions en cache afin de réduire les surcoûts liés au lancement de noyaux Python et CUDA au fil des étapes d’inférence répétées :

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

L’option est désactivée par défaut. La première prédiction d’action compile un graphe pour les formes d’entrée actuelles et est donc plus lente ; les prédictions ultérieures avec les mêmes formes le réutilisent. Des changements de forme peuvent déclencher une recompilation. Le chemin eager reste disponible sur les configurations non prises en charge de PyTorch ou des accélérateurs.

### LIBERO Action Toggle

Les points de contrôle FastWAM LIBERO utilisent `policy.toggle_action_dimensions=[-1]` par défaut afin de correspondre à la convention d’action de la pince utilisée par le pipeline d’évaluation FastWAM d’origine :

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

## Résultats

Évalué sur LIBERO avec [`lerobot/fastwam_libero_uncond_2cam224`](https://huggingface.co/lerobot/fastwam_libero_uncond_2cam224) :

| Suite          | Taux de réussite | n_episodes |
| -------------- | -----------: | ---------: |
| libero_spatial |        97.6% |        500 |
| libero_object  |        99.0% |        500 |
| libero_goal    |        95.0% |        500 |
| libero_10      |        94.0% |        500 |
| **moyenne**    |    **96.4%** |       2000 |

Reproduction : `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 Go).

## Références

- [article Fast-WAM](https://arxiv.org/abs/2603.16666)
- [Page du projet Fast-WAM](https://yuantianyuan01.github.io/FastWAM/)
- [Code Fast-WAM](https://github.com/yuantianyuan01/FastWAM)
- [Points de contrôle publiés en amont](https://huggingface.co/yuanty/fastwam)
- [Wan2.2 TI2V 5B](https://huggingface.co/Wan-AI/Wan2.2-TI2V-5B)

## Citation

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