LeRobot 中的 MolmoAct2 策略：VLM 驱动的机器人动作推理模型训练、评测与部署实战指南

LeRobot 中的 MolmoAct2 策略：VLM 驱动的机器人动作推理模型训练、评测与部署实战指南

【免费下载链接】lerobot🤗 LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot

MolmoAct2 是 Allen Institute for AI（Ai2）提出的动作推理模型（Action Reasoning Model），它将 Molmo 视觉语言骨干与逐层流匹配（flow-matching）动作专家（action expert）结合，通过端到端学习实现连续动作生成。本文以仓库文档 docs/source/policy_molmoact2_README.md 为骨架，结合 src/lerobot/policies/molmoact2 下的配置、建模与处理器源码，系统讲解如何在 LeRobot 中完成 MolmoAct2 的安装、微调、LIBERO 基准评测、真实机器人部署，以及它与原始官方实现之间的关键差异。读完本文，你将掌握从 Hugging Face 原始权重或 LeRobot 已保存检查点两种路径出发的完整训练/评测命令、全部核心策略参数的含义与默认值、混合精度与编译策略背后的原理，并能在 SO-100 等真实机器人上通过lerobot-rollout直接部署。

一、MolmoAct2 与 LeRobot 的集成概况

MolmoAct2 是 Ai2 于 2026 年发布的"面向真实世界部署的动作推理模型"（Action Reasoning Models for Real-world Deployment）。LeRobot 仓库将其移植为标准的molmoact2策略类型，从而完整复用 LeRobot 的训练循环、数据集接口、检查点保存与日志记录体系。从源码结构看，策略实现集中在以下文件：

• configuration_molmoact2.py：定义MolmoAct2Config（继承PreTrainedConfig）、策略本地优化器MolmoAct2AdamW与余弦退火调度器MolmoAct2CosineWithWarmupSchedulerConfig；
• modeling_molmoact2.py：把 vendored 的 HF 模型封装进PreTrainedPolicy接口，实现流匹配损失、离散动作 token 损失、select_action与predict_action_chunk；
• processor_molmoact2.py：构建多模态 prompt（图像 + 离散化状态 + 任务文本）的预处理/后处理流水线；
• molmoact2_hf_model：随仓库携带的 Hugging Face 模型实现（含action_tokenizer.py、modeling_molmoact2.py、video_processing_molmoact2.py等）。

在 factory.py 中，MolmoAct2Config通过@PreTrainedConfig.register_subclass("molmoact2")注册，因此只需要在训练配置中指定：

--policy.type=molmoact2

即可启用该策略。测试文件 tests/policies/molmoact2/test_molmoact2.py 中的test_molmoact2_policy_registration验证了get_policy_class("molmoact2")与配置类型的注册关系。

需要说明的两点边界：

1. 当前 LeRobot 实现支持普通 MolmoAct2 模型的训练与评测；支持自适应深度推理的MolmoAct2-Think 尚未移植，官方标注为"coming soon"；
2. 论文实验使用的原始训练代码位于 allenai/molmoact2 仓库，本文介绍的是 LeRobot 移植实现。

二、环境要求与安装

2.1 硬件与系统要求

运行 MolmoAct2 需要NVIDIA GPU。仓库官方在 Ubuntu 22.04 上完成测试。精度与显存策略方面：

• 当前混合精度路径把完整的动作专家保存在 fp32，而大型 VLM 矩阵保存在 bf16；
• policy.compile_model=true可选地对动作专家块启用编译，而 VLM、视觉塔（vision tower）、连接器（connector）与策略包装器保持 eager 执行。文档说明这一边界通过了"同起点输出、梯度与优化器更新一致性（parity）检查"，而编译 bf16 VLM 路径则未通过，因此刻意不做整模型编译。

2.2 安装可选依赖

使用uv安装带 MolmoAct2 可选依赖的 LeRobot：

uv sync --locked --extra molmoact2

2.3 多卡训练现状

通过accelerate的多卡训练可以提升吞吐与全局 batch size。该路径曾在"两节点、八卡 GB200"上实际运行过，但本移植没有暴露原始 MolmoAct2 的fsdp_devices模型并行训练路径。官方还给出了一个单卡 GB200 回放的实现级检查结果：在两个真实 prompt 宽度下产生了一个无 graph break 的编译动作图，峰值显存与 eager 模式同为 55.15 GiB，稳态速度有适度提升。文档明确提示：这些应视为实现检查结果，而非可移植的吞吐或 ETA 声明。

三、模型架构与运行原理（源码级解读）

3.1 三层结构

从 modeling_molmoact2.py 模块开头 docstring 可见，MolmoAct2 的策略主体由三层组成：

1. Molmo 视觉语言骨干（VLM backbone）：负责理解图像、任务语言与离散化状态；
2. 逐层流匹配动作专家（per-layer flow-matching action expert）：在每个 Transformer 层上并行执行连续动作的流匹配生成，是训练时每个 flow timestep 都要被评估的热点路径；
3. 可选的离散动作 token 头（discrete action token head）：保留离散动作生成能力，供action_mode=discrete或both模式使用。

3.2 损失函数的分支逻辑

_forward_impl根据config.action_mode分发三种训练目标（modeling_molmoact2.py）：

• discrete：仅计算离散动作的交叉熵损失（CE）与可选的 z-loss；
• continuous：仅计算逐层联合流匹配损失action_flow_loss；
• both：同时计算流匹配损失与离散 CE 损失并求和，作为显式的联合消融选项。

推理侧predict_action_chunk则通过inference_action_mode决定走连续流匹配生成、离散自回归解码，还是（连续模式下）RTC 实时控制路径。

3.3 优化器与调度器

官方 MolmoAct2 与 LeRobot 共享 trainer 的差异在于梯度裁剪粒度。MolmoAct2AdamW（configuration_molmoact2.py）实现了按参数组独立裁剪：LLM、ViT、连接器与动作专家四组各自用optimizer_grad_clip_norm裁剪，而不是整模型单一范数裁剪；同时实现 BF16 更新补偿（Kahan 式残差）以保留小于一个 BF16 ULP 的 VLM 更新，该补偿张量按需惰性分配，冻结参数不产生额外开销。测试test_molmoact2_optimizer_clips_each_component_independently验证了这一行为。

调度器MolmoAct2CosineWithWarmupSchedulerConfig复刻官方"warmup + 余弦退火"节奏：余弦时间从 warmup 结束后的第 0 步起算，避免 LeRobot 共享 Pi0 调度器在绝对全局步上的学习率跳变。测试覆盖了 warmup 连续性、提前停止时钟保持与检查点恢复一致性。

3.4 序列长度推断

处理器模块 processor_molmoact2.py 定义了固定 token 预算常量（如每图像 196 个图像 token、固定 prompt 预算 80、任务 token 预算 32、序列长度余量 32 等），infer_molmoact2_max_sequence_length依据图像数、状态维度、动作维度、动作视界与是否含离散动作推断序列上限；批内文本/动作序列在插入 BOS 前被左填充到 8 的倍数（MOLMOACT2_SEQUENCE_BUCKET_MULTIPLE = 8），至多增加 7 个掩码 token，显著减少因形状变化触发的编译预热。

四、训练实战：两条权重初始化路径

MolmoAct2 可以从两种来源初始化并微调，二者使用相同的 LeRobot 训练循环、数据集变换、检查点保存与日志，区别仅在于初始权重与处理器状态的加载方式：

加载方式	参数	适用场景
原始 HF 检查点	policy.checkpoint_path（如allenai/MolmoAct2、allenai/MolmoAct2-LIBERO）	从官方发布的权重开始微调
LeRobot 检查点	policy.path（本地pretrained_model目录或 Hub 仓库）	续训已由 LeRobot 保存的检查点

重要前提（图像增强）：LeRobot 默认关闭数据集图像增强，MolmoAct2 训练命令必须显式开启--dataset.image_transforms.enable=true。原始 MolmoAct2 的变换配方并非 LeRobot 通用变换默认值，因此首个命令还要显式固定其 95% 裁剪、5 度旋转与颜色抖动；原始配方中概率 0.2 的高斯模糊无法用 LeRobot 通用的RandomSubsetApply表达（会偶尔丢弃三个必需变换之一），故不纳入。

重要提示（量化统计）：不要用lerobot/libero近似元数据分位数替代官方发布的norm_stats.json——两者的 q01/q99 数值并不相同。

4.1 从官方 MolmoAct2 权重开始全量微调

以下命令在合并的 LIBERO 数据集上从allenai/MolmoAct2基础检查点全量微调：使用 bf16 模型加载、8 个流匹配时间步、官方 LIBERO 分位数统计、图像增强，以及 LeRobot 的检查点/日志体系：

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 \ --wandb.enable=true \ --wandb.entity=<wandb_entity> \ --wandb.project=<wandb_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

4.2 从 LeRobot 已保存权重继续训练

使用policy.path时，LeRobot 会恢复保存的策略配置、模型权重、处理器与归一化统计。训练期选项（如batch_size、steps、policy.action_mode）仍可覆盖，但检查点加载是严格的，并保留已保存的 FFT 或 LoRA 拓扑，因此使用policy.path时不要覆盖policy.train_mode_vlm。若想启动一个新的 LoRA 训练，应改用policy.checkpoint_path从 HF 权重初始化：

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 \ --wandb.enable=true \ --wandb.entity=<wandb_entity> \ --wandb.project=<wandb_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

4.3 常见实践建议

• 在相对较小的数据集上微调（如单个 LIBERO suite，或演示数少于 200 条的真实数据集），全局 batch size 从 16～32 起步是良好起点；
• 小数据集上推荐policy.train_mode_vlm=lora（默认值），通常能取得与fft相当甚至更好的性能；policy.train_mode_vlm=freeze也是实用选择；
• 在所有模式下动作专家始终保持完全可训练——这是官方实验中被证明对模型性能至关重要的设计；
• 对于更大的微调数据集，通常倾向于更大的全局 batch size 与 VLM 全量微调（fft）。

4.4 学习率与调度参数

MolmoAct2 使用参数组学习率以对齐官方微调实验：

• 全量微调：policy.optimizer_lr=1e-5（VLM）、policy.optimizer_vit_lr=5e-6（视觉塔）、policy.optimizer_connector_lr=5e-6（图像连接器）、policy.optimizer_action_expert_lr=5e-5（动作专家）；
• LoRA 模式：VLM、视觉、连接器的 LoRA 参数组统一为5e-5，动作专家仍以policy.optimizer_action_expert_lr全量微调；
• 冻结 VLM 模式（freeze）：只训练动作专家，使用optimizer_action_expert_lr=5e-5；
• policy.optimizer_grad_clip_norm对 LLM、视觉塔、图像连接器与动作专家四个参数组分别独立应用，并非整模型梯度范数。

调度器默认scheduler_warmup_steps=200、scheduler_decay_steps=24000、scheduler_decay_lr=1e-6，其中 24000 步的衰减视界对齐官方train_lerobot.py配方。上述学习率与调度参数均可通过同名配置项覆盖。

五、核心策略参数全解

下表整合文档与 configuration_molmoact2.py 中的默认值/取值约束：

参数	含义	默认值/可选值
policy.checkpoint_path	原始 MolmoAct2 HF 检查点（用于官方发布权重）	allenai/MolmoAct2
policy.path	LeRobot 已保存检查点（本地目录或 Hub）	无
policy.action_mode	训练目标	continuous/discrete/both（官方机器人微调用continuous）
policy.train_mode_vlm	VLM 微调模式（动作专家始终全量训练）	fft/lora/freeze，默认lora；freeze要求action_mode=continuous
policy.enable_knowledge_insulation	为 true 时在动作损失前分离动作专家上下文 K/V 状态	默认false
policy.chunk_size	动作视界；LIBERO 用 10；会覆盖检查点max_action_horizon	默认 30，需 ≥ 1
policy.n_action_steps	每次查询策略前消费的动作步数；LIBERO 设为等于chunk_size	默认 30，需 ≤ chunk_size
policy.setup_type	写入 prompt 的机器人/场景描述文本，如single franka robotic arm in libero	空字符串
policy.control_mode	写入 prompt 的动作空间描述，如delta end-effector pose、absolute joint pose	空字符串
policy.image_keys	传入处理器的有序图像观测键	空列表
policy.dtype	Pi0.5 风格精度开关：bfloat16（VLM 矩阵 bf16 存储、动作专家与敏感模块 fp32）；float32（全模型 fp32）	bfloat16
policy.compile_model	块级torch.compile：仅编译动作专家块，VLM/ViT/连接器保持 eager	默认false
policy.num_flow_timesteps	训练时每个样本采样的流匹配时间步数	默认 8
policy.num_inference_steps	推理时连续动作生成的步数覆盖	默认无
policy.gradient_checkpointing	VLM/动作路径激活重计算，降低激活显存	默认false
policy.freeze_embedding	冻结输入嵌入	默认true
policy.normalize_gripper	是否将夹爪维度纳入状态/动作分位数归一化	默认false
policy.normalize_language	构造 prompt 前是否归一化任务字符串	默认true
policy.mask_action_dim_padding	是否在流损失中掩码填充的动作维度	默认true（发布检查点用expected_max_action_dim=32）
policy.max_sequence_length	手动序列上限；不设置时按图像/状态/动作/视界/离散模式推断	默认无
policy.expected_max_action_dim	发布检查点固定值，加载时校验	固定 32

5.1policy.dtype=bfloat16的精度细节

这是 Pi0.5 风格的低显存精度剖面：AdamW 动量跟随各参数的存储 dtype，因此大型 bf16 VLM 参数的动量也是 bf16。全量微调时会为每个有梯度的 bf16 参数惰性分配一个bf16 补偿张量，把小于单个参数 ULP 的更新带入后续步骤——注意这不是 fp32 master copy。LoRA 适配器、动作专家与明确敏感的模块保留 fp32 参数与优化器状态；LoRA 模式下冻结的 VLM 参数不分配任何补偿张量。

5.2policy.compile_model=true的编译边界

• 全量微调与 LoRA 都只编译动作专家 Transformer 块；VLM/ViT/连接器 eager 执行，以避免编译器引起的 BF16 激活与梯度漂移，同时保住每个流时间步都要评估的动作路径加速；
• Inductor 被指示在融合算子之间保留 eager 的 BF16 降/升精度边界；
• 动作块使用 PyTorch 自动形状策略；配合梯度检查点时，只有可变的编码器上下文序列维度被标记为动态，batch size、动作视界与流时间步数保持静态；
• 该模式下会禁用 Dynamo 图缓存重排与额外的 DDP 图拆分器，保证反向重计算选中与正向相同的块图——这对应源码中_set_dynamo_lru_cache与_disable_dynamo_ddp_optimizer的实现（modeling_molmoact2.py）。

六、数据集分位数统计

MolmoAct2 默认对状态与动作特征采用分位数归一化。若数据集尚未带分位数统计，可用仓库脚本补上：

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

注意：录制、续写与合并会从逐 episode 摘要聚合分位数，因此meta/stats.json中保存的是保守包络（q <= 50取min，q > 50取max），而非全数据集分位数。若想估算后者，可用运行直方图扫描每个 episode：

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

• --skip-images保留已有图像统计，仅在需要重算STATE/ACTION时避免下载/解码视频；--root可读取本地数据集而非 Hub；
• 直方图估计存在离散化与重分箱误差，与保守包络不同，会改变 MolmoAct2 的归一化目标进而影响损失尺度；已保存在检查点内的统计不受影响。

也可以改用均值/标准差归一化训练 MolmoAct2：

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

七、LIBERO 评测实战

评测同样支持 LeRobot 保存的检查点与原始 MolmoAct2 HF 检查点两种来源。复现 LIBERO 时需要固定 EGL 渲染环境并使用policy.per_episode_seed=true。

关键提醒：官方发现num_steps_wait=10不能可靠地让 LIBERO 场景稳定下来，会拉低测得的成功率。本实现报告的所有 LIBERO 评测结果均使用num_steps_wait=50。

7.1 评测 LeRobot 权重

使用policy.path时，处理器与归一化统计随模型一起恢复：

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

7.2 直接评测原始 HF 权重

无需先转换为 LeRobot 检查点即可直接评测官方发布权重，此时设置policy.checkpoint_path并提供policy.norm_tag。对于 LIBERO，policy.norm_tag=libero会从检查点的norm_stats.json加载动作/状态归一化统计、动作视界、prompt 元数据与图像键顺序：

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

把--env.task换成libero_10,libero_goal,libero_object,libero_spatial即可跑完整 LIBERO 套件。同一命令适用于其他已发布的 MolmoAct2 检查点，只要其norm_stats.json中存在所请求的policy.norm_tag。

7.3 常用评测参数

参数	说明
policy.inference_action_mode	rollout 必需：continuous走流匹配推理，discrete走动作 token 推理；须与检查点中保存的训练期action_mode兼容
policy.path	LeRobot 检查点路径或 Hub 仓库
policy.checkpoint_path	原始 HF 检查点；配合policy.type=molmoact2与policy.norm_tag
policy.norm_tag	从原始检查点norm_stats.json选择归一化统计、prompt 元数据、图像键顺序与动作视界
policy.dtype	存储/autocast 剖面：常规 GPU 评测用bfloat16；仅在需要全 fp32 推理时用float32
policy.enable_inference_cuda_graph	启用推理 CUDA 图路径，加速重复的连续动作 rollout
policy.per_episode_seed/policy.eval_seed	让随机连续动作生成按 episode 确定性执行，便于复现
env.task	逗号分隔的 LIBERO 套件或单个套件
env.camera_name_mapping	将 LIBERO 相机名映射为策略处理器期望的图像键

7.4 LIBERO 基准结果

为对比验证 LeRobot 移植，官方在 8 张 H100 上以每卡 batch size 32 对allenai/MolmoAct2-LIBERO额外微调了 10k 步，与原始 MolmoAct2 参考结果对比如下：

基准	LeRobot 实现	MolmoAct2 原始
LIBERO Spatial	98.4%	97.8%
LIBERO Object	100.0%	100.0%
LIBERO Goal	98.0%	97.8%
LIBERO 10	96.6%	93.2%
平均	98.25%	97.20%

LeRobot 微调检查点（allenai/MolmoAct2-LIBERO-LeRobot）与其训练数据集（allenai/MolmoAct2-LIBERO-Dataset）均已在 Hub 发布，可按上文 LIBERO 评测章节复现。要完全复现论文数字，文档建议使用 v0.5.1 固定的官方molmoact2-hf-inference分支，该分支与报告数字所用的原始评测设置一致。

八、真实机器人部署（lerobot-rollout）

LeRobot 格式的检查点可直接用于lerobot-rollout。每个检查点使用特定的相机键名，必须与你的机器人相机配置匹配；相机名不同时用--rename_map映射：

检查点	相机键	说明
MolmoAct2-LIBERO-LeRobot	image,wrist_image	LIBERO 仿真相机
MolmoAct2-BimanualYAM-LeRobot	top,left,right	YAM 三相机设置
MolmoAct2-DROID-LeRobot	cam0,cam1	外部相机 + 腕部相机
MolmoAct2-SO100_101-LeRobot	cam0,cam1	主视角 + 副视角

SO-100 机器人使用顶部与侧向相机的示例：

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

改用腕部相机只需修改映射：

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

8.1 关节坐标系变换（SO-100/101 零样本）

警告：MolmoAct2-SO100_101检查点训练所用的关节标定约定与 LeRobot ≥ 0.5.0 不同。不做坐标系校正时，机械臂可能朝错误方向运动。这同时影响零样本部署与从原始检查点微调——预训练权重期望旧约定，所有关节数据（观测与动作）都必须变换以匹配。

已转换的 LeRobot 检查点（lerobot/MolmoAct2-SO100_101-LeRobot）在其处理器流水线中已包含该校正。若自行转换或微调该检查点，需在策略配置configuration_molmoact2.py中设置：

• joint_signs:[1, -1, 1, 1, 1, 1]（翻转 shoulder_lift 方向）
• joint_offsets:[0, 90, 90, 0, 0, 0]（将 shoulder_lift 与 elbow_flex 平移 90°）

configuration_molmoact2.py 中joint_signs/joint_offsets默认均为 None（不变换），且二者必须同时设置、长度一致。标定变更细节参见 docs/source/backwardcomp.mdx。

九、与原始实现的差异

本移植的目标是在复用 LeRobot 数据集、训练、评测、检查点与日志基础设施的前提下尽量对齐 MolmoAct2 行为。主要差异：

1. 优化器状态精度：原始论文训练栈保留 fp32 master 参数并在 bf16 AMP 下训练；本移植用policy.dtype=bfloat16降低显存——大 VLM 矩阵存 bf16，动作专家与数值敏感模块保持 fp32，合格算子走 bf16 autocast。bf16 更新补偿张量能减少全量微调中的参数舍入损失，但 bf16 Adam 动量仍无法精确复现原始 fp32 优化器状态；
2. 分布式训练：原始仓库使用自有 FSDP/模型并行路径；本移植使用标准 LeRobot/Accelerate 路径，尚未经多节点训练测试；
3. 序列打包：原始仓库支持序列打包；本移植每个 item 训练一个 LeRobot 样本，使用批内填充与推断出的最大序列长度保护；
4. 工程约定：遵循 LeRobot 的优化器、调度器、检查点保存、数据集变换、图像增强与 Weights & Biases 日志约定；
5. 混合动作视界：原始训练路径支持按max_action_horizon填充并掩码动作专家自注意力中的填充视界槽位，便于跨不同控制频率的数据集训练；本移植当前面向单数据集微调，policy.chunk_size覆盖检查点max_action_horizon，视界掩码尚未实现（官方标注为计划中）。

十、引用与许可

引用论文（arXiv: 2605.02881）可使用仓库提供的 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}, }

模型采用 Apache 2.0 许可，面向研究与教育用途，并遵循 Ai2 的 Responsible Use Guidelines。仓库内对应实现与文档位于 src/lerobot/policies/molmoact2、docs/source/molmoact2.mdx 与 tests/policies/molmoact2/test_molmoact2.py，可直接作为继续深入阅读的入口。

【免费下载链接】lerobot🤗 LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot