# EO-1

EO-1 adalah **kebijakan Vision-Language-Action untuk pengendalian robot**. Implementasi LeRobot mengintegrasikan EO-1 dengan antarmuka pelatihan, evaluasi, dan pemroses standar LeRobot.

## Ringkasan Model

EO-1 menggunakan backbone Qwen2.5-VL untuk pemahaman vision-language dan menambahkan kepala aksi flow-matching kontinu untuk kontrol robot. Kebijakan ini memformat setiap sampel kontrol robot sebagai percakapan multimodal: gambar kamera diteruskan ke Qwen2.5-VL, keadaan robot direpresentasikan dengan token keadaan EO-1, dan chunk aksi masa depan direpresentasikan dengan token aksi EO-1.

<img
  src="https://huggingface.co/datasets/HaomingSong/lerobot-documentation-images/resolve/main/lerobot/eo_pipeline.png"
  alt="An overview of EO-1"
  width="85%"
/>

Selama pelatihan, EO-1 belajar untuk mendenois chunk aksi kontinu pada posisi token aksi. Selama inferensi, ia mengambil sampel sebuah chunk aksi, mengembalikan aksi kontinu, dan mengeksekusi `n_action_steps` dari chunk tersebut sebelum mengambil sampel lagi.

### Cakupan Integrasi LeRobot

- Konfigurasi `policy.type=eo1` standar melalui LeRobot
- Prapemrosesan gambar dan teks Qwen2.5-VL melalui prosesor kebijakan
- Prediksi aksi flow-matching kontinu
- Menyimpan/memuat checkpoint melalui API kebijakan LeRobot
- Pelatihan dengan `lerobot-train` dan evaluasi dengan `lerobot-eval`

Proyek EO-1 yang lebih luas juga mencakup pra-pelatihan aksi-teks-visi yang diselang-seling serta alur kerja penalaran multimodal. Halaman ini berfokus pada jalur kebijakan kontrol robot LeRobot.

## Persyaratan Instalasi

1. Install LeRobot dengan mengikuti [Panduan Instalasi](./installation).
2. Instal dependensi EO-1 dengan menjalankan:

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

3. Jika Anda ingin melatih atau mengevaluasi pada LIBERO, instal juga dependensi LIBERO:

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

EO-1 dapat menggunakan backend scaled-dot-product attention standar PyTorch melalui `policy.attn_implementation=sdpa`. Jika lingkungan Anda memiliki instalasi `flash_attn` yang kompatibel, Anda dapat meminta `policy.attn_implementation=flash_attention_2`.

## Kebutuhan Data

EO-1 mengharapkan dataset LeRobot dengan:

- Minimal satu pengamatan visual, misalnya `observation.images.image`
- `observation.state`
- `action`
- Instruksi tugas bahasa melalui field `task` dataset

Jika dataset Anda menggunakan nama observasi yang berbeda, gunakan `rename_map` untuk menyelaraskannya dengan nama yang diharapkan oleh setup pelatihan atau evaluasi Anda.

## Penggunaan

Untuk menggunakan EO-1 dalam konfigurasi LeRobot, tentukan tipe kebijakan sebagai:

```python
policy.type=eo1
```

Gunakan checkpoint rilis yang telah dikonversi untuk memulai dari pra-pelatihan aksi-teks-visi yang diselang-selingkan dari EO-1:

```bash
--policy.path=lerobot/eo1-base
```

`lerobot/eo1-base` adalah konversi native LeRobot dari [`IPEC-COMMUNITY/EO-1-3B`](https://huggingface.co/IPEC-COMMUNITY/EO-1-3B). Model ini mempertahankan bobot vision-language Qwen yang dirilis dan kepala aksi flow-matching yang telah dilatih. Ukuran chunk aksinya adalah 16, sesuai dengan checkpoint upstream. Untuk menginisialisasi hanya dari backbone Qwen asli, hilangkan `policy.path` dan atur `policy.vlm_base=Qwen/Qwen2.5-VL-3B-Instruct`.

Muat checkpoint EO-1 format LeRobot yang telah dihaluskan lainnya dengan:

```python
policy.path=your-org/your-eo1-checkpoint
```

### Generasi teks dan kontrol interaktif

EO-1 mengekspos backbone Qwen melalui kontrak teks kebijakan bersama. Runtime menambahkan `query_kind` dan `query_text`, lalu menjalankan pemroses input EO-1 yang normal:

```python
request = {
    **observation,
    "query_kind": "vqa",
    "query_text": "Which object is closest to the gripper?",
}
processed_batch = preprocessor(request)
answer = policy.generate_text(processed_batch)
```

`vqa` mempertahankan pertanyaan pemanggil. `next_subtask` menerapkan resep yang disimpan dalam konfigurasi kebijakan EO-1. EO-1 mewarisi `generate_text(processed_batch)` dan menimpa `supports_text_generation` serta `generate_text`; tidak ada VLM terpisah yang dimuat.

Dengan runtime bahasa interaktif, EO-1 dapat menghasilkan subtask dan membangun ulang prompt aksinya dari subtask saat ini:

```bash
# Use the robot, port and cameras your checkpoint was trained with
lerobot-rollout \
  --policy.path=your-org/your-eo1-checkpoint \
  --policy.device=cuda \
  --robot.type=so101_follower \
  --robot.port=/dev/ttyACM0 \
  --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
  --task="clear the table" \
  --interactive=true
```

Setelah `/start`, gunakan `/vqa <question>`, `/autosteer <goal>`, atau `/subtask <text>`.

## Pelatihan

### Contoh Perintah Pelatihan

```bash
lerobot-train \
  --dataset.repo_id=your_org/your_dataset \
  --policy.path=lerobot/eo1-base \
  --policy.dtype=bfloat16 \
  --policy.attn_implementation=sdpa \
  --policy.gradient_checkpointing=false \
  --output_dir=./outputs/eo1_training \
  --job_name=eo1_training \
  --steps=300000 \
  --batch_size=16 \
  --policy.device=cuda
```

### Latih dengan anotasi bahasa

`EO1Config` mencakup resep untuk melatih dari kolom bahasa opsional LeRobot. Resep gabungan bawaan mengawasi respons asisten yang dipilih dan chunk aksi kontinu-nya dalam urutan yang sama:

```bash
lerobot-train \
  --dataset.repo_id=your_org/your_language_annotated_dataset \
  --policy.type=eo1 \
  --policy.text_loss_weight=0.01 \
  --policy.flow_loss_weight=1.0 \
  --policy.device=cuda \
  --batch_size=1 \
  --steps=20000
```

Asisten yang ditargetkan menerima cross-entropy token berikutnya, sementara aliran resep `low_level` menerima supervisi aksi aliran. Sebuah baris dapat menerima salah satu tujuan atau keduanya. Prompt pengguna, gambar, token keadaan, token aksi, dan padding dikecualikan dari kerugian teks. Atur `policy.recipe=null` untuk menonaktifkan perenderan resep dan menggunakan jalur pelatihan hanya-aksi asli.

Lihat [kolom bahasa dan resep](./language_and_recipes) untuk skema anotasi dan struktur resep. `recipe_path` dapat menunjuk ke override YAML eksternal yang eksplisit; LeRobot tidak menyediakan file resep default bersama. Prompt sistem default merupakan bagian dari resep EO1 dan dapat diganti dengan giliran sistem kustom. Input yang dirender tanpa giliran sistem, termasuk prompt VQA, tetap tanpa giliran sistem. Jalur hanya-aksi tanpa pesan yang dirender mempertahankan prompt sistem default. `EO1PrepareModelMessagesStep` menambahkan gambar dan token state/aksi ke pesan yang dirender sebelum format Qwen dan tokenisasi.

### Parameter Pelatihan Utama

| Parameter                              | Default                       | Deskripsi                                                             |
| -------------------------------------- | ----------------------------- | ----------------------------------------------------------------------- |
| `policy.path`                          | `lerobot/eo1-base`            | Bobot EO-1 yang dirilis telah dikonversi ke format LeRobot native                |
| `policy.vlm_base`                      | `Qwen/Qwen2.5-VL-3B-Instruct` | Qwen processor/backbone yang hanya digunakan saat pelatihan tanpa `policy.path`   |
| `policy.dtype`                         | `bfloat16`                    | Permintaan dtype backbone: nama dtype torch, misalnya `bfloat16`, `float32`  |
| `policy.attn_implementation`           | `None`                        | Backend perhatian Qwen opsional, seperti `sdpa`                         |
| `policy.gradient_checkpointing`        | `false`                       | Mengurangi penggunaan memori selama pelatihan                                    |
| `policy.chunk_size`                    | `16`                          | Jumlah aksi masa depan yang diprediksi per chunk                            |
| `policy.n_action_steps`                | `16`                          | Jumlah aksi yang dikonsumsi dari chunk yang disampel                         |
| `policy.num_denoise_steps`             | `10`                          | Jumlah langkah denoising flow-matching yang digunakan selama sampling            |
| `policy.max_state_dim`                 | `32`                          | Dimensi padding State                                                 |
| `policy.max_action_dim`                | `32`                          | Dimensi padding aksi                                                |
| `policy.force_fp32_autocast`           | `true`                        | Menjaga flow head dalam fp32 meskipun backbone menggunakan presisi campuran |
| `policy.supervise_padding_action_dims` | `true`                        | Mengontrol apakah dimensi aksi yang di-*pad* diawasi                |
| `policy.supervise_padding_actions`     | `true`                        | Mengontrol apakah baris aksi masa depan yang di-*padding* diawasi               |
| `policy.recipe_path`                   | `None`                        | Mengaktifkan pengawasan teks berbasis resep dan tindakan per sampel            |
| `policy.text_loss_weight`              | `0.01`                        | Bobot untuk entropi silang token asisten yang diawasi                     |
| `policy.flow_loss_weight`              | `1.0`                         | Bobot untuk kerugian aliran-aksi kontinu                                  |
| `policy.tokenizer_max_length`          | `1000`                        | Panjang maksimum urutan gabungan visi-bahasa-aksi                    |

## Evaluasi

EO-1 dapat dievaluasi melalui `lerobot-eval` setelah Anda memiliki checkpoint dalam format LeRobot:

```bash
lerobot-eval \
  --policy.path=your-org/your-eo1-checkpoint \
  --env.type=libero \
  --env.task=libero_object \
  --eval.batch_size=1 \
  --eval.n_episodes=20
```

Untuk dataset atau lingkungan yang nama kameranya berbeda dari konfigurasi checkpoint, berikan `rename_map`:

```bash
lerobot-eval \
  --policy.path=your-org/your-eo1-checkpoint \
  --env.type=libero \
  --env.task=libero_object \
  --rename_map='{"observation.images.image2":"observation.images.wrist_image"}'
```

## Catatan Konfigurasi

### Pemrosesan Gambar

EO-1 menggunakan prosesor Qwen2.5-VL. Pengaturan `policy.image_min_pixels` dan `policy.image_max_pixels` mengontrol batas pengubahan ukuran gambar sebelum token visual diteruskan ke backbone.

### Dimensi State dan Action

Kebijakan mengisi vektor state dan action hingga `policy.max_state_dim` dan `policy.max_action_dim` sebelum head alur EO-1. Prediksi dipangkas kembali ke dimensi action asli sebelum dikembalikan oleh kebijakan.

### Backend Atensi

Gunakan `policy.attn_implementation=sdpa` untuk setup yang portabel. Gunakan `flash_attention_2` hanya jika `flash_attn` terinstal dan kompatibel dengan lingkungan Anda.

## Referensi

- [Proyek EO-1](https://github.com/EO-Robotics/EO1)
- [paper EO-1](https://arxiv.org/abs/2508.21112)
- [Qwen2.5-VL-3B-Instruct](https://huggingface.co/Qwen/Qwen2.5-VL-3B-Instruct)

## Sitasi

```bibtex
@article{eo1,
  title={EO-1: Interleaved Vision-Text-Action Pretraining for General Robot Control},
  author={Delin Qu and Haoming Song and Qizhi Chen and Zhaoqing Chen and Xianqiang Gao and Xinyi Ye and Qi Lv and Modi Shi and Guanghui Ren and Cheng Ruan and Maoqing Yao and Haoran Yang and Jiacheng Bao and Bin Zhao and Dong Wang},
  journal={arXiv preprint},
  year={2025},
  url={https://arxiv.org/abs/2508.21112}
}
```

## Lisensi

Integrasi LeRobot ini mengikuti **Lisensi Apache 2.0** yang digunakan oleh LeRobot. Periksa halaman model dan dataset EO-1 upstream untuk lisensi checkpoint dan data EO-1 yang dirilis.