LeRobot 中的 π₀.₅Pi05策略OpenPI 移植、相对动作训练与 EMA 推理详解【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobotπ₀.₅ 是一个面向开放世界泛化的 Vision-Language-ActionVLA模型由 Physical Intelligence 提出本仓库以pi05策略类型将其完整移植进 LeRobot 训练与推理框架。本文将带你理解 π₀.₅ 相比 π₀ 的核心架构差异、相对动作Relative Actions的完整数据链路、权重 EMA指数移动平均的启用方式并结合源码与测试给出可复现的训练、微调与部署命令。读完本文你将能够基于 配置类 独立配置并训练一个 π₀.₅ 模型并正确管理相对动作统计量与 EMA 检查点。一、模型概述π₀.₅ 与 π₀ 的关键差异LeRobot 中的 π₀.₅ 移植自 OpenPI 中官方用一张对比表概括了它与 π₀ 的四个核心区别特性π₀π₀.₅时间条件化Time Conditioning通过action_time_mlp_*将时间与动作拼接使用time_mlp_*进行 AdaRMS 条件化AdaRMS不使用在动作专家action expert中使用Tokenizer 长度48 tokens200 tokens离散状态输入否使用state_proj层是参数量更高包含 state embedding更低无 state embedding这些差异在源码中有明确的落点时间条件化与 AdaRMS在 modeling_pi05.py 中PaliGemmaWithExpertModel通过use_adarms[False, True]关闭 VLM 主干的 AdaRMS、仅为动作专家开启embed_suffix()先用正弦位置编码将时间步编码为time_emb再经time_mlp_in - silu - time_mlp_out - silu得到 AdaRMS 条件向量adarms_cond并注入专家 Gemma 的 LayerNorm见layernorm_forward的调用。更长的 tokenizer 长度PI05Config中tokenizer_max_length: int 200见 configuration_pi05.py默认文本 tokenizer 为google/paligemma-3b-pt-224这是一个门控模型使用前需在 Hub 接受其许可协议并执行hf auth login。离散状态输入π₀.₅ 不再需要 π₀ 的state_proj连续状态嵌入层而是在预处理阶段将归一化到 [-1, 1] 的状态离散化为 256 个 bin并写进文本 prompt。从源码结构看processor_pi05.py 中的Pi05PrepareStateTokenizerProcessorStep使用np.digitize(state_np, binsnp.linspace(-1, 1, 256 1)[:-1]) - 1完成离散化随后构造形如Task: {task}, State: {state_str};\nAction:的 prompt与 OpenPI 的PaligemmaTokenizer.tokenize()对应。注意该步骤必须位于 Normalizer 之后因为它依赖归一化后的 [-1, 1] 状态分布源码注释中明确标注了这一顺序约束。在模型加载时modeling_pi05.py 的_fix_pytorch_state_dict_keys()专门处理了两代模型的权重差异将旧检查点中的action_time_mlp_in/out重命名为time_mlp_in/out跳过 π₀.₅ 不应存在的state_proj权重并对 AdaRMS 的 LayerNorm 结构做兼容判断——这意味着从 π₀ 时代检查点迁移时这些逻辑会自动生效。二、相对动作Relative Actions原理与配置2.1 工作原理默认情况下 π₀.₅ 预测绝对动作开启相对动作后模型学习的是相对当前机器人状态的偏移量这与 OpenPI 的DeltaActions变换一致在部分场景下可提升训练稳定性与性能。完整的变换链路README 定义源码实现见 processor_pi05.py预处理阶段绝对动作转换为相对偏移relative action - state仅对选中关节生效。归一化使用基于相对分布计算出的统计量分位数对相对动作做归一化。后处理阶段预测的相对动作还原为绝对动作absolute relative state。在代码层面make_pi05_pre_post_processors() 构造的处理器管道顺序为raw → relative → normalize → model → unnormalize → absolute。其中输入侧包含RelativeActionsProcessorStep由use_relative_actions控制启停输出侧由AbsoluteActionsProcessorStep完成逆变换这两个步骤共享同一个relative_step实例以保证排除关节等配置一致。关节排除规则relative_exclude_joints中列出的关节默认[gripper]按子串匹配保持绝对动作不变例如夹爪命令通常希望保持绝对空间。2.2 配置参数参数类型默认值说明use_relative_actionsboolFalse启用相对动作训练relative_exclude_jointslist[str][gripper]保持绝对的关节名按子串匹配action_feature_nameslist[str]None运行时由make_policy依据数据集元数据自动填充action_feature_names在 configuration_pi05.py 中标注为运行时从数据集元数据由make_policy填充因此训练脚本会自动感知实际动作关节维度一般无需手动指定。2.3 训练前的数据统计量重算相对动作训练的前提是数据集的meta/stats.json中已有相对空间的统计量。README 给出了lerobot-edit-datasetCLI 方案lerobot-edit-dataset \ --repo_id your_dataset \ --operation.type recompute_stats \ --operation.relative_action true \ --operation.chunk_size 50 \ --operation.relative_exclude_joints [gripper] \ --push_to_hub truePython 等价写法from lerobot.datasets import LeRobotDataset, recompute_stats dataset LeRobotDataset(your_dataset) recompute_stats(dataset, relative_actionTrue, chunk_size50, relative_exclude_joints[gripper]) dataset.push_to_hub()其中chunk_size必须与策略的chunk_size一致π₀.₅ 默认 50relative_exclude_joints中列出的关节保持绝对空间如夹爪指令。2.4 训练命令python -m lerobot.scripts.lerobot_train \ --policy.typepi05 \ --dataset.repo_idyour_org/your_dataset \ --policy.use_relative_actionstrue \ --policy.relative_exclude_joints[gripper]当use_relative_actionstrue时训练脚本会自动完成三件事README 明确列出从数据集中计算相对动作统计量基于采样的 chunk 级相对动作用相对统计量替换标准动作统计量用于归一化在分布式训练中把该统计量广播到所有 rank。2.5 分位数统计量Quantile Statistics前置要求π₀.₅ 默认对STATE与ACTION使用分位数归一化配置见 configuration_pi05.pyNormalizationMode.QUANTILES因此数据集的meta/stats.json必须包含q01与q99。老数据集通常只有min/max/mean/std会在首个 batch 训练时抛出ValueError: QUANTILES normalization mode requires q01 and q99 stats两种解法重算统计量结果落在$HF_LEROBOT_HOME/your_dataset训练时用--dataset.root指向该目录或加--push_to_hub truelerobot-edit-dataset \ --repo_id your_dataset \ --new_repo_id your_dataset \ --operation.type recompute_stats \ --operation.overwrite true或保持数据集不变改用均值-标准差归一化--policy.normalization_mapping{ACTION: MEAN_STD, STATE: MEAN_STD, VISUAL: IDENTITY}此外仓库还提供 augment_dataset_quantile_stats.py 用于以直方图方式估算全数据集分位数--skip-images可跳过视频解码、仅重算 STATE/ACTION 统计量。注意直方图估计值与保守聚合值存在舍入误差会改变归一化目标进而影响 loss 量级已保存于检查点内的统计量不受影响。三、策略权重的 EMA指数移动平均OpenPI 在训练期间维护权重的指数移动平均默认ema_decay0.99并保留 EMA 副本用于推理。LeRobot 训练器通过启用常量衰减的 EMA shadow 来复现该行为python -m lerobot.scripts.lerobot_train \ --policy.typepi05 \ --dataset.repo_idyour_org/your_dataset \ --ema.enabletrue \ --ema.decay0.99启用后检查点中会在实时权重旁额外保存一份可直接加载的 EMA 权重位于pretrained_model_ema/目录。需要明确的资源与兼容性边界EMA shadow 是参数在 GPU 上的完整副本显存开销不可忽略与 OpenPI 在 LoRA 配置中禁用 EMA 的做法一致EMA 与 PEFT 适配器不兼容README 明确指出。四、架构纵深π₀.₅ 的模型与处理器实现4.1 模型结构PI05Pytorch核心模型类PI05Pytorch对应 openpi 的PI0Pytorch由PaliGemmaWithExpertModel组装而成modeling_pi05.pyVLM 主干PaliGemmaSigLIP 视觉塔 Gemma 语言模型变体由paligemma_variant决定可选gemma_2b默认或gemma_300m动作专家独立的 Gemma 因果语言模型变体由action_expert_variant决定默认gemma_300m且不包含 token embeddinggemma_expert.model.embed_tokens None只作为连续向量上的动作解码器动作输入输出投影action_in_proj/action_out_proj将动作向量在max_action_dim默认 32与专家宽度之间映射时间 MLPtime_mlp_in/time_mlp_out产生 AdaRMS 条件向量。训练前向forward遵循 flow matching 范式采样噪声noise、按 Beta 分布采样时间time参数time_sampling_beta_alpha1.5、time_sampling_beta_beta1.0、time_sampling_scale0.999、time_sampling_offset0.001见 configuration_pi05.py构造插值x_t time * noise (1 - time) * actions回归速度场u_t noise - actions以 MSE 作为损失。推理时使用 flow_matching.py 中的euler_integrate做欧拉积分步数由num_inference_steps默认 10控制。动作 chunk 由chunk_size默认 50对应 openpi 的action_horizon与n_action_steps默认 50共同约束且配置校验要求n_action_steps chunk_size。embed_prefix中图像 token、语言 token以及可选的 MEM 状态 token经正弦位置嵌入与掩码拼接后送入主干embed_suffix中动作 token只能被第一个动作 token 关注att_masks [1] ([0] * (chunk_size - 1))保证 prefix 侧不会泄露未来动作信息。4.2 处理器管道processormake_pi05_pre_post_processors() 返回预处理与后处理两条管道。预处理步骤依次为特征重命名 → 添加 batch 维 → 相对动作变换可选→ 归一化分位数或均值-标准差→ 状态离散化并构造 promptPi05PrepareStateTokenizerProcessorStep→ PaliGemma tokenizer 分词padding_siderightpaddingmax_length最大长度 200→ 搬移设备。后处理依次为反归一化 → 绝对动作逆变换可选→ 搬回 CPU。图像预处理在 modeling_pi05.py 的_preprocess_images中完成将 LeRobot 的 [0,1] 图像归一化到 SigLIP 期望的 [-1,1]必要时resize_with_pad_torch到image_resolution默认 224×224且要求正方形缺失的相机用 -1 填充、掩码置 0对应empty_cameras配置用于给没有图像特征的场景补空相机。4.3 关键训练参数参数默认值说明paligemma_variantgemma_2bVLM 主干规模action_expert_variantgemma_300m动作专家规模dtypefloat32bfloat16混合精度可显著省显存chunk_size/n_action_steps50/50预测的动作 chunk 长度与实际执行步数image_resolution(224, 224)图像分辨率须为正方形freeze_vision_encoderfalse冻结视觉编码器train_expert_onlyfalse冻结整个 VLM仅训练动作专家与投影层gradient_checkpointingfalse梯度检查点显著降低显存占用compile_modelfalse启用torch.compilecompile_mode默认max-autotuneoptimizer_lr2.5e-5峰值学习率scheduler_warmup_steps/scheduler_decay_steps1000/30000余弦退火调度总步数不足时自动缩放rtc_training_max_delay0训练期 RTC 最大前缀延迟0 表示禁用4.4 短时观测记忆MEMπ₀.₅ 可选支持 MEM 短时视觉/本体感知记忆详见 memory.py两个路径默认关闭use_visual_memoryfalse、use_proprioceptive_memoryfalse因此现有检查点与训练命令保持单帧行为不变。核心机制视觉记忆每第memory_temporal_attention_every默认 4个 SigLIP 层将注意力替换为 MEM 的空间-时间分离注意力space_time_attention复现 MEM 附录 C 公式 3因果时间注意力与标准空间注意力复合复用预训练投影、不给视觉塔增加可学习参数最后一个时间注意力层运行后丢弃历史帧 token下游语言/动作 prefix 长度不变。本体感知记忆每个保留帧投影出一个连续状态 tokenproprio_history_proj同时从文本 prompt 中移除离散状态使状态只表达一次这改变了 prompt 格式因此应从训练开始就启用不宜中途切换。采样节奏memory_frames默认 6含当前观测与memory_stride默认 30单位为数据集帧而非秒共同决定MEM 预训练以 1 秒间隔的 6 帧为准因此 30fps 数据集用memory_stride30而 10fps 数据集如lerobot/robomme需memory_stride10才等价。启用示例微调lerobot-train \ --dataset.repo_idyour_dataset \ --policy.typepi05 \ --policy.pretrained_pathlerobot/pi05_base \ --policy.use_visual_memorytrue \ --policy.memory_frames6 \ --policy.memory_stride30 \ --policy.memory_temporal_attention_every4 \ ...推理侧modeling_pi05.py 的_stack_inference_memory维护一个覆盖整个视界的稠密环形缓冲队列按与训练一致的delta_indices采样历史policy.reset()会清空队列。注意 MEM 推理假设同一 batch 各行共享回合边界异步向量环境中独立自动重置单行不被支持。PEFT 场景下proprio_history_proj通过modules_to_save全量训练与保存因为它没有可适配的预训练权重见_get_default_peft_targets。五、实操从加载检查点到完整训练5.1 安装与依赖按照 安装指南 安装 LeRobot 后补装 π₀.₅ 所需依赖pip install -e .[pi]若从 PyPI 安装pip install lerobot[pi]策略类型统一指定为policy.typepi05。5.2 LIBERO 微调单卡 80GBlerobot-train \ --dataset.repo_idlerobot/libero \ --policy.typepi05 \ --policy.pretrained_pathlerobot/pi05_libero_base \ --policy.normalization_mapping{ACTION: MEAN_STD, STATE: MEAN_STD, VISUAL: IDENTITY} \ --policy.n_action_steps10 \ --policy.empty_cameras1 \ --policy.freeze_vision_encoderfalse \ --policy.train_expert_onlyfalse \ --policy.gradient_checkpointingtrue \ --policy.dtypebfloat16 \ --policy.devicecuda \ --policy.push_to_hubfalse \ --output_dir./outputs/pi05_libero \ --job_namepi05_libero \ --batch_size64 \ --num_workers8 \ --steps30000 \ --save_freq5000 \ --seed1000要点LIBERO 数据集的特征与 π₀.₅ 原生匹配observation.images.imageagentview256×256×3、observation.images.image2wrist256×256×3会 resize 到 224×224observation.state8 维离散化为 256 bins 写入 promptaction7 维内部填充到 32loss 只计算前 7 维。因此无需--rename_map相机键不同时参考 rename_map.mdx。该命令使用均值-标准差归一化而非 π₀.₅ 默认的分位数以对齐lerobot/pi05_libero_finetuned_v044参考检查点。--policy.pretrained_path只加载权重因此n_action_steps、empty_cameras等设置会回退到默认值50 / 0必须显式指定若要继承检查点内的完整配置含特征名与n_action_steps应改用--policy.path。5.3 冻结 VLM 的低显存微调lerobot-train \ --dataset.repo_idlerobot/libero \ --policy.typepi05 \ --policy.pretrained_pathlerobot/pi05_libero_base \ --policy.normalization_mapping{ACTION: MEAN_STD, STATE: MEAN_STD, VISUAL: IDENTITY} \ --policy.n_action_steps10 \ --policy.empty_cameras1 \ --policy.freeze_vision_encodertrue \ --policy.train_expert_onlytrue \ --policy.gradient_checkpointingtrue \ --policy.dtypebfloat16 \ --policy.devicecuda \ --policy.push_to_hubfalse \ --output_dir./outputs/pi05_libero_expert \ --job_namepi05_libero_expert \ --batch_size64 \ --num_workers8 \ --steps30000 \ --save_freq5000 \ --seed1000train_expert_onlytrue会冻结整个 VLM只训练动作专家与投影层显著降低显存需求但成功率会有一定代价。5.4 训练期 RTC实时分块可选启用动作前缀条件化以支持高效 RTC对应论文 Training-Time Action Conditioning for Efficient Real-Time Chunkinglerobot-train \ --dataset.repo_id${HF_USER}/my_dataset \ --policy.typepi05 \ --policy.pretrained_pathlerobot/pi05_base \ --policy.rtc_training_max_delay10 \ --policy.dtypebfloat16 \ --policy.devicecuda \ --batch_size8 \ --steps30000 \ --output_diroutputs/pi05_rtc \ --job_namepi05_rtc默认rtc_training_max_delay0即禁用训练期 RTC保持标准目标不变启用后训练时对每个样本独立采样干净前缀长度flow loss 只作用于剩余 postfix见 modeling_pi05.py 的_sample_training_rtc_prefix_mask与_reduce_training_rtc_loss。使用训练好的 RTC 检查点做 rolloutlerobot-rollout \ --strategy.typebase \ --policy.pathoutputs/pi05_rtc/checkpoints/last/pretrained_model \ --inference.typertc \ --inference.rtc.modetrained \ --inference.rtc.execution_horizon10 \ --robot.typeso100_follower \ --robot.port/dev/ttyACM0 \ --taskpick up the cube \ --fps50 \ --devicecuda5.5 检查点加载方式对比| |--policy.path|--policy.pretrained_path| | -- | -- | -- | | 加载内容 | 权重和检查点的config.json| 仅权重 | | 特征名 | 来自检查点 | 来自数据集经--rename_map后 | | 存储的设置如n_action_steps | 继承 | 重置为默认值 | |--policy.type| 必须省略 | 必须指定 | |--rename_map| 相机键不一致时需要 | 可用于规范化数据集键 |六、验证与测试仓库为 π₀.₅ 提供了完整的测试矩阵见 tests/policies/pi0_pi05可作为功能与数值正确性的参考test_pi05.py策略前向、动作采样与配置校验的常规测试test_pi05_original_vs_lerobot.py与 OpenPI 参考实现的对齐性/奇偶性测试基于 openpi_parity.pytest_pi05_memory.pyMEM 视觉/本体感知记忆路径测试test_pi05_rtc.py 与 test_pi05_training_time_rtc.pyRTC 引导式与训练式模式测试test_pi05_compile.pytorch.compile路径测试。处理器层面还有 test_pi05_processor.py 验证 prompt 构造、状态离散化与相对动作管道的正确性。七、引用与许可若在研究中使用了本实现请同时引用 OpenPI 与 π₀.₅ 论文bibtex 条目见 pi05/README.md。本移植遵循Apache 2.0 License与原始 OpenPI 仓库一致。结语π₀.₅ 在 LeRobot 中的落地从模型结构AdaRMS 时间条件化、离散状态 prompt、200 token 分词、相对动作训练的数据-统计量-处理器全链路到 EMA 推理副本管理都有清晰的配置与源码支撑。无论你是要在 LIBERO 上微调、为自有数据集启用相对动作还是探索 MEM 短时记忆与 RTC 实时分块都可以从 configuration_pi05.py、modeling_pi05.py 与 processor_pi05.py 出发快速构建自己的训练管线。【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考