cyy/Motrixlab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: release v0.3.0

Browse Source
This commit is contained in:
motphys-developers
2026-04-02 03:45:10 +00:00
parent c84d382b8c
commit e1421d1055
232 changed files with 20258 additions and 2004 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
docs/source/zh_CN/user_guide/tutorial/basic_frame.md
View File

@@ -16,6 +16,7 @@ MotrixLab/
│ └── registry.py # 环境注册系统
├── motrix_rl/ # 训练层：RL算法和配置
│ ├── skrl/ # SKRL框架集成（JAX/PyTorch）
│ ├── rslrl/ # RSLRL框架集成（PyTorch）
│ ├── base.py # RL配置基类
│ └── registry.py # RL配置注册系统
└── scripts
@@ -34,7 +35,7 @@ MotrixLab/
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 训练算法层 (SKRL) │
│ 训练算法层 (SKRL / RSLRL) │
│ PPO训练器 │ 网络架构 │ 优化器 │
└─────────────────────────────────────────────────────────────────┘
│
@@ -128,13 +129,15 @@ train.py --env cartpole
- **奖励配置**影响学习信号（奖励权重、计算方式等）
- **训练配置**控制算法行为（网络结构、学习率、批次大小等）
## 多后端支持
## 多框架支持
MotrixLab 的分层设计天然支持多种后端：
MotrixLab 的分层设计天然支持多种 RL 框架：
- **仿真后端**：MotrixSim
- **训练后端**：JAX 和 PyTorch，支持 GPU 加速
- **算法框架**：主要集成 SKRL，易于扩展其他算法
- **仿真后端**：MotrixSim（CPU）
- **训练框架**：
- **SKRL**：支持 JAX 和 PyTorch 后端，支持 GPU 加速
- **RSLRL**：支持 PyTorch 后端，支持 GPU 加速
- **框架选择**：使用 `--rllib` 参数在 `skrl`（默认）和 `rslrl` 之间选择
## 设计优势

45
docs/source/zh_CN/user_guide/tutorial/training_and_result.md
View File

@@ -7,41 +7,62 @@
### 基本训练命令
```bash
# 使用默认参数训练
# 使用默认参数训练（SKRL 框架）
uv run scripts/train.py --env cartpole
# 指定 RL 框架
uv run scripts/train.py --env cartpole --rllib skrl
uv run scripts/train.py --env cartpole --rllib rslrl
# 指定仿真后端
uv run scripts/train.py --env cartpole --sim-backend np
# 指定训练后端
uv run scripts/train.py --env cartpole --train-backend jax
uv run scripts/train.py --env cartpole --train-backend torch
# 指定训练后端（仅 SKRL）
uv run scripts/train.py --env cartpole --rllib skrl --train-backend jax
uv run scripts/train.py --env cartpole --rllib skrl --train-backend torch
```
### 高级训练配置
```bash
# 自定义训练参数
# 使用 SKRL 自定义训练参数
uv run scripts/train.py --env cartpole \
--rllib skrl \
--num-envs 1024 \
--train-backend jax \
--sim-backend np
# 使用 RSLRL 自定义训练参数
uv run scripts/train.py --env cartpole \
--rllib rslrl \
--num-envs 1024 \
--sim-backend np
# 注意：学习率等参数需要通过配置文件或代码覆盖设置
# 启用渲染监控训练过程
uv run scripts/train.py --env cartpole --render
```
### 不同框架配置
系统支持不同的 RL 框架，具有不同的配置系统：
- **SKRL 框架**：支持 JAX 和 PyTorch 训练后端，可通过 Python 数据类为每个后端配置参数
- **RSLRL 框架**：支持 PyTorch 后端，通过 Python 数据类（RslrlCfg）进行配置
对于 SKRL，系统支持为不同训练后端（JAX/Torch）配置不同的强化学习参数。例如：
### 支持的命令行参数
| 参数 | 说明 | 默认值 |
| ----------------- | -------------------- | ---------- |
| `--env` | 环境名称 | `cartpole` |
| `--sim-backend` | 仿真后端 (np) | 自动选择 |
| `--train-backend` | 训练后端 (jax/torch) | 自动选择 |
| `--num-envs` | 并行环境数量 | 2048 |
| `--render` | 启用渲染 | False |
| 参数 | 说明 | 默认值 |
| ----------------- | ----------------------------- | ---------- |
| `--env` | 环境名称 | `cartpole` |
| `--rllib` | RL 框架 (skrl/rslrl) | `skrl` |
| `--sim-backend` | 仿真后端 (np) | 自动选择 |
| `--train-backend` | 训练后端 (jax/torch，仅 SKRL) | 自动选择 |
| `--num-envs` | 并行环境数量 | 2048 |
| `--render` | 启用渲染 | False |
> **注意**: 其他参数如学习率、网络结构等需要通过单独文件设置。

208
docs/source/zh_CN/user_guide/tutorial/training_environment_config.md
View File

@@ -2,85 +2,80 @@
MotrixLab 提供了灵活的配置系统，允许用户自定义强化学习训练参数。本节介绍如何配置训练环境和强化学习算法参数。
## RL 训练配置 (PPOCfg)
## RL 训练配置
MotrixLab 支持多个 RL 框架，具有不同的配置系统：
- **SKRL 框架**：使用 Python 数据类配置（SkrlCfg）
- **RSLRL 框架**：使用 Python 数据类配置（RslrlCfg）
### SKRL 配置 (SkrlCfg)
训练配置定义了基于 PPO 算法的强化学习算法的参数。MotrixLab 现在支持为不同训练后端配置不同的参数。
### 完整配置示例
#### 完整配置示例
```python
@dataclass
class CompletePPOConfig(PPOCfg):
"""
完整的强化学习训练配置示例
包含了从基础到高级的所有配置参数
"""
以下是 `CartPoleSkrlPpo` 的实际配置，展示了完整的显式参数填充方法。该配置使用较小的网络 `[32, 32]`，适合 CartPole 这样的简单任务。
# ===== 基础训练参数 =====
seed: Optional[int] = None # 随机种子
num_envs: int = 2048 # 训练时并行环境数量
play_num_envs: int = 16 # 评估时并行环境数量
max_env_steps: int = 2_048_000 # 最大训练步数
check_point_interval: int = 1000 # 检查点保存间隔
# ===== PPO算法核心参数 =====
learning_rate: float = 3e-4 # 学习率
rollouts: int = 32 # 经验回放轮数
learning_epochs: int = 2 # 每次更新的训练轮数
mini_batches: int = 32 # 小批量数量
discount_factor: float = 0.99 # 折扣因子
lambda_param: float = 0.95 # GAE参数
grad_norm_clip: float = 1.0 # 梯度裁剪
# ===== PPO裁剪参数 =====
ratio_clip: float = 0.2 # PPO裁剪比率
value_clip: float = 0.2 # 价值裁剪
clip_predicted_values: bool = True # 裁剪预测值
# ===== 损失函数参数 =====
entropy_loss_scale: float = 0.0 # 熵损失系数
value_loss_scale: float = 2.0 # 价值损失系数
kl_threshold: float = 0 # KL散度阈值
# ===== 学习率调度器 =====
learning_rate_scheduler_kl_threshold: float = 0.008 # 自适应学习率KL阈值
# ===== 网络架构配置 =====
# 小型网络（适合简单任务如 CartPole）
# policy_hidden_layer_sizes: tuple[int, ...] = (128, 64)
# value_hidden_layer_sizes: tuple[int, ...] = (128, 64)
# 中型网络（默认配置，适合大部分任务）
policy_hidden_layer_sizes: tuple[int, ...] = (256, 128, 64)
value_hidden_layer_sizes: tuple[int, ...] = (256, 128, 64)
# 大型网络（适合复杂任务如机器人控制）
# policy_hidden_layer_sizes: tuple[int, ...] = (512, 256, 128)
# value_hidden_layer_sizes: tuple[int, ...] = (512, 256, 128)
# ===== 网络共享配置 =====
share_policy_value_features: bool = True # 策略和价值网络共享特征提取层
# ===== 训练控制参数 =====
random_timesteps: int = 0 # 随机步数
learning_starts: int = 0 # 开始学习的步数
time_limit_bootstrap: bool = True # 时间限制引导
# ===== 奖励整形 =====
rewards_shaper_scale: float = 1.0 # 奖励缩放因子
```{literalinclude} ../../../../motrix_rl/src/motrix_rl/tasks/cartpole.py
:language: python
:start-after: docs-start: cartpole-skrl-config
:end-before: docs-end: cartpole-skrl-config
```
**关键配置说明：**
- **网络架构**: `hiddens=[32, 32]` - CartPole 是简单任务，使用小网络即可（默认: `[256, 128, 64]`）
- **训练轮数**: `learning_epochs=5` - 比默认值 2 更高，确保充分学习
- **小批量数量**: `mini_batches=4` - 比默认值 32 更少，适合简单任务
- **训练时长**: `timesteps=5000` - 对于 CartPole 来说已经足够（默认: 10000）
- **所有参数**: 从父类继承的所有参数都被显式指定，无隐藏默认值
完整的源代码请参考: [`motrix_rl/src/motrix_rl/tasks/cartpole.py`](https://github.com/Motphys/motrix-lab/blob/main/motrix_rl/src/motrix_rl/tasks/cartpole.py)
### RSLRL 配置 (RslrlCfg)
RSLRL 是另一个高性能强化学习库，专门用于四足机器人等复杂控制任务。
#### 完整配置示例
以下是 `CartPoleRslrlPpo` 的实际配置，展示了完整的显式参数填充方法。该配置使用较小的网络 `[32, 32]`，适合 CartPole 这样的简单任务。
```{literalinclude} ../../../../motrix_rl/src/motrix_rl/tasks/cartpole.py
:language: python
:start-after: docs-start: cartpole-rslrl-config
:end-before: docs-end: cartpole-rslrl-config
```
**关键配置说明：**
- **网络架构**: `hidden_dims=[32, 32]` - CartPole 是简单任务，使用小网络即可（默认: `[256, 128, 64]`）
- **训练迭代**: `max_iterations=300` - 总共训练 300 次迭代
- **每轮步数**: `num_steps_per_env=16` - 每个环境收集 16 步
- **学习率**: `learning_rate=5.0e-4` - 学习率设置
- **熵系数**: `entropy_coef=5e-3` - 熵系数，用于探索
- **所有参数**: 从父类继承的所有参数都被显式指定，无隐藏默认值
详细的 RSLRL 配置选项和默认值，请参考：
- `motrix_rl/rslrl/cfg.py`：配置类定义
- `motrix_rl/template/rslrl_config.yaml`：YAML 参考模板
## 配置使用方法
### 1. 默认配置使用
```bash
# 使用代码中给定的配置
# 使用代码中给定的配置（默认：SKRL 框架）
uv run scripts/train.py --env my-task
# 指定训练后端，系统会自动选择对应的后端配置
uv run scripts/train.py --env my-task --train-backend jax
uv run scripts/train.py --env my-task --train-backend torch
# 指定 RL 框架
uv run scripts/train.py --env my-task --rllib skrl
uv run scripts/train.py --env my-task --rllib rslrl
# 指定 SKRL 的训练后端，系统会自动选择对应的后端配置
uv run scripts/train.py --env my-task --rllib skrl --train-backend jax
uv run scripts/train.py --env my-task --rllib skrl --train-backend torch
```
### 2. 命令行参数覆盖
@@ -88,91 +83,10 @@ uv run scripts/train.py --env my-task --train-backend torch
```bash
# 覆盖支持的命令行参数
uv run scripts/train.py --env my-task \
--rllib skrl \
--num-envs 1024 \
--train-backend jax \
--sim-backend np
# 系统会自动选择JAX后端对应的配置
```
### 3. 配置优先级
系统按以下优先级选择配置：
1. **后端特定配置**: 如果存在 `@rlcfg(env_name, backend="jax/torch")` 装饰的配置
2. **通用配置**: 如果存在 `@rlcfg(env_name)` 装饰的配置（无 backend 参数）
例如：
```python
# 最高优先级 - 后端特定配置
@rlcfg("my-task", backend="jax")
@dataclass
class MyTaskJAXCfg(PPOCfg):
mini_batches: int = 4
# 次优先级 - 通用配置
@rlcfg("my-task")
@dataclass
class MyTaskRLCfg(PPOCfg):
mini_batches: int = 32
# 当使用 --train-backend jax 时，系统会选择 MyTaskJAXCfg
# 当使用 --train-backend torch 时，系统会选择 MyTaskRLCfg
```
## SKRL 框架配置映射
在 MotrixLab 中，用户通过 `PPOCfg` 配置类设置参数，这些参数会被映射到 SKRL 框架的配置字典中。
### 用户可配置参数
| MotrixLab 配置类 | SKRL 框架参数 | 说明 |
| -------------------------------------- | --------------------------------------------- | -------------------- |
| `learning_rate` | `learning_rate` | 学习率 |
| `rollouts` | `rollouts` | 经验回放轮数 |
| `learning_epochs` | `learning_epochs` | 训练轮数 |
| `mini_batches` | `mini_batches` | 小批量数量 |
| `discount_factor` | `discount_factor` | 折扣因子 |
| `grad_norm_clip` | `grad_norm_clip` | 梯度裁剪 |
| `lambda_param` | `lambda` | GAE 参数 |
| `ratio_clip` | `ratio_clip` | PPO 裁剪比率 |
| `value_clip` | `value_clip` | 价值裁剪 |
| `clip_predicted_values` | `clip_predicted_values` | 裁剪预测值 |
| `entropy_loss_scale` | `entropy_loss_scale` | 熵损失系数 |
| `value_loss_scale` | `value_loss_scale` | 价值损失系数 |
| `kl_threshold` | `kl_threshold` | KL 散度阈值 |
| `random_timesteps` | `random_timesteps` | 随机步数 |
| `learning_starts` | `learning_starts` | 开始学习的步数 |
| `time_limit_bootstrap` | `time_limit_bootstrap` | 时间限制引导 |
| `learning_rate_scheduler_kl_threshold` | `learning_rate_scheduler_kwargs.kl_threshold` | 自适应学习率 KL 阈值 |
| `check_point_interval` | `experiment.write_interval` | 日志写入间隔 |
| `check_point_interval` | `experiment.checkpoint_interval` | 检查点保存间隔 |
| `rewards_shaper_scale` | `rewards_shaper` | 奖励缩放函数 |
### 预处理器参数
| SKRL 框架参数 | 类型 | 说明 |
| -------------------- | --------------------- | ---------- |
| `state_preprocessor` | RunningStandardScaler | 状态标准化 |
| `value_preprocessor` | RunningStandardScaler | 价值标准化 |
### 配置层次总结
```
用户配置类 (PPOCfg)
↓ 后端特定选择
后端配置 (JAX/Torch)
↓ 参数映射
SKRL 框架配置字典
↓ 传递给
PPO Agent
↓ 执行
强化学习训练
```
这种设计允许用户：
1. 通过简单的配置类来控制复杂的训练参数
2. 为不同训练后端配置不同的参数以获得最佳性能
3. 保持与 SKRL 框架的完全兼容性