docs: correct Go1 training and evaluation guide

2026-07-31 17:00:49 +08:00
parent ab7fcf480d
commit 269aac5116
1 changed files with 126 additions and 33 deletions
--- a/四足机器狗训练到实机部署全流程指南.md
+++ b/四足机器狗训练到实机部署全流程指南.md
@@ -2,7 +2,7 @@

 > 本教程基于西安交通大学 RoboGauge 团队的研究成果 [Toward Reliable Sim-to-Real Predictability for MoE-based Robust Quadrupedal Locomotion](https://robogauge.github.io/static/files/arxiv.pdf) 及其[项目主页](https://robogauge.github.io/complete/)，将原始 Go2 训练任务适配为 Unitree Go1，并串联 IsaacLab 训练、RoboGauge 评估、MuJoCo sim2sim、ONNX 导出、RDK X5/S100 BPU 量化和 sim2real。
 >
-> 本文依据当前本地仓库代码整理。编写文档的计算机不是训练机或部署机，因此下面的安装、训练、量化和实机命令**尚未在本文编写环境中执行验证**。实际操作时应逐条执行、逐条记录，不要整段复制后无人值守运行。
+> 本文依据当前本地仓库代码和本次 Go1 训练记录整理。IsaacLab 训练、模型导出以及 RoboGauge 单模型评估命令已在训练机上验证；全新环境安装、BPU 量化和实机命令仍需在目标设备上逐条复核。不要整段复制后无人值守运行。

 ## 1. 教程范围与版本约定

@@ -16,7 +16,7 @@
 | 官方公开 SDK | [unitree_legged_sdk](https://github.com/unitreerobotics/unitree_legged_sdk) |
 | 私有 Go1 PRO SDK | 仅在内部部署机使用，本文不公开协议、密钥和专有接口 |

-本教程统一推荐 **26000 轮检查点**，示例名称如下：
+本次训练在约 33540 轮手动停止，最后一个完整保存的检查点是 `model_33500.pt`。综合当前单 seed RoboGauge 结果，本文仍用 **26000 轮检查点**作为平地与三级楼梯之间较均衡的部署基线；33500 是最新候选，而不是无条件替代 26000。示例发布名称如下：

 ```text
 训练检查点: model_26000.pt
@@ -25,7 +25,7 @@ X5 模型:    policy_robotlab_26000_int16_gemm.bin
 S100 模型:  policy_robotlab_26000_s100_int16_gemm.hbm
 ```

-26000 只是当前推荐基线，不表示轮数越大一定越好。最终模型仍应根据 RoboGauge、MuJoCo 回放和真机日志共同选择。
+训练目录中的导出文件会保留课程阶段，例如 `policy_robotlab_26000_post_command_curriculum.onnx`；确定发布版本后可再复制为上面的短名称。26000 只是当前均衡基线，不表示轮数越大一定越好。若任务以上楼梯为主，应同时保留 15000 和 26000；若以平地高速或下楼梯为主，可继续比较 33500。最终模型仍应根据多 seed RoboGauge、MuJoCo 回放和真机日志共同选择。

 ### 1.2 全流程

@@ -184,6 +184,8 @@ RobotLab ONNX 的历史按“观测项分组后堆叠”，不是简单地将 10

 ## 5. 奖励函数与环境设计

+### 5.1 奖励项与判断原则
+
 Go1 奖励配置位于：

 ```text
@@ -223,6 +225,34 @@ source/robot_lab/robot_lab/tasks/go1/env_cfg.py

 环境通过随机初始状态、摩擦/质量等动力学变化、外力扰动、执行器延迟和连续地形难度降低过拟合。Go1 训练中的执行器延迟为 0 到 4 个物理步，即 0 到 20 ms；独立 MuJoCo 部署中的延迟参数按策略步计量，两者单位不同。

+### 5.2 必须单独识别的课程切换
+
+Go1 当前复用了 `Go2RLGymCommandCfg`。速度指令不是全程保持不变，也不是连续缓慢扩大，而是在固定轮次发生硬切换：
+
+| 训练区间 | `lin_vel_x` | `lin_vel_y` | `ang_vel_yaw` |
+| --- | --- | --- | --- |
+| 0 到 19999 | `[-0.5, 0.5] m/s` | `[-0.5, 0.5] m/s` | `[-1.0, 1.0] rad/s` |
+| 20000 到 49999 | `[-1.0, 1.0] m/s` | `[-1.0, 1.0] m/s` | `[-1.5, 1.5] rad/s` |
+| 50000 起 | `[-2.0, 2.0] m/s` | `[-1.0, 1.0] m/s` | `[-2.0, 2.0] rad/s` |
+
+配置位于 `source/robot_lab/robot_lab/tasks/go2/mdp/commands.py`。命令生成器会在环境重新采样指令时应用切换，并在日志打印 `Command range updated at iter ...`。因此：
+
+- 20000 轮后的奖励断崖首先应按“任务分布突然变难”解释，不能直接判定策略坍塌。
+- `model_20000.pt` 已处于切换边界；当前每 500 轮保存一次，明确属于切换前的最后一个检查点是 `model_19500.pt`。
+- 50000 轮还会发生第二次、更激进的切换。继续训练到该位置前，应预留新的适应区间并单独标注曲线。
+
+本次训练在 19900 到 20100 附近的代表性数据如下：
+
+| 指标 | 19900 | 20100 |
+| --- | ---: | ---: |
+| Teacher reward | 55.64 | 38.35 |
+| Student reward | 54.08 | 36.33 |
+| 非法接触终止比例 | 6.64% | 18.05% |
+| 平均地形等级 | 5.687 | 5.735 |
+| 最大 X 速度指令 | 0.5 | 1.0 |
+
+地形等级在切换点附近没有同步跳变，奖励下降与速度指令范围扩大相吻合。后续判断重点是回报是否逐步恢复、非法接触是否下降，而不是要求新课程下的绝对回报回到旧课程水平。另两个固定奖励课程更早结束：`lin_vel_z_l2` 在 0 到 1500 轮由 `-2` 变为 0，`base_height_l2` 在 0 到 5000 轮由 `-1` 变为 `-10`，都不是 20000 轮断崖的原因。
+
 ## 6. 开始训练

 ### 6.1 默认参数的含义
@@ -261,7 +291,7 @@ watch -n 1 nvidia-smi

 选择能稳定运行且留有显存余量的最大环境数。若 OOM，先减小 `num_envs`；只有明确理解 PPO batch 变化后，再修改 `rsl_rl_cfg.py` 中的 `num_steps_per_env`、mini-batch 和 epoch 数。

-### 6.2 正式训练到 26000 轮
+### 6.2 正式训练并保留候选检查点

 ```bash
 cd go2_rl_robotlab
@@ -270,8 +300,8 @@ conda activate go2_rl_robotlab
 python scripts/rsl_rl/train.py \
  --task=RobotLab-Go1-v0 \
  --num_envs=4096 \
-  --max_iterations=26000 \
-  --run_name=go1_26000 \
+  --max_iterations=33500 \
+  --run_name=go1_4096x24 \
  --logger=tensorboard \
  --headless
 ```
@@ -279,15 +309,17 @@ python scripts/rsl_rl/train.py \
 日志默认位于：

 ```text
-logs/rsl_rl/go1_moe_cts/<时间戳>_go1_26000/
+logs/rsl_rl/go1_moe_cts/<时间戳>_go1_4096x24/
 ```

-检查点每 500 轮保存一次。确认 26000 轮文件存在：
+检查点每 500 轮保存一次。不要只保留最后一个文件，至少确认课程切换前后和最终候选都存在：

 ```bash
-find logs/rsl_rl/go1_moe_cts -name 'model_26000.pt' -print
+find logs/rsl_rl/go1_moe_cts -name 'model_*.pt' -print | sort -V
 ```

+本次实际 run 保留了 `model_15000.pt`、`model_19500.pt`、`model_26000.pt` 和 `model_33500.pt`。若训练进程被 `Ctrl+C` 中断，以磁盘上最后一个完整 checkpoint 为准；本次停止日志到 33540 左右，但 33540 没有保存，不能把 33500 标成 33540。
+
 ### 6.3 断点续训

 ```bash
@@ -327,9 +359,12 @@ ssh -L 6006:127.0.0.1:6006 <USER>@<TRAIN_HOST>
 | `Loss/*` | 是否出现 NaN、爆炸或长期异常震荡 |
 | `Policy/mean_noise_std` | 探索强度是否异常塌缩或持续过大 |
 | `Perf/total_fps` | 并行环境设置是否有效利用硬件 |
-| `Episode/*` | 各奖励项、课程难度和终止统计 |
+| `Episode_Reward/*` | 速度跟踪、功率、力矩和动作平滑等分项奖励 |
+| `Episode_Termination/*` | `time_out` 与 `illegal_contact` 的占比 |
+| `Curriculum/terrain_levels` | 地形难度是否连续变化 |
+| `Metrics/base_velocity/max_command_x` | 是否在 20000/50000 轮发生指令课程切换 |

-不要只选平均回报最高的 checkpoint。建议将 15000、20000、23000、26000 等候选同时送入 RoboGauge，比较综合分数和分项指标后再决定。
+不要跨课程直接比较总回报绝对值，也不要只选平均回报最高或轮次最大的 checkpoint。建议将 15000、19500、26000、33500 等候选同时送入 RoboGauge，比较综合分数和分项指标后再决定。

 ## 8. 评估与导出模型

@@ -351,16 +386,18 @@ python scripts/rsl_rl/play.py \
 <RUN_DIR>/exported/policy.onnx
 ```

-导出文件出现后才能终止 play。为了后续名称统一：
+同一 run 下再次导出会覆盖这两个通用文件名。必须在切换到下一个 checkpoint 前复制并带上轮次、课程阶段；导出文件完整写入后才能终止 play：

 ```bash
 cp <RUN_DIR>/exported/policy.onnx /path/to/go1_pro_deploy/deploy_45dim_rl_gym/policy_robotlab_26000.onnx
 cp <RUN_DIR>/exported/policy.pt /path/to/RoboGauge/resources/models/go1/policy_robotlab_26000.pt
 ```

-### 8.2 不打断训练地导出
+RoboGauge 当前通过 `torch.jit.load()` 使用 TorchScript `.pt`；ONNX 用于独立 MuJoCo、量化和实机部署。两者不能只靠改后缀互换。

-训练 runner 保存的是可恢复训练的 checkpoint，不会默认在每次保存时生成 ONNX。要保持主训练进程运行，可在另一块 GPU、另一台机器或训练显存允许时启动独立 `play.py`：
+### 8.2 不打断训练的导出原则
+
+训练 runner 保存的是可恢复训练的 checkpoint，不会默认在每次保存时生成 ONNX。`play.py` 即使使用 `--headless` 也会启动 Isaac Sim 和一个环境，不是纯模型导出器。要保持主训练进程运行，只应在另一块 GPU、另一台机器或确认剩余显存足够时启动独立 `play.py`：

 ```bash
 CUDA_VISIBLE_DEVICES=1 python scripts/rsl_rl/play.py \
@@ -373,7 +410,8 @@ CUDA_VISIBLE_DEVICES=1 python scripts/rsl_rl/play.py \
 注意：

 - 只处理已经完整写完的 checkpoint，不要复制正在写入的文件。
- 同一 GPU 显存不足时会影响训练，应在第二块 GPU 或离线机器导出。
+- 12 GB 级显卡以 4096 环境训练时通常没有余量再启动 Isaac Sim；不要为了导出挤占训练进程。
+- 若没有第二块 GPU，先复制 checkpoint，待训练停止后离线导出。仓库当前没有正式的 `export-only` 命令，不要把临时 Python 片段写成通用教程入口。
 - `play.py` 导出后仍会进入仿真循环；看到导出文件后用 `Ctrl+C` 结束该独立进程，不会中断训练进程。

 ### 8.3 检查 ONNX 接口
@@ -382,7 +420,7 @@ CUDA_VISIBLE_DEVICES=1 python scripts/rsl_rl/play.py \
 python -c "import onnxruntime as ort; s=ort.InferenceSession('policy_robotlab_26000.onnx'); print([(x.name,x.shape,x.type) for x in s.get_inputs()]); print([(x.name,x.shape,x.type) for x in s.get_outputs()])"
 ```

-预期输入为 450 个 `float32`，输出为 12 个动作。输入输出不匹配时不要继续 sim2sim 或量化。
+预期 ONNX 输入为 `obs: [1, 450] float32`，输出为 `actions: [1, 12] float32`。本次导出的 19500、26000 和 33500 ONNX 均已通过 `onnx.checker.check_model()`。输入输出不匹配时不要继续 sim2sim 或量化。

 ### 8.4 独立 MuJoCo 快速检查

@@ -418,6 +456,12 @@ conda activate robogauge

 git clone https://github.com/wty-yy/RoboGauge.git
 cd RoboGauge
+
+# go1 分支当前维护在私有派生仓库；有权限时再执行
+git remote add go1-private <GO1_ROBOGAUGE_REPOSITORY_URL>
+git fetch go1-private go1
+git switch -c go1 --track go1-private/go1
+
 python -m pip install -e .
 ```

@@ -425,33 +469,61 @@ python -m pip install -e .

 ```bash
 git branch --show-current
-python -c "import robogauge.tasks; from robogauge.utils.task_register import task_register; print('\\n'.join(sorted(task_register.pipeline_classes)))"
+python -c "import robogauge.tasks; from robogauge.utils.task_register import task_register; print(*sorted(task_register.pipeline_classes), sep='\n')"
 ```

-若不存在 `go1_lab` 任务，不要用 `go2_lab` 代替，应先同步本地 Go1 适配代码。
+若不存在 `go1_lab.*` 任务，不要用 `go2_lab.*` 代替，应先同步本地 Go1 适配代码。

-### 9.2 单模型与压力测试
+### 9.2 单模型评估

-直接通过 `--model-path` 指定 26000 对应的 TorchScript：
+直接通过 `--model-path` 指定 26000 对应的部署版 TorchScript。不要传入训练 checkpoint `model_26000.pt`，它是包含优化器等状态的字典，不能被 `torch.jit.load()`。平地配置默认没有启用目标，必须显式传入 `--goals`，否则不会得到有效的速度评估：

 ```bash
-python robogauge/scripts/run.py \
+MUJOCO_GL=glfw python robogauge/scripts/run.py \
  --task-name go1_lab.flat \
  --model-path resources/models/go1/policy_robotlab_26000.pt \
  --experiment-name go1_robotlab_26000_flat \
+  --run-name flat_velocity \
+  --goals max_velocity diagonal_velocity \
  --headless
 ```

-跨地形压力测试：
+三级楼梯使用目标点任务。`--spawn-type level_eval` 固定评估出生点，避免和搜索最高等级时的出生点混淆：

 ```bash
-python robogauge/scripts/run.py \
+MUJOCO_GL=glfw python robogauge/scripts/run.py \
+  --task-name go1_lab.stairs_fd \
+  --model-path resources/models/go1/policy_robotlab_26000.pt \
+  --experiment-name go1_robotlab_26000_stairs_fd \
+  --run-name stairs_fd_l3 \
+  --level 3 \
+  --spawn-type level_eval \
+  --headless
+
+MUJOCO_GL=glfw python robogauge/scripts/run.py \
+  --task-name go1_lab.stairs_bd \
+  --model-path resources/models/go1/policy_robotlab_26000.pt \
+  --experiment-name go1_robotlab_26000_stairs_bd \
+  --run-name stairs_bd_l3 \
+  --level 3 \
+  --spawn-type level_eval \
+  --headless
+```
+
+`run.py --headless` 在 Linux 默认选择 EGL。本次评估机的 EGL 驱动不支持 `PLATFORM_DEVICE`，所以命令显式设置 `MUJOCO_GL=glfw`；GLFW 可能打印无法打开 X11 的 warning，但无窗口仿真仍可完成。如果目标机 EGL 工作正常，可改回 `MUJOCO_GL=egl`。
+
+单任务的 `--task-name` 必须是注册表里的完整名称，例如 `go1_lab.flat` 或 `go1_lab.stairs_fd`，不能写成裸的 `go1_lab`。只有下面的 stress pipeline 把 `go1_lab` 当作机器人任务前缀，再拼接具体地形。
+
+### 9.3 跨地形压力测试
+
+```bash
+MUJOCO_GL=glfw python robogauge/scripts/run.py \
  --task-name go1_lab \
  --model-path resources/models/go1/policy_robotlab_26000.pt \
  --experiment-name go1_robotlab_26000_stress \
  --stress-benchmark \
  --stress-terrain-names flat slope_fd slope_bd stairs_fd stairs_bd wave obstacle \
-  --num-processes 32 \
+  --num-processes 8 \
  --seeds 0 1 2 \
  --search-seeds 0 1 2 3 4 \
  --frictions 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0 \
@@ -461,14 +533,34 @@ python robogauge/scripts/run.py \

 `--num-processes` 应根据 CPU 核数和内存调整，不宜盲目设为最大逻辑核心数。

-### 9.3 训练期间异步评估
+### 9.4 本次同条件评估结果
+
+下表来自同一 Go1 MuJoCo 模型、`go1_lab.*` 配置、seed 42 和上述目标参数。所有分数都已归一化为越大越好；楼梯的 `success` 均为 1。15000 的平地对角速度序列曾发生一次翻倒，pipeline 恢复后继续了其余目标。
+
+| Checkpoint | 平地综合 | 对角速度 | 最大速度 | 三级楼梯前向 | 三级楼梯后向 |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| 15000 | 0.7072 | 0.5878 | 0.8265 | **0.6477** | 0.6536 |
+| 19500，20k 课程前最后一版 | 0.7246 | 0.6209 | 0.8283 | 0.6311 | 0.5774 |
+| 26000 | 0.7933 | 0.7540 | 0.8326 | 0.6410 | 0.6904 |
+| 33500，最新完整保存版 | **0.8030** | **0.7558** | **0.8502** | 0.6135 | **0.7009** |
+
+这组结果说明：
+
+- 26000 比 19500 更适应扩大后的速度指令，平地和后向楼梯均明显恢复，整体最均衡。
+- 33500 的平地最大速度和后向楼梯最好，但前向上楼梯继续下降，不适合只按最新轮次替换 26000。
+- 15000 的前向上楼梯分数最高，但存在一次平地对角命令翻倒，不能仅凭楼梯单项直接上机。
+- 这些是单 seed 筛选结果，只用于缩小候选范围。发布前仍需运行多 seed、摩擦、质量和地形压力测试，并结合真实电机温度、电流与保护日志。
+
+RoboGauge 的 `dof_power` 是归一化质量分，不是瓦特或电机温度。它可以比较同条件 checkpoint，但不能据此断言真机不会过热。
+
+### 9.5 训练期间异步评估

 先启动服务端：

 ```bash
 conda activate robogauge
 cd RoboGauge
-python robogauge/scripts/server.py --port 9973 --num-processes 32
+python robogauge/scripts/server.py --port 9973 --num-processes 8
 ```

 再启动训练：
@@ -485,15 +577,15 @@ python scripts/rsl_rl/train.py \
  --headless
 ```

-当前 `OnPolicyRunnerCTS.update_robogauge()` 每 500 轮自动导出一个 JIT 模型并提交评估，但本地版本中 `task_name` 曾硬编码为 `go2_lab`。训练 Go1 前必须确认该处为：
+当前 `OnPolicyRunnerCTS.update_robogauge()` 每 500 轮自动导出一个 JIT 模型并提交评估，但当前 Go1 分支仍将 `task_name` 硬编码为 `go2_lab`。训练 Go1 前必须先改成一个已注册的完整任务名，例如平地筛选使用：

 ```python
-task_name="go1_lab"
+task_name="go1_lab.flat"
 ```

-检查文件为 `source/rsl_rl/rsl_rl/runners/on_policy_runner_cts.py`。否则会用错误的机器人任务评估 Go1 模型。异步评估生成的是 `jit_models/policy_jit_<ITER>.pt`；ONNX 仍需通过 `play.py` 导出。
+检查文件为 `source/rsl_rl/rsl_rl/runners/on_policy_runner_cts.py`。裸的 `go1_lab` 不是单任务注册名，`go2_lab` 也会评估错误的机器人。更合理的长期修复是把评估任务写入训练配置，而不是继续硬编码。完成修复前不要启用 `--robogauge`。异步评估生成的是 `jit_models/policy_jit_<ITER>.pt`；ONNX 仍需通过 `play.py` 导出。

-### 9.4 如何选择 26000 模型
+### 9.6 如何选择发布模型

 至少比较：

@@ -1006,7 +1098,7 @@ loop_dt_ms / recv_ms / policy_ms / work_ms / state_fresh / state_age_ms

 ### 16.4 TensorBoard 总回报上涨，但 RoboGauge 下降

-可能是训练奖励偏向速度跟踪，牺牲了力矩、姿态或关节裕度，也可能是后期 checkpoint 对训练域过拟合。比较分项指标和多个 checkpoint，不要只保留最后一轮。
+先检查是否跨过 20000 或 50000 轮的速度指令课程切换。课程变难后总回报下降、非法接触短时上升是预期现象，旧课程和新课程的绝对回报不能直接比较。若命令范围和地形等级都未变化，才进一步排查训练奖励偏向速度跟踪、牺牲力矩/姿态/关节裕度或后期 checkpoint 对训练域过拟合。无论哪种情况，都应比较分项指标和多个 checkpoint，不要只保留最后一轮。

 ### 16.5 真机一进入 RL 就力矩保护

@@ -1017,9 +1109,10 @@ loop_dt_ms / recv_ms / policy_ms / work_ms / state_fresh / state_age_ms
 - [ ] RoboGo 镜像和容器启动信息已补全。
 - [ ] 硬件、接线、网络和急停章节已由设备负责人补全。
 - [ ] 所有仓库 commit 和 Python 依赖已记录。
- [ ] 26000 checkpoint 已完成 TensorBoard、IsaacLab play 和导出检查。
+- [ ] 15000、19500、26000、33500 候选已注明课程阶段，并完成 TensorBoard 与 RoboGauge 对比。
+- [ ] 最终选定 checkpoint 已完成 IsaacLab play、TorchScript/ONNX 导出及哈希记录。
 - [ ] ONNX 输入 450、输出 12，关节顺序为 `FR, FL, RR, RL`。
- [ ] RoboGauge 使用 `go1_lab` 而非 `go2_lab`。
+- [ ] RoboGauge 单任务使用完整的 `go1_lab.*` 注册名，而非裸 `go1_lab` 或 `go2_lab`。
 - [ ] MuJoCo 平地、转向、侧移、急停和台阶测试通过。
 - [ ] 真实日志校准集与模型版本一致。
 - [ ] X5/S100 量化模型通过离线精度和延迟验收。