# Kebijakan MolmoAct2

MolmoAct2 adalah implementasi kebijakan LeRobot dari [MolmoAct2](https://allenai.org/blog/molmoact2), yang dipindahkan ke antarmuka pelatihan, evaluasi, checkpointing, dan dataset LeRobot untuk memudahkan penggunaan dengan dataset LeRobot.

Implementasi ini saat ini mendukung pelatihan dan evaluasi untuk model MolmoAct2 reguler. MolmoAct2-Think, yang mendukung penalaran kedalaman adaptif, belum termasuk dalam kebijakan LeRobot ini.

Untuk kode pelatihan MolmoAct2 asli yang digunakan untuk eksperimen yang dilaporkan dalam makalah, lihat [allenai/molmoact2](https://github.com/allenai/molmoact2).

## Persyaratan Instalasi

Instal LeRobot dengan dependensi opsional MolmoAct2:

```bash
uv sync --locked --extra molmoact2
```

Untuk menjalankan model di repositori ini, Anda memerlukan GPU NVIDIA. Jalur presisi-mixed saat ini menyimpan action expert lengkap dalam fp32 dan matriks VLM besar dalam bf16. `policy.compile_model=true` secara opsional mengompilasi blok action expert sambil membiarkan VLM, vision tower, connector, dan policy wrapper tetap eager. Batas ini lolos pemeriksaan paritas output, gradien, dan pembaruan optimizer dengan awal yang sama; mengompilasi jalur VLM bf16 tidak lolos.

Pelatihan multi-GPU melalui `accelerate` meningkatkan throughput dan ukuran batch global. Jalur ini telah diuji pada eksekusi dua-node, delapan-GPU GB200, tetapi port LeRobot ini tidak membuka jalur pelatihan paralel model `fsdp_devices` asli MolmoAct2. Pemutaran ulang satu-GPU GB200 dengan dua lebar prompt asli menghasilkan satu grafik aksi terkompilasi tanpa pemutusan grafik, memori puncak 55,15 GiB yang sama dengan eksekusi eager, dan peningkatan kecepatan keadaan tunak yang moderat. Anggap ini sebagai pemeriksaan implementasi, bukan klaim throughput atau ETA yang portabel.

Repo telah diuji dengan Ubuntu 22.04.

## Penggunaan

Untuk menggunakan MolmoAct2 dalam konfigurasi pelatihan LeRobot, atur:

```bash
--policy.type=molmoact2
```

## Pelatihan

MolmoAct2 dapat di-*fine-tune* dari format checkpoint Hugging Face MolmoAct2 yang dirilis atau dari checkpoint yang sudah disimpan oleh LeRobot. Kedua jalur ini menggunakan *training loop*, transformasi dataset, penyimpanan checkpoint, dan *logging* LeRobot yang sama. Perbedaannya hanya terletak pada cara bobot kebijakan awal dan status *processor* dimuat.

LeRobot menonaktifkan augmentasi gambar dataset secara default. Pertahankan `--dataset.image_transforms.enable=true` dalam perintah pelatihan MolmoAct2. Resep transformasi MolmoAct2 asli bukanlah default transformasi generik LeRobot, sehingga perintah pertama juga menetapkan secara eksplisit crop 95%, rotasi 5 derajat, dan color jitter-nya. Resep asli tersebut juga menerapkan Gaussian blur dengan probabilitas 0,2; konfigurasi subset transformasi generik LeRobot tidak dapat mengekspresikan transformasi opsional keempat tersebut tanpa kadang-kadang menghilangkan salah satu dari tiga transformasi yang wajib.

### Pelatihan Dengan Bobot MolmoAct2 Asli

Gunakan `policy.checkpoint_path` saat memulai dari checkpoint MolmoAct2 yang telah dirilis, misalnya `allenai/MolmoAct2` atau `allenai/MolmoAct2-LIBERO`. LeRobot akan memuat file model HF asli, lalu membangun policy processor-nya sendiri dari metadata dataset dan opsi policy di bawah ini.

Perintah di bawah ini menunjukkan fine-tuning penuh pada dataset LIBERO yang telah digabungkan dari checkpoint dasar yang dirilis. Perintah ini menggunakan pemuatan model bf16, 8 timestep aliran, statistik kuantil resmi LIBERO, augmentasi gambar, dan jalur checkpointing/pencatatan log LeRobot. Jangan mengganti kuantil metadata perkiraan dari `lerobot/libero` dengan `norm_stats.json` yang dirilis; nilai q01/q99 keduanya tidak identik.

```bash
accelerate launch \
  --num_processes=8 \
  --mixed_precision=bf16 \
  -m lerobot.scripts.lerobot_train \
  --dataset.repo_id=lerobot/libero \
  --dataset.root=/path/to/lerobot/libero \
  --dataset.video_backend=pyav \
  --dataset.image_transforms.enable=true \
  --dataset.image_transforms.max_num_transforms=3 \
  --dataset.image_transforms.random_order=false \
  --dataset.image_transforms.tfs='{"crop":{"weight":1.0,"type":"RandomResizedCrop","kwargs":{"size":[256,256],"scale":[0.9025,0.9025],"ratio":[1.0,1.0]}},"rotation":{"weight":1.0,"type":"RandomRotation","kwargs":{"degrees":[-5.0,5.0],"interpolation":2}},"color":{"weight":1.0,"type":"ColorJitter","kwargs":{"brightness":0.2,"contrast":[0.8,1.2],"saturation":[0.8,1.2],"hue":0.05}}}' \
  --policy.type=molmoact2 \
  --policy.checkpoint_path=allenai/MolmoAct2 \
  --policy.device=cuda \
  --policy.action_mode=continuous \
  --policy.norm_tag=libero \
  --policy.norm_stats_path=/path/to/MolmoAct2-LIBERO/norm_stats.json \
  --policy.train_mode_vlm=fft \
  --policy.chunk_size=10 \
  --policy.n_action_steps=10 \
  --policy.setup_type="single franka robotic arm in libero" \
  --policy.control_mode="delta end-effector pose" \
  --policy.image_keys='["observation.images.image","observation.images.image2"]' \
  --policy.dtype=bfloat16 \
  --policy.num_flow_timesteps=8 \
  --policy.gradient_checkpointing=true \
  --policy.compile_model=true \
  --policy.freeze_embedding=true \
  --policy.normalize_gripper=false \
  --policy.enable_knowledge_insulation=false \
  --policy.push_to_hub=false \
  --trackio.enable=true \
  --trackio.project=<trackio_project> \
  --job_name=<job_name> \
  --output_dir=outputs/<job_name> \
  --steps=10000 \
  --batch_size=32 \
  --num_workers=4 \
  --log_freq=20 \
  --env_eval_freq=-1 \
  --save_checkpoint=true \
  --save_freq=2000
```

### Pelatihan Dengan Bobot LeRobot MolmoAct2

Gunakan `policy.path` saat memulai dari checkpoint MolmoAct2 yang disimpan oleh LeRobot, baik dari direktori `pretrained_model` lokal maupun dari Hub. Ini memulihkan konfigurasi kebijakan LeRobot yang disimpan, bobot model, prosesor, dan statistik normalisasi. Anda masih dapat menimpa opsi saat pelatihan seperti `batch_size`, `steps`, atau `policy.action_mode`. Pemuatan checkpoint bersifat ketat dan mempertahankan topologi FFT atau LoRA yang disimpan, jadi jangan menimpa `policy.train_mode_vlm` saat menggunakan `policy.path`. Untuk memulai eksekusi LoRA baru, inisialisasi dari bobot HF dengan `policy.checkpoint_path` sebagai gantinya, misalnya dengan `--policy.type=molmoact2`, `--policy.checkpoint_path=allenai/MolmoAct2`, dan `--policy.train_mode_vlm=lora`.

```bash
accelerate launch \
  --num_processes=8 \
  --mixed_precision=bf16 \
  -m lerobot.scripts.lerobot_train \
  --dataset.repo_id=allenai/MolmoAct2-LIBERO-Dataset \
  --dataset.root=/path/to/lerobot/data/allenai/MolmoAct2-LIBERO-Dataset \
  --dataset.video_backend=pyav \
  --dataset.image_transforms.enable=true \
  --policy.path=/path/to/pretrained_model \
  --policy.device=cuda \
  --policy.action_mode=continuous \
  --policy.chunk_size=10 \
  --policy.n_action_steps=10 \
  --policy.dtype=bfloat16 \
  --policy.num_flow_timesteps=8 \
  --policy.gradient_checkpointing=true \
  --policy.compile_model=true \
  --trackio.enable=true \
  --trackio.project=<trackio_project> \
  --job_name=<job_name> \
  --output_dir=outputs/<job_name> \
  --steps=10000 \
  --batch_size=32 \
  --num_workers=4 \
  --log_freq=20 \
  --env_eval_freq=-1 \
  --save_checkpoint=true \
  --save_freq=2000
```

### Praktik Umum

Untuk fine-tuning pada dataset yang relatif kecil, seperti satu suite LIBERO atau dataset dunia nyata dengan kurang dari 200 demonstrasi, global batch size 16 hingga 32 adalah titik awal yang baik. Dalam pengaturan ini, kami merekomendasikan penggunaan `policy.train_mode_vlm=lora` (default), yang biasanya memberikan performa yang serupa atau bahkan lebih baik daripada `fft`. Selain itu, `policy.train_mode_vlm=freeze` juga merupakan pilihan yang praktis. Di semua mode, kami sengaja menjaga action expert agar sepenuhnya trainable, yang kami temukan sangat krusial untuk performa model. Untuk dataset fine-tuning yang lebih besar, global batch size yang lebih besar dan full VLM fine-tuning (`policy.train_mode_vlm=fft`) biasanya lebih disukai.

### Opsi Kebijakan Umum

- `policy.checkpoint_path`: checkpoint MolmoAct2 HF asli untuk inisialisasi. Gunakan ini untuk bobot MolmoAct2 yang dirilis.
- `policy.path`: checkpoint LeRobot untuk diinisialisasi. Gunakan ini untuk checkpoint yang dibuat oleh pelatihan LeRobot.
- `policy.action_mode`: target pelatihan, salah satu dari `continuous`, `discrete`, atau `both`. Fine-tuning robot MolmoAct2 resmi menggunakan `continuous`. Checkpoint yang dirilis mempertahankan bobot aksi diskrit; `both` tersedia sebagai ablasi eksplisit untuk flow-matching gabungan plus token aksi.
- `policy.train_mode_vlm`: mengontrol mode fine-tuning VLM, salah satu dari `fft`, `lora`, atau `freeze`. `fft` melakukan fine-tuning penuh pada VLM, `lora` melatih adapter LoRA pada lapisan linear VLM, dan `freeze` membekukan VLM. Action expert dilakukan fine-tuning penuh di ketiga mode tersebut. Nilai defaultnya adalah `lora`. `freeze` membutuhkan `policy.action_mode=continuous`.
- `policy.enable_knowledge_insulation`: ketika `true`, memisahkan (detach) status K/V konteks action-expert sebelum loss aksi. Nilai defaultnya adalah `false`.
- `policy.chunk_size`: horizon aksi yang digunakan oleh kebijakan. Untuk LIBERO, kami menggunakan `10`. Port LeRobot ini menimpa `max_action_horizon` dari checkpoint yang dimuat dengan nilai ini.
- `policy.n_action_steps`: jumlah aksi yang dikonsumsi dari setiap chunk prediksi sebelum policy dikonsultasikan kembali. Untuk LIBERO, atur nilainya ke `chunk_size`.
- `policy.setup_type`: teks yang disisipkan ke dalam prompt untuk menggambarkan robot dan adegan, misalnya `single franka robotic arm in libero`. Contoh lainnya tercantum dalam entri `metadata_by_tag` dari [`norm_stats.json`](https://huggingface.co/allenai/MolmoAct2/blob/main/norm_stats.json).
- `policy.control_mode`: teks yang disisipkan ke dalam prompt untuk menjelaskan ruang aksi, misalnya `delta end-effector pose` atau `absolute joint pose`.
- `policy.image_keys`: kunci observasi gambar LeRobot yang terurut dan diteruskan ke prosesor.
- `policy.dtype`: Saklar presisi bergaya Pi0.5. `bfloat16` menggunakan autocast/penyimpanan bf16 untuk matriks VLM besar, sementara mempertahankan seluruh action expert dan modul yang sensitif secara numerik dalam fp32. `float32` menonaktifkan autocast dan menjaga seluruh model dalam fp32. Profil `bfloat16` ber memori rendah secara sengaja berbeda dari eksekusi AMP FP32-master MolmoAct2 asli: momen AdamW mengikuti dtype penyimpanan masing-masing parameter, sehingga parameter VLM bf16 yang besar juga memiliki momen bf16. Fine-tuning penuh mengalokasikan secara lazy satu tensor kompensasi bf16 untuk setiap parameter bf16 yang membawa gradien, sehingga pembaruan yang lebih kecil dari satu ULP parameter dibawa ke langkah-langkah berikutnya. Ini bukan salinan master fp32. Adapter LoRA, action expert, dan modul yang secara eksplisit sensitif mempertahankan parameter dan status optimizer fp32; parameter VLM yang dibekukan dalam mode LoRA tidak mengalokasikan tensor kompensasi.
- `policy.compile_model`: mengaktifkan jalur `torch.compile` per-blok untuk MolmoAct2. Baik fine-tuning penuh maupun LoRA hanya mengompilasi blok transformer action-expert. Eksekusi VLM/ViT/connector secara eager menghindari pergeseran aktivasi dan gradien BF16 yang disebabkan oleh compiler, sambil tetap mempertahankan akselerasi untuk jalur aksi yang dievaluasi pada setiap timestep flow. Inductor juga diinstruksikan untuk mempertahankan batas downcast/upcast BF16 eager di antara operasi yang difusi. Ini adalah satu batas presisi-aman yang tetap dan tidak menambahkan opsi compile lainnya. Kompilasi dinonaktifkan secara default; aktifkan untuk pelatihan GPU jangka panjang. Blok aksi menggunakan strategi bentuk otomatis dari PyTorch. Dengan gradient checkpointing, hanya dimensi sekuens konteks encoder yang variabel yang ditandai dinamis; ukuran batch, horizon aksi, dan jumlah timestep flow tetap statis. Pengurutan ulang cache graf Dynamo dan pemecah graf DDP tambahan dinonaktifkan pada mode tersebut sehingga rekomputasi backward memilih graf blok yang sama dengan forward. Sekuens teks/aksi lokal batch di-pad kiri hingga kelipatan internal 8 sebelum penyisipan BOS. Ini menambahkan maksimal tujuh token yang di-mask, sekaligus secara tajam mengurangi warm-up compile yang spesifik bentuk; ini bukan opsi yang menghadap ke pengguna.
- `policy.num_flow_timesteps`: jumlah timestep flow-matching yang diambil per contoh selama pelatihan. Kami menggunakan `8` untuk fine-tuning.
- `policy.num_inference_steps`: override opsional untuk langkah-langkah generasi aksi kontinu pada saat inferensi.
- `policy.gradient_checkpointing`: mengaktifkan checkpointing di jalur VLM/aksi untuk mengurangi memori aktivasi.
- `policy.freeze_embedding`: membekukan embedding input. Nilainya secara default adalah `true`.
- `policy.normalize_gripper`: mengontrol apakah dimensi gripper disertakan dalam normalisasi kuantil state/action. Nilainya secara default adalah `false`.
- `policy.normalize_language`: menormalisasi string tugas sebelum konstruksi prompt. Nilainya secara default adalah `true`.
- `policy.mask_action_dim_padding`: memask dimensi yang di-padding dalam flow loss. Checkpoint yang dirilis menggunakan `policy.expected_max_action_dim=32`.
- `policy.max_sequence_length`: batas panjang urutan manual opsional. Biarkan tidak disetel untuk menurunkannya dari gambar, dimensi state, dimensi aksi, horizon aksi, dan mode aksi diskrit.

### Laju Pembelajaran

MolmoAct2 menggunakan learning rate per grup parameter untuk menyelaraskan dengan eksperimen fine-tuning MolmoAct2 asli.

- Full fine-tuning menggunakan `policy.optimizer_lr=1e-5` untuk VLM, `policy.optimizer_vit_lr=5e-6` untuk vision tower, `policy.optimizer_connector_lr=5e-6` untuk lapisan image connector, dan `policy.optimizer_action_expert_lr=5e-5` untuk action expert.
- Fine-tuning LoRA VLM mengatur grup parameter LoRA untuk VLM, vision, dan connector menjadi `5e-5` ketika `policy.train_mode_vlm=lora`; action expert tetap di-fine-tune sepenuhnya dengan `policy.optimizer_action_expert_lr`.
- Fine-tuning Frozen-VLM menggunakan `policy.train_mode_vlm=freeze`, hanya melatih action expert, dan menggunakan `policy.optimizer_action_expert_lr=5e-5`.
- `policy.optimizer_grad_clip_norm` diterapkan secara independen pada grup parameter LLM, vision tower, image connector, dan action-expert, sesuai dengan optimizer MolmoAct2 asli. Ini bukan norma gradien model global tunggal.

Anda dapat menimpa learning rate untuk full fine-tuning dan action-expert dengan `policy.optimizer_lr`, `policy.optimizer_vit_lr`, `policy.optimizer_connector_lr`, dan `policy.optimizer_action_expert_lr`. Pengaturan scheduler dapat diubah dengan `policy.scheduler_warmup_steps`, `policy.scheduler_decay_steps`, dan `policy.scheduler_decay_lr`. Horizon decay default 24.000 langkah sesuai dengan resep resmi [`train_lerobot.py`](https://github.com/allenai/molmoact2/blob/5aac8f8a1180d79757ce500f819a02217079811c/experiments/launch_scripts/train_lerobot.py#L867-L868).

### Statistik Kuantil Dataset

MolmoAct2 secara default menggunakan normalisasi kuantil untuk fitur state dan action. Jika dataset Anda belum dikonversi dengan statistik kuantil, Anda dapat menambahkannya dengan:

```bash
python src/lerobot/scripts/augment_dataset_quantile_stats.py \
  --repo-id=your_dataset
```

Merekam, melanjutkan, dan menggabungkan kuantil agregat dari ringkasan per episode, sehingga `meta/stats.json` pada akhirnya menyimpan amplop konservatif (`min` untuk `q <= 50`, `max` untuk `q > 50`) alih-alih kuantil seluruh dataset. Untuk memperkirakan yang terakhir, pindai setiap episode dengan histogram berjalan:

```bash
python src/lerobot/scripts/augment_dataset_quantile_stats.py \
  --repo-id=your_dataset \
  --overwrite \
  --skip-images
```

`--skip-images` mempertahankan statistik gambar yang ada dan menghindari pengunduhan atau dekoding data video ketika hanya `STATE`/`ACTION` yang perlu dihitung ulang, dan `--root` membaca dataset lokal alih-alih dari Hub. Nilai-nilai ini adalah estimasi histogram, yang rentan terhadap error diskritisasi dan rebinning, sehingga dapat berbeda dari nilai konservatif — yang mengubah target ternormalisasi MolmoAct2 dan karenanya skala loss-nya. Statistik yang sudah disimpan di dalam checkpoint yang ada tidak terpengaruh.

Sebagai alternatif, latih MolmoAct2 dengan normalisasi mean/std:

```bash
--policy.normalization_mapping='{"ACTION": "MEAN_STD", "STATE": "MEAN_STD", "VISUAL": "IDENTITY"}'
```

## Evaluasi

Evaluasi juga mendukung checkpoint yang disimpan oleh LeRobot dan checkpoint MolmoAct2 HF asli. Untuk replikasi LIBERO, pertahankan lingkungan rendering EGL tetap dan gunakan `policy.per_episode_seed=true`.

**Penting:** Kami menemukan bahwa `num_steps_wait=10` tidak secara andal memungkinkan adegan LIBERO untuk stabil dan dapat menurunkan keberhasilan yang diukur. Semua hasil evaluasi LIBERO yang dilaporkan di sini menggunakan `num_steps_wait=50`.

### Evaluasi Dengan LeRobot MolmoAct2 Weight

Gunakan `policy.path` untuk checkpoint yang disimpan oleh LeRobot. Prosesor dan statistik normalisasi yang disimpan akan dipulihkan bersama dengan model.

```bash
export MUJOCO_GL=egl
export PYOPENGL_PLATFORM=egl
export OMP_NUM_THREADS=1
export MKL_NUM_THREADS=1

lerobot-eval \
  --policy.path=allenai/MolmoAct2-LIBERO-LeRobot \
  --policy.inference_action_mode=continuous \
  --policy.dtype=bfloat16 \
  --policy.enable_inference_cuda_graph=true \
  --policy.device=cuda \
  --policy.per_episode_seed=true \
  --policy.eval_seed=1000 \
  --env.type=libero \
  --env.task=libero_10,libero_goal,libero_object,libero_spatial \
  --env.camera_name_mapping='{"agentview_image":"image","robot0_eye_in_hand_image":"wrist_image"}' \
  --eval.batch_size=1 \
  --eval.n_episodes=50 \
  --seed=1000
```

### Evaluasi Dengan Bobot MolmoAct2 Asli

Anda dapat mengevaluasi checkpoint Hugging Face yang telah dirilis secara langsung tanpa terlebih dahulu mengonversinya menjadi checkpoint LeRobot. Dalam kasus ini, atur `policy.checkpoint_path` ke repo model HF dan berikan `policy.norm_tag`. Untuk LIBERO, `policy.norm_tag=libero` memuat statistik normalisasi aksi/keadaan LIBERO, horizon aksi, metadata prompt, dan urutan kunci gambar dari `norm_stats.json` checkpoint.

Untuk sepenuhnya mereplikasi hasil paper MolmoAct2 dengan checkpoint Hugging Face yang dirilis, kami merekomendasikan menggunakan cabang [`allenai/lerobot` `molmoact2-hf-inference`](https://github.com/allenai/lerobot/tree/molmoact2-hf-inference) yang dipatok pada v0.5.1. Cabang tersebut sesuai dengan pengaturan evaluasi asli yang digunakan untuk angka-angka yang dilaporkan.

```bash
export MUJOCO_GL=egl
export PYOPENGL_PLATFORM=egl
export OMP_NUM_THREADS=1
export MKL_NUM_THREADS=1

lerobot-eval \
  --policy.type=molmoact2 \
  --policy.checkpoint_path=allenai/MolmoAct2-LIBERO \
  --policy.norm_tag=libero \
  --policy.inference_action_mode=continuous \
  --policy.dtype=float32 \
  --policy.enable_inference_cuda_graph=true \
  --policy.device=cuda \
  --policy.per_episode_seed=true \
  --policy.eval_seed=1000 \
  --env.type=libero \
  --env.task=libero_goal \
  --env.camera_name_mapping='{"agentview_image":"image","robot0_eye_in_hand_image":"wrist_image"}' \
  --eval.batch_size=1 \
  --eval.n_episodes=50 \
  --seed=1000
```

Gunakan `--env.task=libero_10,libero_goal,libero_object,libero_spatial` untuk menjalankan seluruh suite LIBERO. Perintah yang sama juga berlaku untuk checkpoint MolmoAct2 lain yang telah dirilis, selama `policy.norm_tag` yang diminta ada di `norm_stats.json` checkpoint tersebut.

### Opsi Evaluasi Umum

- `policy.inference_action_mode`: wajib untuk rollout. Gunakan `continuous` untuk inferensi flow-matching atau `discrete` untuk inferensi action-token. Nilai ini harus kompatibel dengan `policy.action_mode` saat pelatihan yang disimpan di checkpoint.
- `policy.path`: Jalur checkpoint LeRobot atau repo Hub. Gunakan ini untuk checkpoint yang disimpan oleh LeRobot.
- `policy.checkpoint_path`: jalur checkpoint MolmoAct2 HF asli atau repo Hub. Gunakan ini dengan `policy.type=molmoact2` dan `policy.norm_tag`.
- `policy.norm_tag`: memilih statistik normalisasi, metadata prompt, urutan kunci gambar, dan horizon aksi dari `norm_stats.json` checkpoint asli. Parameter ini wajib untuk evaluasi langsung checkpoint asli-HF.
- `policy.dtype`: profil penyimpanan/autocast model. Gunakan `bfloat16` untuk evaluasi GPU normal. Gunakan `float32` hanya jika Anda secara eksplisit menginginkan inferensi fp32 penuh.
- `policy.enable_inference_cuda_graph`: mengaktifkan jalur grafik CUDA inferensi MolmoAct2 untuk rollout aksi kontinu berulang yang lebih cepat.
- `policy.per_episode_seed` dan `policy.eval_seed`: membuat generasi aksi kontinu stokastik menjadi deterministik per episode untuk replikasi.
- `env.task`: suite LIBERO yang dipisahkan koma atau satu suite. Gunakan `libero_10,libero_goal,libero_object,libero_spatial` untuk benchmark lengkap.
- `env.camera_name_mapping`: memetakan nama kamera LIBERO ke kunci gambar yang diharapkan oleh pemroses kebijakan.

## Hasil Kinerja

### Hasil Benchmark LIBERO

MolmoAct2 telah menunjukkan kinerja yang kuat pada suite benchmark LIBERO. Untuk membandingkan dan menguji implementasi LeRobot-nya, kami melakukan fine-tuning pada [`allenai/MolmoAct2-LIBERO`](https://huggingface.co/allenai/MolmoAct2-LIBERO) selama 10k langkah tambahan pada dataset LIBERO dengan per-GPU batch size 32 di 8 GPU H100, kemudian membandingkan hasilnya dengan hasil referensi MolmoAct2 asli.

Checkpoint LeRobot yang telah dihaluskan (fine-tuned) dan dilaporkan di sini tersedia di [`allenai/MolmoAct2-LIBERO-LeRobot`](https://huggingface.co/allenai/MolmoAct2-LIBERO-LeRobot) dan dilatih pada [`allenai/MolmoAct2-LIBERO-Dataset`](https://huggingface.co/datasets/allenai/MolmoAct2-LIBERO-Dataset).

| Benchmark      | Implementasi LeRobot | MolmoAct2 Asli |
| -------------- | ---------------------: | -----------------: |
| LIBERO Spatial |                  98.4% |              97.8% |
| LIBERO Object  |                 100.0% |             100.0% |
| Tujuan LIBERO    |                  98.0% |              97.8% |
| LIBERO 10      |                  96.6% |              93.2% |
| Rata-rata        |                 98.25% |             97.20% |

Hasil ini menunjukkan kinerja kuat MolmoAct2 di berbagai tugas manipulasi robotik. Untuk mereplikasinya, ikuti instruksi di bagian evaluasi LIBERO.

## Deployment Perangkat Keras (lerobot-rollout)

Checkpoint berformat LeRobot tersedia di Hub untuk digunakan langsung dengan `lerobot-rollout`. Setiap checkpoint menggunakan nama kamera spesifik yang harus sesuai dengan konfigurasi kamera robot Anda.

### Konvensi penamaan kamera

Setiap checkpoint mengharapkan kunci `observation.images.*` tertentu. Jika kamera robot Anda memiliki nama yang berbeda, gunakan `--rename_map` untuk memetakannya:

| Checkpoint                    | Kunci kamera            | Deskripsi              |
| ----------------------------- | ---------------------- | ------------------------ |
| MolmoAct2-LIBERO-LeRobot      | `image`, `wrist_image` | Kamera simulasi LIBERO       |
| MolmoAct2-BimanualYAM-LeRobot | `top`, `left`, `right` | YAM 3-camera setup       |
| MolmoAct2-DROID-LeRobot       | `cam0`, `cam1`         | Eksternal + pergelangan tangan         |
| MolmoAct2-SO100_101-LeRobot   | `cam0`, `cam1`         | Tampilan utama + sekunder |

Contoh dengan robot SO-100 yang menggunakan kamera atas dan samping:

```bash
lerobot-rollout \
  --policy.path=lerobot/MolmoAct2-SO100_101-LeRobot \
  --rename_map='{"observation.images.top": "observation.images.cam0", "observation.images.side": "observation.images.cam1"}' \
  --robot.type=so100_follower \
  --robot.port=/dev/ttyACM0 \
  --robot.cameras='{
      top: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30},
      side: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30}
  }' \
  --task="pick up the red cube" --duration=30
```

Untuk menggunakan kamera pergelangan tangan sebagai gantinya, cukup ubah pemetaan penamaan:

```bash
--rename_map='{"observation.images.top": "observation.images.cam0", "observation.images.wrist": "observation.images.cam1"}'
```

### Transformasi bingkai bersama (SO-100/101 zero-shot)

Checkpoint MolmoAct2-SO100_101 dilatih pada data yang menggunakan konvensi kalibrasi sendi yang berbeda dari LeRobot >= 0.5.0. Tanpa koreksi frame, lengan robot mungkin bergerak ke arah yang salah.

Hal ini memengaruhi baik **zero-shot deployment** maupun **fine-tuning** dari checkpoint asli. Bobot pretrained mengharapkan konvensi lama, sehingga semua data gabungan (observasi dan aksi) harus ditransformasi agar sesuai.

Checkpoint LeRobot yang dikonversi (`lerobot/MolmoAct2-SO100_101-LeRobot`) sudah termasuk koreksi ini dalam pipeline prosesor. Jika Anda mengonversi atau melakukan fine-tuning checkpoint sendiri, atur hal berikut dalam konfigurasi policy (`configuration_molmoact2.py`):

- `joint_signs`: `[1, -1, 1, 1, 1, 1]` (membalik arah shoulder_lift)
- `joint_offsets`: `[0, 90, 90, 0, 0, 0]` (menggeser shoulder_lift dan elbow_flex sebesar 90°)

Lihat [panduan kompatibilitas mundur](./backwardcomp) untuk detail mengenai perubahan kalibrasi.

## Perbedaan dari Implementasi Asli

Port LeRobot ini dimaksudkan untuk mencocokkan perilaku MolmoAct2 sambil menggunakan infrastruktur dataset, pelatihan, evaluasi, checkpoint, dan logging dari LeRobot. Perbedaan utama dari repositori pelatihan aslinya adalah:

- Stack pelatihan dari paper asli mempertahankan parameter master fp32 dan melatih di bawah AMP bf16. Port LeRobot ini menggunakan `policy.dtype=bfloat16` untuk menurunkan memori: matriks VLM besar disimpan dalam bf16, sementara action expert dan modul yang sensitif secara numerik tetap dalam fp32, dan operator yang memenuhi syarat dijalankan di bawah autocast bf16. Tensor kompensasi pembaruan bf16 mengurangi kerugian pembulatan parameter selama fine-tuning penuh, tetapi momen Adam bf16-nya masih tidak mereproduksi secara persis state optimizer fp32 asli.
- Repositori asli menggunakan jalur pelatihan FSDP/paralel-model-nya sendiri. Port LeRobot menggunakan jalur pelatihan standar LeRobot/Accelerate dan belum diuji untuk pelatihan multi-node.
- Repositori asli mendukung pengemasan urutan. Port LeRobot melatih pada satu sampel LeRobot per item dan menggunakan padding lokal batch dengan penjaga panjang urutan maksimum yang disimpulkan.
- Port LeRobot mengikuti konvensi optimizer, scheduler, penyimpanan checkpoint, transformasi dataset, augmentasi gambar, dan logging Trackio dari LeRobot.
- Jalur pelatihan asli mendukung horizon aksi campuran dengan melakukan padding hingga `max_action_horizon` dan mem-mask slot horizon yang di-pad pada self-attention pakar aksi. Hal ini berguna saat melatih di atas dataset dengan frekuensi kontrol yang berbeda. Port LeRobot saat ini menargetkan fine-tuning dataset tunggal, sehingga `policy.chunk_size` menimpa `max_action_horizon` dari checkpoint dan masking horizon belum diimplementasikan. Dukungan untuk jalur horizon campuran ini direncanakan.

## Sitasi

```bibtex
@misc{fang2026molmoact2actionreasoningmodels,
      title={MolmoAct2: Action Reasoning Models for Real-world Deployment},
      author={Haoquan Fang and Jiafei Duan and Donovan Clay and Sam Wang and Shuo Liu and Weikai Huang and Xiang Fan and Wei-Chuan Tsai and Shirui Chen and Yi Ru Wang and Shanli Xing and Jaemin Cho and Jae Sung Park and Ainaz Eftekhar and Peter Sushko and Karen Farley and Angad Wadhwa and Cole Harrison and Winson Han and Ying-Chun Lee and Eli VanderBilt and Rose Hendrix and Suveen Ellawela and Lucas Ngoo and Joyce Chai and Zhongzheng Ren and Ali Farhadi and Dieter Fox and Ranjay Krishna},
      year={2026},
      eprint={2605.02881},
      archivePrefix={arXiv},
      primaryClass={cs.RO},
      url={https://arxiv.org/abs/2605.02881},
}
```

## Lisensi

Model ini berlisensi Apache 2.0. Model ini ditujukan untuk penggunaan penelitian dan pendidikan sesuai dengan [Panduan Penggunaan Bertanggung Jawab Ai2](https://allenai.org/responsible-use), yang konsisten dengan [allenai/molmoact2](https://github.com/allenai/molmoact2).

