debug: 固定验证集上的随机噪声，修复resnet在训练时bn层会切换到train的问题
This commit is contained in:
gouhanke
134
README.md
134
README.md
@@ -1,134 +0,0 @@
|
||||
# VLA Framework: Vision-Language-Action Policy Framework
|
||||
|
||||
**VLA Framewrok** 是 `roboimi` 生态系统中的下一代具身智能策略框架。它采用**完全解耦**与**基于组合**的架构设计，支持视觉语言模型（VLM）、投影层（Projector）与动作生成头（Action Head）的灵活搭配。
|
||||
|
||||
本框架基于 [Hydra](https://hydra.cc/) 进行配置管理，并采用 HDF5 作为标准数据格式。
|
||||
|
||||
---
|
||||
|
||||
## 🏗 架构概览 (Directory Structure)
|
||||
|
||||
我们采用“接口与实现分离”以及“代码与配置镜像映射”的设计原则。
|
||||
|
||||
```text
|
||||
roboimi/vla/
|
||||
├── agent.py # [Core] VLAAgent 组装类，负责串联各个模块
|
||||
├── conf/ # [Config] Hydra 配置文件 (单一真值源)
|
||||
│ ├── config.yaml # 主入口配置
|
||||
│ ├── agent/ # Agent 结构定义 (定义模块间的连接与插值)
|
||||
│ ├── backbone/ # 视觉骨干配置 (e.g., SigLIP, CLIP)
|
||||
│ ├── projector/ # 投影层配置 (e.g., MLP, Perceiver)
|
||||
│ ├── head/ # 动作头配置 (e.g., Diffusion, ACT)
|
||||
│ └── data/ # 数据流配置
|
||||
├── core/ # [Interface] 抽象基类
|
||||
│ ├── base_vlm.py # VLMBackbone (ABC)
|
||||
│ └── base_policy.py # ActionHead (ABC)
|
||||
├── models/ # [Implementation] 具体模型实现
|
||||
│ ├── backbones/ # 视觉模型 (Sub-package)
|
||||
│ ├── projectors/ # 投影层 (Sub-package)
|
||||
│ └── heads/ # 策略头 (Sub-package)
|
||||
├── data/ # [Data Pipeline] Dataset 与 DataLoader
|
||||
├── modules/ # [Building Blocks] 通用组件 (Encoders, Fusion)
|
||||
└── scripts/ # [Utilities] 数据转换与维护脚本
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 快速开始 (Quick Start)
|
||||
|
||||
### 1. 环境依赖
|
||||
请确保安装以下核心库：
|
||||
```bash
|
||||
pip install hydra-core h5py zarr diffusers transformers
|
||||
```
|
||||
|
||||
### 2. 启动训练 (Training)
|
||||
训练入口脚本通常位于 `demos/vla_scripts/train_vla.py`。
|
||||
由于使用了 Hydra，您可以在命令行动态组合模型架构：
|
||||
|
||||
```bash
|
||||
# 1. 默认训练 (SigLIP + MLP + Diffusion)
|
||||
python demos/vla_scripts/train_vla.py
|
||||
|
||||
# 2. 切换视觉骨干为 CLIP
|
||||
python demos/vla_scripts/train_vla.py agent/backbone=clip
|
||||
|
||||
# 3. 切换投影层为 Perceiver Resampler
|
||||
python demos/vla_scripts/train_vla.py agent/projector=perceiver
|
||||
|
||||
# 4. 修改超参数 (例如 batch size)
|
||||
python demos/vla_scripts/train_vla.py train.batch_size=32
|
||||
|
||||
# 5. 调试模式 (使用 Tiny 模型快速跑通流程)
|
||||
python demos/vla_scripts/train_vla.py agent=tiny
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠 开发指南 (Developer Guide)
|
||||
|
||||
### 1. 添加新的视觉骨干 (New Backbone)
|
||||
1. **代码**: 在 `models/backbones/` 下新建文件 (如 `my_model.py`)，继承 `VLMBackbone`。
|
||||
2. **导出**: 在 `models/backbones/__init__.py` 中添加导出。
|
||||
3. **配置**: 在 `conf/backbone/` 下新建 `my_model.yaml`。
|
||||
* *注意*: 必须定义 `output_dim`，供 Projector 引用。
|
||||
|
||||
### 2. 添加新的投影层 (New Projector)
|
||||
Projector 负责将 VLM 特征维度对齐到 Agent 的 Embedding 维度。
|
||||
1. **代码**: 在 `models/projectors/` 下实现 `nn.Module`。
|
||||
2. **配置**: 在 `conf/projector/` 下新建 YAML 文件。
|
||||
* *关键*: 设置 `input_dim: ???` 和 `output_dim: ???`，让 Hydra 在 `agent/default.yaml` 中自动插值填充。
|
||||
|
||||
### 3. 添加新的动作头 (New Action Head)
|
||||
1. **代码**: 在 `models/heads/` 下新建文件，继承 `ActionHead`。
|
||||
* 必须实现 `compute_loss(context, actions)` 和 `predict_action(context)`。
|
||||
2. **配置**: 在 `conf/head/` 下新建 YAML 文件。
|
||||
* 同样建议设置 `input_dim: ???` 以保持动态性。
|
||||
|
||||
---
|
||||
|
||||
## 📊 数据流水线 (Data Pipeline)
|
||||
|
||||
本框架强制使用 **HDF5** 格式以优化 IO 性能。
|
||||
|
||||
### 1. 数据结构标准
|
||||
数据集必须遵循 [Robomimic](https://robomimic.github.io/) 的层级结构：
|
||||
```text
|
||||
episode_0.hdf5
|
||||
├── action: Dataset, shape=(700, 16), dtype=float32
|
||||
└── observations: Group
|
||||
├── images: Group
|
||||
│ ├── angle: Dataset, shape=(700, 480, 640, 3), dtype=uint8
|
||||
│ ├── r_vis: Dataset, shape=(700, 480, 640, 3), dtype=uint8
|
||||
│ └── top: Dataset, shape=(700, 480, 640, 3), dtype=uint8
|
||||
└── qpos: Dataset, shape=(700, 16), dtype=float32
|
||||
```
|
||||
|
||||
### 2. 数据转换工具
|
||||
使用内置脚本将您的原始数据转换为标准 HDF5：
|
||||
|
||||
```bash
|
||||
# 在项目根目录下运行
|
||||
python -m roboimi.vla.scripts.convert_to_hdf5 \
|
||||
--input_dir /path/to/raw/images \
|
||||
--output_path ./data/demo.hdf5
|
||||
```
|
||||
|
||||
### 3. 调试数据
|
||||
如果不确定数据是否正确，使用可视化工具检查：
|
||||
```bash
|
||||
python -m roboimi.vla.scripts.visualize_data --dataset ./data/demo.hdf5
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 最佳实践 (Best Practices)
|
||||
|
||||
1. **绝对导入**: 禁止使用 `from . import xxx`。请始终使用全路径 `from roboimi.vla.models.backbones import SigLIPBackbone`。
|
||||
2. **Hydra 插值**: 在 `agent/default.yaml` 中，我们使用了 `${..embed_dim}` 语法来确保所有子模块的维度一致。**不要在子配置中硬编码维度数值。**
|
||||
3. **HDF5 IO**: 在 `Dataset` 类中，**必须在 `__getitem__` 内部打开 HDF5 文件**。如果在 `__init__` 中打开，多进程 DataLoader 会因无法序列化文件句柄而报错。
|
||||
4. **接口导出**:每当在 `models/xxx/` 下添加新文件时，务必在对应的 `__init__.py` 中更新 `__all__`，以保持引用整洁。
|
||||
|
||||
---
|
||||
|
||||
*Maintainer: VLA Framework Team*
|
||||
Reference in New Issue
Block a user