ManiSkill 中 Unitree H1 人形机器人：模型配置、关节控制器与站立任务实战

ManiSkill 中 Unitree H1 人形机器人模型配置、关节控制器与站立任务实战【免费下载链接】ManiSkillManipulation Skill Framework, an open source GPU parallelized robotics simulator and benchmark项目地址: https://gitcode.com/GitHub_Trending/ma/ManiSkillUnitree H1 是 ManiSkillGPU 并行化机器人仿真与操作基准框架内置建模的全尺寸双足人形机器人其仿真模型以 19 自由度完整还原躯干、双臂与双腿并配套pd_joint_pos/pd_joint_delta_pos两套关节位置控制器。本文以官方机器人文档 docs/source/robots/unitree_h1/index.md 为主体结合 h1.py 源码与 UnitreeH1Stand-v1 环境 的实现讲清该机器人如何加载、如何配置控制器、如何初始化站立姿态以及如何在实际任务环境如站立保持任务中使用它。机器人概览UID、自由度与质量评级Unitree H1 在 ManiSkill 中的核心身份信息如下属性值Robot UIDunitree_h1对应 Agent 类UnitreeH1定义于 h1.py质量评级QualityB稳定可仿真但部分动力学参数不够真实自由度Degrees of Freedom19可用控制器pd_joint_pos、pd_joint_delta_pos机器人 UID 是框架内注册与引用该机器人的唯一标识可用于EmptyEnv(robot_uidsunitree_h1)或gym.make(...)等加载入口。质量评级采用与 docs/source/robots/index.md 中相同的 Mujoco Menagerie 五档体系A / A / B / C其中 B 级表示稳定但部分数值不真实。这意味着 H1 在默认参数下可以稳定地在 SAPIEN 物理引擎中运行但官方明确建议若要进行 sim2real 迁移或需要高保真动力学请自行执行系统辨识system ID。元数据文件中同样记录了这一评级见 docs/metadata/robot.json 中unitree_h1条目。从源码结构看Unitree H1 属于非固定基座floating base机器人——fix_root_link Falseh1.py根关节不锁定机器人的平衡完全依赖 19 个受控关节的协调输出这与手臂固定在工作台上的机械臂建模思路有本质区别。视觉模型与碰撞模型看懂仿真外观与物理包围ManiSkill 为每个内置机器人提供从正前方与侧方两个视角渲染的视觉网格图与碰撞网格图。Unitree H1 的对应图片位于 docs/source/_static/robot_images/unitree_h1/碰撞网格图的着色规则在 docs/source/robots/unitree_h1/index.md 中明确给出绿色代表凸网格Convex Mesh蓝色代表基元形状网格Primitive Shape Mesh如球、盒、胶囊等。这一点与文档生成脚本 generate_robot_docs.py 的实现完全对应脚本为球/盒/胶囊等基元碰撞形状附加蓝色渲染材质为凸网格碰撞形状附加绿色材质从而直观呈现机器人的物理碰撞体分布。值得注意的是源码中设置了load_multiple_collisions Trueh1.py允许每个 link 加载多个碰撞形状这有助于更精确地还原 H1 复杂的外壳轮廓。Agent 类源码解析URDF 加载与注册Unitree H1 的仿真模型通过 URDF 文件加载类定义如下h1.pyregister_agent(asset_download_ids[unitree_h1]) class UnitreeH1(BaseAgent): uid unitree_h1 urdf_path f{ASSET_DIR}/robots/unitree_h1/urdf/h1.urdf urdf_config dict() fix_root_link False load_multiple_collisions True关键点说明register_agent(asset_download_ids[unitree_h1])将类注册进 Agent 注册表并声明该机器人依赖unitree_h1资产组。首次使用前需要通过资产下载流程获取 URDF 与网格文件模型文件位于 mani_skill/assets/robots/g1_humanoid/ 同级目录结构中H1 的 URDF 路径以ASSET_DIR为基准拼接。urdf_config dict()未指定任何 URDF 覆写配置使用 URDF 文件内默认的关节限位、质量与惯性参数。fix_root_link False根链节不固定这是双足/四足等自由移动机器人的典型配置让物理引擎可以计算全身平衡。站立关键帧初始化机器人的标准姿态keyframes定义了机器人的典型姿态供环境重置与文档渲染使用。Unitree H1 的standing关键帧h1.pykeyframes dict( standingKeyframe( posesapien.Pose(p[0, 0, 0.975]), qposnp.array( [0, 0, 0, 0, 0, 0, 0, # 前 7 个自由关节腰、髋偏航等 -0.4, -0.4, 0.0, 0.0, # 髋滚转、肩俯仰等 0.8, 0.8, 0.0, 0.0, # 髋俯仰、肩滚转 -0.4, -0.4, 0.0, 0.0] # 膝、踝、肘等 ) * 1, ) )pose机器人根链节的世界位姿z 方向抬升至 0.975 m对应 H1 站直时髋部大致高度。qpos19 维关节角数组与下文body_joints顺序一一对应全部为弧度制。其中双腿膝关节附近关节设为-0.4、髋部俯仰设为0.8等非零值构成一个微屈膝的稳定站立姿态便于物理引擎从静态开始求解平衡。关键帧Keyframe是 ManiSkill Agent 的标准机制环境可以通过self.agent.keyframes[standing]取回该姿态在每回合初始化时设置set_qpos与set_pose。19 个受控关节与 PD 参数body_joints按顺序列出了全部 19 个受控关节h1.py覆盖双腿、双臂与躯干关节组关节名髋部left_hip_yaw_joint、right_hip_yaw_joint、left_hip_roll_joint、right_hip_roll_joint、left_hip_pitch_joint、right_hip_pitch_joint膝 / 踝left_knee_joint、right_knee_joint、left_ankle_joint、right_ankle_joint肩部left_shoulder_pitch_joint、right_shoulder_pitch_joint、left_shoulder_roll_joint、right_shoulder_roll_joint、left_shoulder_yaw_joint、right_shoulder_yaw_joint肘部left_elbow_joint、right_elbow_joint躯干torso_joint对应的 PD比例-微分驱动参数在类属性中统一定义h1.pybody_stiffness 1e3刚度系数N·m/rad决定关节抵抗位置偏差的力度body_damping 1e2阻尼系数N·m·s/rad决定关节抵抗速度偏差的力度body_force_limit 100关节最大输出力矩N·m。这三个参数在物理仿真中决定了 H1 能否站稳刚度不足会导致机器人下坠刚度过大则可能引发数值不稳定。评级 B 即意味着这些取值能稳定运行但并非真实电机的精确参数。控制器配置绝对位置控制与增量位置控制H1 的控制器通过_controller_configs属性暴露h1.py提供两种模式body_pd_joint_pos PDJointPosControllerConfig( self.body_joints, lowerNone, upperNone, stiffnessself.body_stiffness, dampingself.body_damping, force_limitself.body_force_limit, normalize_actionFalse, ) body_pd_joint_delta_pos PDJointPosControllerConfig( self.body_joints, lower-0.2, upper0.2, stiffnessself.body_stiffness, dampingself.body_damping, force_limitself.body_force_limit, use_deltaTrue, )控制器动作语义关节限位动作归一化pd_joint_pos输出绝对目标关节角不额外限制lower/upperNone使用 URDF 限位关闭normalize_actionFalsepd_joint_delta_pos输出相对当前关节角的增量每步增量限幅 ±0.2 rad开启默认归一化到 [-1, 1]use_delta与normalize_action是 PDJointPosControllerConfig 的核心字段use_deltaTrue时控制器内部将动作解释为目标位置增量并累加到当前 qposnormalize_actionTrue时动作空间会被裁剪并按限位缩放到[-1, 1]区间。实践中绝对位置控制适合需要精确指定目标姿态的任务而增量控制更适合策略输出平滑小幅度修正的强化学习场景。控制器配置中还包含一处对自由基座机器人至关重要的注释h1.py# note we must add balance_passive_forceFalse otherwise gravity will be disabled for the robot itself # balance_passive_forceTrue is only useful for fixed robots return dict( pd_joint_posdict(bodybody_pd_joint_pos, balance_passive_forceFalse), pd_joint_delta_posdict(bodybody_pd_joint_delta_pos, balance_passive_forceFalse), )即两个控制器都必须显式设置balance_passive_forceFalse。balance_passive_force用于对固定基座机器人补偿重力被动项若对 H1 这类自由基座机器人开启会关闭机器人自身的重力作用导致平衡任务完全失去物理意义。这是移植固定机械臂配置到人形机器人时最易踩的坑之一。传感器与状态判定无相机纯关节状态H1 的默认传感器配置为空h1.pyproperty def _sensor_configs(self): return []即默认情况下 H1 不挂载任何相机任务可通过obs_modestate获取关节 qpos/qvel 等本体状态完成训练与评估。需要视觉时任务环境可自行添加相机如 UnitreeH1Stand-v1 只配置了用于人类观察渲染的render_camera。此外Agent 类还提供了两个实用的状态判定方法h1.pyis_standing()基于根链节高度启发式判断是否站立——高度在(0.8, 1.2)区间内视为站立is_fallen()高度低于0.3视为摔倒。这两个方法以根链节 z 坐标为判据简单高效被HumanoidStandEnv.evaluate()直接调用作为任务成功/失败信号见下文。简化版本 UnitreeH1Simplified仓库还提供了简化建模版本UnitreeH1Simplifiedh1.pyregister_agent(asset_download_ids[unitree_h1]) class UnitreeH1Simplified(UnitreeH1): uid unitree_h1_simplified urdf_path f{ASSET_DIR}/robots/unitree_h1/urdf/h1_simplified.urdf它继承UnitreeH1的全部关节、控制器与关键帧逻辑仅将 URDF 替换为h1_simplified.urdf简化腿部/外壳网格从而减少碰撞检测与渲染开销在 GPU 并行仿真中换取更高吞吐。其对应的机器人页面见 docs/source/robots/unitree_h1_simplified/index.md自由度同样为 19。实战UnitreeH1Stand-v1 站立保持任务Unitree H1 系列机器人实际应用在 mani_skill/envs/tasks/humanoid/ 目录下的任务中。其中UnitreeH1Stand-v1定义于 humanoid_stand.py是直接使用 H1 简化版的人形站立任务register_env(UnitreeH1Stand-v1, max_episode_steps1000) class UnitreeH1StandEnv(HumanoidStandEnv): SUPPORTED_ROBOTS [unitree_h1_simplified] agent: Union[UnitreeH1Simplified] def __init__(self, *args, robot_uidsunitree_h1_simplified, **kwargs): super().__init__(*args, robot_uidsrobot_uids, **kwargs) property def _default_sim_config(self): return SimConfig( gpu_memory_configGPUMemoryConfig( max_rigid_contact_count2**22, max_rigid_patch_count2**21 ) )回合初始化逻辑humanoid_stand.py展示了对关键帧与随机化的标准用法def _initialize_episode(self, env_idx: torch.Tensor, options: dict): with torch.device(self.device): b len(env_idx) standing_keyframe self.agent.keyframes[standing] random_qpos torch.randn(size(b, self.agent.robot.dof[0]), dtypetorch.float) * 0.05 random_qpos common.to_tensor(standing_keyframe.qpos, deviceself.device) self.agent.robot.set_qpos(random_qpos) self.agent.robot.set_pose(sapien.Pose(p[0, 0, 0.975]))即在站立关键帧 qpos 上叠加标准差 0.05 rad 的高斯噪声并把根链节放到z0.975每回合都会生成略有差异的初始姿态迫使策略学会鲁棒地恢复平衡。评估与奖励则完全复用了前文提到的启发式判定humanoid_stand.pydef evaluate(self): is_standing self.agent.is_standing() self.agent.is_fallen() return {is_standing: is_standing, fail: ~is_standing} def compute_sparse_reward(self, obs, action, info): return info[is_standing]max_episode_steps1000意味着策略需要在整个回合内持续保持站立姿态。由于任务默认使用unitree_h1_simplified简化腿部模型其 GPU 内存配置针对大规模并行环境调大了刚体接触数与 patch 数上限2**22/2**21以支撑大量并行环境的接触求解。这一任务同时支持sparse与none两种奖励模式是验证 H1 平衡控制能力的最小可用基准。附机器人文档的自动生成机制docs/source/robots/unitree_h1/index.md由脚本 docs/generate_robot_docs.py 自动生成文件头部明确标注DO NOT MODIFY THIS FILE DIRECTLY。生成流程要点generate_robot_docs.py遍历mani_skill.agents.robots模块中所有以该模块为定义源的 Agent 类实例化EmptyEnv(robot_uidsagent.uid)并设置到第一个关键帧用 RT 着色器渲染前视/侧视 RGB 图与碰撞可视化图从环境读取实际自由度env.agent.robot.dof与控制器列表env.agent._controller_configs从 docs/metadata/robot.json 读取质量评级与展示名称最终拼装出机器人独立页面。这意味着本文描述的 UID、自由度、控制器清单等元数据全部由真实仿真环境运行时推导而来而非手工填写确保了文档与代码的一致性。小结围绕 docs/source/robots/unitree_h1/index.md 提供的信息结合 h1.py 与 UnitreeH1Stand-v1 任务 的源码可以总结出使用 Unitree H1 的关键要点加载通过 UIDunitree_h1或简化版unitree_h1_simplified创建环境首次使用需先下载unitree_h1资产组初始化优先复用keyframes[standing]z0.975 的根位姿 19 维关节角可按任务需求叠加 qpos 噪声控制默认提供绝对位置控制pd_joint_pos与增量位置控制pd_joint_delta_pos增量限幅 ±0.2 rad两者都必须关闭balance_passive_force评估可直接调用is_standing()/is_fallen()作为平衡任务的成功与失败判据调参模型评级为 B若用于 sim2real 或高保真研究需自行执行系统辨识校准body_stiffness、body_damping与body_force_limit。【免费下载链接】ManiSkillManipulation Skill Framework, an open source GPU parallelized robotics simulator and benchmark项目地址: https://gitcode.com/GitHub_Trending/ma/ManiSkill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考