# MolmoAct2 Politikası

MolmoAct2, [MolmoAct2](https://allenai.org/blog/molmoact2)'nin LeRobot politikası uygulamasıdır ve LeRobot veri setleriyle daha kolay kullanım için LeRobot eğitim, değerlendirme, checkpoint ve veri seti arayüzlerine taşınmıştır.

Bu uygulama şu anda standart MolmoAct2 modeli için eğitim ve değerlendirme desteklemektedir. Adaptif derinlik çıkarımını destekleyen MolmoAct2-Think, bu LeRobot politikasına henüz dahil edilmemiştir.

Makalede raporlanan deneyler için kullanılan orijinal MolmoAct2 eğitim kodu için [allenai/molmoact2](https://github.com/allenai/molmoact2) adresine bakın.

## Kurulum Gereksinimleri

MolmoAct2 isteğe bağlı bağımlılıklarıyla LeRobot'u yükleyin:

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

Bu depodaki modelleri çalıştırmak için bir NVIDIA GPU'ya ihtiyacınız vardır. Mevcut karma hassasiyet yolu, tam eylem uzmanını fp32'de ve büyük VLM matrislerini bf16'da saklar. `policy.compile_model=true` isteğe bağlı olarak eylem uzmanı bloklarını derlerken VLM, görme kulesi, bağlayıcı ve politika sarmalayıcısını eager olarak bırakır. Bu sınır, aynı başlangıç çıktısı, gradyan ve optimizleyici güncelleme eşitlik kontrollerinden geçti; bf16 VLM yolunun derlenmesi ise geçmedi.

`accelerate` üzerinden çoklu GPU eğitimi, işleme hızını ve küresel parti boyutunu artırır. Bu yol, iki düğümlü, sekiz GPU'lu GB200 çalıştırmalarında test edilmiştir; ancak bu LeRobot portu, orijinal MolmoAct2 `fsdp_devices` model paralelliği eğitim yolunu dışa vurmaz. İki gerçek istem genişliğiyle yapılan tek GPU'lu GB200 tekrarı, grafik kırılmaları olmadan tek derlenmiş eylem grafiği, aceleci (eager) çalıştırmayla aynı 55,15 GiB tepe bellek kullanımı ve mütevazı bir kararlı durum hızlanımı üretti. Bunları taşınabilir işleme hızı veya tahmini bitiş süresi iddiaları olarak değil, uygulama kontrolleri olarak değerlendirin.

Depo, Ubuntu 22.04 ile test edilmiştir.

## Kullanım

LeRobot eğitim yapılandırmasında MolmoAct2'yi kullanmak için şunu ayarlayın:

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

## Eğitim

MolmoAct2, hem yayımlanan MolmoAct2 Hugging Face checkpoint biçiminden hem de LeRobot tarafından zaten kaydedilmiş bir checkpoint'ten ince ayarlanabilir. Her iki yol da aynı LeRobot eğitim döngüsünü, veri seti dönüşümlerini, checkpoint kaydetme ve günlük kaydetme işlemlerini kullanır. Fark, yalnızca başlangıç politikası ağırlıklarının ve işlemci durumunun nasıl yüklendiğindedir.

LeRobot, veri seti görüntü artırma işlemlerini varsayılan olarak devre dışı bırakır. MolmoAct2 eğitim komutlarında `--dataset.image_transforms.enable=true` parametresini koruyun. Orijinal MolmoAct2 dönüştürme tarifi, LeRobot'un genel dönüştürme varsayılanı değildir; bu nedenle ilk komut, %95'lik kırpma, 5 derecelik döndürme ve renk sapmasını (color jitter) açıkça sabitler. Orijinal tarif ayrıca 0,2 olasılıkla Gauss bulanıklığı uygular; LeRobot'un genel dönüştürme alt kümesi yapılandırması, üç zorunlu dönüştürmeden birini bazen düşürmeden bu isteğe bağlı dördüncü dönüştürmeyi ifade edemez.

### Orijinal MolmoAct2 Ağırlığıyla Eğitim

Yayınlanmış bir MolmoAct2 checkpoint'inden başlarken `policy.checkpoint_path` kullanın, örneğin `allenai/MolmoAct2` veya `allenai/MolmoAct2-LIBERO`. LeRobot, orijinal HF model dosyalarını yükledikten sonra, veri seti meta verileri ve aşağıdaki policy seçeneklerinden kendi policy işleyicisini oluşturur.

Aşağıdaki komut, yayınlanan temel kontrol noktasından birleştirilmiş LIBERO veri seti üzerinde tam ince ayar gösterir. bf16 model yükleme, 8 akış zaman adımı, resmi LIBERO kantil istatistikleri, görüntü artırmaları ve LeRobot'un kontrol noktası/günlük yolu kullanır. `lerobot/libero`'nun yaklaşık metadata kantillerini, yayınlanan `norm_stats.json` yerine kullanmayın; q01/q99 değerleri aynı değildir.

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

### LeRobot MolmoAct2 Ağırlığıyla Eğitim

LeRobot tarafından kaydedilen bir MolmoAct2 checkpoint’inden başlarken, ister yerel bir `pretrained_model` dizininden ister Hub’dan olsun, `policy.path` kullanın. Bu, kaydedilen LeRobot policy yapılandırmasını, model ağırlıklarını, işlemciyi ve normalizasyon istatistiklerini geri yükler. `batch_size`, `steps` veya `policy.action_mode` gibi eğitim zamanı seçeneklerini yine de geçersiz kılabilirsiniz. Checkpoint yükleme katıdır ve kaydedilen FFT veya LoRA topolojisini koruduğundan, `policy.path` kullanırken `policy.train_mode_vlm` değerini geçersiz kılmayın. Yeni bir LoRA çalıştırması başlatmak için, örneğin `--policy.type=molmoact2`, `--policy.checkpoint_path=allenai/MolmoAct2` ve `--policy.train_mode_vlm=lora` ile, bunun yerine `policy.checkpoint_path` kullanarak HF ağırlıklarından başlatın.

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

### Yaygın Uygulamalar

Karşılaştırmalı olarak küçük bir veri setinde, örneğin tek bir LIBERO paketi veya 200'den az gösterim içeren gerçek dünya veri seti üzerinde ince ayar için, 16 ile 32 arasında bir küresel parti boyutu iyi bir başlangıç noktasıdır. Bu ayarlarda, genellikle `fft`'den benzer veya hatta daha iyi performans veren `policy.train_mode_vlm=lora`'yı (varsayılan) kullanmanızı öneririz. Ayrıca, `policy.train_mode_vlm=freeze` de pratik bir seçenektir. Tüm modlarda, model performansı için kritik olduğunu tespit ettiğimiz için eylem uzmanını tamamen eğitilebilir tutarız. Daha büyük ince ayar veri setleri için, daha büyük küresel parti boyutları ve tam VLM ince ayarı (`policy.train_mode_vlm=fft`) genellikle tercih edilir.

### Yaygın Politika Seçenekleri

- `policy.checkpoint_path`: başlatılacak orijinal MolmoAct2 HF checkpoint'i. Yayınlanmış MolmoAct2 ağırlıkları için bunu kullanın.
- `policy.path`: Başlatılacak LeRobot checkpoint'i. LeRobot eğitimiyle oluşturulan checkpoint'ler için bunu kullanın.
- `policy.action_mode`: eğitim hedefi, `continuous`, `discrete` veya `both` değerlerinden biri. Resmi MolmoAct2 robot ince ayarı `continuous` kullanır. Yayınlanan checkpoint'ler ayrık eylem ağırlıklarını korur; `both`, açık bir ortak akış eşleştirme ve eylem-jeton ablasyonu olarak kullanılabilir.
- `policy.train_mode_vlm`: VLM ince ayar modunu kontrol eder; `fft`, `lora` veya `freeze` değerlerinden biridir. `fft` VLM'yi tamamen ince ayarlar, `lora` VLM doğrusal katmanlarında LoRA adaptörleri eğitir ve `freeze` VLM'yi dondurur. Üç modda da eylem uzmanı tamamen ince ayarlanır. Varsayılan değer `lora`'dır. `freeze` için `policy.action_mode=continuous` gereklidir.
- `policy.enable_knowledge_insulation`: `true` olduğunda, eylem kaybı hesaplanmadan önce eylem uzmanı bağlam K/V durumları ayrıştırılır. Varsayılan değer `false`'dir.
- `policy.chunk_size`: politikanın kullandığı eylem ufku. LIBERO için `10` kullanıyoruz. Bu LeRobot portu, yüklenen kontrol noktasının `max_action_horizon` değerini bu değerle geçersiz kılar.
- `policy.n_action_steps`: politika tekrar sorgulanmadan önce her tahmin edilen parçadan tüketilen eylem sayısı. LIBERO için bunu `chunk_size` olarak ayarlayın.
- `policy.setup_type`: robotu ve sahneyi açıklamak için prompt'a eklenen metin, örn. `single franka robotic arm in libero`. Daha fazla örnek, [`norm_stats.json`](https://huggingface.co/allenai/MolmoAct2/blob/main/norm_stats.json) dosyasındaki `metadata_by_tag` girdilerinde listelenmiştir.
- `policy.control_mode`: eylem uzayını açıklamak için istem içine eklenen metin, örn. `delta end-effector pose` veya `absolute joint pose`.
- `policy.image_keys`: işlemciye iletilen sıralı LeRobot görüntü gözlem anahtarları.
- `policy.dtype`: Pi0.5 tarzı hassasiyet anahtarı. `bfloat16`, büyük VLM matrisleri için bf16 otomatik dökümünü (autocast) ve depolamayı kullanırken, tam eylem uzmanını (action expert) ve sayısal olarak hassas modülleri fp32'de tutar. `float32`, otomatik dökümünü devre dışı bırakır ve tüm modeli fp32'de tutar. Düşük bellekli `bfloat16` profili, orijinal MolmoAct2 FP32-master AMP çalışmasından bilinçli olarak farklıdır: AdamW anları (moments), her parametrenin depolama veri türünü (dtype) takip eder, bu nedenle büyük bf16 VLM parametrelerinin anları da bf16'dır. Tam ince ayar (full fine-tuning), gradyan taşıyan her bf16 parametresi için tembelce (lazily) bir bf16 telafi tensörü tahsis eder, böylece bir parametre ULP'sinden küçük güncellemeler sonraki adımlara taşınır. Bu, bir fp32 ana kopyası değildir. LoRA adaptörleri, eylem uzmanı ve açıkça hassas olarak belirtilen modüller, fp32 parametrelerini ve optimizör durumunu korur; LoRA modundaki dondurulmuş VLM parametreleri için telafi tensörü tahsis edilmez.
- `policy.compile_model`: MolmoAct2'nin blok bazlı `torch.compile` yolunu etkinleştirir. Hem tam ince ayar (full fine-tuning) hem de LoRA, yalnızca eylem uzmanı (action-expert) transformer bloklarını derler. VLM/ViT/connector'ın acil (eager) çalıştırılması, her akış zaman adımında (flow timestep) değerlendirilen eylem yolundaki hızlanmayı korurken derleyiciden kaynaklanan BF16 aktivasyon ve gradyan sapmasını önler. Inductor, füzyonlu işlemler boyunca acil BF16 aşağı/aşağı yukarı dönüş (downcast/upcast) sınırlarını korumak için de talimatlandırılır. Bu, tek bir sabit hassasiyet-güvenli sınırdır ve başka bir derleme seçeneği eklenmez. Derleme varsayılan olarak devre dışıdır; uzun GPU eğitim çalıştırmaları için etkinleştirin. Eylem blokları PyTorch'un otomatik şekil (shape) stratejisini kullanır. Gradyan denetimi (gradient checkpointing) ile yalnızca değişken kodlayıcı-bağlam (encoder-context) dizisi boyutu dinamik olarak işaretlenir; parti boyutu (batch size), eylem ufku (action horizon) ve akış-zaman-adımı sayısı statik kalır. Bu modda Dynamo grafik önbelleği yeniden sıralaması ve ek DDP grafik bölücüsü devre dışı bırakılır, böylece geriye doğru yeniden hesaplama (backward recomputation), ileri yönde (forward) kullanılanla aynı blok grafiğini seçer. Partiye özgü metin/eylem dizileri, BOS eklenmeden önce dahili olarak 8'in katına soldan dolgu (left-padded) yapılır. Bu, en fazla yedi maskelenmiş token eklerken şekle özgü derleme ısınma süresini (compile warm-up) keskin biçimde azaltır; kullanıcıya yönelik bir seçenek değildir.
- `policy.num_flow_timesteps`: eğitim sırasında örnek başına örneklenen flow-matching zaman adımı sayısı. İnce ayar için `8` kullanıyoruz.
- `policy.num_inference_steps`: çıkarım sırasında sürekli eylem üretim adımları için isteğe bağlı geçersiz kılma.
- `policy.gradient_checkpointing`: VLM/aksiyon yolunda aktivasyon belleğini azaltmak için checkpointing'i etkinleştirir.
- `policy.freeze_embedding`: giriş gömme katmanlarını dondurur. Varsayılan değer `true`'dür.
- `policy.normalize_gripper`: gripper boyutlarının durum/aksiyon kantil normalizasyonuna dahil edilip edilmeyeceğini kontrol eder. Varsayılan değer `false`'dir.
- `policy.normalize_language`: prompt oluşturulmadan önce görev dizelerini normalize eder. Varsayılan değer `true`'dür.
- `policy.mask_action_dim_padding`: akış kaybında dolgulu boyutları maskeleme. Yayınlanan kontrol noktaları `policy.expected_max_action_dim=32` kullanır.
- `policy.max_sequence_length`: isteğe bağlı manuel dizi sınırı. Görsellerden, durum boyutundan, eylem boyutundan, eylem ufku ve ayrık eylem modundan çıkarılmasını istiyorsanız ayarlamayın.

### Öğrenme Hızları

MolmoAct2, orijinal MolmoAct2 ince ayar deneyleriyle uyumlu olmak için parametre-grubu öğrenme oranlarını kullanır.

- Tam ince ayar, VLM için `policy.optimizer_lr=1e-5`, görme kulesi için `policy.optimizer_vit_lr=5e-6`, görüntü bağlayıcı katmanları için `policy.optimizer_connector_lr=5e-6` ve eylem uzmanı için `policy.optimizer_action_expert_lr=5e-5` kullanır.
- LoRA VLM ince ayarı, `policy.train_mode_vlm=lora` olduğunda VLM, görme ve bağlayıcı LoRA parametre gruplarını `5e-5` olarak ayarlar; eylem uzmanı ise hâlâ `policy.optimizer_action_expert_lr` ile tamamen ince ayarlanır.
- Frozen-VLM ince ayarı `policy.train_mode_vlm=freeze` kullanır, yalnızca eylem uzmanını eğitir ve `policy.optimizer_action_expert_lr=5e-5` kullanır.
- `policy.optimizer_grad_clip_norm`, orijinal MolmoAct2 optimizatörüyle uyumlu olacak şekilde, LLM, vision tower, image connector ve action-expert parametre gruplarına bağımsız olarak uygulanır. Tek bir global-model gradyan normu değildir.

Tam ince ayar ve eylem uzmanı öğrenme oranlarını `policy.optimizer_lr`, `policy.optimizer_vit_lr`, `policy.optimizer_connector_lr` ve `policy.optimizer_action_expert_lr` ile geçersiz kılabilirsiniz. Zamanlayıcı ayarları `policy.scheduler_warmup_steps`, `policy.scheduler_decay_steps` ve `policy.scheduler_decay_lr` ile değiştirilebilir. Varsayılan 24.000 adımlık azalma ufku, resmi [`train_lerobot.py`](https://github.com/allenai/molmoact2/blob/5aac8f8a1180d79757ce500f819a02217079811c/experiments/launch_scripts/train_lerobot.py#L867-L868) tarifine uygundur.

### Veri Kümesi Çeyreklik İstatistikleri

MolmoAct2, durum ve eylem özellikleri için varsayılan olarak quantile normalization kullanır. Veri setiniz quantile istatistikleriyle dönüştürülmediyse, bunları şu şekilde ekleyebilirsiniz:

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

Bölüm başına özetlerden toplanan toplam çeyrekleri (quantile) kaydetme, devam ettirme ve birleştirme, böylece `meta/stats.json` tüm veri setinin çeyrekleri yerine muhafazakâr bir zarfı (`q <= 50` için `min`, `q > 50` için `max`) içersin. Sonuncusunu tahmin etmek için, her bölümü akan bir histogramla tarayın:

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

`--skip-images`, yalnızca `STATE`/`ACTION` yeniden hesaplanacaksa mevcut görüntü istatistiklerini korur ve video verilerinin indirilmesini veya çözümlenmesini önler; `--root` ise Hub yerine yerel bir veri setini okur. Bu değerler histogram tahminleridir, ayrıklaştırma ve yeniden sınıflandırma hatasına tabidir; bu nedenle muhafazakâr olanlardan farklılık gösterebilir. Bu durum, MolmoAct2'nin normalize edilmiş hedeflerini ve dolayısıyla kayıp ölçeğini değiştirir. Mevcut bir checkpoint içinde zaten kaydedilmiş istatistikler etkilenmez.

Alternatif olarak, MolmoAct2'yi ortalama/standart sapma normalizasyonu ile eğitin:

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

## Değerlendirme

Değerlendirme, hem LeRobot ile kaydedilen kontrol noktalarını hem de orijinal MolmoAct2 HF kontrol noktalarını destekler. LIBERO tekrarı için EGL render ortamını sabit tutun ve `policy.per_episode_seed=true` kullanın.

**Önemli:** `num_steps_wait=10`'ın LIBERO sahnesinin kararlı hale gelmesini güvenilir bir şekilde sağlamadığını ve ölçülen başarıyı düşürebileceğini tespit ettik. Burada raporlanan tüm LIBERO değerlendirme sonuçları `num_steps_wait=50` kullanılarak elde edilmiştir.

### LeRobot MolmoAct2 Ağırlığı ile Değerlendirme

LeRobot tarafından kaydedilen bir kontrol noktası için `policy.path` kullanın. Kaydedilen işlemci ve normalizasyon istatistikleri, modelle birlikte geri yüklenir.

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

### Orijinal MolmoAct2 Ağırlığıyla Değerlendirme

Yayınlanmış bir Hugging Face checkpoint'ini önce bir LeRobot checkpoint'ine dönüştürmeden doğrudan değerlendirebilirsiniz. Bu durumda, `policy.checkpoint_path` değerini HF model deposuna ayarlayın ve `policy.norm_tag` parametresini sağlayın. LIBERO için, `policy.norm_tag=libero` ayarı, checkpoint'in `norm_stats.json` dosyasından LIBERO eylem/durum normalizasyon istatistiklerini, eylem ufku (action horizon) değerini, prompt meta verilerini ve görüntü anahtarı sırasını yükler.

Yayınlanan Hugging Face checkpoint'leriyle MolmoAct2 makalesinin sonuçlarını tam olarak yeniden üretmek için, v0.5.1'e sabitlenmiş [`allenai/lerobot` `molmoact2-hf-inference`](https://github.com/allenai/lerobot/tree/molmoact2-hf-inference) dalını kullanmanızı öneririz. Bu dal, raporlanan sayılar için kullanılan orijinal değerlendirme ayarlarıyla eşleşmektedir.

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

Tüm LIBERO paketini çalıştırmak için `--env.task=libero_10,libero_goal,libero_object,libero_spatial` kullanın. İstenen `policy.norm_tag` o checkpoint'in `norm_stats.json` dosyasında mevcut olduğu sürece, aynı komut diğer yayımlanmış MolmoAct2 checkpoint'leri için de geçerlidir.

### Yaygın Değerlendirme Seçenekleri

- `policy.inference_action_mode`: rollout için zorunludur. Akış eşleştirme çıkarımı için `continuous` veya eylem-jetonu çıkarımı için `discrete` kullanın. Kontrol noktasında kaydedilen eğitim zamanı `policy.action_mode` ile uyumlu olmalıdır.
- `policy.path`: LeRobot kontrol noktası yolu veya Hub deposu. LeRobot tarafından kaydedilen kontrol noktaları için bunu kullanın.
- `policy.checkpoint_path`: orijinal MolmoAct2 HF checkpoint yolu veya Hub deposu. Bunu `policy.type=molmoact2` ve `policy.norm_tag` ile kullanın.
- `policy.norm_tag`: orijinal checkpoint'in `norm_stats.json` dosyasından normalizasyon istatistiklerini, istem (prompt) meta verilerini, anahtar sırasını ve eylem ufuk seçer. Doğrudan orijinal HF checkpoint değerlendirmesi için gereklidir.
- `policy.dtype`: model depolama/autocast profili. Normal GPU değerlendirmesi için `bfloat16` kullanın. Tam fp32 çıkarımını açıkça istediğiniz durumlarda yalnızca `float32` kullanın.
- `policy.enable_inference_cuda_graph`: Daha hızlı tekrarlı sürekli eylem dağıtımı için MolmoAct2 çıkarım CUDA grafı yolunu etkinleştirir.
- `policy.per_episode_seed` ve `policy.eval_seed`: tekrarlanabilirlik için stokastik sürekli eylem üretimini bölüm başına deterministik hale getirir.
- `env.task`: virgülle ayrılmış LIBERO setleri veya tek bir set. Tam benchmark için `libero_10,libero_goal,libero_object,libero_spatial` kullanın.
- `env.camera_name_mapping`: LIBERO kamera adlarını, politika işleyicisinin beklediği görüntü anahtarlarına eşler.

## Performans Sonuçları

### LIBERO Benchmark Sonuçları

MolmoAct2, LIBERO benchmark setinde güçlü bir performans sergilemiştir. LeRobot uygulamasını karşılaştırmak ve test etmek için, [`allenai/MolmoAct2-LIBERO`](https://huggingface.co/allenai/MolmoAct2-LIBERO) modelini 8 H100 GPU üzerinde, GPU başına 32 parti boyutuyla LIBERO veri setinde ek olarak 10k adım boyunca ince ayarladık ve ardından sonuçları orijinal MolmoAct2 referans sonuçlarıyla karşılaştırdık.

Burada raporlanan LeRobot ile ince ayarlanmış kontrol noktası [`allenai/MolmoAct2-LIBERO-LeRobot`](https://huggingface.co/allenai/MolmoAct2-LIBERO-LeRobot) adresinde bulunabilir ve [`allenai/MolmoAct2-LIBERO-Dataset`](https://huggingface.co/datasets/allenai/MolmoAct2-LIBERO-Dataset) üzerinde eğitilmiştir.

| Karma      | LeRobot Uygulaması | MolmoAct2 Orijinal |
| -------------- | ---------------------: | -----------------: |
| LIBERO Uzamsal |                  98.4% |              97.8% |
| LIBERO Nesne  |                 100.0% |             100.0% |
| LIBERO Hedef    |                  98.0% |              97.8% |
| LIBERO 10      |                  96.6% |              93.2% |
| Ortalama        |                 98.25% |             97.20% |

Bu sonuçlar, MolmoAct2'nin çeşitli robotik manipülasyon görevlerinde güçlü performansını göstermektedir. Bunları yeniden üretmek için LIBERO değerlendirme bölümündeki talimatları izleyin.

## Donanım Dağıtımı (lerobot-rollout)

LeRobot formatındaki checkpoint'ler, `lerobot-rollout` ile doğrudan kullanım için Hub'da mevcuttur. Her checkpoint, robotunuzun kamera yapılandırmasıyla eşleşmesi gereken belirli kamera adlarını kullanır.

### Kamera adlandırma kuralı

Her checkpoint, belirli `observation.images.*` anahtarlarını bekler. Robotunuzun kameraları farklı adlara sahipse, bunları eşlemek için `--rename_map` kullanın:

| Kontrol Noktası                    | Kamera anahtarları            | Açıklama              |
| ----------------------------- | ---------------------- | ------------------------ |
| MolmoAct2-LIBERO-LeRobot      | `image`, `wrist_image` | LIBERO sim kameraları       |
| MolmoAct2-BimanualYAM-LeRobot | `top`, `left`, `right` | YAM 3 kamera kurulumu       |
| MolmoAct2-DROID-LeRobot       | `cam0`, `cam1`         | Dış + bilek         |
| MolmoAct2-SO100_101-LeRobot   | `cam0`, `cam1`         | Birincil + ikincil görünüm |

Üst ve yan kameralar kullanan bir SO-100 robotu ile örnek:

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

Bilek kamerası kullanmak için yalnızca yeniden adlandırma eşlemesini değiştirin:

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

### Ortak çerçeve dönüşümü (SO-100/101 sıfır atış)

MolmoAct2-SO100_101 checkpoint, LeRobot >= 0.5.0'den farklı bir eklem kalibrasyonu sözleşmesi kullanan veriler üzerinde eğitilmiştir. Çerçebe düzeltmesi yapılmadığı takdirde kol yanlış yönde hareket edebilir.

Bu durum, orijinal kontrol noktasından hem **sıfır atış dağıtımını** hem de **ince ayarlamayı** etkiler. Ön eğitilmiş ağırlıklar eski konvansiyonu beklediği için tüm ortak veriler (gözlemler ve eylemler) buna uygun şekilde dönüştürülmelidir.

Dönüştürülen LeRobot kontrol noktası (`lerobot/MolmoAct2-SO100_101-LeRobot`), işlemci hattında bu düzeltmeyi zaten içerir. Kontrol noktasını kendiniz dönüştürür veya ince ayar yaparsanız, politika yapılandırmasında (`configuration_molmoact2.py`) aşağıdakileri ayarlayın:

- `joint_signs`: `[1, -1, 1, 1, 1, 1]` (omuz kaldırma yönünü tersine çevirir)
- `joint_offsets`: `[0, 90, 90, 0, 0, 0]` (shoulder_lift ve elbow_flex değerlerini 90° kaydırır)

Kalibrasyon değişikliğine ilişkin ayrıntılar için [geriye dönük uyumluluk kılavuzuna](./backwardcomp) bakın.

## Orijinal Uygulamadan Farklar

Bu LeRobot portu, LeRobot'un veri seti, eğitim, değerlendirme, checkpoint ve günlük altyapısını kullanırken MolmoAct2 davranışını eşleştirmek üzere tasarlanmıştır. Orijinal eğitim deposundan ana farklar şunlardır:

- Orijinal makaledeki eğitim yığını, fp32 ana parametreleri korur ve bf16 AMP altında eğitim yapar. Bu LeRobot portu, belleği azaltmak için `policy.dtype=bfloat16` kullanır: büyük VLM matrisleri bf16'da saklanırken, eylem uzmanı ve sayısal olarak hassas modüller fp32'de kalır ve uygun operatörler bf16 autocast altında çalışır. bf16 güncelleme telafi tensörü, tam ince ayar sırasında parametre yuvarlama kaybını azaltır, ancak bf16 Adam anları, orijinal fp32 optimizör durumunu tam olarak yeniden üretmez.
- Orijinal depo, kendi FSDP/model-parallel eğitim yolunu kullanır. LeRobot portu, standart LeRobot/Accelerate eğitim yolunu kullanır ve çoklu düğüm (multi-node) eğitimi için test edilmemiştir.
- Orijinal depo, dizi paketlemeyi (sequence packing) destekler. LeRobot portu, her öğe için bir LeRobot örneği üzerinde eğitim yapar ve çıkarılan maksimum dizi uzunluğu korumasıyla partiye özgü dolgu (batch-local padding) kullanır.
- LeRobot portu, LeRobot'un optimizleyici, zamanlayıcı, kontrol noktası kaydetme, veri seti dönüşümleri, görüntü artırma ve Trackio günlük tutma kurallarını takip eder.
- Orijinal eğitim yolu, `max_action_horizon` değerine padding uygulanarak ve eylem uzmanı öz-dikkatinde (self-attention) padding'li ufuk (horizon) slotlarının maskelenmesiyle karışık eylem ufuklarını (mixed action horizons) destekler. Bu, farklı kontrol frekanslarına sahip veri setleri arasında eğitim yapılırken faydalıdır. LeRobot portu şu anda tek veri setiyle ince ayar (fine-tuning) hedeflediğinden, `policy.chunk_size` checkpoint'teki `max_action_horizon` değerini geçersiz kılar ve ufuk maskelenmesi henüz uygulanmamıştır. Bu karışık ufuk yolunun desteği planlanmaktadır.

## Atıf

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

## Lisans

Bu model, Apache 2.0 lisansı altında lisanslanmıştır. [Ai2 Sorumlu Kullanım İlkeleri](https://allenai.org/responsible-use) ile uyumlu olarak ve [allenai/molmoact2](https://github.com/allenai/molmoact2) ile tutarlı biçimde, araştırma ve eğitim amaçlı kullanılmak üzere tasarlanmıştır.

