# 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/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. 怎么评估是不是更会往前走

训练结束后，`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
```

这样你后面调：

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

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

## 8. 策略回放

如果你想在 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
```

## 9. MuJoCo 版和 Gazebo 版有什么关系

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

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

建议你后面这样使用：

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

## 10. 你后面最常改的地方

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

- `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 课程、目标速度和参考步态

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

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