# Kudada_RL

**Repository Path**: ps-micro/kudada_rl

## Basic Information

- **Project Name**: Kudada_RL
- **Description**: Kudada 训练源码仓库
- **Primary Language**: Unknown
- **License**: BSD-3-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-14
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Kudada RL 训练框架

基于 [HIMLoco](https://github.com/OpenRobotLab/HIMLoco) 改造的 **Kudada 机器人** 强化学习训练与部署框架（Isaac Gym + RSL-RL / HIM Policy）。

> 注：Kudada 使用 `resources/robots/kudada/kudada_lingzu.urdf` 模型（10 自由度双足），其环境代码位于 `legged_gym/legged_gym/envs/kudada/`。

## 支持的训练任务

| task 名称 | 说明 |
|-----------|------|
| `kudada` | Isaac Gym 仿真训练（terrain 课程 + 域随机化） |
| `kudada_real` | 对齐真机部署策略的训练/微调（44×21 obs 历史、10 维动作输出） |

## 项目结构

```
kudada_rl/
├── legged_gym/
│   └── legged_gym/
│       ├── envs/
│       │   ├── base/                 # 基础环境类（LeggedRobot、配置基类）
│       │   └── kudada/               # Kudada 配置与机器人（自包含，含 sim/real）
│       ├── scripts/train.py, play.py # 训练 / 推理导出入口
│       ├── utils/                    # 地形、日志、task_registry 等
│       └── logs/kudada_real/         # 训练日志与检查点
├── rsl_rl/                           # 修改版 RSL-RL（含 HIM Policy）
├── resources/robots/kudada/         # Kudada URDF/MJCF/网格模型
├── sim2sim/sim2sim_kudada.py         # MuJoCo sim2sim 验证（.pt / .onnx，支持部署流水线复刻）
├── train.py / play.py                # 便捷入口（等价于 legged_gym 内 scripts）
└── setup.py
```

## 快速开始

### 环境要求

| 项 | 要求 |
|----|------|
| Python | 3.8 |
| GPU | NVIDIA（开发用 4060） |
| OS | Ubuntu 22.04（推荐 20.04） |
| CUDA | Toolkit 12.6（CUDA 12.4 runtime） |
| Isaac Gym | Preview 版（本地下载解压） |

### 安装

#### 1. 安装 CUDA Toolkit

下载地址：https://developer.nvidia.com/cuda-toolkit-archive

```bash
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update
sudo apt-get -y install cuda-toolkit-12-6

echo 'export PATH=/usr/local/cuda-12.4/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.4/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

nvidia-smi          # 能看到 GPU 与驱动版本
nvcc -V             # 确认 CUDA Toolkit 安装
```

#### 2. 使用 uv 创建虚拟环境并安装依赖

```bash
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 进入项目目录
cd kudada_rl

# 创建虚拟环境
uv venv --python 3.8 --prompt gym

# 安装 PyTorch（CUDA 12.1）
uv pip install torch==2.4.1+cu121 torchvision==0.19.1+cu121 --index-url https://download.pytorch.org/whl/cu121
uv pip install numpy==1.23

# 下载解压 Isaac Gym 后软链接到项目根目录
ln -s ~/Downloads/isaacgym/ ./isaacgym/

# 安装核心依赖（editable 模式）
uv pip install -e ./isaacgym/python --config-setting editable_mode=compat
uv pip install -e ./rsl_rl        --config-setting editable_mode=compat
uv pip install -e ./legged_gym   --config-setting editable_mode=compat

# 安装辅助依赖
uv pip install setuptools==75.3.4
uv pip install onnx==1.17.0
uv pip install tensorboard==2.14.0
uv pip install mujoco==3.2.3

# 锁定依赖（可选）
uv pip freeze > requirements.lock.txt
```

### 训练

```bash
cd legged_gym/legged_gym/scripts
python train.py --task=kudada_real             # 对齐真机部署策略的训练/微调
python train.py --task=kudada_real --resume    # 断点续训
```

常用参数：`--headless`、`--num_envs N`、`--max_iterations N`、`--seed N`。

训练日志保存在 `legged_gym/logs/<experiment_name>/`，包含 `config_snapshot.yaml/json`、`training_log.csv`、`reward_curve.png`、`model_*.pt`。

### 推理与导出

```bash
python play.py --task=kudada_real      # 或 --task=kudada_real
```

策略导出至 `legged_gym/logs/<experiment_name>/exported/policies/`：
- `policy.pt`：TorchScript（sim2sim 使用）
- `policy.onnx`：ONNX（真机部署使用）

### MuJoCo Sim2Sim 验证

```bash
cd sim2sim
python sim2sim_kudada.py --policy ../legged_gym/logs/kudada_real/exported/policies/policy.onnx --duration 10
python sim2sim_kudada.py --policy <policy.pt|onnx> --render            # 带渲染 + 键盘控制（I/K/J/L/U/O/0/H）
python sim2sim_kudada.py --policy <policy.pt|onnx> --deploy            # 复刻 C++ 部署流水线（滤波/相位冻结/限幅/关节限位钳制）
```

默认加载 `resources/robots/kudada/kudada_lingzu.xml`。

### 真机部署

C++ 基于 ONNX Runtime，obs 44×21 历史堆叠、输出 10 关节动作

## 关键配置

| 项 | `kudada` | `kudada_real` |
|----|----------|---------------|
| 关节数（动作维） | 10 | 10 |
| 单帧观测 | 40 | 44 |
| 历史帧数 | 10 | 21 |
| 策略输入维度 | 400 | 924 |
| 部署输出维度 | 10 | 10（10 关节动作） |
| 控制频率 | 50 Hz（decimation=20, sim_dt=0.001） | 同左 |

PD 增益 / 默认姿态 / 奖励权重 / 域随机化范围等均在 `legged_gym/legged_gym/envs/kudada/kudada_config.py` 中集中配置。

## 观测维度详解

### `kudada_real` 单帧观测（44 维）

策略输入 = 44 维 × 21 帧历史 = 924 维

| 维度区间 | 内容 | 缩放 | 说明 |
|:---:|---|---|---|
| 0–2 | reserved | — | 恒为 0（占位，对齐 C++ 布局） |
| 3–5 | cmd_x / cmd_y / cmd_rate | ×lin_vel(2.0) 或 ×ang_vel(0.25) | 遥控速度指令 |
| 6–7 | gait_signal | — | sin/cos(2π·phase) 步态相位 |
| 8–10 | base_ang_vel | ×0.25 | roll/pitch/yaw 角速度 |
| 11–13 | projected_gravity | — | 重力投影向量 |
| 14–23 | dof_err | ×1.0 | 关节位置偏差（q_now − default） |
| 24–33 | dof_vel | ×0.05 | 关节速度 |
| 34–43 | actions | — | 上一帧动作（自回归输入） |

### `kudada` 单帧观测（40 维）

策略输入 = 40 维 × 10 帧历史 = 400 维，用于 Isaac Gym 仿真训练。

| 维度区间 | 内容 | 说明 |
|:---:|---|---|
| 0–2 | base_ang_vel | 角速度 |
| 3–5 | projected_gravity | 重力投影 |
| 6–8 | cmd_x / cmd_y / cmd_rate | 速度指令 |
| 9–18 | dof_err | 关节位置偏差 |
| 19–28 | dof_vel | 关节速度 |
| 29–38 | actions | 上一帧动作 |
| 39 | gait_signal | sin(2π·phase)（仅 sin） |

### 两个任务的关键差异

| 差异点 | `kudada` | `kudada_real` |
|--------|----------|---------------|
| reserved 占位 | 无 | 3 维 |
| gait_signal | 1 维（仅 sin） | 2 维（sin + cos） |
| 历史帧数 | 10 | 21 |
| 维度顺序 | ang_vel 在前 | reserved + cmd 在前（对齐 C++ 布局） |
| 用途 | 仿真训练 | 真机部署对齐 |

## 参考

- [HIMLoco](https://github.com/OpenRobotLab/HIMLoco) — 原始框架
- [RSL-RL](https://github.com/leggedrobotics/rsl_rl) — 强化学习算法库
- [Isaac Gym](https://developer.nvidia.com/isaac-gym) — NVIDIA GPU 加速物理仿真