# 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` 的虚拟环境：

```bash
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 的模型，可以先导出：

```bash
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：

```bash
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 配置里的参考步态，也可以运行：

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

## 5. 第一步先训平衡

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

```bash
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：

```bash
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 平衡模型继续训练：

```bash
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 也必须改成“跟踪当前命令”，而不是永远只奖励一个固定前进速度。

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

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

## 9. 命令条件化 walking 怎么跑

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

```bash
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`

你也可以手动单独评估：

```bash
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
```

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

```bash
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 里回放训练好的策略：

```bash
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 窗口看画面：

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

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

```bash
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 版更适合快速做强化学习迭代

建议你后面这样使用：

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

## 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`
  调命令采样范围、转弯课程和命令跟踪奖励

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

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