guguji MuJoCo 强化学习指南

这份文档对应的是仓库里新加入的 MuJoCo 训练后端。

目标是让你可以在不启动 Gazebo 的情况下，直接在 MuJoCo 里完成：

模型加载
环境自检
平衡训练
walking 课程训练
策略回放

1. 代码放在哪里

MuJoCo 训练代码继续放在 guguji_rl/ 目录，而不是单独再开一个同级仓库，原因是：

guguji_rl/ 本来就是强化学习工程
Gazebo 和 MuJoCo 可以共用大部分 PPO、奖励函数和评估脚本
你后面切换后端时，只需要换配置文件，不需要换一套完全不同的工程

这次新增的关键文件有：

guguji_rl/guguji_rl/mujoco_model.py 从现有 URDF 动态生成 MuJoCo 用的 MJCF
guguji_rl/guguji_rl/envs/mujoco_biped_env.py MuJoCo 训练环境
guguji_rl/configs/mujoco_balance_ppo.yaml MuJoCo 平衡训练配置
guguji_rl/configs/mujoco_walk_ppo.yaml MuJoCo walking 课程训练配置
guguji_rl/configs/mujoco_command_walk_ppo.yaml 前进 / 后退 / 转弯命令条件化训练配置
guguji_rl/scripts/export_mujoco_xml.py 把动态生成的 MJCF 导出到文件，方便你逐行查看

2. 安装步骤

在 Ubuntu 22.04 下，建议直接复用 guguji_rl 的虚拟环境：

cd /home/corvin/Project/guguji_simulation/guguji_rl
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt

现在 requirements.txt 里已经包含：

mujoco
gymnasium
stable-baselines3
torch

如果你只是跑 MuJoCo 环境本身，mujoco 用 CPU 就可以。如果你要加速 PPO 训练，还是主要依赖 torch 的 GPU。

3. 先导出一份 MJCF 看结构

MuJoCo 版不是手写死一个 XML，而是从当前 URDF 动态生成 MJCF。如果你想看最终送进 MuJoCo 的模型，可以先导出：

cd /home/corvin/Project/guguji_simulation/guguji_rl
source .venv/bin/activate
python scripts/export_mujoco_xml.py \
  --config configs/mujoco_balance_ppo.yaml \
  --output generated/guguji_mujoco.xml

导出后的 generated/guguji_mujoco.xml 很适合你后面自己调：

关节 range
actuator kp
floor friction
根 body 结构

4. 环境自检

先不要急着训练，先确认 MuJoCo 环境能 reset 和 step：

cd /home/corvin/Project/guguji_simulation/guguji_rl
source .venv/bin/activate
python scripts/check_env.py --config configs/mujoco_balance_ppo.yaml --steps 8

如果这一步正常，你会看到：

reset ok
observation shape
每一步的 reward / vx / base_z

如果你要检查 walking 配置里的参考步态，也可以运行：

python scripts/check_env.py --config configs/mujoco_walk_ppo.yaml --steps 8

5. 第一步先训平衡

第一次在 MuJoCo 上训练，建议还是先从平衡开始：

cd /home/corvin/Project/guguji_simulation/guguji_rl
source .venv/bin/activate
python scripts/train.py --config configs/mujoco_balance_ppo.yaml --device cpu

如果你想用 GPU 加速 PPO：

python scripts/train.py --config configs/mujoco_balance_ppo.yaml --device cuda

说明：

MuJoCo 物理本身不吃 CUDA
GPU 主要加速的是 torch 的策略网络训练

6. walking 训练怎么做

configs/mujoco_walk_ppo.yaml 已经内置了三段速度课程，不建议一上来就直接追高速度：

0.18 m/s
0.22 m/s
0.26 m/s

推荐先用已经训好的 MuJoCo 平衡模型继续训练：

cd /home/corvin/Project/guguji_simulation/guguji_rl
source .venv/bin/activate
python scripts/train.py \
  --config configs/mujoco_walk_ppo.yaml \
  --init-model outputs/<你的_mujoco_balance_实验目录>/final_model.zip \
  --device auto

训练脚本会自动按三段课程顺序继续训练，不需要你手动分三次运行。

7. 平衡模型什么时候算“可以毕业”

不要只看“训练跑完了没有”，更重要的是看它是不是已经满足下一阶段的稳定性门槛。

建议至少检查下面 4 条：

5 次左右确定性回放里，大多数 episode 都能站满 max_episode_steps
不应该频繁出现 terminated=True 的摔倒终止
roll / pitch 峰值最好控制在 0.10 ~ 0.15 rad 以内
站立命令下的 delta_x 最好只有厘米级甚至毫米级漂移

你这次的 MuJoCo balance 实测已经满足进入下一阶段的条件：

5 / 5 次确定性回放都站满了 400 步
没有出现摔倒终止
max_abs_roll 大约 0.076 rad
max_abs_pitch 大约 0.058 rad
min_height 大约 0.3325 m
delta_x 只有约 -0.001 ~ -0.002 m

这说明它已经不是“勉强不摔”，而是足够作为命令条件化 walking 的初始化模型。

8. 为什么下一步要做命令条件化，而不是继续只训固定前进

固定目标前进版的作用，是先把“迈腿并保持大体稳定”这件事学出来。

但如果你后面要做：

前进
后退
左转 / 右转
原地等待

那策略就必须知道“现在到底想让我做什么”。所以 observation 里必须加入命令，reward 也必须改成“跟踪当前命令”，而不是永远只奖励一个固定前进速度。

这次代码里已经把三件事接好了：

observation 新增了 yaw_rate / cmd_vx / cmd_yaw
reward 新增了 yaw_rate_tracking / turn_progress / command_stillness
训练配置新增了 commands 段，用来采样 stand / turn / translate / combined 命令

9. 命令条件化 walking 怎么跑

直接基于已经训好的 balance 模型继续：

cd /home/corvin/Project/guguji_simulation/guguji_rl
source .venv/bin/activate
python scripts/train.py \
  --config configs/mujoco_command_walk_ppo.yaml \
  --init-model outputs/<你的_mujoco_balance_实验目录>/final_model.zip \
  --device auto

注意，这个配置的 observation 会从 29 维扩展到 32 维，所以旧 balance 模型不能再“完全一模一样地”加载。

现在 train.py 已经做了兼容处理：

如果维度没变，就完整加载旧模型参数
如果维度变了，就自动跳过第一层输入权重，只保留后续兼容层做 warm start

所以你仍然可以复用 balance 模型里已经学到的大部分稳定控制能力。

10. 怎么评估是不是更会往前走

训练结束后，train.py 会自动输出：

delta_x
mean_vx

你也可以手动单独评估：

cd /home/corvin/Project/guguji_simulation/guguji_rl
source .venv/bin/activate
python scripts/evaluate_forward_progress.py \
  --config configs/mujoco_walk_ppo.yaml \
  --model outputs/<你的实验目录>/final_model.zip

命令条件化模型推荐先固定一个前进命令再评估：

python scripts/evaluate_forward_progress.py \
  --config configs/mujoco_command_walk_ppo.yaml \
  --model outputs/<你的实验目录>/final_model.zip \
  --command-forward 0.18 \
  --command-yaw 0.0

这样你后面调：

参考步态振幅
目标速度
摩擦参数
actuator kp

都可以直接看量化指标，而不是只靠肉眼猜。

11. 策略回放

如果你想在 MuJoCo 里回放训练好的策略：

cd /home/corvin/Project/guguji_simulation/guguji_rl
source .venv/bin/activate
python scripts/run_policy.py \
  --config configs/mujoco_walk_ppo.yaml \
  --model outputs/<你的实验目录>/final_model.zip \
  --deterministic \
  --max-episodes 1

如果你想打开 MuJoCo 窗口看画面：

python scripts/run_policy.py \
  --config configs/mujoco_walk_ppo.yaml \
  --model outputs/<你的实验目录>/final_model.zip \
  --deterministic \
  --render-human

命令条件化模型回放时，也可以直接在命令行指定要看的命令：

python scripts/run_policy.py \
  --config configs/mujoco_command_walk_ppo.yaml \
  --model outputs/<你的实验目录>/final_model.zip \
  --deterministic \
  --render-human \
  --command-forward 0.18 \
  --command-yaw 0.0

12. MuJoCo 版和 Gazebo 版有什么关系

这两套后端现在是并行存在的：

Gazebo 版更接近 ROS 2 / 真实系统接口
MuJoCo 版更适合快速做强化学习迭代

建议你后面这样使用：

先在 MuJoCo 里快速调奖励、课程和参考步态
再把比较靠谱的策略思路迁回 Gazebo
最后再往真实机器人部署链路上收敛

13. 你后面最常改的地方

如果你后面要自己继续调，我建议优先看这些文件：

guguji_rl/guguji_rl/mujoco_model.py 看 MuJoCo 模型是怎么从 URDF 生成出来的
guguji_rl/guguji_rl/envs/mujoco_biped_env.py 看动作映射、reset、参考步态和观测
guguji_rl/configs/mujoco_balance_ppo.yaml 调平衡训练参数
guguji_rl/configs/mujoco_walk_ppo.yaml 调 walking 课程、目标速度和参考步态
guguji_rl/configs/mujoco_command_walk_ppo.yaml 调命令采样范围、转弯课程和命令跟踪奖励

如果后面你愿意继续推进，最自然的下一步一般是：

先在 MuJoCo 里把 balance 训练跑稳
再把 MuJoCo walking 课程跑起来
最后把 MuJoCo 学到的 walking 参数往 Gazebo 版迁移一轮

guguji_mujoco_rl_guide.md 9.0 KB History Raw