机器人仿真: 训练自己第一个平衡机器人Cartpole

小编2026 Spring 开启一段关于Robotics的学习，本文记录了在 Windows 系统上训练自己第一个机器人的过程。

---

Cartpole 代码是如何工作的

用 Isaac Lab 做强化学习时，一个任务是怎么被「注册」的？配置里的奖励、终止、观测到底在哪生效？训练脚本又是怎么把环境和 PPO 串起来的？这篇博客顺着「从注册到训练」的一条线，把 Cartpole 项目里的代码是怎么 work 的讲清楚。

---

当我们输入指令：

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

该指令会执行训练 Cartpole 任务（Template-Cartpole-v0），同时调用 4096 个并行环境 做 PPO 训练

背后大致是这几步：

1. 启动 Isaac Sim
2. 解析命令行
3. 根据任务名找到「环境配置」和「算法配置」（Cartpole 的 MDP 和 PPO 超参）
4. 用这份配置创建 Gym 环境（多个 Cartpole 并行仿真）
5. 用 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",
    },
)

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

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

---

二、环境配置 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

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 里的那两份配置

---

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）即可。

---