添加readme文件
This commit is contained in:
gouhanke
208
README.md
Normal file
208
README.md
Normal file
@@ -0,0 +1,208 @@
|
|||||||
|
# RoboIMI
|
||||||
|
|
||||||
|
基于 MuJoCo 的机器人仿真与模仿学习框架，实现了使用扩散策略的视觉-语言-动作（VLA）模型，用于机器人操作任务。
|
||||||
|
|
||||||
|
## 主要特性
|
||||||
|
|
||||||
|
- **多机器人平台支持**：支持 Diana 和 vx300s 机械臂，可扩展至其他机器人
|
||||||
|
- **扩散策略**：采用最先进的扩散模型（DDPM/DDIM）进行动作序列预测
|
||||||
|
- **视觉-语言-动作模型**：使用 ResNet-18 视觉骨干网络和空间 softmax 进行视觉特征提取
|
||||||
|
- **灵活的控制模式**：支持关节空间和末端执行器（笛卡尔）控制
|
||||||
|
- **Hydra 配置系统**：模块化配置系统，便于实验
|
||||||
|
- **HDF5 数据集格式**：高效存储和加载演示数据
|
||||||
|
- **单臂和双臂任务**：支持单臂和双臂操作任务
|
||||||
|
|
||||||
|
## 安装
|
||||||
|
|
||||||
|
### 环境要求
|
||||||
|
|
||||||
|
- Python 3.8+
|
||||||
|
- 支持 CUDA 的 GPU（训练时推荐）
|
||||||
|
- Conda 或 Miniconda
|
||||||
|
|
||||||
|
### 安装步骤
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 克隆仓库
|
||||||
|
git clone <repository-url>
|
||||||
|
cd robo-imi-act
|
||||||
|
|
||||||
|
# 创建并激活 conda 环境
|
||||||
|
conda env create -f environment.yml
|
||||||
|
conda activate roboimi
|
||||||
|
|
||||||
|
# 以开发模式安装包
|
||||||
|
pip install -e .
|
||||||
|
```
|
||||||
|
|
||||||
|
## 快速开始
|
||||||
|
|
||||||
|
### 1. 数据采集
|
||||||
|
|
||||||
|
在仿真环境中记录演示轨迹：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 为 vx300s 机器人记录轨迹
|
||||||
|
python roboimi/demos/record_sim_episodes.py
|
||||||
|
|
||||||
|
# 为 Diana 机器人记录轨迹
|
||||||
|
python roboimi/demos/diana_record_sim_episodes.py
|
||||||
|
```
|
||||||
|
|
||||||
|
轨迹数据以 HDF5 文件格式保存，包含机器人状态、动作和相机观测。
|
||||||
|
|
||||||
|
### 2. 计算数据集统计信息
|
||||||
|
|
||||||
|
训练前需要计算归一化统计数据：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python roboimi/vla/scripts/calculate_stats.py
|
||||||
|
```
|
||||||
|
|
||||||
|
该命令会生成 `data_stats.pkl` 文件，包含动作和观测的均值/标准差或最小值/最大值。
|
||||||
|
|
||||||
|
### 3. 训练 VLA 模型
|
||||||
|
|
||||||
|
使用采集的数据训练视觉-语言-动作模型：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 使用默认配置训练
|
||||||
|
python roboimi/demos/vla_scripts/train_vla.py
|
||||||
|
|
||||||
|
# 覆盖特定参数
|
||||||
|
python roboimi/demos/vla_scripts/train_vla.py train.batch_size=32 train.lr=5e-5 train.max_steps=50000
|
||||||
|
|
||||||
|
# 使用不同的模型架构
|
||||||
|
python roboimi/demos/vla_scripts/train_vla.py agent=resnet_diffusion data=resnet_dataset
|
||||||
|
```
|
||||||
|
|
||||||
|
训练输出保存至 `outputs/<日期>/<时间>/`，模型检查点保存至 `checkpoints/`。
|
||||||
|
|
||||||
|
### 4. 评估模型
|
||||||
|
|
||||||
|
在仿真环境中评估训练好的模型：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 使用默认配置评估（使用最佳检查点）
|
||||||
|
python roboimi/demos/vla_scripts/eval_vla.py
|
||||||
|
|
||||||
|
# 指定检查点和评估轮数
|
||||||
|
python roboimi/demos/vla_scripts/eval_vla.py eval.ckpt_path=checkpoints/vla_model_step_8000.pt eval.num_episodes=5
|
||||||
|
|
||||||
|
# 启用动作平滑以获得更流畅的执行
|
||||||
|
python roboimi/demos/vla_scripts/eval_vla.py eval.use_smoothing=true eval.smooth_alpha=0.5
|
||||||
|
```
|
||||||
|
|
||||||
|
## 项目结构
|
||||||
|
|
||||||
|
```
|
||||||
|
robo-imi-act/
|
||||||
|
├── roboimi/
|
||||||
|
│ ├── assets/ # 机器人模型和资源
|
||||||
|
│ │ ├── models/manipulators/ # URDF 和 MuJoCo XML 文件
|
||||||
|
│ │ └── robots/ # 机器人抽象类
|
||||||
|
│ ├── envs/ # 仿真环境
|
||||||
|
│ │ ├── mujoco_base.py # MuJoCo 环境基类
|
||||||
|
│ │ ├── single_base.py # 单臂任务基类
|
||||||
|
│ │ └── double_base.py # 双臂任务基类
|
||||||
|
│ ├── vla/ # 视觉-语言-动作模型
|
||||||
|
│ │ ├── agent.py # VLAAgent（训练与推理）
|
||||||
|
│ │ ├── models/
|
||||||
|
│ │ │ ├── backbones/ # 视觉编码器（ResNet 等）
|
||||||
|
│ │ │ └── heads/ # 策略头（扩散 UNet1D）
|
||||||
|
│ │ ├── conf/ # Hydra 配置文件
|
||||||
|
│ │ └── scripts/ # 训练和工具脚本
|
||||||
|
│ └── demos/ # 演示脚本和示例
|
||||||
|
├── checkpoints/ # 保存的模型检查点
|
||||||
|
├── outputs/ # 训练输出（Hydra）
|
||||||
|
├── environment.yml # Conda 环境配置
|
||||||
|
└── CLAUDE.md # Claude Code 开发指南
|
||||||
|
```
|
||||||
|
|
||||||
|
## 架构设计
|
||||||
|
|
||||||
|
### VLA 训练流程
|
||||||
|
|
||||||
|
```
|
||||||
|
HDF5 轨迹数据 → Dataset → DataLoader → VLAAgent → 模型检查点
|
||||||
|
```
|
||||||
|
|
||||||
|
**模型组件**：
|
||||||
|
- **视觉骨干网络**：ResNet-18 + 空间 softmax，用于从相机图像中提取视觉特征
|
||||||
|
- **扩散头**：条件 UNet1D，使用 DDPM/DDIM 预测动作序列
|
||||||
|
- **VLAAgent**：组合视觉编码器和扩散策略，处理训练和推理
|
||||||
|
|
||||||
|
### 配置系统
|
||||||
|
|
||||||
|
基于 Hydra 的配置文件位于 `roboimi/vla/conf/`：
|
||||||
|
- `config.yaml`：主要训练配置（批次大小、学习率、设备）
|
||||||
|
- `agent/resnet_diffusion.yaml`：模型架构（动作维度、观测维度、时间窗口）
|
||||||
|
- `data/resnet_dataset.yaml`：数据集路径、相机名称、归一化类型
|
||||||
|
- `eval/eval.yaml`：评估设置（检查点路径、轮数、平滑参数）
|
||||||
|
|
||||||
|
使用配置插值保持一致性：`${agent.obs_horizon}`
|
||||||
|
|
||||||
|
### 数据集格式
|
||||||
|
|
||||||
|
HDF5 轨迹文件（`episode_*.hdf5`）包含：
|
||||||
|
- `action`：机器人动作 `[T, action_dim]`
|
||||||
|
- `observations/qpos`：关节位置 `[T, obs_dim]`
|
||||||
|
- `observations/images/<cam_name>`：相机图像 `[T, H, W, C]`
|
||||||
|
|
||||||
|
统计文件（`data_stats.pkl`）存储归一化参数（最小值/最大值/均值/标准差）。
|
||||||
|
|
||||||
|
## 开发指南
|
||||||
|
|
||||||
|
### 添加新机器人
|
||||||
|
|
||||||
|
1. 在 `roboimi/assets/models/manipulators/<robot_name>/` 创建 URDF/XML 文件
|
||||||
|
2. 在 `roboimi/assets/robots/<robot_name>.py` 定义机器人类（继承自 `arm_base.py`）
|
||||||
|
3. 在 `roboimi/envs/<robot_name>_*.py` 创建环境类
|
||||||
|
4. 如需要，在常量中注册机器人
|
||||||
|
|
||||||
|
### 修改 VLA 架构
|
||||||
|
|
||||||
|
1. **自定义骨干网络**：在 `roboimi/vla/models/backbones/` 创建新类，继承 `VLABackbone`
|
||||||
|
2. **自定义头部**：在 `roboimi/vla/models/heads/` 创建新类，继承 `VLAHead`
|
||||||
|
3. **更新配置**：在 `roboimi/vla/conf/agent/` 添加新的 YAML 文件
|
||||||
|
4. **接口定义**：参考 `roboimi/vla/core/interfaces.py` 的抽象基类
|
||||||
|
|
||||||
|
### 训练最佳实践
|
||||||
|
|
||||||
|
- 采集新数据后务必运行 `calculate_stats.py`
|
||||||
|
- 训练时会归一化输入/输出；推理时使用检查点中保存的统计信息进行反归一化
|
||||||
|
- 模型预测 `pred_horizon` 步，但只执行前 `action_horizon` 步
|
||||||
|
- 推理使用 DDIM（10 步）快速采样；训练使用 DDPM（100 步）
|
||||||
|
- 监控验证损失以防止过拟合
|
||||||
|
|
||||||
|
## 技术细节
|
||||||
|
|
||||||
|
- **坐标系**：关节空间（qpos）或末端执行器空间（xyz + rpy + 夹爪）
|
||||||
|
- **动作时间窗口**：`obs_horizon` 为观测窗口，`pred_horizon` 为预测窗口，`action_horizon` 为执行窗口
|
||||||
|
- **归一化**：对稳定训练至关重要 - 训练前务必计算统计信息
|
||||||
|
- **推理加速**：使用 DDIM 调度器，比训练时的 DDPM 快 10 倍
|
||||||
|
- **设备配置**：通过 `train.device` 配置（cuda/cpu）
|
||||||
|
|
||||||
|
## 许可证
|
||||||
|
|
||||||
|
[在此添加许可证信息]
|
||||||
|
|
||||||
|
## 引用
|
||||||
|
|
||||||
|
如果您在研究中使用了本代码库，请引用：
|
||||||
|
|
||||||
|
```bibtex
|
||||||
|
[在此添加引用信息]
|
||||||
|
```
|
||||||
|
|
||||||
|
## 贡献
|
||||||
|
|
||||||
|
欢迎贡献！请随时提交 Pull Request 或开启 Issue。
|
||||||
|
|
||||||
|
## 致谢
|
||||||
|
|
||||||
|
本项目基于以下开源项目构建：
|
||||||
|
- [MuJoCo](https://mujoco.org/) - 物理仿真引擎
|
||||||
|
- [PyTorch](https://pytorch.org/) - 深度学习框架
|
||||||
|
- [Hydra](https://hydra.cc/) - 配置管理系统
|
||||||
|
- [Diffusers](https://github.com/huggingface/diffusers) - 扩散模型库
|
||||||
Reference in New Issue
Block a user