# 克隆仓库
git clone <repository-url>
cd robo-imi-act

# 创建并激活 conda 环境
conda env create -f environment.yml
conda activate roboimi

# 以开发模式安装包
pip install -e .

快速开始

1. 数据采集

在仿真环境中记录演示轨迹：

# 为 vx300s 机器人记录轨迹
python roboimi/demos/record_sim_episodes.py

# 为 Diana 机器人记录轨迹
python roboimi/demos/diana_record_sim_episodes.py

轨迹数据以 HDF5 文件格式保存，包含机器人状态、动作和相机观测。

2. 计算数据集统计信息

训练前需要计算归一化统计数据：

python roboimi/vla/scripts/calculate_stats.py

该命令会生成 data_stats.pkl 文件，包含动作和观测的均值/标准差或最小值/最大值。

3. 训练 VLA 模型

使用采集的数据训练视觉-语言-动作模型：

# 使用默认配置训练
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. 评估模型

在仿真环境中评估训练好的模型：

# 使用默认配置评估（使用最佳检查点）
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）存储归一化参数（最小值/最大值/均值/标准差）。

开发指南

添加新机器人

在 roboimi/assets/models/manipulators/<robot_name>/ 创建 URDF/XML 文件
在 roboimi/assets/robots/<robot_name>.py 定义机器人类（继承自 arm_base.py）
在 roboimi/envs/<robot_name>_*.py 创建环境类
如需要，在常量中注册机器人

修改 VLA 架构

自定义骨干网络：在 roboimi/vla/models/backbones/ 创建新类，继承 VLABackbone
自定义头部：在 roboimi/vla/models/heads/ 创建新类，继承 VLAHead
更新配置：在 roboimi/vla/conf/agent/ 添加新的 YAML 文件
接口定义：参考 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）

许可证

[在此添加许可证信息]

引用

如果您在研究中使用了本代码库，请引用：

[在此添加引用信息]

贡献

欢迎贡献！请随时提交 Pull Request 或开启 Issue。

致谢

本项目基于以下开源项目构建：

MuJoCo - 物理仿真引擎
PyTorch - 深度学习框架
Hydra - 配置管理系统
Diffusers - 扩散模型库

README.md Unescape Escape

RoboIMI

主要特性

安装

环境要求

安装步骤