ManiSkill 数据生成脚本全解析从演示回放、PPO 策略生成到运动规划的三条官方数据流水线【免费下载链接】ManiSkillManipulation Skill Framework, an open source GPU parallelized robotics simulator and benchmark项目地址: https://gitcode.com/GitHub_Trending/ma/ManiSkillscripts/data_generation/是 ManiSkill 官方用于批量生成 Benchmark 演示数据集的脚本目录涵盖了基于官方 Hugging Face 演示数据集的演示回放replay、基于 PPO 稠密奖励策略的策略 rolloutRL以及基于预设运动规划解法的启发式生成motion planning三条完整流水线。阅读本文后你将掌握 ManiSkill 演示数据集从零生成到标准化的完整流程理解.h5轨迹文件与.json元数据的组织格式、replay_trajectory的核心命令行参数、PPO 训练后轨迹的清洗后处理逻辑以及三类数据源motionplanning / rl / 官方上传数据集各自的使用场景与适用前提。一、为什么需要专门的数据生成脚本ManiSkill 演示数据集的三种来源ManiSkill 作为 GPU 并行化的机器人操作仿真器与基准benchmark其评测与模仿学习IL基线都依赖大规模、标准化的演示数据集。scripts/data_generation/README.md明确说明该目录下的代码/脚本用于生成 ManiSkill Benchmark 的全部演示数据集同时为模仿学习基线生成标准的基于状态state-based和基于视觉vision-based的演示数据集。从脚本与源码结构看官方演示数据存在三种互补的来源来源脚本核心思路适用任务官方数据集回放replay_for_il_baselines.sh下载官方上传的演示重放以补充目标观测模式与控制模式已有官方演示的任务如 PushCube、PickCube、StackCube 等RL 策略 rolloutrl.shprocess_rl_trajectories.py用 PPO 从稠密奖励学策略再 rollout 成功轨迹无法用运动规划直接求解的接触式任务PushT、RollBall、AnymalC 系列等运动规划求解motionplanning.sh调用预设的启发式解算器直接生成成功轨迹有明确运动规划解法的任务PickCube、StackCube、DrawTriangle 等三条流水线的产出物均为标准化的轨迹文件命名格式遵循源码 replay_trajectory.py 中注释的约定trajectory_name.obs_mode.control_mode.sim_backend.h5例如trajectory.none.pd_ee_delta_pose.physx_cuda.h5。每个.h5文件还配套一个同名的.json元数据文件含env_info、episodes列表等二者共同构成可被 ManiSkillTrajectoryDataset 直接加载的标准数据集格式。二、流水线一基于官方数据集的演示回放replay_for_il_baselines.sh2.1 脚本职责与核心策略replay_for_il_baselines.sh用于重放下载的官方演示以补入模仿学习基准所需的观测数据observation与动作空间controller数据。脚本注释点明了两个关键设计控制模式可被重指定回放时指定的控制模式可以与数据集中原始存储的不同官方策略是“使用最简单且任务仍然可解的控制模式”回放结果不上传由于回放会保存图像数据导致文件极大官方上传的数据集通常只保留体积小得多的环境状态数据env state因此回放后的完整数据集需要用户本地自行生成。2.2 目录与环境变量脚本默认从~/.maniskill/demos读取演示数据DEMO_PATH~/.maniskill/demos # if you set a different maniskill data directory you can uncomment the line below # DEMO_PATH${MS_ASSET_DIR}/demos如果你通过MS_ASSET_DIR设置了自定义的 ManiSkill 数据目录取消第二行的注释即可。官方演示数据可从 ManiSkill HuggingFace 数据集仓库获取haosulab/ManiSkill_Demonstrations。2.3 基于状态的演示回放State-based脚本中的状态型回放命令统一使用mani_skill.trajectory.replay_trajectory模块核心命令模式如下python -m mani_skill.trajectory.replay_trajectory \ --traj-path ${DEMO_PATH}/PushCube-v1/motionplanning/trajectory.h5 \ --use-first-env-state -c pd_ee_delta_pos -o state \ --save-traj --num-envs 10 -b physx_cpu各参数含义均对应 replay_trajectory.py 中Args数据类的字段参数别名说明--traj-path—待回放的轨迹.h5文件路径必填-o/--obs-mode—回放时写入轨迹的目标观测模式如state、rgb、rgbd等-c/--target-control-mode—目标控制模式如pd_ee_delta_pos、pd_ee_delta_pose注意并非所有控制模式都能互相转换目前 Panda 机器人支持最好且控制模式转换在 GPU 并行环境下不支持源码会直接抛出NotImplementedError-b/--sim-backend—仿真后端physx_cpu或physx_gpu不指定时沿用采集轨迹时的后端-n/--num-envs—并行环境数。CPU 后端下通过 Python 多进程并行GPU 后端下在同一进程内利用 GPU 并行--use-first-env-state—仅使用轨迹中的第一个环境状态设置初始状态。官方注释指出这有助于把 CPU 仿真采集的演示在 GPU 仿真中重放因为同样的种子下 GPU 仿真与 CPU 仿真的初始状态随机化结果不同--use-env-states—按环境状态而非动作逐帧回放保证每一帧环境与原始轨迹完全一致--save-traj—保存回放后的轨迹到磁盘不会覆盖原始轨迹文件--save-video—同时保存视频--count—回放的演示数量默认回放全部--vis—通过 GUI 可视化回放过程--discard-timeout—丢弃超时被截断的片段--allow-failure—在保存的视频和轨迹中允许包含失败片段脚本为不同任务选择了不同的控制模式平移类任务PushCube、PickCube、StackCube、DrawTriangle使用pd_ee_delta_pos末端执行器位置增量而涉及姿态调整的任务StackPyramid、PegInsertionSide、PushT使用pd_ee_delta_pose末端执行器位姿增量。PushT 这类对物理精度敏感的任务额外使用了--use-env-states与physx_cuda后端python -m mani_skill.trajectory.replay_trajectory \ --traj-path ${DEMO_PATH}PushT-v1/rl/trajectory.none.pd_ee_delta_pose.physx_cuda.h5 \ --use-env-states -c pd_ee_delta_pose -o state \ --save-traj --num-envs 1024 -b physx_cuda从源码 replay_parallelized_sim 的实现看GPU 并行回放时每个时间步先用动作执行env.step若指定--use-env-states则再强制set_state_dict覆盖到原始状态——源码注释特别警告部分高精度任务如 PushT-v1即使单步也会因 GPU 仿真的非确定性产生约 1e-4 级的观测/奖励误差因此回放时尽量使用与原始采集相同的并行环境数量。2.4 基于 RGB 视觉的演示回放Vision-based视觉型回放与状态型唯一区别是将-o state换成-o rgb其余参数保持一致例如python -m mani_skill.trajectory.replay_trajectory \ --traj-path ${DEMO_PATH}DrawTriangle-v1/motionplanning/trajectory.h5 \ --use-first-env-state -c pd_ee_delta_pos -o rgb \ --save-traj --num-envs 10 -b physx_cpu视觉回放的任务范围更广额外包含 DrawTriangle而 PushT 的视觉回放使用pd_ee_delta_pos控制模式与--num-envs 256python -m mani_skill.trajectory.replay_trajectory \ --traj-path ${DEMO_PATH}PushT-v1/rl/trajectory.none.pd_ee_delta_pos.physx_cuda.h5 \ --use-env-states -c pd_ee_delta_pos -o rgb \ --save-traj --num-envs 256 -b physx_cuda由于图像数据量大视觉回放建议在 GPU 后端批量并行执行。回放生成的轨迹保存在原始轨迹同目录下命名会自动拼接新的obs_mode.control_mode.sim_backend后缀见 replay_trajectory.py不会覆盖原文件。2.5 回放实现原理与动作转换限制回放的核心逻辑位于 replay_trajectory.pyCPU 后端replay_cpu_sim逐个 episode 回放支持控制模式转换。当原始控制模式为pd_joint_pos或pd_joint_delta_pos时会调用 conversion.py 中的转换函数如from_pd_joint_delta_pos把关节空间动作转换为目标末端空间动作该模块在源码顶部注明“专为 Franka Panda 设计不保证其他机器人可用”。控制模式转换不支持与--use-env-states同时使用因为转换会改变达到相同状态所需的动作步数。GPU 后端replay_parallelized_sim将 episodes 分批并行只支持同控制模式的轨迹若指定不同控制模式直接NotImplementedError。多进程合并CPU 后端使用num_envs个进程并行回放后通过merge_trajectories合并成单个.h5见 main。三、流水线二PPO 稠密奖励策略生成成功演示rl.sh3.1 整体思路rl.sh的职责是用强化学习从稠密奖励中学出一个策略再对不同控制模式 rollout 成功演示。训练好的模型权重与预生成演示同样发布在官方 Hugging Face 数据集上。脚本注释给出的前置条件是需要安装torchrl与tensordict如果cudagraphs在你的环境不可用可移除该 flag运行前需先进入examples/baselines/ppo目录ppo_fast.py所在位置。3.2 标准训练与评估模式每个任务对三种控制模式循环执行“训练 → 评估 rollout”两步### PushCube-v1 ### for control_mode in pd_joint_delta_pos pd_ee_delta_pos pd_ee_delta_pose; do python ppo_fast.py --env_idPushCube-v1 \ --num_envs4096 --num-steps4 --update_epochs8 --num_minibatches32 \ --total_timesteps5_000_000 --eval_freq100 \ --save-model --cudagraphs --exp-namedata_generation/PushCube-v1-ppo-${control_mode} --control-mode ${control_mode} python ppo_fast.py --env_idPushCube-v1 --evaluate --control-mode ${control_mode} \ --checkpointruns/data_generation/PushCube-v1-ppo-${control_mode}/final_ckpt.pt \ --num_eval_envs1024 --num-eval-steps50 --no-capture-video --save-trajectory done训练阶段的关键参数对应 ppo_fast.py 的Args--num_envs4096并行环境数体现 ManiSkill GPU 仿真的规模化并行能力--num-steps每次 rollout 的步数PushCube/PickCube/PullCube/PokeCube 用 4StackCube/PushT/RollBall 用 16PegInsertionSide 与双机器人任务用 100--update_epochs8 --num_minibatches32PPO 更新轮数与 minibatch 数--total_timesteps总训练步数从 PushCube 的 5M 到 PegInsertionSide 的 100M 不等--save-model保存模型到runs/{run_name}最终 checkpoint 固定命名为final_ckpt.pt见 ppo_fast.py--exp-name实验名统一放在data_generation/下--cudagraphs启用 CUDA Graph 加速。评估阶段通过--evaluate进入纯评估模式源码注释只运行评估并根据给定 checkpoint 保存评估轨迹使用--save-trajectory让RecordEpisode包装器把评估轨迹写入runs/data_generation/task-ppo-mode/test_videos/目录对应 ppo_fast.py 中的eval_output_dir与trajectory_nametrajectory因此评估产物固定为test_videos/trajectory.h5trajectory.json。3.3 各任务的超参配置速查脚本中为不同任务精心调校了超参以下为完整汇总评估统一使用--num_eval_envs1024与--no-capture-video任务控制模式num-stepstotal_timestepsnum-eval-steps特殊超参PushCube-v13 种45M50—PickCube-v13 种45M50—StackCube-v13 种1650M50—PushT-v13 种1625M100--gamma0.99RollBall-v13 种1620M80--gamma0.95PokeCube-v13 种420M50—PullCube-v13 种45M50—LiftPegUpright-v1pd_joint_delta_pos、pd_ee_delta_pose48M50—AnymalC-Reach-v1pd_joint_delta_pos1610M200--gamma0.99 --gae_lambda0.95AnymalC-Spin-v1pd_joint_delta_pos1610M200--gamma0.99 --gae_lambda0.95脚本注释“任务无成功暂不生成演示”PegInsertionSide-v1pd_ee_delta_pose100100M100--gamma0.97 --gae_lambda0.95、--num_envs1024TwoRobotPickCube-v1pd_joint_delta_pos10035M100--num_envs1024TwoRobotStackCube-v1pd_joint_delta_pos10050M100--num_envs1024UnitreeG1PlaceAppleInBowl-v1pd_joint_delta_pos3250M100--num_envs1024UnitreeG1TransportBox-v1pd_joint_delta_pos3250M100--num_envs1024注意AnymalC-Spin-v1 在脚本中只训练不评估因为“任务没有成功episode”所以暂不生成演示UnitreeG1 系列注释提示num-steps32可能还有进一步优化空间。四足AnymalC、双机器人TwoRobot*、人形UnitreeG1*任务均使用pd_joint_delta_pos关节空间控制这与其机器人本体特征相符。3.4 轨迹后处理process_rl_trajectories.pyrl.sh头部注释给出了后处理命令python scripts/data_generation/process_rl_trajectories.py --runs_path examples/baselines/ppo/runs/data_generation/ --out-dir ~/.maniskill/demos/该脚本读取每个任务的 checkpoint 与test_videos/trajectory.h5把“成功轨迹”清洗成标准数据集其核心逻辑process_rl_trajectories.py筛选与截断遍历metadata[episodes]丢弃success全为 False 的 episode对成功的 episode截断到最后一次成功时刻last_success_index见 process_rl_trajectories.py并将elapsed_steps更新为last_success_index 1。递归复制通过recursive_copy_and_slice递归拷贝轨迹数据跳过obs/rewards键并自动决定是否追加最后一帧env_states需要多保存一帧。元数据重写为每个 episode 标记successTrue写入source_typerl与source_descDemonstrations generated by rolling out a PPO dense reward trained policy见 process_rl_trajectories.py。输出命名按{env_id}/rl/trajectory.none.{control_mode}.{sim_backend}.h5组织输出与replay_for_il_baselines.sh中 PushT 的路径PushT-v1/rl/trajectory.none.pd_ee_delta_pose.physx_cuda.h5对应。质量监控与样例视频统计失败率、截断率、平均 episode 长度、首次成功平均步数失败率 ≥ 5% 的任务会输出告警提示“需要更好的策略”对每个控制模式用rt-med着色器渲染一条sample_control_mode.mp4样例视频同时把final_ckpt.pt复制为ppo_control_mode_ckpt.pt一并发布。脚本的Args还包含dry_run参数默认True只打印统计信息、不写文件便于先验证数据是否齐全。四、流水线三运动规划启发式生成演示motionplanning.sh4.1 Panda 机械臂解法对于有明确运动规划解法的任务官方提供了预写好的解算器。脚本对 9 个任务批量执行“先少量采样生成视频再大规模生成轨迹”## Panda Arm Solutions for env_id in PushCube-v1 PickCube-v1 StackCube-v1 PegInsertionSide-v1 PlugCharger-v1 PullCubeTool-v1 LiftPegUpright-v1 PullCube-v1 StackPyramid-v1 do python -m mani_skill.examples.motionplanning.panda.run --env-id $env_id \ --traj-nametrajectory --only-count-success --save-video -n 1 \ --shaderrt # generate sample videos mv demos/$env_id/motionplanning/0.mp4 demos/$env_id/motionplanning/sample.mp4 python -m mani_skill.examples.motionplanning.panda.run --env-id $env_id --traj-nametrajectory -n 1000 --only-count-success done第一步用-n 1配合--save-video --shaderrt生成一条光线追踪ray tracing示例视频sample.mp4用于可视化第二步用-n 1000 --only-count-success生成 1000 条成功轨迹。输出默认保存在demos/env_id/motionplanning/目录。4.2 Panda Stick 解法对于使用“Panda 加长杆”工具的绘图任务 DrawTriangle-v1脚本单独处理并在大规模生成时用--num-procs 10通过多进程加速for env_id in DrawTriangle-v1 do python -m mani_skill.examples.motionplanning.panda.run --env-id $env_id \ --traj-nametrajectory --only-count-success --save-video -n 1 \ --shaderrt # generate sample videos mv demos/$env_id/motionplanning/0.mp4 demos/$env_id/motionplanning/sample.mp4 python -m mani_skill.examples.motionplanning.panda.run --env-id $env_id --traj-nametrajectory -n 1000 --num-procs 10 --only-count-success done4.3 运动规划解算器与记录包装器run.pymani_skill/examples/motionplanning/panda/run.py是这一流水线的执行入口解算器注册表MP_SOLUTIONS字典把 12 个任务映射到 solutions/ 目录下的对应求解函数solvePushCube、solvePickCube、solveStackCube、solvePegInsertionSide、solvePlugCharger、solvePullCubeTool、solveLiftPegUpright、solvePullCube、solveDrawTriangle、solveDrawSVG、solvePlaceSphere、solveStackPyramid未注册的任务会直接抛RuntimeError固定控制模式环境以control_modepd_joint_pos创建这是解算器输出关节目标位置的基础记录包装器用RecordEpisode包装trajectory_name默认取--traj-name未指定则用时间戳source_typemotionplanning、source_descofficial motion planning solution from ManiSkill contributors见 run.py视频帧率 30fps成功计数--only-count-success开启时失败轨迹会被flush_trajectory(saveFalse)丢弃并继续采样直到成功数量达到num_traj--num-procs 1时按进程拆分任务并在结束后用merge_trajectories合并见 main其他参数--obs-mode默认none注释说明观测不必存储、可事后用 replay_trajectory 补充、--sim-backendauto/cpu/gpu、--render-mode、--record-dir默认demos、--shaderdefault/rt/rt-fast。由于运动规划生成的轨迹以pd_joint_pos控制模式保存且不含观测官方文档推荐的做法是先用 motionplanning 流水线生成轨迹再用 replay_for_il_baselines.sh 中的回放命令转换为目标观测模式与控制模式——这正是两条流水线在数据集生成中协同工作的关键衔接。五、三条流水线的产物如何被消费数据集加载与使用闭环无论哪条流水线最终产出的.h5.json都可以被 ManiSkillTrajectoryDataset 直接加载该 PyTorchDataset读取json_data[episodes]与env_info逐条加载traj_episode_id轨迹支持success_only过滤失败片段并自动把uint16类型转换为int32以便张量化。评估轨迹时的配套重放工具为 replay_trajectory.py含--count、--save-video、--vis等辅助参数。此外scripts/data_generation/learning_from_demos.sh 还保留了一条“从少量演示学习策略、再 rollout 更多成功演示”的补充思路目前该脚本仅含一行说明注释可视为 RL 流水线在数据稀缺场景下的扩展方向。六、实践建议与注意事项按任务特性选择数据源有运动规划解法的任务优先走motionplanning.sh确定性高、无需训练接触密集或运动规划困难的任务PushT、RollBall、PegInsertionSide、AnymalC 等走rl.sh已有官方演示的任务直接用replay_for_il_baselines.sh补观测与控制模式。控制模式转换的边界转换目前主要为 Panda 优化且 GPU 并行环境不支持转换跨后端回放建议使用--use-first-env-state或--use-env-states规避初始状态随机化差异。运行环境RL 流水线需要torchrl、tensordict与 CUDA 环境cudagraphs不可用时移除该 flag运动规划与 CPU 回放仅依赖 CPU 后端与 Python 多进程。数据规模与磁盘图像数据使回放产物体积巨大官方仅上传不含图像的状态型数据大规模视觉数据集生成请优先使用physx_cuda后端并行。质量校验process_rl_trajectories.py输出的失败率、截断率与平均 episode 长度统计以及sample.mp4/sample_control_mode.mp4样例视频是快速核验数据质量的标准手段--dry-run可在正式生成前先行体检。【免费下载链接】ManiSkillManipulation Skill Framework, an open source GPU parallelized robotics simulator and benchmark项目地址: https://gitcode.com/GitHub_Trending/ma/ManiSkill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考