# Política de MolmoAct2

MolmoAct2 es la implementación de la política de [MolmoAct2](https://allenai.org/blog/molmoact2) en LeRobot, adaptada a las interfaces de entrenamiento, evaluación, checkpointing y conjuntos de datos de LeRobot para facilitar su uso con conjuntos de datos de LeRobot.

Esta implementación actualmente admite el entrenamiento y la evaluación para el modelo MolmoAct2 regular. MolmoAct2-Think, que admite razonamiento de profundidad adaptativa, aún no está incluido en esta política de LeRobot.

Para el código de entrenamiento original de MolmoAct2 utilizado en los experimentos reportados en el artículo, consulte [allenai/molmoact2](https://github.com/allenai/molmoact2).

## Requisitos de instalación

Instale LeRobot con las dependencias opcionales de MolmoAct2:

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

Para ejecutar los modelos de este repositorio, se necesita una GPU de NVIDIA. La ruta actual de precisión mixta almacena el experto de acción completo en fp32 y las matrices grandes del VLM en bf16. `policy.compile_model=true` compila opcionalmente los bloques del experto de acción, mientras que el VLM, la torre de visión, el conector y el envoltorio de la política se mantienen en modo eager. Esta frontera pasó las comprobaciones de paridad de salida con el mismo inicio, gradientes y actualizaciones del optimizador; compilar la ruta del VLM en bf16 no las pasó.

El entrenamiento multi-GPU a través de `accelerate` aumenta el rendimiento y el tamaño del lote global. Esta ruta se ha probado en ejecuciones de GB200 con dos nodos y ocho GPUs, pero este port de LeRobot no expone la ruta de entrenamiento con paralelismo de modelos `fsdp_devices` original de MolmoAct2. Una reproducción de GB200 con una GPU y dos anchos de prompt reales produjo un grafo de acciones compilado sin rupturas de grafo, la misma memoria pico de 55.15 GiB que la ejecución eager y una aceleración moderada en estado estacionario. Considere estos resultados como comprobaciones de implementación y no como afirmaciones portables de rendimiento o ETA.

El repositorio se ha probado con Ubuntu 22.04.

## Uso

Para usar MolmoAct2 en una configuración de entrenamiento de LeRobot, establezca:

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

## Entrenamiento

MolmoAct2 se puede ajustar a partir del formato de checkpoint de Hugging Face de MolmoAct2 publicado o desde un checkpoint ya guardado por LeRobot. Ambas rutas utilizan el mismo bucle de entrenamiento de LeRobot, las transformaciones de datos, el guardado de checkpoints y el registro de eventos. La única diferencia es cómo se cargan los pesos iniciales de la política y el estado del procesador.

LeRobot desactiva la aumentación de imágenes de los conjuntos de datos de forma predeterminada. Mantenga `--dataset.image_transforms.enable=true` en los comandos de entrenamiento de MolmoAct2. La receta de transformación original de MolmoAct2 no es la configuración predeterminada de transformación genérica de LeRobot, por lo que el primer comando también fija explícitamente su recorte del 95%, su rotación de 5 grados y su variación de color. La receta original aplica además un desenfoque gaussiano con probabilidad 0.2; la configuración de subconjunto de transformación genérica de LeRobot no puede expresar esa cuarta transformación opcional sin a veces omitir una de las tres transformaciones requeridas.

### Entrenamiento con los pesos originales de MolmoAct2

Use `policy.checkpoint_path` al partir de un checkpoint de MolmoAct2 publicado, por ejemplo `allenai/MolmoAct2` o `allenai/MolmoAct2-LIBERO`. LeRobot cargará los archivos de modelo de HF originales y luego construirá su propio policy processor a partir de los metadatos del dataset y las opciones de policy que se indican a continuación.

El comando siguiente muestra el ajuste fino completo en el conjunto de datos LIBERO fusionado a partir del punto de control base publicado. Utiliza la carga del modelo en bf16, 8 pasos de flujo, las estadísticas de cuantiles oficiales de LIBERO, la aumentación de imágenes y la ruta de puntos de control/registros de LeRobot. No sustituya los cuantiles de metadatos aproximados de `lerobot/libero` por los publicados en `norm_stats.json`; sus valores de q01/q99 no son idénticos.

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

### Entrenamiento con el peso LeRobot MolmoAct2

Use `policy.path` al iniciar desde un checkpoint de MolmoAct2 guardado por LeRobot, ya sea desde un directorio local `pretrained_model` o desde el Hub. Esto restaura la configuración de la política de LeRobot guardada, los pesos del modelo, el procesador y las estadísticas de normalización. Aún así, puede sobrescribir opciones de entrenamiento como `batch_size`, `steps` o `policy.action_mode`. La carga de checkpoints es estricta y preserva la topología FFT o LoRA guardada, por lo que no debe sobrescribir `policy.train_mode_vlm` al usar `policy.path`. Para iniciar una nueva ejecución de LoRA, inicialice desde los pesos de HF con `policy.checkpoint_path` en su lugar, por ejemplo con `--policy.type=molmoact2`, `--policy.checkpoint_path=allenai/MolmoAct2` y `--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
```

### Prácticas comunes

Para el ajuste fino en un conjunto de datos relativamente pequeño, como una sola suite de LIBERO o un conjunto de datos del mundo real con menos de 200 demostraciones, un tamaño de lote global de 16 a 32 es un buen punto de partida. En estos escenarios, recomendamos usar `policy.train_mode_vlm=lora` (el valor predeterminado), que suele ofrecer un rendimiento similar o incluso mejor que `fft`. Además, `policy.train_mode_vlm=freeze` también es una opción práctica. En todos los modos, mantenemos intencionalmente al experto de acciones completamente entrenable, lo cual consideramos crucial para el rendimiento del modelo. Para conjuntos de datos de ajuste fino más grandes, generalmente se prefieren tamaños de lote global más grandes y el ajuste fino completo del VLM (`policy.train_mode_vlm=fft`).

### Opciones de política comunes

- `policy.checkpoint_path`: punto de control original de MolmoAct2 HF desde el que inicializar. Utilice esto para los pesos de MolmoAct2 publicados.
- `policy.path`: Punto de control de LeRobot desde el que inicializar. Úselo para los puntos de control creados por el entrenamiento de LeRobot.
- `policy.action_mode`: objetivo de entrenamiento, uno de `continuous`, `discrete` o `both`. El ajuste fino oficial de robots MolmoAct2 utiliza `continuous`. Los puntos de control publicados conservan los pesos de acciones discretas; `both` está disponible como ablation explícita de flujo de emparejamiento conjunto más token de acción.
- `policy.train_mode_vlm`: controla el modo de ajuste fino del VLM, uno de `fft`, `lora` o `freeze`. `fft` realiza un ajuste fino completo del VLM, `lora` entrena adaptadores LoRA en las capas lineales del VLM y `freeze` congela el VLM. El experto de acción se ajusta completamente en los tres modos. El valor predeterminado es `lora`. `freeze` requiere `policy.action_mode=continuous`.
- `policy.enable_knowledge_insulation`: cuando es `true`, desvincula los estados K/V del contexto del experto de acción antes de la pérdida de acción. El valor predeterminado es `false`.
- `policy.chunk_size`: horizonte de acción utilizado por la política. Para LIBERO usamos `10`. Esta portada de LeRobot sobrescribe el `max_action_horizon` del checkpoint cargado con este valor.
- `policy.n_action_steps`: número de acciones consumidas de cada bloque predicho antes de consultar la política nuevamente. Para LIBERO, establézcalo en `chunk_size`.
- `policy.setup_type`: texto insertado en el prompt para describir el robot y la escena, p. ej. `single franka robotic arm in libero`. Se enumeran más ejemplos en las entradas de `metadata_by_tag` de [`norm_stats.json`](https://huggingface.co/allenai/MolmoAct2/blob/main/norm_stats.json).
- `policy.control_mode`: texto insertado en el prompt para describir el espacio de acciones, p. ej. `delta end-effector pose` o `absolute joint pose`.
- `policy.image_keys`: claves de observación de imagen de LeRobot ordenadas que se pasan al procesador.
- `policy.dtype`: conmutador de precisión al estilo Pi0.5. `bfloat16` utiliza autocast/almacenamiento bf16 para las matrices grandes del VLM, manteniendo el experto de acciones completo y los módulos numéricamente sensibles en fp32. `float32` desactiva el autocast y mantiene el modelo completo en fp32. El perfil de baja memoria `bfloat16` difiere intencionalmente de la ejecución original de MolmoAct2 con AMP y maestro FP32: los momentos de AdamW siguen el dtype de almacenamiento de cada parámetro, por lo que los grandes parámetros bf16 del VLM también tienen momentos bf16. El ajuste fino completo asigna de forma perezosa un tensor de compensación bf16 para cada parámetro bf16 que lleva gradiente, de modo que las actualizaciones menores que un ULP del parámetro se lleven a pasos posteriores. Esto no es una copia maestra en fp32. Los adaptadores LoRA, el experto de acciones y los módulos explícitamente sensibles conservan parámetros y estado del optimizador en fp32; los parámetros VLM congelados en modo LoRA no asignan ningún tensor de compensación.
- `policy.compile_model`: habilita la ruta de `torch.compile` por bloques de MolmoAct2. Tanto el ajuste fino completo como LoRA compilan únicamente los bloques del transformer del experto de acciones. La ejecución eager de VLM/ViT/connector evita la deriva de activaciones y gradientes en BF16 inducida por el compilador, al tiempo que conserva la aceleración para la ruta de acciones evaluada en cada paso de flujo. Se instruye a Inductor para que preserve los límites de downcast/upcast eager en BF16 a través de las operaciones fusionadas. Este es un límite fijo seguro en precisión y no añade otra opción de compilación. La compilación está deshabilitada de forma predeterminada; actívela para ejecuciones largas de entrenamiento en GPU. Los bloques de acciones utilizan la estrategia de forma automática de PyTorch. Con el checkpointing de gradientes, solo la dimensión de secuencia del contexto del codificador variable se marca como dinámica; el tamaño del lote, el horizonte de acciones y la cantidad de pasos de flujo permanecen estáticos. El reordenamiento de la caché de grafos de Dynamo y su divisor de grafos DDP adicional se deshabilitan en ese modo para que la recomputación hacia atrás seleccione el mismo grafo de bloques que el hacia adelante. Las secuencias de texto/acción locales al lote se rellenan a la izquierda hasta un múltiplo interno de 8 antes de la inserción de BOS. Esto añade como máximo siete tokens enmascarados y reduce drásticamente el calentamiento de compilación específico de forma; no es una opción visible para el usuario.
- `policy.num_flow_timesteps`: número de pasos de tiempo de flow-matching muestreados por ejemplo durante el entrenamiento. Usamos `8` para el ajuste fino.
- `policy.num_inference_steps`: reemplazo opcional para los pasos de generación de acciones continuas en tiempo de inferencia.
- `policy.gradient_checkpointing`: habilita el checkpointing en la ruta VLM/acción para reducir la memoria de activaciones.
- `policy.freeze_embedding`: congela los embeddings de entrada. El valor predeterminado es `true`.
- `policy.normalize_gripper`: controla si las dimensiones del agarre se incluyen en la normalización de cuantiles del estado/acción. El valor predeterminado es `false`.
- `policy.normalize_language`: normaliza las cadenas de tareas antes de la construcción del prompt. El valor predeterminado es `true`.
- `policy.mask_action_dim_padding`: enmascara las dimensiones rellenas en la pérdida de flujo. Los puntos de control publicados usan `policy.expected_max_action_dim=32`.
- `policy.max_sequence_length`: límite manual opcional de la secuencia. Déjelo sin establecer para inferirlo a partir de las imágenes, la dimensión del estado, la dimensión de la acción, el horizonte de acción y el modo de acción discreta.

### Tasas de aprendizaje

MolmoAct2 utiliza tasas de aprendizaje por grupo de parámetros para coincidir con los experimentos de ajuste fino originales de MolmoAct2.

- El ajuste fino completo utiliza `policy.optimizer_lr=1e-5` para el VLM, `policy.optimizer_vit_lr=5e-6` para la torre de visión, `policy.optimizer_connector_lr=5e-6` para las capas del conector de imágenes y `policy.optimizer_action_expert_lr=5e-5` para el experto de acción.
- El ajuste fino de VLM con LoRA establece los grupos de parámetros LoRA del VLM, la visión y el conector en `5e-5` cuando `policy.train_mode_vlm=lora`; el experto de acción sigue ajustándose por completo con `policy.optimizer_action_expert_lr`.
- El ajuste fino de Frozen-VLM utiliza `policy.train_mode_vlm=freeze`, entrena solo el experto de acción y usa `policy.optimizer_action_expert_lr=5e-5`.
- `policy.optimizer_grad_clip_norm` se aplica de forma independiente a los grupos de parámetros del LLM, la torre de visión, el conector de imágenes y el experto de acciones, coincidiendo con el optimizador original de MolmoAct2. No se trata de una norma de gradiente global del modelo.

Puede sobrescribir las tasas de aprendizaje del ajuste fino completo y del experto de acciones con `policy.optimizer_lr`, `policy.optimizer_vit_lr`, `policy.optimizer_connector_lr` y `policy.optimizer_action_expert_lr`. La configuración del programador se puede cambiar con `policy.scheduler_warmup_steps`, `policy.scheduler_decay_steps` y `policy.scheduler_decay_lr`. El horizonte de decaimiento predeterminado de 24.000 pasos coincide con la receta oficial de [`train_lerobot.py`](https://github.com/allenai/molmoact2/blob/5aac8f8a1180d79757ce500f819a02217079811c/experiments/launch_scripts/train_lerobot.py#L867-L868).

### Estadísticas de cuantiles del conjunto de datos

MolmoAct2 utiliza la normalización por cuantiles de forma predeterminada para las características de estado y acción. Si su conjunto de datos no se ha convertido con estadísticas de cuantiles, puede añadirlas con:

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

Grabación, reanudación y fusión de cuantiles agregados a partir de resúmenes por episodio, de modo que `meta/stats.json` contenga un sobre envolvente conservador (`min` para `q <= 50`, `max` para `q > 50`) en lugar de cuantiles de todo el conjunto de datos. Para estimar estos últimos, recorra cada episodio con un histograma en ejecución:

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

`--skip-images` conserva las estadísticas de imagen existentes y evita la descarga o decodificación de datos de video cuando solo se necesitan recalcular `STATE`/`ACTION`, y `--root` lee un conjunto de datos local en lugar del Hub. Estos valores son estimaciones de histograma, sujetas a errores de discretización y rebinning, por lo que pueden diferir de los conservadores, lo que cambia los objetivos normalizados de MolmoAct2 y, por tanto, la escala de su pérdida. Las estadísticas ya guardadas dentro de un checkpoint existente no se ven afectadas.

Alternativamente, entrene MolmoAct2 con normalización media/desviación estándar:

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

## Evaluación

La evaluación también admite tanto los puntos de control guardados con LeRobot como los puntos de control originales de MolmoAct2 de HF. Para la replicación de LIBERO, mantenga fijo el entorno de renderizado EGL y use `policy.per_episode_seed=true`.

**Importante:** Hemos observado que `num_steps_wait=10` no permite de forma fiable que la escena de LIBERO se estabilice y puede degradar el éxito medido. Todos los resultados de evaluación de LIBERO informados aquí utilizan `num_steps_wait=50`.

### Evaluación con LeRobot MolmoAct2 Weight

Use `policy.path` para un checkpoint guardado por LeRobot. El procesador guardado y las estadísticas de normalización se restauran junto con el modelo.

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

### Evaluación con los pesos originales de MolmoAct2

Puede evaluar un checkpoint publicado de Hugging Face directamente, sin necesidad de convertirlo primero en un checkpoint de LeRobot. En este caso, establezca `policy.checkpoint_path` en el repositorio del modelo de HF y proporcione `policy.norm_tag`. Para LIBERO, `policy.norm_tag=libero` carga las estadísticas de normalización de acciones/estados de LIBERO, el horizonte de acciones, los metadatos del prompt y el orden de las claves de imagen desde el `norm_stats.json` del checkpoint.

Para replicar por completo los resultados del paper de MolmoAct2 con los checkpoints de Hugging Face publicados, recomendamos usar la rama [`allenai/lerobot` `molmoact2-hf-inference`](https://github.com/allenai/lerobot/tree/molmoact2-hf-inference) con la versión v0.5.1 fijada. Esa rama coincide con la configuración de evaluación original utilizada para los números reportados.

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

Use `--env.task=libero_10,libero_goal,libero_object,libero_spatial` para ejecutar la suite completa de LIBERO. El mismo comando funciona para otros checkpoints de MolmoAct2 publicados, siempre que el `policy.norm_tag` solicitado exista en el `norm_stats.json` de ese checkpoint.

### Opciones de evaluación comunes

- `policy.inference_action_mode`: obligatorio para el rollout. Use `continuous` para la inferencia de flow-matching o `discrete` para la inferencia de tokens de acción. Debe ser compatible con el `policy.action_mode` de entrenamiento guardado en el checkpoint.
- `policy.path`: Ruta del checkpoint de LeRobot o repositorio de Hub. Utilice esto para los checkpoints guardados por LeRobot.
- `policy.checkpoint_path`: ruta original del checkpoint de MolmoAct2 en HF o repositorio de Hub. Úsalo con `policy.type=molmoact2` y `policy.norm_tag`.
- `policy.norm_tag`: selecciona las estadísticas de normalización, los metadatos del prompt, el orden de las claves de imagen y el horizonte de acción desde el `norm_stats.json` del checkpoint original. Es obligatorio para la evaluación directa de un checkpoint original de HF.
- `policy.dtype`: perfil de almacenamiento/autocast del modelo. Use `bfloat16` para la evaluación normal en GPU. Use `float32` solo cuando desee explícitamente inferencia en fp32 completo.
- `policy.enable_inference_cuda_graph`: habilita la ruta de grafo CUDA de inferencia de MolmoAct2 para un despliegue continuo de acciones repetidas más rápido.
- `policy.per_episode_seed` y `policy.eval_seed`: hacen que la generación de acciones continuas estocásticas sea determinista por episodio para la replicación.
- `env.task`: suites de LIBERO separadas por comas o una sola suite. Utilice `libero_10,libero_goal,libero_object,libero_spatial` para el benchmark completo.
- `env.camera_name_mapping`: asigna los nombres de las cámaras de LIBERO a las claves de imagen esperadas por el procesador de la política.

## Resultados de rendimiento

### Resultados del benchmark LIBERO

MolmoAct2 ha demostrado un rendimiento sólido en la suite de benchmarks LIBERO. Para comparar y probar su implementación en LeRobot, ajustamos finamente [`allenai/MolmoAct2-LIBERO`](https://huggingface.co/allenai/MolmoAct2-LIBERO) durante 10k pasos adicionales en el conjunto de datos LIBERO, con un tamaño de lote por GPU de 32 en 8 GPUs H100, y luego comparamos los resultados con los resultados de referencia originales de MolmoAct2.

El punto de control afinado con LeRobot reportado aquí está disponible en [`allenai/MolmoAct2-LIBERO-LeRobot`](https://huggingface.co/allenai/MolmoAct2-LIBERO-LeRobot) y se entrenó con [`allenai/MolmoAct2-LIBERO-Dataset`](https://huggingface.co/datasets/allenai/MolmoAct2-LIBERO-Dataset).

| Benchmark      | Implementación de LeRobot | MolmoAct2 Original |
| -------------- | ---------------------: | -----------------: |
| LIBERO Espacial |                  98.4% |              97.8% |
| LIBERO Object  |                 100.0% |             100.0% |
| Objetivo de LIBERO    |                  98.0% |              97.8% |
| LIBERO 10      |                  96.6% |              93.2% |
| Promedio        |                 98.25% |             97.20% |

Estos resultados demuestran el sólido rendimiento de MolmoAct2 en diversas tareas de manipulación robótica. Para reproducirlos, siga las instrucciones de la sección de evaluación de LIBERO.

## Despliegue de hardware (lerobot-rollout)

Los puntos de control en formato LeRobot están disponibles en el Hub para su uso directo con `lerobot-rollout`. Cada punto de control utiliza nombres de cámara específicos que deben coincidir con la configuración de cámaras de tu robot.

### Convención de nomenclatura de cámaras

Cada punto de control espera claves específicas de `observation.images.*`. Si las cámaras de tu robot tienen nombres diferentes, usa `--rename_map` para mapearlas:

| Checkpoint                    | Teclas de la cámara            | Descripción              |
| ----------------------------- | ---------------------- | ------------------------ |
| MolmoAct2-LIBERO-LeRobot      | `image`, `wrist_image` | LIBERO cámaras simuladas       |
| MolmoAct2-BimanualYAM-LeRobot | `top`, `left`, `right` | Configuración de 3 cámaras de YAM       |
| MolmoAct2-DROID-LeRobot       | `cam0`, `cam1`         | Externa + muñeca         |
| MolmoAct2-SO100_101-LeRobot   | `cam0`, `cam1`         | Vista principal + secundaria |

Ejemplo con un robot SO-100 que utiliza cámaras superior y lateral:

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

Para usar una cámara de muñeca en su lugar, simplemente cambie el mapeo de renombrado:

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

### Transformación de marco conjunta (SO-100/101 zero-shot)

El checkpoint MolmoAct2-SO100_101 se entrenó con datos que utilizan una convención de calibración de articulaciones diferente a la de LeRobot >= 0.5.0. Sin una corrección de marco, el brazo puede moverse en la dirección incorrecta.

Esto afecta tanto a la **implementación sin ejemplos** como al **ajuste fino** a partir del punto de control original. Los pesos preentrenados esperan la convención anterior, por lo que todos los datos conjuntos (observaciones y acciones) deben transformarse para que coincidan.

El punto de control de LeRobot convertido (`lerobot/MolmoAct2-SO100_101-LeRobot`) ya incluye esta corrección en su pipeline de procesador. Si conviertes o ajustas el punto de control por tu cuenta, configura lo siguiente en la configuración de la política (`configuration_molmoact2.py`):

- `joint_signs`: `[1, -1, 1, 1, 1, 1]` (invierte la dirección de shoulder_lift)
- `joint_offsets`: `[0, 90, 90, 0, 0, 0]` (desplaza shoulder_lift y elbow_flex en 90°)

Consulte la [guía de compatibilidad hacia atrás](./backwardcomp) para obtener detalles sobre el cambio de calibración.

## Diferencias con la implementación original

Este port de LeRobot está diseñado para replicar el comportamiento de MolmoAct2 mientras utiliza la infraestructura de conjuntos de datos, entrenamiento, evaluación, puntos de control y registro de LeRobot. Las principales diferencias con el repositorio de entrenamiento original son:

- La pila de entrenamiento del artículo original mantiene parámetros maestros en fp32 y entrena con AMP en bf16. Esta portación de LeRobot utiliza `policy.dtype=bfloat16` para reducir la memoria: las matrices grandes de VLM se almacenan en bf16, mientras que el experto de acciones y los módulos numéricamente sensibles permanecen en fp32 y los operadores elegibles se ejecutan bajo autocast de bf16. Un tensor de compensación de actualización en bf16 reduce la pérdida por redondeo de parámetros durante el ajuste fino completo, pero sus momentos de Adam en bf16 aún no reproducen exactamente el estado del optimizador original en fp32.
- El repositorio original utiliza su propia ruta de entrenamiento FSDP/paralelismo de modelo. La versión de LeRobot utiliza la ruta de entrenamiento estándar de LeRobot/Accelerate y no ha sido probada para entrenamiento multinodo.
- El repositorio original admite el empaquetado de secuencias. La versión de LeRobot entrena con una muestra de LeRobot por elemento y usa relleno local por lote con una salvaguarda de longitud máxima de secuencia inferida.
- La portada de LeRobot sigue las convenciones de LeRobot para el optimizador, el programador, el guardado de puntos de control, las transformaciones de conjuntos de datos, la aumentación de imágenes y el registro de Trackio.
- La ruta de entrenamiento original admite horizontes de acción mixtos mediante el relleno hasta `max_action_horizon` y la enmascaración de los huecos rellenados del horizonte en la autoatención del experto de acciones. Esto resulta útil al entrenar en conjuntos de datos con frecuencias de control diferentes. La versión de LeRobot se centra actualmente en el ajuste fino de un solo conjunto de datos, por lo que `policy.chunk_size` anula el `max_action_horizon` del punto de control y la enmascaración del horizonte aún no está implementada. Se prevé el soporte para esta ruta de horizonte mixto.

## Cita

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

## Licencia

Este modelo está licenciado bajo Apache 2.0. Está destinado a su uso en investigación y educación de conformidad con las [Directrices de Uso Responsable de Ai2](https://allenai.org/responsible-use), en línea con [allenai/molmoact2](https://github.com/allenai/molmoact2).

