# Wall-OSS-0.5

Wall-OSS-0.5 adalah model vision-language-action 4B dari [XSquare Robot](https://x2robot.com/en/research/68bc2cde8497d7f238dde690). Model ini menggabungkan backbone vision-language Qwen2.5-VL dengan pakar aksi flow-matching kontinu.

LeRobot menyediakan Wall-OSS-0.5 melalui tipe kebijakan `wall_oss_05` dan checkpoint [`lerobot/wall-oss-0.5`](https://huggingface.co/lerobot/wall-oss-0.5).

`wall_oss_05` dan kebijakan `wall_x` yang ada menargetkan rilis WALL yang berbeda. Gunakan `wall_oss_05` dengan checkpoint Wall-OSS-0.5.

## Ringkasan Model

Wall-OSS-0.5 mengondisikan generasi aksi pada pengamatan kamera, status robot, dan tugas dalam bahasa alami. Kebijakan ini memprediksi sepotong aksi kontinu dengan flow matching. Pakar bahasa-visi-nya juga dapat menghasilkan teks untuk captioning, visual question answering, grounding, dan subtask bahasa.

Model yang dirilis menggunakan:

- representasi state dan aksi kanonik berdimensi 26;
- chunk aksi 32 langkah;
- normalisasi rentang q01/q99;
- sampler alur 10 langkah;
- Qwen2.5-VL untuk input visual dan bahasa.

Checkpoint dasar dimaksudkan untuk fine-tuning pada dataset robot dan tugas target sebelum deployment.

### Cakupan Integrasi LeRobot

- Konfigurasi standar `policy.type=wall_oss_05` dan pemuatan checkpoint Hub.
- Pemrosesan bahasa-visi Qwen2.5-VL asli dan pakar aksi Wall.
- Pelatihan aliran prediksi-x kontinu dan pengambilan sampel Euler 10-langkah.
- Fine-tuning cross-entropy teks dan fine-tuning gabungan teks/aksi yang didorong oleh resep.
- Generasi teks asli untuk VQA, grounding, caption, dan subtask bahasa.
- Generasi teks langsung melalui rollout interaktif LeRobot.
- Input state dan aksi kanonik 26D menggunakan pemroses q01/q99 LeRobot.
- Fine-tuning dengan `lerobot-train` dan inferensi melalui API kebijakan standar.

## Persyaratan Instalasi

Wall-OSS-0.5 memerlukan GPU NVIDIA dengan CUDA. Instal LeRobot dengan dependensi kebijakan:

```bash
pip install "lerobot[wall_oss_05]"
```

Untuk checkout sumber LeRobot:

```bash
uv sync --extra wall_oss_05
```

Policy ini diimplementasikan secara native di LeRobot. Ketergantungan spesifik policy-nya hanyalah Transformers; tidak diperlukan checkout Wall-X terpisah. Pemrosesan berbasis recipe juga memerlukan extra dataset. Untuk kueri bahasa atau pelatihan, instal `uv sync --extra wall_oss_05 --extra training` (pelatihan mencakup dukungan dataset). Atur `--policy.recipe=null` untuk pemrosesan hanya aksi tanpa extra dataset.

## Checkpoint

| Varian | Checkpoint LeRobot                                                    | Tujuan penggunaan                             |
| ------- | --------------------------------------------------------------------- | ---------------------------------------- |
| Base 4B | [`lerobot/wall-oss-0.5`](https://huggingface.co/lerobot/wall-oss-0.5) | Fine-tuning dan deployment 26D kanonik |

Checkpoint ini mencakup konfigurasi kebijakan, prosesor dan tokenizer Qwen, bobot model, pre/postprocessor LeRobot yang disimpan, statistik normalisasi, dan metadata konversi. Ini adalah checkpoint dasar: lakukan fine-tuning pada robot dan tugas target sebelum melaporkan hasil tingkat tugas.

## Penggunaan

Pilih kebijakan dengan:

```bash
--policy.type=wall_oss_05
```

Inisialisasi dari checkpoint LeRobot dengan:

```bash
--policy.path=lerobot/wall-oss-0.5
```

Gunakan `--policy.path=your-org/your-finetuned-checkpoint` saat mengevaluasi atau mendeploymen checkpoint LeRobot yang disimpan.

### Teks dan VQA

Wall-OSS-0.5 menggunakan kontrak teks kebijakan bersama. Runtime menyediakan `query_kind` dan `query_text`, lalu menjalankan pemroses input kebijakan normal:

```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 pemanggil. `next_subtask` menerapkan resep yang dimiliki oleh `WallOSS05Config`. Kebijakan ini mewarisi `generate_text(processed_batch)` dan menimpa `supports_text_generation` serta `generate_text`. Generasi menggunakan kepala kosakata Qwen yang terikat pada checkpoint dan pakar vision-language; tidak memanggil VLM terpisah.

Runtime bahasa dapat menghasilkan subtask dan kemudian mengondisikan prediksi aksi Wall berdasarkan subtask tersebut:

```bash
lerobot-rollout \
  --policy.path=your-org/your-finetuned-wall-oss-0.5 \
  --policy.device=cuda \
  --task="clear the table" \
  --interactive=true
```

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

Wall mempertahankan kemampuan VQA dan grounding yang berguna, tetapi model ini dikhususkan untuk observasi robot dan tidak dimaksudkan untuk menggantikan VLM serbaguna.

## Kebutuhan Data

Wall-OSS-0.5 beroperasi secara internal pada tata letak state dan action kanonik 26D. Fitur state dan action yang lebih sempit dinormalisasi dengan statistik dataset aslinya, kemudian di-zero-pad hingga 26D untuk model. Dimensi action yang di-pad dikecualikan dari loss pelatihan. Output dipangkas ke lebar action dataset sebelum dinormalisasi kembali: state 8D dengan action 7D mengembalikan action 7D. `postprocess_action_dim` dapat menerapkan pemangkasan output tambahan. Padding tidak memetakan ulang koordinat sendi atau konvensi controller; berikan nilai yang kompatibel.

Konfigurasi input gambar dengan `camera_key_mapping`. Pemetaan ini mengaitkan setiap fitur gambar LeRobot dengan slot kamera Wall. Checkpoint default menggunakan `face_view` dan `right_wrist_view`.

String tugas dataset diteruskan ke kebijakan sebagai instruksi bahasanya. Gunakan deskripsi tugas yang konsisten saat merekam, melatih, dan mengevaluasi.

Normalisasi state dan action q01/q99 ditangani oleh preprocessor dan postprocessor LeRobot yang disimpan. Saat inferensi, statistik yang disimpan bersama checkpoint dipulihkan. Saat fine-tuning dengan `lerobot-train`, statistik dataset pelatihan menggantikan statistik processor pretrained dan disimpan bersama checkpoint baru.

Checkpoint yang dipublikasikan menggunakan kamus status kebijakan LeRobot asli dan format pre/postprocessor saat ini. Bobot dimuat dan disimpan melalui kode persistensi kebijakan bersama, termasuk pengumpulan terdistribusi dan gerbang penulisan proses utama. Konfigurasi mempertahankan referensi aset tokenizer yang stabil dan dapat dimuat dari direktori kerja mana pun.

## Pelatihan

Lakukan fine-tuning pada checkpoint dasar dengan perintah pelatihan LeRobot standar:

### Contoh Perintah Pelatihan

```bash
lerobot-train \
  --dataset.repo_id=your-org/your-dataset \
  --policy.path=lerobot/wall-oss-0.5 \
  --policy.repo_id=your-org/wall-oss-0.5-your-task \
  --output_dir=outputs/train/wall_oss_05 \
  --job_name=wall_oss_05_finetune \
  --policy.device=cuda \
  --batch_size=1 \
  --steps=20000
```

Mulai dengan ukuran batch kecil karena Wall-OSS-0.5 adalah model dengan 4B parameter. Tingkatkan sesuai dengan memori GPU yang tersedia, atau gunakan akumulasi gradien melalui konfigurasi pelatihan terdistribusi Anda.

Untuk dataset dengan nama kamera yang berbeda, petakan kunci fitur mereka ke slot kamera Wall. Sebagai contoh, tambahkan opsi berikut untuk `top` dan `wrist`:

```bash
--policy.camera_key_mapping='{"observation.images.top":"face_view","observation.images.wrist":"right_wrist_view"}'
```

Fine-tuning menyelesaikan bentuk kamera dan lebar state/action dari dataset, termasuk saat memuat checkpoint dasar dengan `--policy.path`.

### Latih dengan anotasi bahasa

Resep yang dimiliki oleh `WallOSS05Config` menggunakan kolom bahasa opsional dari LeRobot secara default. Resep subtask joint-nya mengawasi respons asisten dan chunk aksi kontinu dalam satu urutan kausal:

```bash
lerobot-train \
  --dataset.repo_id=your-org/your-language-annotated-dataset \
  --policy.path=lerobot/wall-oss-0.5 \
  --policy.use_language_recipe=true \
  --policy.text_loss_weight=0.1 \
  --policy.flow_loss_weight=1.0 \
  --policy.device=cuda \
  --batch_size=1 \
  --steps=20000
```

Aliran resep menentukan tujuan mana yang dijalankan untuk setiap sampel:

- giliran asisten yang ditargetkan menerima cross-entropy teks next-token;
- a `low_level` turn menerima supervisi alur-aksi kontinu; dan
- Resep `low_level` dengan giliran asisten yang ditargetkan menerima kedua kerugian, dengan token aksi yang memperhatikan teks yang diawasi.

Hanya payload asisten yang ditargetkan dan token `<|im_end|>`-nya yang digunakan sebagai label bahasa. Prompt pengguna, padding, gambar, propriosepsi, dan token action-query kontinu dimask dari cross-entropy teks. Baris tanpa anotasi mempertahankan prompt action-only dan loss asli. Atur `use_language_recipe=false` untuk menonaktifkan rendering anotasi, atau `recipe=null` untuk menonaktifkan kedua renderer recipe. `recipe_path` yang eksplisit menimpa recipe bawaan. Fine-tuning baru membangun ulang processor dari recipe tersebut dan statistik pelatihan; pelatihan yang dilanjutkan dan rollout memulihkan processor dan statistik yang disimpan dalam checkpoint.

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.

## Parameter Konfigurasi Utama

| Parameter                 | Default                    | Deskripsi                                                    |
| ------------------------- | -------------------------- | -------------------------------------------------------------- |
| `pretrained_name_or_path` | `lerobot/wall-oss-0.5`     | Sumber aset tokenizer dan image-processor                     |
| `tokenizer_revision`      | `None`                     | Pin tokenizer dasar opsional, terpisah dari revisi bobot |
| `chunk_size`              | `32`                       | Jumlah aksi yang diprediksi per chunk                          |
| `n_action_steps`          | `32`                       | Jumlah aksi prediksi yang dieksekusi sebelum perencanaan ulang         |
| `camera_key_mapping`      | tampilan wajah dan pergelangan tangan kanan | Mengaitkan kunci fitur gambar dengan slot kamera model          |
| `use_language_recipe`     | `true`                     | Mengaktifkan resep yang disimpan dalam konfigurasi kebijakan                 |
| `recipe_path`             | `None`                     | Override resep eksternal eksplisit opsional                     |
| `text_loss_weight`        | `0.1`                      | Bobot untuk entropi silang token asisten yang diawasi            |
| `flow_loss_weight`        | `1.0`                      | Bobot untuk kerugian aliran-aksi kontinu                         |
| `tokenizer_max_length`    | `1000`                     | Panjang maksimum urutan token gabungan visi-bahasa-aksi     |
| `device`                  | auto                       | Gunakan `cuda` untuk Wall-OSS-0.5                                    |

## Evaluasi dan Inferensi

Gunakan checkpoint yang telah dihaluskan dengan alur kerja evaluasi LeRobot standar atau rollout robot dengan meneruskan repositori Hub atau direktori lokalnya sebagai jalur kebijakan.

Wall-OSS-0.5 menghasilkan potongan aksi kontinu dengan flow sampler-nya. Kebijakan saat ini mendukung cabang aliran kontinu; cabang aksi autoregresif tidak diekspos.

Setiap chunk mengodekan gambar kameranya dan melakukan prefill pada prefix observasi/teks sekali. Sepuluh langkah Euler tersebut menggunakan ulang kunci dan nilai prefix serta hanya mendekode token aksi. Cache dibangun ulang untuk setiap observasi baru.

Untuk simulator yang didukung, berikan checkpoint hasil fine-tuning dan opsi spesifik lingkungan melalui `lerobot-eval`:

```bash
lerobot-eval \
  --policy.path=your-org/your-finetuned-wall-oss-0.5 \
  --policy.device=cuda \
  --env.type=<environment> \
  --env.task=<task> \
  --eval.batch_size=1 \
  --eval.n_episodes=10
```

Jangan mengevaluasi checkpoint dasar seolah-olah itu adalah kebijakan yang spesifik untuk tugas. Representasi kanonik, statistik normalisasi, dan distribusi tugas harus cocok dengan checkpoint yang telah dihaluskan (fine-tuned).

## Referensi

- [Halaman proyek Wall-OSS-0.5](https://x2robot.com/en/research/68bc2cde8497d7f238dde690)
- [Checkpoint Wall-OSS-0.5 LeRobot](https://huggingface.co/lerobot/wall-oss-0.5)

## Lisensi

Wall-OSS-0.5 dan Wall-X dirilis di bawah Lisensi Apache 2.0.

