Gymnasium MuJoCo 连续控制环境完整实战指南从 5 行代码到造出自己的机器人【免费下载链接】GymnasiumA standard API for single-agent reinforcement learning environments, with popular reference environments and related utilities (formerly Gym)项目地址: https://gitcode.com/GitHub_Trending/gy/Gymnasium如果你只训练过离散环境Gymnasium 的 MuJoCo 环境就是连续控制的入口几行 Python 就能让一只小猎豹跑起来一套完整训练闭环能看着奖励曲线从零爬升。本文带你从能跑起来的代码一路走到自定义环境。五分钟跑通第一个 MuJoCo 环境HalfCheetah 的最小循环 假设你刚装好依赖pip install gymnasium[mujoco]现在打开 Python把下面这段原样跑一遍import gymnasium as gym env gym.make(HalfCheetah-v5) obs, info env.reset(seed42) print(obs.shape) # (17,) print(info) # {x_position: -0.262...} action env.action_space.sample() # 随机采样一个动作 obs, reward, terminated, truncated, info env.step(action) print(reward) # 例如 0.42 print(info) # 含 x_position / x_velocity / reward_forward / reward_ctrl env.close()逐行拆一下发生了什么gym.make(HalfCheetah-v5)从注册表实例化环境。它是一只二维的半截猎豹躯干和头固定6 个关节前后大腿、小腿、脚能施加扭矩目标就是往右跑得越快越好。env.reset(seed42)把机器人放回初始姿态并加一点随机噪声返回(obs, info)。注意 0.26 之后reset()返回的是二元组而不是单个观测。obs.shape是(17,)一个 float64 向量。它其实就是位置 速度的拼接7 个关节角度加躯干高度等 8 个 qpos位置9 个 qvel速度。env.action_space.sample()在Box(-1, 1, (6,))里随机抽一个 6 维向量——相当于给 6 个关节随机拧一下力矩。step()返回五元组新观测、标量奖励、terminated任务是否失败结束、truncated是否到时间上限、info诊断信息。这就是全部循环观测进、动作出、拿奖励。训练强化学习就是让这个随机拧一下逐步变成知道怎么拧。读懂环境信号HalfCheetah 的 17 维观测里装了什么刚拿到obs时最容易犯的错误是把它当成一团数字。其实 Gymnasium 的 MuJoCo 环境里观测和动作都有清晰的物理含义。信号形状 / 范围含义obs(17,), float64前 8 项是 qpos各关节角度、躯干高度等位置后 9 项是 qvel对应速度actionBox(-1, 1, (6,)), float326 个关节的归一化扭矩环境内部再映射成牛顿米reward标量前进速度奖励 - 0.1 × ‖action‖²往前跑加分、用力过猛扣分terminated恒为FalseHalfCheetah 永远不会摔倒只有 1000 步后truncatedTrue三个值得注意的设计细节位置被故意藏起来了。17 维里没有躯干的前后坐标rootx——因为奖励本身就算自前进速度直接喂位置等于把答案抄给智能体。想拿位置看info[x_position]即可。这个取舍可以开关gym.make(HalfCheetah-v5, exclude_current_positions_from_observationFalse)会得到 18 维观测。奖励是拆解过的。每步info里都有reward_forward和reward_ctrl两项。调试为什么奖励上不去时先看这两项谁在拖后腿比盯着总奖励猜要快得多。v5 帮你标注了观测结构。env.observation_structure直接告诉你哪些维度是 qpos、哪些是 qvel做自定义 wrapper 时非常省事。对比另一个环境更能体会差异InvertedPendulum-v5的奖励是每保持直立 0.2 弧度以内一步 1且摔倒立刻terminatedTrue。同样是位置速度的观测任务性质从耐力跑变成了走钢丝。环境选型指南从哪个 MuJoCo 环境开始训练第一次做连续控制最忌讳一上来就冲 Humanoid——21 维动作、全身协调奖励曲线能让你怀疑人生。选环境的依据其实就三条动作维度、有没有摔倒终止、你想对标什么论文。先定动作维度预算。维度直接决定训练难度1~2 维InvertedPendulum-v51 维、InvertedDoublePendulum-v52 维、Reacher-v52 维3~6 维Hopper-v53 维、Pusher-v53 维、Swimmer-v55 维、HalfCheetah-v56 维、Walker2d-v56 维8 维及以上Ant-v58 维、Humanoid-v5/HumanoidStandup-v521 维再看有没有摔倒终止。HalfCheetah永不终止奖励曲线平滑最适合当第一个 locomotion 任务Hopper、Walker2d、Humanoid一旦摔倒就提前截断回合长度忽长忽短奖励曲线天然带噪声——这对调算法是好事但对刚上手的人是干扰。最后看你想要什么。验证代码管线、快速看到收敛选InvertedPendulum-v54 维观测、1 维动作仓库官方教程就用它做 REINFORCE 示例见 docs/tutorials/training_agents/mujoco_reinforce.py。想学奔跑控制HalfCheetah-v5。想摸 3D 操作manipulationReacher-v5入门、Pusher-v5进阶。要发论文做对比Ant-v5和Humanoid-v5是 PPO/SAC 论文的标配基准。一句话决策链调试期用 InvertedPendulum正式开跑用 HalfCheetah冲基准上 Ant/Humanoid。另外所有环境都有 v4/v5 两代新研究直接用-v5mujoco2.3.3特性最全要复现旧文献结果再考虑 v4。采样提速三板斧渲染模式、向量化与无头后端 ⚡训练 MuJoCo 环境时真正的瓶颈往往不是算法而是环境采样速度。三板斧按收益排序第一斧训练时别开渲染。窗口渲染会实打实地拖慢每一步train_env gym.make(HalfCheetah-v5) # 训练不渲染最快 eval_env gym.make(HalfCheetah-v5, render_modehuman) # 评估弹窗看效果想留训练过程当证据用视频录制代替实时窗口from gymnasium.wrappers import RecordVideo video_env RecordVideo( gym.make(HalfCheetah-v5, render_modergb_array), video_folder./videos, )第二斧向量化环境并行采样。PPO 这类算法一个 update 要吃上千步样本8 个环境并行跑比单环境快得多from gymnasium.vector import SyncVectorEnv envs SyncVectorEnv([lambda: gym.make(HalfCheetah-v5) for _ in range(8)]) obs, infos envs.reset(seed42) actions envs.action_space.sample() # 一次给 8 个环境各抽一个动作 obs, rewards, terminateds, truncateds, infos envs.step(actions) print(obs.shape) # (8, 17)多核机器上可以再换成AsyncVectorEnv用多进程进一步并行。第三斧无头图形后端。服务器上根本没有显示器默认后端会报错或卡死。MuJoCo 用MUJOCO_GL环境变量切换后端后端设置方式适用场景GLFWMUJOCO_GLglfw默认本地开发带窗口的 GPU 渲染EGLMUJOCO_GLegl服务器无头 GPU推荐OSMesaMUJOCO_GLosmesa无 GPU 的纯 CPU 渲染兼容性最好export MUJOCO_GLegl python train.py三者叠加之后一个 4 环境并行的 PPO 训练环境侧基本不再是短板。完整训练闭环用 PPO 训练 HalfCheetah 并读懂奖励曲线采样提速之后来看一个能落地的完整闭环训练 → 监控 → 评估。算法选 PPO工具选 Stable-Baselines3它是 Gymnasium 生态里最顺手的连续控制搭档。训练。核心就这几行import gymnasium as gym from stable_baselines3 import PPO from stable_baselines3.common.callbacks import EvalCallback env gym.make(HalfCheetah-v5) model PPO(MlpPolicy, env, n_steps1024, batch_size64) model.learn(total_timesteps1_000_000)监控。用EvalCallback周期性在独立评估环境里打分并保存最优权重比盯着训练奖励靠谱eval_env gym.make(HalfCheetah-v5) cb EvalCallback(eval_env, best_model_save_path./best, eval_freq10_000) model.learn(1_000_000, callbackcb)评估。评估一定多跑几个回合取平均单回合在 MuJoCo 环境里噪声很大rewards [] for _ in range(10): obs, _ env.reset() total, done 0.0, False while not done: action, _ model.predict(obs) obs, r, terminated, truncated, _ env.step(action) total r done terminated or truncated rewards.append(total) print(f10 回合平均奖励: {sum(rewards)/10:.1f})怎么读奖励曲线。下面这张是 Gymnasium 官方教程里 REINFORCE 训练InvertedPendulum的曲线5 条运行叠加形态对所有连续控制任务通用前 1000 回合贴着 0策略基本在瞎探索别急着调参。中段陡升学到了基本姿势。曲线陡峭程度取决于任务难度InvertedPendulum 五千多回合就能摸到满分 1000 附近HalfCheetah 则要在百万步级别才见平台期。多条曲线之间的散度是随机性不是 bug——初始状态噪声 策略初始化噪声都会体现在这。后半段围绕一个平台震荡那是策略上限了继续加步数收益递减该去看评估环境里的平均数而不是训练曲线本身。踩坑排查手册MuJoCo 环境的 5 个高频问题Q1种子都固定了为什么两次跑出来还是不一样env.reset(seed42)只固定了初始状态噪声。策略网络的初始化是另一套随机源还要torch.manual_seed(42)/np.random.seed(42)一起管。另外 MuJoCo 官方说明过不同版本的mujoco包因浮点运算顺序结果会有微小差异——严格复现要连mujoco的版本号一起锁死。Q2服务器上报错或渲染卡死怎么办十有八九是后端问题。服务器没有窗口系统默认的 GLFW 会出问题export MUJOCO_GLegl用 GPU 无头渲染或MUJOCO_GLosmesa走 CPU。再检查一点训练脚本里是不是不小心写了render_modehuman有窗口的渲染能把采样拖慢几倍。Q3奖励变 NaN、terminated全 True机器人炸了这是状态数值溢出MuJoCo 环境对非有限状态直接判终止。按顺序排查网络输出没压缩到[-1, 1]用tanh或动作缩放 wrapper观测没归一化gymnasium.wrappers.NormalizeObservation学习率过大。三者占齐前两个大多数爆炸都能救回来。Q4随机策略的奖励为什么低得离谱正常。随机动作下的 HalfCheetah 基本在原地扑腾平均奖励接近 0 甚至为负。想快速 sanity check直接看info[x_position]是否随回合缓慢漂移比看总奖励直观。Q5不同环境的奖励数值不能直接比对。InvertedPendulum一步最多 1满回合 1000 分HalfCheetah满回合几百Humanoid是几百上千的量级。跨环境谈我的算法更强之前先统一到各自的评估协议多回合平均、固定种子否则比的是奖励标度。造一个自己的 MuJoCo 环境XML 模型 继承 MujocoEnv当你想换一个机器人、改一个任务规则就有两条路难度差一个数量级。轻量路线只换模型。v5 的环境类全部支持xml_file参数直接把自己的 XML 塞给现成环境env gym.make(HalfCheetah-v5, xml_filemy_cheetah.xml)观测空间会按新模型的 qpos/qvel 维度自动重建不用改 Python 代码。参考模型都在 gymnasium/envs/mujoco/assets/ 下XML 骨架长这样mujoco option timestep0.01 gravity0 0 -9.81/ worldbody light pos0 0 3 dir0 0 -1/ geom namefloor typeplane size5 5 0.1/ body namecart joint nameslide typeslide axis1 0 0/ geom typecapsule size0.1 0.2 mass1/ /body /worldbody actuatormotor jointslide gear3//actuator /mujoco三个关键标签joint给自由度每对 qpos/qvelgeom定义碰撞与外观actuator决定动作维度和控制强度。重量路线自定义环境类。换任务规则比如推到指定位置给奖励时继承MujocoEnv并实现观测、奖励、终止、重置几个钩子物理推进直接复用基类的do_simulationimport numpy as np from gymnasium.envs.mujoco import MujocoEnv class MyCartEnv(MujocoEnv): def __init__(self): super().__init__(xml_filemy_cart.xml, frame_skip5) def _get_obs(self): return np.concatenate([self.data.qpos, self.data.qvel]) def _get_rew(self, x_velocity, action): return x_velocity - 0.1 * np.sum(np.square(action)), {} def _get_terminated(self): return bool(np.any(~np.isfinite(self.data.qpos))) def step(self, action): before self.data.qpos[0] self.do_simulation(action, self.frame_skip) x_vel (self.data.qpos[0] - before) / self.dt reward, info self._get_rew(x_vel, action) return (self._get_obs(), reward, self._get_terminated(), False, info)完整实现对照 gymnasium/envs/mujoco/mujoco_env.py 和 gymnasium/envs/mujoco/half_cheetah_v5.py 即可上手钩子命名与官方环境完全一致。一张表收尾Gymnasium MuJoCo 环境要点速查事项写法安装依赖pip install gymnasium[mujoco]创建环境 / 传参gym.make(Ant-v5, render_modergb_array)查空间env.observation_space/env.action_space固定初始状态env.reset(seed42)并行采样gymnasium.vector.SyncVectorEnv/AsyncVectorEnv录制训练视频gymnasium.wrappers.RecordVideo观测归一化 / 动作缩放NormalizeObservation/RescaleAction无头 GPU 渲染export MUJOCO_GLegl继续深入可以翻这几处仓库内相对路径MuJoCo 环境总览与渲染参数docs/environments/mujoco.md环境类与基类源码gymnasium/envs/mujoco/环境注册表所有可用 idgymnasium/envs/init.py官方 REINFORCE 训练教程docs/tutorials/training_agents/mujoco_reinforce.py向量化环境实现gymnasium/vector/从InvertedPendulum的第一条曲线到Humanoid的全身协调路径都在这几节里了。现在去把MUJOCO_GLegl设上让猎豹先跑起来。【免费下载链接】GymnasiumA standard API for single-agent reinforcement learning environments, with popular reference environments and related utilities (formerly Gym)项目地址: https://gitcode.com/GitHub_Trending/gy/Gymnasium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考