chore: release v0.0.1

This commit is contained in:
motphys-developers
2025-11-20 08:57:48 +00:00
commit 5133830b5a
105 changed files with 8789 additions and 0 deletions

View File

@@ -0,0 +1,149 @@
# 基础框架
MotrixLab 是一个机器人强化学习平台,这一节我们会介绍 MotrixLab 的框架设计以及各个组成部分之间的关系。如果您已经熟悉强化学习的内容,可以直接跳转至下一节,了解如何开发自己的训练环境。
## MotrixLab 的框架设计
MotrixLab 采用分层架构设计,将训练环境与训练逻辑进行了清晰拆分:
```
MotrixLab/
├── motrix_envs/ # 环境层:物理仿真和任务定义
│ ├── basic/ # 基础环境cartpole、walker等
│ ├── locomotion/ # 运动环境GO1机器人等
│ ├── np/ # NumPy仿真后端框架
│ ├── base.py # 环境基类
│ └── registry.py # 环境注册系统
├── motrix_rl/ # 训练层RL算法和配置
│ ├── skrl/ # SKRL框架集成JAX/PyTorch
│ ├── base.py # RL配置基类
│ └── registry.py # RL配置注册系统
└── scripts
├── train.py # 训练入口脚本
├── play.py # 测试入口脚本
└── view.py # 可视化脚本
```
## 核心组件架构
```
┌─────────────────────────────────────────────────────────────────┐
│ 用户接口层 │
│ train.py │ play.py │ view.py │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ 训练算法层 (SKRL) │
│ PPO训练器 │ 网络架构 │ 优化器 │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ 环境实现层 │
│ 环境配置(EnvCfg) │ 环境实现(Env) │ 奖励函数(Reward) │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ 物理仿真层 (MotrixSim) │
│ MJCF模型 │ 物理引擎 │ 碰撞检测 │
└─────────────────────────────────────────────────────────────────┘
```
## 核心组件详解
### 1. 训练环境 (Training Environment)
**位置**:环境实现层
训练环境是 MotrixLab 的核心组件,包含三个关键部分:
- **环境配置 (EnvCfg)**定义物理仿真参数模型文件、时间步长、episode 长度等)和任务特定参数
- **环境实现 (Env)**:继承基础环境类,实现具体的任务逻辑、物理仿真交互和终止条件检查
- **奖励函数 (Reward)**:在环境的 step 方法中实现,根据当前状态和动作计算奖励值
环境通过装饰器注册到系统中。
### 2. 奖励函数 (Reward Function)
**位置**:配置管理层 + 环境实现层
奖励函数在 MotrixLab 中采用双重结构设计:
- **配置层面**:在配置类中定义奖励权重、奖励组件类型和缩放参数
- **实现层面**:在环境的 `_compute_reward` 方法中根据配置参数计算具体奖励值
这种设计使得奖励函数既可以通过配置文件灵活调整,又能在代码中实现复杂的计算逻辑。
### 3. 配置参数 (Configuration Parameters)
**位置**:配置管理层
配置参数采用分层管理结构:
- **环境配置 (EnvCfg)**:控制物理仿真和任务行为,包括仿真参数、重置噪声、时间限制等
- **训练配置 (RLCfg)**:控制强化学习算法,包括网络结构、学习率、批次大小、训练步数等
配置类支持继承、参数验证和运行时覆盖,确保参数的合理性和灵活性。
### 4. 注册系统 (Registry System)
**位置**:连接各组件的枢纽
注册系统通过装饰器模式实现组件的自动注册:
- 环境配置类通过 `@registry.envcfg()` 注册
- 环境实现类通过 `@registry.env()` 注册,支持多后端
- RL 配置类通过 `@rlcfg()` 注册
注册系统实现了组件的解耦,使得新增环境或修改配置变得简单快捷。
## 数据流和工作流程
### 训练流程概览
```
用户命令 → 配置解析 → 环境创建 → 训练循环 → 模型保存
train.py --env cartpole
查找配置类 → 创建环境 → 启动PPO训练 → 保存模型
```
### 核心工作流程
1. **环境定义**:在 `/motrix_envs/` 中创建环境配置类和实现类
2. **自动注册**:通过装饰器将组件注册到系统中
3. **配置加载**:命令行启动时,系统自动查找并加载对应的配置
4. **环境创建**:工厂模式创建环境实例,支持参数覆盖
5. **训练执行**PPO 算法与环境交互,收集数据并更新策略
6. **结果保存**:定期保存检查点和最终模型
### 配置参数的作用
配置参数在整个流程中起到关键的连接作用:
- **环境配置**决定物理仿真行为(时间步长、模型文件、噪声等)
- **奖励配置**影响学习信号(奖励权重、计算方式等)
- **训练配置**控制算法行为(网络结构、学习率、批次大小等)
## 多后端支持
MotrixLab 的分层设计天然支持多种后端:
- **仿真后端**MotrixSim
- **训练后端**JAX 和 PyTorch支持 GPU 加速
- **算法框架**:主要集成 SKRL易于扩展其他算法
## 设计优势
这种架构设计带来了以下核心优势:
1. **模块解耦**:环境开发与训练逻辑完全分离
2. **配置灵活**:支持分层配置和运行时参数覆盖
3. **扩展性强**:通过注册系统轻松添加新组件
4. **多后端兼容**:同一环境可使用不同仿真和训练后端
5. **实验友好**:配置可保存、比较,确保实验可重现
通过这个框架设计MotrixLab 为机器人强化学习提供了一个清晰、灵活且易用的开发平台。

View File

@@ -0,0 +1,61 @@
# 物理环境配置
物理环境配置定义了强化学习训练中的仿真参数和模型文件设置。
MotrixLab 使用了[MotrixSim](https://motrixsim.readthedocs.io/zh-cn/latest/user_guide/index.html)作为物理仿真后端。
## 支持的文件格式
- [**MJCF**](https://mujoco.readthedocs.io/en/stable/XMLreference.html)(MuJoCo XML 格式) - 提供丰富的物理特性和仿真配置
## 模型文件配置
需要在环境配置类中指定模型文件路径:
```python
@registry.envcfg("my-task")
@dataclass
class MyTaskEnvCfg(EnvCfg):
# 模型文件路径(必需)
model_file: str = "my_model.xml"
# 仿真时间参数
sim_dt: float = 0.002 # 仿真时间步
ctrl_dt: float = 0.02 # 控制更新频率
```
### 推荐目录结构
```
motrix_envs/my_task/
├── __init__.py # 模块初始化
├── cfg.py # 环境配置
├── my_model.xml # 物理模型文件
└── my_env.py # 环境实现
```
对于结构复杂,引用文件较多的模型,推荐使用文件夹管理。
## 常见配置问题
### 文件路径问题
- 使用相对路径时,确保路径相对于配置文件位置
- 避免使用硬编码的绝对路径
- 检查文件权限和可访问性
- 确保所有引用的子文件都存在
### 时间步设置
- `ctrl_dt` 应该是 `sim_dt` 的整数倍
- `sim_dt` 过小会影响仿真性能
- `ctrl_dt` 过大会影响控制精度
- 推荐 `sim_dt` 在 0.001-0.02 秒之间
### 仿真稳定性
- 避免过大的时间步长
- 合理设置接触参数避免穿透
- 质量和惯性分布要合理
- 关节限制要符合实际情况
通过合理的物理环境配置,您可以为强化学习训练创建准确且高效的仿真环境。

View File

@@ -0,0 +1,50 @@
# 奖励函数设计
奖励函数告诉智能体什么样的行为是期望的,是强化学习环境设计中的核心部分。
## 奖励函数在训练循环中的位置
在 MotrixLab 的 NpEnv 中,奖励计算发生在 `step` 函数的 `update_state` 阶段:
```python
# NpEnv.step() 的执行流程
def step(self, actions: np.ndarray) -> NpEnvState:
# 1. 准备阶段:清空奖励和状态
self._prev_physics_step() # reward = 0.0, terminated = False, truncated = False
# 2. 应用动作
self._state = self.apply_action(actions, self._state)
# 3. 物理仿真
self.physics_step() # 执行物理仿真
# 4. 更新状态 ← 奖励函数在这里计算
self._state = self.update_state(self._state) # 计算奖励和观察值
# 5. 后续处理
self._update_truncate() # 检查时间截断
self._reset_done_envs() # 重置完成的环境
return self._state
```
您需要在子类的 `update_state` 方法中实现奖励计算逻辑,具体奖励函数设计思路请参考训练示例。
### 奖励组件设计原则
1. **分离关注点**:每个奖励函数负责一个特定的目标
2. **权重配置**:通过配置文件管理不同组件的权重
3. **归一化**:保持奖励值在合理的范围内
4. **平滑性**:避免硬性阈值,使用指数函数等平滑过渡
这种方法使得奖励函数模块化,便于调试和调整各个组件的权重。
## 设计原则
1. **明确的目标导向**:奖励函数应该直接反映任务目标
2. **合理的奖励范围**:避免过大或过小的奖励值,保持训练稳定
3. **平衡探索与利用**:适当奖励接近目标的行为,避免稀疏奖励
4. **避免奖励漏洞**:检查智能体是否可能通过不期望的方式获得高奖励
5. **调试友好**:在开发阶段输出奖励分解信息,便于调优
通过在 `update_state` 方法中正确实现奖励计算,您可以为各种机器人任务设计有效的学习信号。

View File

@@ -0,0 +1,79 @@
# 训练执行和结果分析
本节介绍如何执行强化学习训练,以及如何分析和使用训练结果。
## 启动训练
### 基本训练命令
```bash
# 使用默认参数训练
uv run scripts/train.py --env cartpole
# 指定仿真后端
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
```
### 高级训练配置
```bash
# 自定义训练参数
uv run scripts/train.py --env cartpole \
--num-envs 1024 \
--train-backend jax \
--sim-backend np
# 注意:学习率等参数需要通过配置文件或代码覆盖设置
# 启用渲染监控训练过程
uv run scripts/train.py --env cartpole --render
```
### 支持的命令行参数
| 参数 | 说明 | 默认值 |
| ----------------- | -------------------- | ---------- |
| `--env` | 环境名称 | `cartpole` |
| `--sim-backend` | 仿真后端 (np) | 自动选择 |
| `--train-backend` | 训练后端 (jax/torch) | 自动选择 |
| `--num-envs` | 并行环境数量 | 2048 |
| `--render` | 启用渲染 | False |
> **注意**: 其他参数如学习率、网络结构等需要通过单独文件设置。
## 训练过程监控
### TensorBoard 监控
启动 TensorBoard 查看训练进度:
```bash
uv run tensorboard --logdir runs/{env-name}
```
例如:
```bash
uv run tensorboard --logdir runs/cartpole
```
## 模型评估和测试
### 使用训练好的策略
```bash
# 自动寻找最佳策略测试(推荐)
uv run scripts/play.py --env cartpole
# 手动指定策略文件测试
uv run scripts/play.py --env cartpole --policy runs/cartpole/nn/best_agent.pickle
# 指定测试环境数量
uv run scripts/play.py --env cartpole --num-envs 100
```
> **说明**:系统会自动在 `runs/cartpole/` 目录下寻找最新、最佳的策略文件进行测试。

View File

@@ -0,0 +1,178 @@
# 训练环境配置
MotrixLab 提供了灵活的配置系统,允许用户自定义强化学习训练参数。本节介绍如何配置训练环境和强化学习算法参数。
## RL 训练配置 (PPOCfg)
训练配置定义了基于 PPO 算法的强化学习算法的参数。MotrixLab 现在支持为不同训练后端配置不同的参数。
### 完整配置示例
```python
@dataclass
class CompletePPOConfig(PPOCfg):
"""
完整的强化学习训练配置示例
包含了从基础到高级的所有配置参数
"""
# ===== 基础训练参数 =====
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 # 奖励缩放因子
```
## 配置使用方法
### 1. 默认配置使用
```bash
# 使用代码中给定的配置
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
```
### 2. 命令行参数覆盖
```bash
# 覆盖支持的命令行参数
uv run scripts/train.py --env my-task \
--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 框架的完全兼容性