本文档面向首次接触 RSL-RL 的开发者，目标是在本地环境中完成安装、理解项目骨架，并跑通一个最小化的训练闭环。阅读完成后，你将掌握从 pip install 到调用 runner.learn() 的完整路径，并清楚下一步该深入哪个模块。

Sources: pyproject.toml, README.md

环境准备与安装

RSL-RL 要求 Python 版本不低于 3.9，核心计算依赖 PyTorch 2.6 以上，同时使用 tensordict 作为结构化张量容器。下表列出了硬性系统要求与关键依赖版本。

Sources: pyproject.toml

安装方式

目前支持两种等价的安装路径：通过 PyPI 直接安装稳定版，或克隆源码后本地可编辑安装。后者适合需要修改框架源码、调试算法或提交贡献的场景。

执行完安装命令后，可在 Python 解释器中验证：import rsl_rl 无报错即表示安装成功。

Sources: README.md

项目结构概览

RSL-RL 的代码组织遵循“算法—网络—存储—运行器”四层分离原则。初学者无需一次性理解所有子包，但建立顶层地图有助于快速定位问题。

rsl_rl/
├── algorithms/          # 学习算法：PPO、AMP、Distillation
├── modules/             # 策略网络：ActorCritic 及其变体（CNN、RNN、Attention）
├── networks/            # 基础网络单元：MLP、CNN、Memory、Normalization
├── runners/             # 训练主循环：环境交互 + 策略更新
├── storage/             # 数据缓冲区：RolloutStorage、CircularBuffer
├── env/                 # 环境抽象接口
└── utils/               # 日志、监控、工具函数

下图展示了各模块在单次训练迭代中的协作关系。环境产生观测，Runner 调度算法收集经验，存储模块缓存轨迹，最后由算法模块执行梯度更新。

graph LR
    A[VecEnv<br/>向量化环境] -->|get_observations / step| B[Runner<br/>训练运行器]
    B -->|act / process_env_step| C[Algorithm<br/>PPO / AMP / Distillation]
    C -->|读写| D[Storage<br/>RolloutStorage]
    C -->|前向/反向| E[Modules<br/>ActorCritic]
    B -->|记录指标| F[Utils/Logger<br/>TensorBoard / W&B]

Sources: runners/init.py, algorithms/init.py, modules/init.py

最小训练示例

一条可运行的训练流水线只需要三步：准备向量化环境、读取配置构造 Runner、调用 learn() 进入主循环。下图展示了从配置到模型保存的完整动作序列。

flowchart TD
    Start([开始]) --> A[创建 VecEnv 实例]
    A --> B[加载 YAML 配置]
    B --> C[实例化 OnPolicyRunner]
    C --> D{分布式?}
    D -->|是| E[初始化 torch.distributed]
    D -->|否| F[构造 ActorCritic + PPO]
    E --> F
    F --> G[调用 runner.learn<br/>num_learning_iterations]
    G --> H{每 save_interval 迭代}
    H -->|是| I[保存 model_{it}.pt]
    H -->|否| J[继续训练]
    I --> J
    J -->|达到最大迭代| K[保存最终模型]
    K --> End([结束])

最小代码骨架如下。其中 MyVecEnv 是你需要自行实现的向量化环境类，必须继承 rsl_rl.env.VecEnv 并实现 get_observations() 与 step() 两个抽象方法。

import yaml
from rsl_rl.runners import OnPolicyRunner
from my_env import MyVecEnv  # 用户自定义环境

# 1. 加载配置
with open("config.yaml") as f:
    train_cfg = yaml.safe_load(f)["runner"]

# 2. 创建环境
env = MyVecEnv(cfg=env_cfg, num_envs=4096, device="cuda:0")

# 3. 构造运行器
runner = OnPolicyRunner(env, train_cfg, log_dir="./logs", device="cuda:0")

# 4. 开始训练
runner.learn(num_learning_iterations=1500, init_at_random_ep_len=True)

# 5. 保存与加载
runner.save("./model_1500.pt")
runner.load("./model_1500.pt")

Sources: runners/on_policy_runner.py, env/vec_env.py

环境接口契约

VecEnv 是框架与环境之间的唯一契约层。你的环境需要提供以下成员与行为：

Sources: env/vec_env.py

Runner 类型选择

RSL-RL 目前内置三种运行器，分别对应标准 on-policy 强化学习、对抗动作先验（AMP）以及策略蒸馏场景。初学者通常从 OnPolicyRunner 入手。

Sources: runners/init.py, runners/amp_runner.py, runners/distillation_runner.py

配置文件入门

框架采用 YAML 嵌套字典描述训练超参数，顶层通常分为 runner、policy、algorithm 三大块。下面列出对初学者最关键的配置键。

完整配置模板请参考仓库根目录下的 config/example_config.yaml。该文件同时展示了 RND 探索奖励与对称性增强的可选配置，初始权重设为 0.0 或 false 时即关闭对应功能，不会影响基础训练流程。

Sources: config/example_config.yaml

模型保存、加载与推理

OnPolicyRunner 封装了统一的状态字典接口。调用 save() 时，框架会自动保存策略网络权重、优化器状态以及当前迭代次数；如果启用了 RND，也会一并保存 RND 网络与优化器状态。加载时默认恢复优化器状态，便于断点续训；若仅做推理，可将 load_optimizer 设为 false。

# 训练过程中自动保存
# runner.save(os.path.join(log_dir, f"model_{it}.pt"))

# 手动加载并继续训练
runner.load("./logs/model_500.pt", load_optimizer=True)

# 获取推理策略（自动切换 eval 模式）
inference_fn = runner.get_inference_policy(device="cuda:0")
actions = inference_fn(obs)  # 无需梯度，确定性推理

Sources: runners/on_policy_runner.py

下一步阅读建议

完成安装并跑通最小示例后，建议按以下顺序深入：

1. 若需自定义观测组、理解配置层级，继续阅读 配置文件与参数体系。
2. 若正在集成 Isaac Lab / Isaac Gym / MuJoCo 等仿真环境，阅读 向量化环境接入指南。
3. 若希望深入 PPO 的 loss 计算、GAE 估计与自适应 KL 调度，跳转至 PPO 算法实现与训练流程。
4. 若需要了解循环网络、CNN 观测编码或注意力策略，参考 循环与注意力策略变体 与 CNN 观测编码与特征提取。