Unitree RL Gym — Legged Gym 项目深度技术解析

Unitree RL Gym — Legged Gym 项目深度技术解析

本文是对宇树科技（Unitree）开源足式机器人强化学习训练框架 legged_gym 的全面技术拆解，涵盖项目架构、核心算法、数学公式、奖励工程与使用实践。

一、项目概述

1.1 背景与定位

legged_gym 是宇树科技基于 NVIDIA Isaac Gym GPU 并行物理仿真引擎构建的足式机器人强化学习（RL）训练框架。它专为四足与双足机器人的端到端步态控制策略训练而设计，采用 PPO（Proximal Policy Optimization） 算法，在单个 GPU 上可同时并行仿真数千个环境（默认 4096 个），极大地加速了策略收敛。

1.2 核心特性

二、项目目录结构

legged_gym/
├── __init__.py # 包初始化，定义根目录常量
├── envs/
│ ├── __init__.py # 环境注册（注册所有机器人任务）
│ ├── base/
│ │ ├── base_config.py # 配置基类（递归实例化机制）
│ │ ├── base_task.py # 任务基类（仿真生命周期管理）
│ │ ├── legged_robot.py # 足式机器人核心环境（奖励/观测/控制）
│ │ └── legged_robot_config.py # 足式机器人默认配置（含PPO配置）
│ ├── g1/
│ │ ├── g1_config.py # G1 双足机器人配置
│ │ └── g1_env.py # G1 双足机器人环境（步态相位+足部追踪）
│ ├── go2/
│ │ └── go2_config.py # GO2 四足机器人配置（使用通用环境类）
│ ├── h1/
│ │ ├── h1_config.py # H1 双足机器人配置
│ │ └── h1_env.py # H1 双足机器人环境
│ └── h1_2/
│ ├── h1_2_config.py # H1_2 双足机器人配置
│ └── h1_2_env.py # H1_2 双足机器人环境
├── scripts/
│ ├── train.py # 训练入口脚本
│ └── play.py # 推理/测试入口脚本
└── utils/
├── __init__.py # 工具模块导出
├── helpers.py # 通用辅助函数（配置转换/参数解析/JIT导出）
├── isaacgym_utils.py # Isaac Gym 工具（四元数→欧拉角）
├── logger.py # 训练日志记录器
├── math.py # 数学工具（角度归一化/偏航旋转）
├── task_registry.py # 任务注册表（环境创建/算法创建）
└── terrain.py # 程序化地形生成器

三、核心功能模块解析

3.1 配置系统（base_config.py）

设计理念：声明式配置

传统配置需要为每个类手写 __init__ 方法。BaseConfig 采用递归实例化机制：子类只需以嵌套 class 方式声明参数，__init__ 自动将所有类类型属性转换为实例对象。

class MyCfg(BaseConfig):
class env:
num_envs = 4096
class control:
class stiffness:
joint_a = 10.0

cfg = MyCfg() # 自动得到 cfg.env.num_envs, cfg.control.stiffness.joint_a

核心算法：递归实例化

def init_member_classes(obj):
for key in dir(obj):
if key == "__class__": continue
var = getattr(obj, key)
if inspect.isclass(var):
i_var = var() # 实例化
setattr(obj, key, i_var)
init_member_classes(i_var) # 递归处理嵌套

3.2 任务基类（base_task.py）

BaseTask 封装 Isaac Gym 仿真的核心生命周期：

子类必须实现的抽象接口：

• reset_idx(env_ids)：重置指定环境
• step(actions)：执行一步仿真并返回 (obs, privileged_obs, reward, done, info)

3.3 足式机器人核心环境（legged_robot.py）

这是项目最核心、代码量最大的文件（约 600 行），包含完整的仿真-训练循环。

3.3.1 仿真步进流程

策略网络输出 actions
↓
[step()] 动作裁剪到 [-clip_actions, clip_actions]
↓
循环 decimation 次（默认 4 次）：
├─ _compute_torques(actions) → PD 控制器计算关节力矩
├─ gym.set_dof_actuation_force_tensor() → 施加力矩
├─ gym.simulate() → 推进物理仿真一步
└─ gym.refresh_dof_state_tensor() → 刷新关节状态
↓
[post_physics_step()] 后处理：
├─ 刷新根状态和接触力张量
├─ 提取基座位置/姿态/速度（世界坐标→机体坐标）
├─ 计算重力投影向量（用于姿态感知）
├─ 检测终止条件（碰撞/倾覆/超时）
├─ 计算奖励
├─ 重置已终止环境
├─ 域随机化：随机推力
└─ 构建观测向量

3.3.2 PD 控制器

支持三种控制模式：

P 模式（位置控制，默认）：

$$\tau =K_p\cdot ({\theta }_{target}-\theta )-K_d\cdot \dot{\theta }$$

其中：

• ${\theta }_{target}=\text{action\_scale}\cdot a+{\theta }_{default}$
• $K_p$：刚度（stiffness）
• $K_d$：阻尼（damping）

V 模式（速度控制）：

$$\tau =K_p\cdot ({\dot{\theta }}_{target}-\dot{\theta })-K_d\cdot \frac{\Delta \dot{\theta }}{\Delta t}$$

T 模式（力矩控制）：

$$\tau =\text{action\_scale}\cdot a$$

最终力矩裁剪到关节力矩限制范围内：

$$\tau =\text{clip}(\tau ,-{\tau }_{limit},{\tau }_{limit})$$

3.3.3 观测空间构建

默认观测向量（以 GO2 为例，48 维）：

$$o=\left[\frac{v_{body}}{s_v},\frac{{\omega }_{body}}{s_{\omega }},g_{proj},\frac{c}{s_c},\frac{(q-q_{default})}{s_q},\frac{\dot{q}}{s_{\dot{q}}},a_{prev}\right]$$

其中：

• $v_{body}\in {\mathbb{R}}^3$：机体坐标系线速度
• ${\omega }_{body}\in {\mathbb{R}}^3$：机体坐标系角速度
• $g_{proj}\in {\mathbb{R}}^3$：重力向量在机体坐标系的投影
• $c\in {\mathbb{R}}^3$：速度指令（x 线速度, y 线速度, yaw 角速度）
• $q\in {\mathbb{R}}^{N_{dof}}$：关节位置
• $\dot{q}\in {\mathbb{R}}^{N_{dof}}$：关节速度
• $a_{prev}\in {\mathbb{R}}^{N_{act}}$：上一步动作
• $s$ 为各维度的观测缩放系数

若启用噪声：

$$o_{noisy}=o+(2\cdot U(0,1)-1)\odot \sigma$$

其中 $U(0,1)$ 为均匀分布，$\sigma$ 为噪声缩放向量，$\odot$ 为逐元素乘法。

非对称观测（G1/H1/H1_2）：

• Actor 观测：不含线速度 $v_{body}$（部署时无法直接测量）
• Critic 特权观测：包含线速度 $v_{body}$，用于更准确地估计价值函数

3.3.4 终止条件

环境在以下任一条件满足时终止：

超时终止与碰撞终止的区别：

• 碰撞终止：机器人倒地，给予负奖励（惩罚）
• 超时终止：正常完成回合，不给予终止惩罚

3.4 奖励工程详解

奖励设计是足式机器人 RL 训练的核心。本项目采用多目标加权奖励体系，共 17 个奖励/惩罚项。

3.4.1 速度跟踪奖励（高斯核）

线速度跟踪：

$$r_{lin}=\exp \left(-\frac{\Vert c_{xy}-v_{xy}{\Vert }^2}{{\sigma }^2}\right)$$

角速度跟踪：

$$r_{ang}=\exp \left(-\frac{(c_{yaw}-{\omega }_z{)}^2}{{\sigma }^2}\right)$$

其中 $\sigma =0.25$ 为高斯核宽度。误差越小，奖励越接近 1；误差越大，奖励趋近 0。

3.4.2 姿态与运动惩罚

3.4.3 关节相关惩罚

3.4.4 接触与步态奖励

足部腾空时间奖励：

$$r_{air}=\sum _{i\in feet}(t_{air,i}-0.5)\cdot 1[first\_contac{t}_i]\cdot 1[\Vert c_{xy}\Vert >0.1]$$

其中：

• $t_{air,i}$：第 $i$ 只脚的腾空时间
• 仅在首次触地时计算奖励
• 零指令时不奖励（避免原地踏步获得奖励）

碰撞惩罚：

$$r_{collision}=-\sum _{j\in penalized}1[\Vert f_{contact,j}\Vert >0.1]$$

终止惩罚：

$$r_{term}=1[reset]\cdot 1[\neg timeout]$$

仅对非超时的终止（即碰撞倒地）施加惩罚。

3.4.5 软限制惩罚

为防止关节到达物理硬极限，引入软限制：

$$q_{soft,lower}=m-0.5\cdot r\cdot \alpha$$

$$q_{soft,upper}=m+0.5\cdot r\cdot \alpha$$

其中 $m$ 为限制中点，$r$ 为限制范围，$\alpha \in [0,1]$ 为软限制系数（默认 0.9）。

当关节超出软限制时：

$$r_{pos\_limit}=-\sum _i\left[(q_i-q_{soft,lower}{)}_{-}+(q_i-q_{soft,upper}{)}_{+}\right]$$

其中 $(x{)}_{-}=\min (x,0)$，$(x{)}_{+}=\max (x,0)$。

3.4.6 奖励裁剪策略

若启用 only_positive_rewards：

$$r_{total}=\max \left(\sum _i{w}_i\cdot r_i,0\right)+w_{term}\cdot r_{term}$$

终止奖励在正奖励裁剪后单独添加，确保终止惩罚始终生效。

3.5 域随机化（Domain Randomization）

域随机化通过在训练时随机化物理参数，使策略对参数不确定性具有鲁棒性。

3.5.1 摩擦力随机化

预生成 64 个摩擦系数桶：

$${\mu }_k\sim U({\mu }_{min},{\mu }_{max}),k=1,\dots ,64$$

每个环境随机分配一个桶：

$${\mu }_{env}={\mu }_{bucket[randint(0,63)]}$$

3.5.2 基座质量随机化

$$m_{base}=m_{base,original}+\Delta m,\Delta m\sim U(-1,3)\text{kg}$$

3.5.3 随机推力扰动

按固定间隔（默认 15 秒）为所有环境设置随机的基座水平速度：

$$v_{push}\sim U(-v_{max},v_{max}),v_{max}=1.0\text{m/s}$$

3.6 步态相位控制（G1/H1/H1_2）

双足机器人需要显式的步态相位控制以实现交替行走。

3.6.1 相位计算

设步态周期 $T=0.8\text{s}$，则当前相位：

$$\varphi =\frac{(t\cdot \Delta t)\mathrm{mod}T}{T}\in [0,1)$$

左右脚相位偏移 0.5（半周期，交替步态）：

$${\varphi }_{left}=\varphi$$

$${\varphi }_{right}=(\varphi +0.5)\mathrm{mod}1$$

3.6.2 相位编码

将相位以 sin/cos 编码注入观测：

$$o_{phase}=[\sin (2\pi \varphi ),\cos (2\pi \varphi )]$$

这种连续编码比原始相位值更利于神经网络学习周期性模式。

3.6.3 接触一致性奖励

检查每只脚的接触状态是否与步态相位一致：

$$is\_stance={\varphi }_{leg}<0.55$$

$$contact=f_{z,foot}>1\text{N}$$

$$consistent=\neg (contact\oplus is\_stance)$$

其中 $\oplus$ 为异或（XOR），$\neg$ 为取反。stance 阶段应接触，swing 阶段应离地。

四、PPO 算法解析

本项目使用 rsl_rl 库实现的 PPO 算法进行策略训练。

4.1 PPO 核心思想

PPO 通过**裁剪替代目标（Clipped Surrogate Objective）**限制策略更新幅度，避免传统策略梯度方法中步长过大导致策略崩溃的问题。

4.2 关键公式

4.2.1 策略目标

$$L^{CLIP}(\theta )={\hat{\mathbb{E}}}_t\left[\min \left(r_t(\theta ){\hat{A}}_t,\text{clip}(r_t(\theta ),1-ϵ,1+ϵ){\hat{A}}_t\right)\right]$$

其中：

• $r_t(\theta )=\frac{{\pi }_{\theta }(a_t|s_t)}{{\pi }_{{\theta }_{old}}(a_t|s_t)}$：概率比
• ${\hat{A}}_t$：广义优势估计（GAE）
• $ϵ=0.2$：裁剪参数

4.2.2 广义优势估计（GAE）

$${\hat{A}}_t^{GAE(\gamma ,\lambda )}=\sum _{l=0}^{\infty }(\gamma \lambda {)}^l{\delta }_{t+l}^V$$

其中：

$${\delta }_t^V=r_t+\gamma V(s_{t+1})-V(s_t)$$

• $\gamma =0.99$：折扣因子
• $\lambda =0.95$：GAE 参数

4.2.3 价值函数损失

$$L^{VF}(\theta )={\hat{\mathbb{E}}}_t\left[(V_{\theta }(s_t)-V_t^{target}{)}^2\right]$$

若启用裁剪价值损失：

$$L^{VF,clip}(\theta )={\hat{\mathbb{E}}}_t\left[\max \left((V_{\theta }-V^{target}{)}^2,(V_{{\theta }_{old}}+\text{clip}(V_{\theta }-V_{{\theta }_{old}},-ϵ,ϵ)-V^{target}{)}^2\right)\right]$$

4.2.4 总损失

$$L^{TOTAL}(\theta )=-L^{CLIP}(\theta )+c_1{L}^{VF}(\theta )-c_2\cdot \text{Entropy}({\pi }_{\theta })$$

其中：

• $c_1=1.0$：价值损失系数
• $c_2=0.01$：熵正则化系数

4.2.5 自适应学习率

若学习率调度为 adaptive：

• 当 KL 散度 $<0.5\times target\_KL$ 时：学习率 $\times 1.5$
• 当 KL 散度 $>1.5\times target\_KL$ 时：学习率 $\times 0.5$
• 目标 KL 散度：$0.01$

4.3 网络架构

4.3.1 标准 Actor-Critic（GO2）

Actor:
Input: obs (48-dim)
→ Linear(48, 512) + ELU
→ Linear(512, 256) + ELU
→ Linear(256, 128) + ELU
→ Linear(128, 12) # 输出动作均值
→ 可学习噪声标准差

Critic:
Input: privileged_obs (48-dim)
→ Linear(48, 512) + ELU
→ Linear(512, 256) + ELU
→ Linear(256, 128) + ELU
→ Linear(128, 1) # 输出状态价值

4.3.2 LSTM Actor-Critic（G1/H1/H1_2）

Actor:
Input: obs (47-dim or 41-dim)
→ Linear(input_dim, 32) + ELU
→ LSTM(32, 64, num_layers=1)
→ Linear(64, num_actions)

Critic:
Input: privileged_obs (50-dim or 44-dim)
→ Linear(input_dim, 32) + ELU
→ LSTM(32, 64, num_layers=1)
→ Linear(64, 1)

LSTM 隐状态在每个回合开始时重置为零。

五、关键文件技术说明

5.1 配置体系（legged_robot_config.py）

配置采用分层嵌套结构，12 个子配置类覆盖全部参数：

5.2 任务注册表（task_registry.py）

采用注册表模式解耦任务定义与使用：

# 注册（envs/__init__.py）
task_registry.register("go2", LeggedRobot, GO2RoughCfg(), GO2RoughCfgPPO())

# 使用（scripts/train.py）
env, env_cfg = task_registry.make_env(name=args.task, args=args)
runner, train_cfg = task_registry.make_alg_runner(env=env, name=args.task, args=args)

5.3 程序化地形（terrain.py）

地形生成支持三种模式：

7 种地形类型及难度参数化：

六、技术架构设计

6.1 类继承关系

BaseConfig
└── LeggedRobotCfg
├── GO2RoughCfg
├── H1RoughCfg
├── H1_2RoughCfg
└── G1RoughCfg

BaseConfig
└── LeggedRobotCfgPPO
├── GO2RoughCfgPPO
├── H1RoughCfgPPO
├── H1_2RoughCfgPPO
└── G1RoughCfgPPO

BaseTask
└── LeggedRobot
├── (GO2 直接使用 LeggedRobot)
├── H1Robot
├── H1_2Robot
└── G1Robot

6.2 训练数据流

┌─────────────┐ actions ┌──────────────┐ torques ┌──────────────┐
│ PPO 算法 │ ──────────────→ │ LeggedRobot │ ──────────────→ │ Isaac Gym │
│ (rsl_rl) │ │ _compute_ │ │ 物理仿真 │
│ │ ←────────────── │ torques() │ ←────────────── │ │
│ │ obs, rew, done │ step() │ 状态更新 │ │
└─────────────┘ └──────────────┘ └──────────────┘
↑ ↑
│ │
策略网络更新 奖励计算/终止检测/域随机化

6.3 控制频率链

仿真频率: 1/dt (默认 200Hz, H1_2 为 400Hz)
│
│ ÷ decimation (默认 4, H1_2 为 8)
↓
策略频率: 50Hz (所有机器人统一)

6.4 观测空间对比

七、使用方法及示例代码

7.1 环境依赖

# 基础依赖
pip install torch>=1.10 numpy scipy

# Isaac Gym (需从 NVIDIA 官网下载)
# https://developer.nvidia.com/isaac-gym

# rsl_rl (强化学习算法库)
pip install git+https://github.com/leggedrobotics/rsl_rl.git

7.2 训练

# 训练 GO2 四足机器人
python legged_gym/scripts/train.py –task go2

# 训练 G1 双足机器人
python legged_gym/scripts/train.py –task g1

# 无头模式训练（服务器环境）
python legged_gym/scripts/train.py –task h1 –headless

# 指定随机种子
python legged_gym/scripts/train.py –task go2 –seed 42

# 指定最大迭代次数
python legged_gym/scripts/train.py –task g1 –max_iterations 5000

7.3 推理与测试

# 测试 GO2
python legged_gym/scripts/play.py –task go2

# 指定运行名称加载模型
python legged_gym/scripts/play.py –task h1_2 –load_run <run_name>

# 指定检查点编号
python legged_gym/scripts/play.py –task g1 –load_run <run_name> –checkpoint 1000

7.4 自定义机器人配置示例

from legged_gym.envs.base.legged_robot_config import LeggedRobotCfg

class MyRobotCfg(LeggedRobotCfg):
class env(LeggedRobotCfg.env):
num_envs = 2048
num_observations = 48
num_actions = 12

class control(LeggedRobotCfg.control):
control_type = 'P'
stiffness = {'joint': 50.}
damping = {'joint': 2.}
action_scale = 0.25
decimation = 4

class asset(LeggedRobotCfg.asset):
file = '{LEGGED_GYM_ROOT_DIR}/resources/robots/my_robot/robot.urdf'
name = "my_robot"
foot_name = "foot"

class rewards(LeggedRobotCfg.rewards):
class scales(LeggedRobotCfg.rewards.scales):
tracking_lin_vel = 2.0 # 增大线速度跟踪权重
torques = –0.0005 # 调整力矩惩罚

7.5 自定义奖励函数示例

from legged_gym.envs.base.legged_robot import LeggedRobot

class MyRobot(LeggedRobot):
def _reward_custom(self):
"""自定义奖励：惩罚基座前后晃动"""
return torch.abs(self.base_ang_vel[:, 1]) # pitch 角速度绝对值

然后在配置中添加权重：

class MyRobotCfg(LeggedRobotCfg):
class rewards(LeggedRobotCfg.rewards):
class scales(LeggedRobotCfg.rewards.scales):
custom = –0.1

八、数学工具详解

8.1 四元数到欧拉角（ZYX 内旋）

给定四元数 $q=[q_x,q_y,q_z,q_w]$：

Roll（X 轴旋转）：

$$\varphi =\arctan 2(2(q_w{q}_x+q_y{q}_z),q_w^2-q_x^2-q_y^2+q_z^2)$$

Pitch（Y 轴旋转）：

$$\theta =\arcsin (\text{clip}(2(q_w{q}_y-q_z{q}_x),-1,1))$$

Yaw（Z 轴旋转）：

$$\psi =\arctan 2(2(q_w{q}_z+q_x{q}_y),q_w^2+q_x^2-q_y^2-q_z^2)$$

8.2 仅偏航旋转的四元数变换

将四元数的 roll 和 pitch 分量置零，只保留 yaw：

$$q_{yaw}=\text{normalize}([0,0,q_z,q_w])$$

然后对向量施加旋转：

$$v^{\prime }=q_{yaw}\otimes v\otimes q_{yaw}^{\ast }$$

8.3 角度归一化到 $[-\pi ,\pi ]$

$${\theta }_{norm}=((\theta \mathrm{mod}2\pi )+2\pi )\mathrm{mod}2\pi$$

$${\theta }_{norm}=\{\begin{array}{ll}{\theta }_{norm}-2\pi & \text{if }{\theta }_{norm}>\pi \\ {\theta }_{norm}& \text{otherwise}\end{array}$$

8.4 平方根分布随机数

生成概率密度向中间集中的随机数：

$$r=\text{sign}(u)\cdot \sqrt{|u|},u\sim U(-1,1)$$

$$r_{norm}=\frac{r+1}{2}\in [0,1]$$

$$x=(upper-lower)\cdot r_{norm}+lower$$

相比均匀分布，减少了极端值的出现概率。

九、各文件功能详解与注释意义

9.1 包初始化模块

__init__.py（legged_gym/）

envs/__init__.py

9.2 基类模块（envs/base/）

base_config.py

关键方法：

• init_member_classes(obj): 遍历对象属性，将类类型属性替换为实例，递归处理嵌套

base_task.py

关键方法：

• __init__(): 解析设备、分配缓冲区、创建仿真、注册键盘事件
• step(): 抽象方法，子类实现一步仿真
• reset(): 重置所有环境并返回初始观测
• render(): 渲染当前帧，处理 ESC/V 键盘事件

legged_robot.py

核心功能模块：

奖励函数体系：

legged_robot_config.py

配置子类一览：

9.3 机器人特定模块

g1/g1_config.py + g1/g1_env.py

G1 特有奖励函数：

go2/go2_config.py

h1/h1_config.py + h1/h1_env.py

h1_2/h1_2_config.py + h1_2/h1_2_env.py

9.4 脚本模块（scripts/）

train.py

play.py

9.5 工具模块（utils/）

helpers.py

关键函数：

isaacgym_utils.py

logger.py

math.py

task_registry.py

核心方法：

• register(): 注册任务（名称→环境类+配置）
• make_env(): 创建仿真环境（解析参数→设置种子→创建实例）
• make_alg_runner(): 创建PPO运行器（设置日志→创建运行器→可选恢复）

terrain.py

地形类型：

十、快速上手

训练

# 训练 GO2 四足机器人
python legged_gym/scripts/train.py –task go2

# 训练 G1 双足机器人
python legged_gym/scripts/train.py –task g1

# 无头模式训练
python legged_gym/scripts/train.py –task h1 –headless

测试

# 测试 GO2
python legged_gym/scripts/play.py –task go2

# 指定运行名称测试
python legged_gym/scripts/play.py –task h1_2 –load_run <run_name>

依赖

• Isaac Gym (Preview)
• PyTorch ≥ 1.10
• rsl_rl (强化学习算法库)
• numpy, scipy