π₀.₅（Pi05）策略完全指南：LeRobot 中的开放世界视觉-语言-动作模型移植与实战配置

π₀.₅Pi05策略完全指南LeRobot 中的开放世界视觉-语言-动作模型移植与实战配置【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobotπ₀.₅ 是 Physical Intelligence 提出的具有开放世界泛化能力的视觉-语言-动作VLA模型本文以 docs/source/policy_pi05_README.md 为核心骨架结合仓库内 pi05 策略源码、预处理管线与测试用例系统讲解 LeRobot 移植版的模型架构差异、相对动作训练、EMA 权重、微调命令、MEM 记忆机制等完整内容。读完本文你将掌握如何在 LeRobot 中配置、训练、评估 π₀.₅并理解其相对 OpenPI 原版实现的工程化细节。1. 模型概览π₀.₅ 与 π₀ 的关键差异LeRobot 仓库中的 π₀.₅ 是 Hugging Face 对 Physical Intelligence 开源 OpenPI被设计为面向开放世界泛化的 VLA 模型。与 π₀ 相比π₀.₅ 在架构上做了多处重要调整官方文档给出的对比表如下特性π₀π₀.₅时间条件编码通过action_time_mlp_*将时间与动作拼接使用time_mlp_*生成 AdaRMS 条件AdaRMS不使用在 action expert 中使用Tokenizer 长度48 tokens200 tokens离散状态输入否使用state_proj层是参数量更高包含状态嵌入更低无状态嵌入这些差异在源码中都有直接对应实现可以在 modeling_pi05.py 中逐项验证time_mlp_*与 AdaRMS 条件PI05Pytorch中定义了self.time_mlp_in与self.time_mlp_out两个线性层见 modeling_pi05.py。在embed_suffix中时间步先经正弦位置编码再依次通过time_mlp_in → SiLU → time_mlp_out → SiLU最终输出作为adarms_cond传给 action expert 的 AdaRMS 层。构造PaliGemmaWithExpertModel时显式传入use_adarms[False, True]见 modeling_pi05.py即 VLM 主干不使用 AdaRMS而 action expert 使用。无state_proj层π₀ 中用于嵌入连续状态向量的state_proj在 π₀.₅ 中不再存在。from_pretrained加载旧权重时_fix_pytorch_state_dict_keys会跳过state_proj.*键并打印告警见 modeling_pi05.py而 π₀ 的action_time_mlp_*键会被自动重命名为 π₀.₅ 的time_mlp_*见 modeling_pi05.py保证旧 checkpoint 兼容迁移。离散状态输入π₀.₅ 把归一化到[-1, 1]的机器人状态离散化为256 个 bin直接写进文本提示词Task: ...; State: ...; Action:。该逻辑实现在 processor_pi05.py 的Pi05PrepareStateTokenizerProcessorStep中使用np.digitize将状态映射到 256 个等距区间。架构执行流训练PI05Policy.forward先对图像、语言 token和可选的 MEM 状态历史编码为 prefix 嵌入再把加噪动作与时间步编码为 suffix 嵌入两者拼接到一起后由PaliGemmaWithExpertModel对 VLM 与 action expert 的 18 层 Transformer 逐层联合前向compute_layer_complete最后经action_out_proj输出速度场预测v_t与u_t noise - actions计算 MSE 损失见 modeling_pi05.py。1.1 与 OpenPI 的对应关系与加载提示PI05Policy.from_pretrained在加载时会打印一段免责声明说明本实现为 OpenPI 的直接移植、为兼容性保持原始结构。加载流程对 state dict 做了三层处理见 modeling_pi05.py通过cached_file获取远程model.safetensors调用_fix_pytorch_state_dict_keys修复新旧 key 差异层归一化结构变化、action_time_mlp_*→time_mlp_*、跳过state_proj、lm_head.weight映射到embed_tokens.weight为所有缺少model.前缀的键补上前缀再调用_prepare_pretrained_state_dict处理 MEM 新增的proprio_history_proj层初始化。加载完成后会打印 missing/unexpected keys 统计便于诊断 checkpoint 与配置不匹配的问题。2. 相对动作Relative Actions训练π₀.₅ 默认预测绝对动作关节绝对位置。通过use_relative_actions开关可以让模型学习相对当前机器人状态的偏移量这与 OpenPI 中的DeltaActions变换对应在特定场景下能提升训练稳定性与性能。2.1 工作原理相对动作在预处理preprocessing与后处理postprocessing两个阶段对称完成预处理阶段绝对动作被转换为相对偏移——relative action - state仅针对选中的关节维度相对动作使用基于相对分布计算出的统计量进行归一化后处理阶段模型预测的相对动作被还原为绝对动作——absolute relative state。其中列入relative_exclude_joints的关节默认[gripper]保持绝对空间不变。源码中的对称实现位于 processor_pi05.py预处理管线在NormalizerProcessorStep之前插入RelativeActionsProcessorStep后处理管线则在unnormalize之后插入AbsoluteActionsProcessorStepenabledconfig.use_relative_actions并复用同一个relative_step实例保证变换一致性整体顺序为「raw → relative → normalize → model → unnormalize → absolute」。2.2 配置参数参数类型默认值说明use_relative_actionsboolFalse启用相对动作训练relative_exclude_jointslist[str][gripper]保持绝对空间的关节名按子串匹配action_feature_nameslist[str]None运行时由make_policy依据数据集元数据自动填充action_feature_names的默认值在 configuration_pi05.py 中为None由策略工厂在运行时读取数据集元数据自动注入因此用户在训练命令中通常无需手动指定。2.3 训练示例原文档给出的最小训练命令如下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时训练脚本会自动完成三件事从数据集采样 chunk 级相对动作计算相对动作统计量用相对统计量替换标准动作统计量用于归一化在分布式训练中向所有 rank 广播这些统计量。配套的完整操作路径在 docs/source/pi05.mdx 中有更详细说明训练前应先通过lerobot-edit-dataset --operation.type recompute_stats --operation.relative_action true或 Python APIrecompute_stats(dataset, relative_actionTrue, chunk_size50, relative_exclude_joints[gripper])在相对空间重算数据集统计量。注意chunk_size应与策略的chunk_sizeπ₀.₅ 默认 50一致relative_exclude_joints里列出的关节如夹爪指令保持绝对空间。3. 策略权重的 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启用后checkpoint 中会在实时权重旁生成一个可直接加载的 EMA 权重副本存放于pretrained_model_ema/目录。使用时有两点必须注意显存开销EMA shadow 是参数在 GPU 上的完整额外副本会显著增加显存占用与 PEFT 不兼容与 OpenPI 在其 LoRA 配置中禁用 EMA 的做法一致EMA不支持与 PEFT adapter 同时使用。4. 深入关键训练参数与微调实战在进入推理与评估之前先完整掌握PI05Config的核心参数它们直接决定训练资源占用与收敛行为全部定义见 configuration_pi05.py。4.1 模型结构与动作输出参数参数默认值说明paligemma_variantgemma_2bVLM 主干规模可选gemma_300m/gemma_2baction_expert_variantgemma_300mAction expert 规模可选gemma_300m/gemma_2bdtypefloat32精度可选bfloat16/float32n_obs_steps1观测步数chunk_size50一次预测的动作步数OpenPI 中称action_horizonn_action_steps50实际执行的动作步数max_state_dim/max_action_dim32/32状态/动作向量统一填充到的维度image_resolution(224, 224)输入图像分辨率PaliGemma 要求正方形tokenizer_max_length200文本 tokenizer 最大长度text_tokenizer_namegoogle/paligemma-3b-pt-224PaliGemma 门控 tokenizer配置校验逻辑__post_init__会主动拦截三类非法配置n_action_steps chunk_size、rtc_training_max_delay不在[0, chunk_size)、变体或 dtype 取值非法见 configuration_pi05.py。4.2 流匹配Flow Matching参数π₀.₅ 使用流匹配目标而非扩散目标训练核心参数与 OpenPI 的PI0Pytorch对齐参数默认值说明num_inference_steps10推理去噪步数time_sampling_beta_alpha/beta_beta1.5/1.0Beta 分布时间采样形状参数time_sampling_scale/offset0.999/0.001时间采样缩放与偏移min_period/max_period4e-3/4.0时间步正弦编码周期范围这些参数在sample_time训练时抽样时间步与embed_suffix生成时间正弦嵌入中被消费见 modeling_pi05.py 与 modeling_pi05.py。4.3 训练与微调设置参数默认值说明gradient_checkpointingFalse启用梯度检查点显著降低显存compile_model/compile_modeFalse/max-autotune是否用torch.compile加速freeze_vision_encoderFalse冻结视觉编码器train_expert_onlyFalse冻结整个 VLM仅训练 action expert 与投影层optimizer_lr2.5e-5AdamW 峰值学习率optimizer_betas(0.9, 0.95)AdamW beta 系数optimizer_weight_decay0.01权重衰减optimizer_grad_clip_norm1.0梯度裁剪范数scheduler_warmup_steps1_000预热步数scheduler_decay_steps30_000衰减步数scheduler_decay_lr2.5e-6衰减终值学习率调度器支持自动缩放当--steps scheduler_decay_steps时warmup 与 decay 步数会按比例缩放例如--steps3000会把 warmup 缩到 100、decay 缩到 3000。优化器与调度器预设在get_optimizer_preset/get_scheduler_preset中构建见 configuration_pi05.py。归一化模式π₀.₅ 默认对STATE与ACTION使用QUANTILES分位数归一化对VISUAL使用IDENTITY见 configuration_pi05.py。这意味着数据集meta/stats.json必须包含q01与q99统计量否则首个 batch 会报错ValueError: QUANTILES normalization mode requires q01 and q99 stats对只有min/max/mean/std的旧数据集可重算统计量或改用均方根归一化lerobot-edit-dataset \ --repo_id your_dataset \ --new_repo_id your_dataset \ --operation.type recompute_stats \ --operation.overwrite truelerobot-train ... --policy.normalization_mapping{ACTION: MEAN_STD, STATE: MEAN_STD, VISUAL: IDENTITY}4.4 完整微调命令单卡 80GB GPU以 LIBERO 基准为例数据集特征observation.images.image/image2为 256×256 的 agentview 与 wrist 相机observation.state为 8 维action为 7 维π₀.₅ 会先把图像缩放到 224×224、把状态离散化进提示词、把动作内部填充到 32 维且损失只算前 7 维。数据集 key 与策略名完全一致时无需--rename_maplerobot-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要点解析--policy.pretrained_path只加载权重lerobot/pi05_libero_base中保存的n_action_steps、empty_cameras等设置不会被继承会回退到默认值50/0因此命令中必须显式给出--policy.n_action_steps10与--policy.empty_cameras1empty_cameras当数据集缺少策略声明的图像特征时用全-1填充的空白图补位掩码置零见validate_features与_preprocess_imagesconfiguration_pi05.py门控 tokenizerπ₀.₅ 使用门控模型google/paligemma-3b-pt-224训练前需在 Hub 接受其许可并执行hf auth login参数记忆freeze_vision_encodertrue与train_expert_onlytrue的组合会冻结整个 VLM仅训练 action expert 与投影层适合显存受限场景以一定成功率下降为代价。4.5 checkpoint 加载的两种形式--policy.path--policy.pretrained_path加载内容权重和checkpoint 的config.json仅权重特征名来源来自 checkpoint来自你的数据集经--rename_map后存储的设置如n_action_steps继承重置为默认值--policy.type必须省略必须给出--rename_map相机 key 不同时使用可用于规整数据集 key5. 短时观测记忆MEMπ₀.₅ 可选启用基于 MEM 的短时视觉与本体感受记忆两条路径默认关闭因此现有 checkpoint 与训练命令保持单帧行为不变。核心实现位于 memory.py。5.1 启用方式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 \ ...5.2 关键参数与设计要点参数默认值说明use_visual_memoryFalse启用视觉历史帧记忆use_proprioceptive_memoryFalse启用本体感受历史记忆memory_frames6记忆帧数包含当前观测memory_stride30采样间隔按数据集帧计memory_temporal_attention_every4每 N 个 SigLIP 层替换为时空注意力memory_stride按帧计而非按秒MEM 预训练使用间隔 1 秒的 6 帧观测30 fps 数据集LeRobot 常规录制帧率对应memory_stride30而 10 fps 数据集如lerobot/robomme需要memory_stride10才能达到同样的 1 秒间隔零新增可学习参数每隔 4 层的 SigLIP 注意力被替换为 MEM 的组合式时空注意力论文附录 C 公式 3复用预训练 q/k/v 投影先做帧间因果时间注意力、再做空间注意力通过 SDPA 实现、不物化注意力矩阵见 memory.pytoken 长度不变最后一个时间注意力层运行后即丢弃历史帧 token下游语言/动作 prefix 长度与单帧模式完全一致见 memory.py推理侧对齐reset()会按(memory_frames-1) * memory_stride 1的长度维护一个稠密环形队列使推理时采样年龄与训练delta_indices严格对齐见 modeling_pi05.py限制说明本实现仅覆盖 MEM 的短时视觉/本体感受记忆论文 III-C、III-D 节未实现长时语言记忆III-B 节且记忆需在训练/微调阶段就启用推理阶段单独开启不会给单帧 checkpoint 带来记忆能力从无记忆 checkpoint 微调引入记忆对应论文中较弱的MEM-Posttrain-Only消融设置PEFT 兼容proprio_history_proj无预训练权重可适配通过modules_to_save全量训练并保存见 modeling_pi05.py。5.3 本体感受记忆--policy.use_proprioceptive_memorytrue启用后每个保留帧会加入一个经线性投影的连续状态 tokenproprio_history_proj同时从文本提示词中移除离散化状态保证状态在模型中只出现一次。这会改变提示词格式因此必须从训练一开始就启用不能中途切换。视觉与本体感受记忆共用memory_frames和memory_stride但两条路径可独立开启。5.4 推理约束推理时 MEM 维护单一 batch 级历史队列要求所有 batch 行共享 episode 边界。lerobot-eval通过在每次 batched rollout 前及重置向量环境前调用policy.reset()满足这一约束异步向量 batch 中独立自动重置行不受支持应整体开启新 rollout 以同时重置策略与动作队列。6. 实时分块RTC支持π₀.₅ 的PI05Policy.supports_rtc()返回True见 modeling_pi05.py支持实时分块推理。相关配置项参数默认值说明rtc_configNoneRTC 配置对象详见 RTC 文档rtc_training_max_delay0训练期最大干净动作前缀长度0表示禁用训练期 RTCrtc_training_max_delay必须满足0 delay chunk_size。启用后训练时会对每个样本独立采样一个干净前缀长度仅对剩余后缀计算流匹配损失_sample_training_rtc_prefix_mask与_reduce_training_rtc_loss见 modeling_pi05.py并在forward的loss_per_dim统计中排除前缀维度。推理阶段sample_actions支持guided默认与trained两种模式trained模式会校验测量延迟不超过训练上限、chunk 前缀形状与数值合法性_prepare_trained_rtc_prefix见 modeling_pi05.py。训练期 RTC 示例lerobot-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_rtc7. 引用与许可若在研究与工程中使用了本实现请同时引用 OpenPI 与 π₀.₅ 论文misc{openpi2024, author {Physical Intelligence Lab}, title {OpenPI: PyTorch Implementation of π0 and π0.5 Policies}, year {2024}, publisher {GitHub}, howpublished {\url{https://github.com/Physical-Intelligence/openpi}}, license {Apache-2.0} } misc{intelligence2025pi05visionlanguageactionmodelopenworld, title {π₀.₅: a Vision-Language-Action Model with Open-World Generalization}, author {Physical Intelligence and Kevin Black and Noah Brown and James Darpinian and Karan Dhabalia and Danny Driess and Adnan Esmail and Michael Equi and Chelsea Finn and Niccolo Fusai and Manuel Y. Galliker and Dibya Ghosh and Lachy Groom and Karol Hausman and Brian Ichter and Szymon Jakubczak and Tim Jones and Liyiming Ke and Devin LeBlanc and Sergey Levine and Adrian Li-Bell and Mohith Mothukuri and Suraj Nair and Karl Pertsch and Allen Z. Ren and Lucy Xiaoyang Shi and Laura Smith and Jost Tobias Springenberg and Kyle Stachowicz and James Tanner and Quan Vuong and Homer Walke and Anna Walling and Haohuan Wang and Lili Yu and Ury Zhilinsky}, year {2025}, eprint {2504.16054}, archivePrefix {arXiv}, primaryClass {cs.LG}, url {https://arxiv.org/abs/2504.16054}, }本移植遵循Apache 2.0 License与原始 OpenPI 仓库一致。8. 相关资源索引以下仓库文件可帮助你继续深入策略配置类与全部参数默认值configuration_pi05.py核心模型PaliGemmaWithExpertModel、PI05Pytorch、PI05Policymodeling_pi05.py预处理/后处理管线相对动作、状态离散化、tokenizerprocessor_pi05.pyMEM 时空注意力实现memory.py配套的 pi05 官方使用文档docs/source/pi05.mdx策略包导出PI05Config、PI05Policy、make_pi05_pre_post_processorssrc/lerobot/policies/pi05/init.py测试覆盖相对动作、RTC、编译、MEM 与 OpenPI 一致性测试见 tests/policies/pi0_pi05/【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考