# WALL-OSS

WALL-OSS adalah model fondasi open-source untuk kecerdasan embodied, yang diusulkan oleh tim [XSquare Robot](https://x2robot.com/en/research/68bc2cde8497d7f238dde690) pada tahun 2025. Implementasi LeRobot diadaptasi dari repositori open-source [WallX](https://github.com/X-Square-Robot/wall-x) mereka.

WALL-OSS dari X Square Robot kini terintegrasi ke dalam ekosistem LeRobot milik Hugging Face. Ini adalah proyek kolaboratif yang menarik antara tim LeRobot dan tim X Square Robot. Anda kini dapat melakukan post-training, evaluasi, dan deployment WALL-OSS secara langsung melalui LeRobot. Dengan ini, kami bertujuan untuk memudahkan komunitas robotika open-source dalam menyesuaikan dan mendeploy model dasar WALL-OSS. Baca dan jelajahi [paper](https://arxiv.org/pdf/2509.11766) dan [code](https://github.com/X-Square-Robot/wall-x) WALL-OSS.

## Ringkasan Model

Tim WALL-OSS sedang membangun model dasar embodied untuk menangkap dan mengompres data paling berharga di dunia: aliran interaksi fisik yang kontinu dan ber-fidelitas tinggi. Dengan menciptakan umpan balik langsung antara keputusan model dan pengalaman hidup tubuh, munculnya kecerdasan yang benar-benar dapat digeneralisasi menjadi memungkinkan—kecerdasan yang tidak hanya memahami bagaimana dunia bekerja, tetapi juga bagaimana bertindak secara efektif di dalamnya.

<img
  src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/walloss-lerobot-paper.png"
  alt="An overview of WALL-OSS"
  width="85%"
/>

Secara teknis, WALL-OSS memperkenalkan arsitektur multimodal yang terintegrasi erat (struktur MoE yang terintegrasi erat) yang menggabungkan strategi pemodelan aksi diskrit dan kontinu. Melalui pipeline pelatihan dua tahap (Inspirasi → Integrasi), model secara bertahap menyatukan penalaran semantik dan generasi aksi frekuensi tinggi. Inovasi intinya meliputi:

- **Prapelatihan multimodal yang ditingkatkan dengan persepsi berwujud**: Pelatihan berskala besar pada data terpadu visi–bahasa–aksi untuk memperkuat pemahaman spasial, kausal, dan manipulasi.
- **Unified Cross-Level Chain-of-Thought (Uni-CoT)**: Kerangka kerja diferensiable tunggal yang menyatukan penalaran instruksi tingkat tinggi, dekomposisi sub-tugas, dan sintesis aksi bergranularitas halus, membentuk rantai kontinu dari “pemahaman” hingga “eksekusi.”
- **Head aksi Mixture-of-Experts (MoE)**: Mengaktifkan pakar secara dinamis tergantung pada fase tugas dan memodelkan aksi dalam ruang diskrit atau kontinu untuk mempertahankan prior VLM yang stabil.
- **Paradigma pelatihan dua tahap**:
  - **Tahap inspirasi**: Menyuntikkan prior aksi diskrit untuk memperkuat pemahaman spasial dan keselarasan semantik-aksi.
  - **Tahap integrasi**: Menggunakan flow matching untuk mencapai kontrol kontinu berfrekuensi tinggi.

## Persyaratan Instalasi

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

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

## Penggunaan

Untuk menggunakan WallX di LeRobot, tentukan jenis kebijakan sebagai:

```python
policy.type=wall_x
```

### Generasi teks dan kontrol interaktif

WALL-OSS mengekspos generasi teks asli melalui kontrak kebijakan dari [Bawa kebijakan Anda sendiri](./bring_your_own_policies#text-capable-policies). Runtime menyediakan `query_kind` dan `query_text` yang dimiliki pemanggil sebelum menjalankan pipeline input normal WALL-OSS:

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

`vqa` mempertahankan pertanyaan sebagai payload pengguna. `next_subtask` menerapkan resep checkpoint sebelum `${subtask}`. WALL-X secara langsung menimpa API publik `generate_text(processed_batch)` untuk ahli vision-language Qwen-nya dan melaporkan kemampuan tersebut melalui `supports_text_generation()`.

Runtime bahasa interaktif dapat menghasilkan subtask dan kemudian mengondisikan prediksi aksi WALL-OSS berdasarkan subtask tersebut:

```bash
lerobot-rollout \
  --strategy.type=base \
  --policy.path=your-org/your-wall-oss-checkpoint \
  --robot.type=your_robot_type \
  --robot.port=/dev/your_robot_port \
  --task="clear the table" \
  --interactive=true
```

Setelah `/start`, gunakan `/vqa <question>` untuk VQA berbasis gambar atau `/autosteer <goal>` untuk generasi subtask berikutnya yang didukung resep. `/subtask <text>` melewati proses generasi dan mengirim instruksi langsung ke inferensi aksi.

## Pelatihan

Untuk melatih WallX, Anda dapat menggunakan skrip pelatihan LeRobot standar dengan konfigurasi yang sesuai:

```bash
lerobot-train \
    --dataset.repo_id=your_dataset \
    --policy.type=wall_x \
    --output_dir=./outputs/wallx_training \
    --job_name=wallx_training \
    --policy.repo_id=your_repo_id \
    --policy.pretrained_name_or_path=x-square-robot/wall-oss-flow \
    --policy.prediction_mode=diffusion \
    --policy.attn_implementation=eager \
    --steps=3000 \
    --policy.device=cuda \
    --batch_size=32
```

### Latih dengan anotasi bahasa

WALL-X menggunakan resep bawaannya untuk melatih dari kolom bahasa opsional LeRobot. Atur `recipe_path` hanya untuk mengganti resep tersebut:

```bash
lerobot-train \
  --dataset.repo_id=your_org/your_language_annotated_dataset \
  --policy.type=wall_x \
  --policy.pretrained_name_or_path=x-square-robot/wall-oss-flow \
  --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 pengawasan aksi-aliran yang berkelanjutan. Sebuah baris dapat menerima salah satu tujuan atau keduanya. Prompt pengguna, gambar, propriosepsi, token kueri aksi, dan padding dikecualikan dari kerugian teks. Atur `policy.recipe=null` untuk menggunakan jalur pelatihan hanya-aksi asli dari WALL-OSS.

Lihat [Kolom bahasa dan resep](./language_and_recipes) untuk skema anotasi dan resep yang tersedia.

### Argumen Pelatihan

| Argumen                           | Deskripsi                                                                                                                                                   |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--dataset.repo_id`                | ID repositori Hugging Face Hub untuk dataset pelatihan Anda (misalnya, `lerobot/aloha_sim_insertion_human`)                                                      |
| `--policy.type`                    | Menentukan penggunaan arsitektur kebijakan WallX                                                                                                                 |
| `--output_dir`                     | Direktori lokal tempat checkpoint pelatihan dan log akan disimpan                                                                                             |
| `--job_name`                       | Pengidentifikasi nama untuk sesi pelatihan ini (digunakan dalam pencatatan/penelusuran)                                                                                            |
| `--policy.repo_id`                 | ID repo Hugging Face Hub Anda tempat model terlatih akan didorong                                                                                          |
| `--policy.pretrained_name_or_path` | Path ke bobot WallX pretrained untuk inisialisasi (checkpoint WALL-OSS resmi)                                                                        |
| `--policy.prediction_mode`         | Strategi prediksi aksi: `diffusion` atau `fast` - `diffusion` menggunakan denoising iteratif untuk menghasilkan aksi, sedangkan `fast` menggunakan prediksi token berikutnya |
| `--policy.attn_implementation`     | Backend implementasi attention - `eager` menggunakan attention PyTorch standar (alternatifnya termasuk `flash_attention_2` atau `sdpa`)                               |
| `--steps`                          | Jumlah total langkah pelatihan yang akan dijalankan                                                                                                                         |
| `--policy.device`                  | Perangkat untuk pelatihan (`cuda` untuk GPU, `cpu` untuk CPU)                                                                                                            |
| `--batch_size`                     | Jumlah sampel per batch pelatihan                                                                                                                          |

Pelatihan bahasa menggunakan `policy.text_loss_weight` (default `0.01`), `policy.flow_loss_weight` (default `1.0`), dan `policy.tokenizer_max_length` (default `768`). `policy.recipe_path` secara opsional menggantikan resep bawaan.

## Lisensi

Model ini mengikuti **Lisensi Apache 2.0**, yang konsisten dengan [repositori WallX](https://github.com/X-Square-Robot/wall-x) asli.

