机器人仿真入门：使用 Isaac Lab 训练 Cartpole 平衡机器人

在 Isaac Lab 中构建强化学习任务，核心在于理解环境是如何被注册、配置如何生效以及训练脚本如何串联起环境与算法。本文顺着从注册到训练的一条线，把 Cartpole 项目里的代码逻辑讲清楚。

任务启动流程

当我们输入指令时：

python scripts/rsl_rl/train.py --task Template-Cartpole-v0 --num_envs 4096

该指令会执行训练 Cartpole 任务（Template-Cartpole-v0），同时调用 4096 个并行环境做 PPO 训练。背后大致是这几步：

启动 Isaac Sim
解析命令行参数
根据任务名找到「环境配置」和「算法配置」（Cartpole 的 MDP 和 PPO 超参）
用这份配置创建 Gym 环境（多个 Cartpole 并行仿真）
用 RSL-RL 的 PPO Runner 收集数据、更新策略，循环直到达到迭代数

一、任务识别与 Gym 注册

文件路径： source/Cartpole/Cartpole/tasks/manager_based/cartpole/__init__.py

import gymnasium as gym
from . import agents

gym.register(
    id="Template-Cartpole-v0",
    entry_point="isaaclab.envs:ManagerBasedRLEnv",
    disable_env_checker=True,
    kwargs={
        "env_cfg_entry_point": f"{__name__}.cartpole_env_cfg:CartpoleEnvCfg",
        "rsl_rl_cfg_entry_point": f"{agents.__name__}.rsl_rl_ppo_cfg:PPORunnerCfg",
    },
)

这里的关键点在于 gym.register 把名字、通用环境类、以及「环境配置」和「PPO 配置」两个类的路径绑在一起。

id：就是环境的名字。Gym 通过 id 定位环境。
entry_point：一个字符串，像门牌号一样指向「用哪个模块里的哪个类」。
kwargs：
- env_cfg_entry_point：告诉程序「环境长什么样、奖励怎么算、什么时候结束」的配置类 CartpoleEnvCfg 在哪个文件里，程序会按这个路径去 import。
- rsl_rl_cfg_entry_point：告诉程序「PPO 用多大网络、学多少轮」的配置类 PPORunnerCfg 在哪个文件里，同样按路径 import。

二、环境配置 CartpoleEnvCfg

当调用 gym.make("Template-Cartpole-v0", cfg=env_cfg) 时，Isaac Lab 会按 env_cfg_entry_point 拿到 CartpoleEnvCfg。这个类就是「Cartpole 长什么样、怎么交互、怎么给奖励、什么时候结束」的一张总表。

它的逻辑结构大致如下：

CartpoleEnvCfg
├── scene: CartpoleSceneCfg          # 场景里有什么
├── observations: ObservationsCfg     # 智能体看到什么
├── actions: ActionsCfg               # 智能体能做什么
├── events: EventCfg                  # 重置时怎么随机化
├── rewards: RewardsCfg               # 每一步怎么给奖励
├── terminations: TerminationsCfg     # 什么时候算结束
└── __post_init__                     # 仿真步长、回合长度、视角等

scene：地面、Cartpole 机器人（每个环境一个）、灯光。机器人用的是 Isaac Lab Assets 里现成的 CARTPOLE_CFG，只是把 prim_path 换成带环境命名空间的，这样 4096 个环境就有 4096 个互不干扰的 Cartpole。
actions：当前只有一项——对「小车关节」slider_to_cart 施加力矩，scale 100，即动作 [-1,1] 映射到 ±100 的力。
observations：两项——关节位置、关节速度（都来自 mdp 里的通用函数），拼成一个向量给策略网络。
events：重置时给小车的位姿/速度、杆的角/角速度一个随机范围，让每局起始状态有变化。
rewards：下面单独说。
terminations：一是超时（例如 5 秒），二是小车跑出 [-3, 3] 就提前结束。

所以：配置类本身不「算」任何东西，它只是声明「用哪个函数、绑哪几个关节、权重多少」。真正在仿真里被调用的，是这些函数——它们多数来自 Isaac Lab 的 MDP 库，Cartpole 只自定义了一个奖励。

三、动作配置与关节力矩

Cartpole 的「动」完全由动作空间决定：策略网络输出一个标量，被转换成对小车滑轨关节的力矩，物理引擎再根据力矩更新小车和杆的状态。

动作配置在 cartpole_env_cfg.py 里只有一段：

@configclass
class ActionsCfg:
    """Action specifications for the MDP."""
    joint_effort = mdp.JointEffortActionCfg(
        asset_name="robot",
        joint_names=["slider_to_cart"],
        scale=100.0,
    )

asset_name="robot"：作用对象是场景里的 robot（Cartpole 机器人）。
joint_names=["slider_to_cart"]：只控制「小车相对世界」的那一个关节（滑轨），杆的转动由物理仿真自然产生，不直接给力矩。
scale=100.0：策略输出在 [-1, 1]，会先乘 100 再当力矩（单位 N）送给关节，所以实际施加的是 ±100 的力。

数据流：policy(obs) → 一个 float 在 [-1,1] → 乘 100 → 作为 slider_to_cart 的关节力矩 → 物理仿真一步 → 小车左右移动、杆摆动。所以「机器人怎么动」就是：策略决定向左/向右推小车的力有多大，物理引擎负责把力变成位置和速度。

四、如何计算奖励

在 RewardsCfg 里你会看到五类奖励项，例如：

alive = RewTerm(func=mdp.is_alive, weight=1.0)
terminating = RewTerm(func=mdp.is_terminated, weight=-2.0)
pole_pos = RewTerm(func=mdp.joint_pos_target_l2, weight=-1.0, params={...})
cart_vel = RewTerm(func=mdp.joint_vel_l1,...)
pole_vel = RewTerm(func=mdp.joint_vel_l1,...)

alive：只要没因「失败条件」结束，就给 1.0，鼓励尽量别提前挂。
terminating：若是因失败结束（例如小车出界），给 -2.0。
pole_pos：希望杆保持竖直，所以用「关节角度相对 0 的偏差」当惩罚，这是 Cartpole 唯一自定义的奖励函数，在 mdp/rewards.py 里：

def joint_pos_target_l2(env, target, asset_cfg):
    asset = env.scene[asset_cfg.name]
    joint_pos = wrap_to_pi(asset.data.joint_pos[:, asset_cfg.joint_ids])
    return torch.sum(torch.square(joint_pos - target), dim=1)

这里取的是「杆关节」相对竖直 (0) 的角度的平方和，每个环境一个标量；配置里 target=0.0，所以杆越竖、这项越小（惩罚越小）。

cart_vel / pole_vel：用 Isaac Lab 自带的 joint_vel_l1，给「小车速度」和「杆角速度」一点小惩罚，鼓励平稳。

ManagerBasedRLEnv 会按配置调用这些函数，得到每个环境的标量，再乘 weight 加起来，得到这一步的总奖励。

五、PPO 配置：网络与超参

训练时用的算法是 RSL-RL 里的 PPO，超参和网络结构都在 agents/rsl_rl_ppo_cfg.py 的 PPORunnerCfg 里，在这里可以修改学习行为。

@configclass
class PPORunnerCfg(RslRlOnPolicyRunnerCfg):
    num_steps_per_env = 16  # 每个环境每次收集 16 步再更新
    max_iterations = 150    # 训练总迭代次数（可被 --max_iterations 覆盖）
    save_interval = 50      # 每 50 次迭代存一次 checkpoint
    experiment_name = "cartpole_direct"
    
    policy = RslRlPpoActorCriticCfg(
        init_noise_std=1.0,           # 策略初始探索噪声
        actor_obs_normalization=False,
        critic_obs_normalization=False,
        actor_hidden_dims=[32, 32],   # Actor 两层、每层 32 维
        critic_hidden_dims=[32, 32],  # Critic 两层、每层 32 维
        activation="elu",
    )
    
    algorithm = RslRlPpoAlgorithmCfg(
        value_loss_coef=1.0,
        use_clipped_value_loss=True,
        clip_param=0.2,                 # PPO 的 clip 范围
        entropy_coef=0.005,
        num_learning_epochs=5,          # 每次收集数据后更新 5 轮
        num_mini_batches=4,
        learning_rate=1.0e-3,
        schedule="adaptive",
        gamma=0.99,
        lam=0.95,
        desired_kl=0.01,
        max_grad_norm=1.0,
    )

和机器人/环境的关系：
- actor_hidden_dims 决定「观测 → 动作」的 MLP 有多大；观测维度由上面的 ObservationsCfg（关节位置 + 关节速度）决定，动作维度由 ActionsCfg（一个关节力矩）决定。
- gamma / lam 影响回报和优势估计，从而影响策略更关注短期还是长期奖励。
- 所以：机器人怎么动看 ActionsCfg，奖励怎么算看 RewardsCfg，学多猛、网络多大看这个 PPORunnerCfg。

六、训练脚本

scripts/rsl_rl/train.py 核心就三件事：先启动 App、再按任务名拿到两份配置、最后建环境 + Runner 并调 learn()。

1. 先启动 App，再解析参数

Isaac Lab 要求在 import 任何 isaaclab/isaacsim 仿真相关模块之前，必须先启动 App，然后解析 --task、--num_envs、--max_iterations 等，把 sys.argv 精简给 Hydra 用，再启动 Isaac Sim。

from isaaclab.app import AppLauncher
import cli_args
import argparse

parser = argparse.ArgumentParser(...)
parser.add_argument("--num_envs", ...)
parser.add_argument("--task", ...)
parser.add_argument("--max_iterations", ...)
cli_args.add_rsl_rl_args(parser)
AppLauncher.add_app_launcher_args(parser)
args_cli, hydra_args = parser.parse_known_args()
sys.argv = [sys.argv[0]] + hydra_args  # 只留 Hydra 需要的
app_launcher = AppLauncher(args_cli)
simulation_app = app_launcher.app

2. Hydra 按任务名注入 env_cfg / agent_cfg

@hydra_task_config(args_cli.task, args_cli.agent) 会根据你传的 --task、--agent，从注册表里找到两个 entry point，动态加载 CartpoleEnvCfg 和 PPORunnerCfg，并注入到 main 的参数里。

import Cartpole.tasks  # 执行后 Gym 里才有 Template-Cartpole-v0

@hydra_task_config(args_cli.task, args_cli.agent)
def main(env_cfg: ManagerBasedRLEnvCfg | ..., agent_cfg: RslRlBaseRunnerCfg):
    # main 里拿到的就是 cartpole_env_cfg.py 和 rsl_rl_ppo_cfg.py 里的那两份配置
    pass

3. main 里：建环境 → 包一层 → 建 Runner → learn()

main 里先用命令行覆盖 num_envs、max_iterations、seed、device 等，建好日志目录；然后建环境、包成 RSL-RL 接口、建 Runner、开训。

def main(env_cfg, agent_cfg):
    # 命令行覆盖 num_envs / max_iterations / seed / device 等，建 log_dir（略）
    env = gym.make(args_cli.task, cfg=env_cfg, ...)  # 配置在此生效：场景+MDP 都来自 env_cfg
    env = RslRlVecEnvWrapper(env, clip_actions=agent_cfg.clip_actions)
    runner = OnPolicyRunner(env, agent_cfg.to_dict(), log_dir=log_dir, device=agent_cfg.device)
    # 可选：runner.load(resume_path)、dump_yaml(env.yaml / agent.yaml)
    runner.learn(num_learning_iterations=agent_cfg.max_iterations, init_at_random_ep_len=True)
    env.close()

if __name__ == "__main__":
    main()
    simulation_app.close()

gym.make(…, cfg=env_cfg)：按 CartpoleEnvCfg 建场景和 MDP（动作/观测/奖励/终止都在这里生效）。
RslRlVecEnvWrapper：把 Isaac Lab 的向量化环境接口适配成 RSL-RL 的 step/obs 格式。
OnPolicyRunner：按 agent_cfg 建 Actor/Critic 和 PPO；runner.learn() 里才是「多环境 step 收集轨迹 → 算 returns/advantages → PPO 更新」的循环。

工作流总结

修改配置 (CartpoleEnvCfg / PPORunnerCfg)
↓
gym.make("Template-Cartpole-v0", cfg=env_cfg) → 建场景 (地面 + 4096 个 Cartpole)
→ 挂 MDP：动作=关节力矩，观测=关节位置 + 速度，奖励=alive+terminating+pole_pos+cart_vel+pole_vel，终止=超时/出界
↓
env.step(actions) → 物理仿真一步 → 调用你配置的观测函数 → obs
→ 调用你配置的奖励函数 → reward
→ 调用你配置的终止函数 → done
↓
OnPolicyRunner 用 obs 跑 policy 得到 actions，再 env.step(actions)，收集整段轨迹
→ 算 returns / advantages → PPO 更新 Actor、Critic → 下一个 iteration

代码是怎么 work 的通过 Gym 注册把你的任务名和两份配置（环境 + 算法）绑在一起；再用这份环境配置去建 ManagerBasedRLEnv，让「场景 + MDP」都按配置里的函数和参数跑；训练脚本只负责解析参数、建环境、建 Runner、调 runner.learn()。你要改行为，就改配置或配置所引用的 MDP 函数（例如 rewards.py）即可。

工作流程示意图