feat(vla): add SmolVLA conditioning and experiment artifacts

2026-07-31 10:11:04 +08:00
parent acbd7c605a
commit 5ae9f5fa48
175 changed files with 317471 additions and 70 deletions
@@ -0,0 +1,498 @@
+# 实验操作指南
+
+## 0. 适用范围与当前起点
+
+这份文档面向 **当前 `main` 分支** 的通用训练 / 验证 / 评估流程，不绑定某一条历史实验分支。
+
+当前默认 Hydra 起点：
+- agent：`resnet_transformer`
+- data：`simpe_robot_dataset`
+- eval：`eval`
+
+当前仓库里常见可选 agent 配置包括：
+- `resnet_transformer`
+- `resnet_diffusion`
+- `resnet_gr00t_dit`
+- `resnet_imf_attnres`
+- `resnet_imf_attnres_multitoken`
+- `siglip2_imf_attnres`
+- `lewm_imf_attnres`
+
+说明：
+- `experiment_suites/` 下的历史目录仍然可以作为参考，但**正文以当前 `main` 的通用流程为准**。
+- 如果你只是想快速开始，优先从默认 `resnet_transformer` 配置出发，再按实验需求替换 agent。
+
+---
+
+## 1. 关键文件与入口
+
+| 路径 | 作用 |
+| --- | --- |
+| `roboimi/demos/vla_scripts/train_vla.py` | 主训练入口；负责数据集、checkpoint、`val/loss`、held-out action MSE、训练期 rollout 验证、SwanLab |
+| `roboimi/demos/vla_scripts/eval_vla.py` | 单次 rollout / 离线评估入口；支持 headless、summary、trajectory image、video artifact、多进程并行 rollout |
+| `roboimi/vla/conf/config.yaml` | 全局 Hydra 训练配置 |
+| `roboimi/vla/conf/data/simpe_robot_dataset.yaml` | 默认数据集配置；数据路径、相机名、图像 resize 都在这里 |
+| `roboimi/vla/conf/eval/eval.yaml` | eval 默认配置；`eval.ckpt_path`、`eval.num_episodes`、artifact 开关、多进程 rollout 配置都在这里 |
+| `roboimi/vla/conf/agent/*.yaml` | 可选 agent 配置集合 |
+| `roboimi/vla/data/simpe_robot_dataset.py` | HDF5 懒加载数据集；支持 `episode_indices` 过滤与 `available_episode_indices` 元信息 |
+| `roboimi/vla/scripts/calculate_stats.py` | 重算 `dataset_stats.pkl` |
+| `experiment_suites/` | 历史实验目录；可参考，但不作为当前主流程的唯一事实来源 |
+
+---
+
+## 2. 三台机器与环境
+
+| 机器 | GPU | Python | 常用数据集路径 | 备注 |
+| --- | --- | --- | --- | --- |
+| 本地 `droid-z790eagleax` | 1× RTX 5090 32GB | `/home/droid/.conda/envs/roboimi/bin/python` | `/home/droid/project/diana_sim/sim_transfer` | 适合 smoke、单条主跑、本地调参 |
+| 5880 节点 `100.73.14.65` | 2× RTX 5880 Ada 48GB | `/home/droid/miniforge3/envs/roboimi/bin/python` | `/home/droid/sim_dataset/sim_transfer` | 适合 2 条并行主跑 |
+| L20 节点 `100.119.99.14` | 8× NVIDIA L20 46GB | `/home/droid/miniforge3/envs/roboimi/bin/python` | `/data/simtransfer/current` | 适合大规模 grid；建议数据与 run 放 `/data` |
+
+连接：
+- 5880：`ssh droid@100.73.14.65`
+- L20：`ssh droid@100.119.99.14`
+
+说明：
+- repo / worktree 路径可能会随当前 checkout 或同步目录变化，**以你当前机器上的实际 repo 路径为准**。
+- 如果训练目录会被 Hydra 自动切走，建议显式设置 `hydra.run.dir=...` 以固定输出目录。
+
+---
+
+## 3. 训练流怎么走
+
+`train_vla.py` 当前主流程如下：
+
+1. 读取 Hydra 配置并打印完整 cfg
+2. 根据配置确定数据集图像 resize：
+   - 默认用 `data.image_resize_shape`
+   - 如果 `agent.vision_backbone.dataset_image_resize_shape` 存在，则优先用 backbone 覆盖值
+3. 通过 `build_train_val_datasets()` 构建 dataset / train dataset / val dataset
+   - 若设置 `train.val_episode_indices`：按显式 episode 切出 held-out val
+   - 否则按 `train.val_split` 做随机划分
+4. 用 `DataLoader` 建 train / val loader
+5. 从 `dataset_dir/dataset_stats.pkl` 读取归一化统计
+6. 实例化当前指定的 agent：`instantiate(cfg.agent, dataset_stats=...)`
+7. 可选加载：
+   - `train.pretrained_ckpt`：微调起点
+   - `train.resume_ckpt`：断点续训（支持显式路径或 `auto`）
+8. 建 optimizer 与 scheduler
+9. 训练循环里按 `log_freq` 记录 train loss / lr
+10. 按 `save_freq` 保存 `checkpoints/vla_model_step_*.pt`，并在有 val loader 时计算 `val/loss`
+11. 若设置了显式 held-out val，并且 `train.action_mse_val_freq_epochs > 0`，则按 epoch 计算 held-out `action MSE`
+12. 按 `train.rollout_val_freq_epochs` 跑训练期 rollout 验证
+13. 最后写：
+    - `checkpoints/vla_model_best.pt`
+    - `checkpoints/vla_model_final.pt`
+
+当前 best model 选择逻辑：
+- **第一次拿到 rollout reward 之前**：先用 `val_loss`（或 train loss 回退）挑 best
+- **第一次 rollout 之后**：优先用 `rollout_avg_reward` 挑 best
+
+输出目录：
+- 当前代码实际输出写到 **Hydra runtime output dir** 下
+- checkpoint 默认在：`<hydra_output_dir>/checkpoints/`
+- 如果不显式指定 `hydra.run.dir`，Hydra 会自动生成目录
+
+---
+
+## 4. 验证流怎么走
+
+### 4.1 常规 `val/loss`
+
+常规验证有两种来源：
+
+1. **随机划分验证集**
+   - 用 `train.val_split > 0`
+   - 训练脚本会在保存 checkpoint 时计算 `val/loss`
+
+2. **显式 held-out episode 验证集**
+   - 用 `train.val_episode_indices=[...]`
+   - 训练集 = 全部 episode - held-out episode
+   - 验证集 = held-out episode
+   - checkpoint 保存时同样会计算 `val/loss`
+
+说明：
+- 若 `train.val_split=0.0` 且未设置 `train.val_episode_indices`，则不会有 `val/loss`。
+
+### 4.2 held-out action MSE
+
+如果想对固定 held-out episode 做更稳定、可复现的动作预测误差验证，推荐使用：
+
+- `train.val_split=0.0`
+- `train.val_episode_indices=[100]`（或你指定的 episode 列表）
+- `train.action_mse_val_freq_epochs=1`
+
+当前 `main` 中这套逻辑会：
+- 每隔 `action_mse_val_freq_epochs` 个 epoch
+- 对 held-out val loader 调 `agent.predict_action_chunk(...)`
+- 与 batch 中的 `action` 计算 masked MSE
+- 如果存在 `action_is_pad`，会自动 mask 掉 padding 部分
+
+日志 key：
+- 控制台 / `train_vla.log`：`held-out action MSE`
+- SwanLab：`val/action_mse`
+
+重要约束：
+- `train.action_mse_val_freq_epochs > 0` **必须搭配** `train.val_episode_indices`
+- 如果只设了 `action_mse_val_freq_epochs` 而没有设 `val_episode_indices`，训练会直接报错
+
+### 4.3 rollout 验证
+
+训练内 rollout 验证由：
+- `train_vla.py -> run_rollout_validation() -> eval_vla._run_eval()`
+
+当前训练内 rollout 会强制：
+- `headless=true`
+- `verbose_action=false`
+- `record_video=false`
+- `save_trajectory_image=true`
+- `trajectory_image_camera_name=front`
+- `save_summary_json=true`
+
+当前这套路径是**配置驱动**的：
+- `train.rollout_device`：默认跟随 `train.device`
+- `train.rollout_num_workers`：默认 `null`
+  - 当 rollout 设备是 CPU 时，自动退化为 `1`
+  - 当 rollout 设备是 CUDA 时，自动推断为 `min(train.rollout_num_episodes, 8)`
+- `train.rollout_cuda_devices`：默认 `null`，等价于逻辑 GPU `[0]`
+- `train.rollout_response_timeout_s`
+- `train.rollout_server_startup_timeout_s`
+
+所以现在：
+- 训练在 CUDA 上时，训练期 rollout 默认也会走 GPU
+- `rollout_num_workers > 1` 时，会走并行 rollout
+- 可以是 **单 GPU 多 worker 共用一个 inference server**
+- 也可以是 **多 GPU 多 server 分摊 worker**
+
+训练内 rollout artifact 默认落到：
+- `<hydra_output_dir>/rollout_artifacts/<checkpoint_stem>/`
+
+常见文件：
+- `rollout_summary.json`
+- `rollout_front_ep01_trajectory.png` ...
+
+日志重点看：
+- `Epoch X rollout 平均奖励`
+- `最佳模型已更新`
+
+---
+
+## 5. 数据集加载与 `val_episode_indices` 机制
+
+### 5.1 数据集格式
+
+`SimpleRobotDataset` 读取 `dataset_dir` 下的 `*.hdf5` / `episode_*.hdf5`，每个 episode 文件至少要有：
+- `action`
+- `observations/qpos`
+- `observations/images/{cam_name}`
+
+默认数据配置中的相机：
+- `r_vis`
+- `top`
+- `front`
+
+### 5.2 懒加载行为
+
+`roboimi/vla/data/simpe_robot_dataset.py` 是按帧懒加载，不会一次性把整套 HDF5 全读进内存。
+
+它会：
+- 扫描目录下的 HDF5 文件
+- 在 worker 内做 HDF5 文件句柄 LRU 缓存
+- 根据文件名中的 `episode_XXX` 建立 `available_episode_indices`
+
+### 5.3 `val_episode_indices` 怎么切
+
+`build_train_val_datasets()` 的逻辑是：
+
+1. 先 instantiate 一次完整 dataset
+2. 读取 `dataset.available_episode_indices`
+3. 检查 `train.val_episode_indices` 是否都存在
+4. 用 `episode_indices=` 再各 instantiate 一次：
+   - train dataset = 全部 episode - held-out episode
+   - val dataset = 只包含 held-out episode
+
+因此：
+- `train.val_episode_indices=[100]` 的意思是把 `episode_100.hdf5` 整个拿去做 held-out val
+- 如果 episode 不存在，会直接报错
+- 如果你把所有 episode 都塞进 `val_episode_indices`，也会直接报错，因为训练集会变空
+
+### 5.4 图像 resize 与返回字段
+
+dataset 侧 resize 默认来自：
+- `data.image_resize_shape`
+- 如果 backbone 额外覆盖，则优先 `agent.vision_backbone.dataset_image_resize_shape`
+
+当前通用 batch 返回字段包括：
+- `observation.state`
+- `observation_is_pad`
+- `observation.<cam>`
+- `action`
+- `action_is_pad`
+- `task`
+
+### 5.5 统计文件
+
+训练和推理都默认依赖 `dataset_stats.pkl`。数据集更新后需要重算：
+
+```bash
+/home/droid/.conda/envs/roboimi/bin/python roboimi/vla/scripts/calculate_stats.py \
+  --dataset_dir /home/droid/project/diana_sim/sim_transfer
+```
+
+远端只要把：
+- Python 路径
+- `--dataset_dir`
+
+替换成对应机器上的实际路径即可。
+
+---
+
+## 6. SwanLab 行为
+
+当前默认配置里：
+- `train.use_swanlab=false`
+
+如果要开启，通常显式设置：
+- `train.use_swanlab=true`
+- `train.swanlab_project=roboimi-vla`
+- `train.swanlab_run_name=<run_name>`
+
+`train_vla.py` 当前会记录：
+- 初始化时上传 `train` / `data` / `agent` 三段 config
+- 训练中：
+  - `train/loss`
+  - `train/lr`
+  - `train/best_loss`
+  - `train/step`
+- checkpoint 验证时：
+  - `val/loss`
+- held-out 数值验证时：
+  - `val/action_mse`
+- rollout 验证时：
+  - `rollout/avg_reward`
+  - `rollout/epoch`
+- 训练结束时：
+  - `final/checkpoint_path`
+  - `final/best_checkpoint_path`
+
+训练期 rollout 生成的前视图轨迹 PNG 会 best-effort 上传到 SwanLab；上传失败只会 warning，不会让训练中断。
+
+---
+
+## 7. 并行 rollout 说明
+
+### 7.1 这套能力现在在哪里
+
+当前主仓库已经**内置**多进程并行 rollout 能力，入口就是：
+- `roboimi/demos/vla_scripts/eval_vla.py`
+
+控制参数：
+- `eval.num_workers`
+- `eval.cuda_devices`
+
+语义：
+- `eval.num_workers`：环境 worker 数，按 episode 切分
+- `eval.cuda_devices`：推理 server 绑定到哪些逻辑 GPU
+
+### 7.2 两种常见模式
+
+1. **单机单卡，多 worker 共用同一张 GPU**
+   - 典型：5090 只有 1 卡，但想让 4 个 rollout worker 并行跑环境
+   - 形式：`eval.device=cuda eval.num_workers=4 'eval.cuda_devices=[0]'`
+   - 这时是 **1 个 CUDA inference server + 4 个 env worker**
+
+2. **单机多卡，多 server 分摊 worker**
+   - 典型：5880 / L20 有多卡
+   - 形式：`eval.device=cuda eval.num_workers=8 'eval.cuda_devices=[0,1]'`
+   - worker 会按 round-robin 分到多个 server 上
+
+### 7.3 操作约束
+
+- 并行 rollout 依赖 **多进程 eval 路径**，不是 `train.num_workers`
+- `train.num_workers` 是 DataLoader worker，和 rollout 并行不是一回事
+- `eval.num_workers > 1` 时必须 `eval.headless=true`
+- worker 数会自动 cap 到 `eval.num_episodes`
+- 多 worker 时**不支持**同时导出：
+  - `eval.record_video=true`
+  - `eval.save_trajectory=true`
+  - `eval.save_trajectory_npz=true`
+- `eval.save_trajectory_image=true` 可以开，适合并行 reward + 定性检查一起做
+
+---
+
+## 8. 常用命令模板
+
+下面的模板都以 **当前 `main` 通用流程** 为准。远端机器只需要替换：
+- Python 路径
+- repo 路径
+- `data.dataset_dir`
+- `hydra.run.dir`
+
+### 8.1 本地 smoke train
+
+```bash
+/home/droid/.conda/envs/roboimi/bin/python roboimi/demos/vla_scripts/train_vla.py \
+  agent=resnet_transformer \
+  data.dataset_dir=/home/droid/project/diana_sim/sim_transfer \
+  train.device=cuda \
+  train.batch_size=8 \
+  train.max_steps=1000 \
+  train.num_workers=4 \
+  train.save_freq=200 \
+  hydra.run.dir=/home/droid/project/roboimi/runs/smoke-resnet-transformer
+```
+
+### 8.2 通用训练模板
+
+```bash
+/home/droid/.conda/envs/roboimi/bin/python roboimi/demos/vla_scripts/train_vla.py \
+  agent=resnet_transformer \
+  data.dataset_dir=/home/droid/project/diana_sim/sim_transfer \
+  train.device=cuda \
+  train.batch_size=16 \
+  train.lr=0.0001 \
+  train.max_steps=100000 \
+  train.num_workers=4 \
+  train.save_freq=2000 \
+  train.use_swanlab=true \
+  train.swanlab_project=roboimi-vla \
+  train.swanlab_run_name=<run_name> \
+  hydra.run.dir=/home/droid/project/roboimi/runs/<run_name>
+```
+
+### 8.3 带 held-out episode 验证的训练模板
+
+```bash
+/home/droid/.conda/envs/roboimi/bin/python roboimi/demos/vla_scripts/train_vla.py \
+  agent=resnet_transformer \
+  data.dataset_dir=/home/droid/project/diana_sim/sim_transfer \
+  train.device=cuda \
+  train.batch_size=16 \
+  train.lr=0.0001 \
+  train.max_steps=100000 \
+  train.num_workers=4 \
+  train.val_split=0.0 \
+  'train.val_episode_indices=[100]' \
+  train.action_mse_val_freq_epochs=1 \
+  train.rollout_val_freq_epochs=5 \
+  train.rollout_num_episodes=10 \
+  train.use_swanlab=true \
+  train.swanlab_project=roboimi-vla \
+  train.swanlab_run_name=<run_name> \
+  hydra.run.dir=/home/droid/project/roboimi/runs/<run_name>
+```
+
+### 8.4 断点续训模板
+
+`train_vla.py` 支持通过 CLI override 使用 `train.resume_ckpt`：
+
+```bash
+/home/droid/.conda/envs/roboimi/bin/python roboimi/demos/vla_scripts/train_vla.py \
+  agent=resnet_transformer \
+  data.dataset_dir=/home/droid/project/diana_sim/sim_transfer \
+  train.device=cuda \
+  train.resume_ckpt=auto \
+  hydra.run.dir=/home/droid/project/roboimi/runs/<run_name>
+```
+
+也可以把 `train.resume_ckpt` 换成显式 checkpoint 路径。
+
+### 8.5 单次离线评估
+
+```bash
+/home/droid/.conda/envs/roboimi/bin/python roboimi/demos/vla_scripts/eval_vla.py \
+  agent=resnet_transformer \
+  data.dataset_dir=/home/droid/project/diana_sim/sim_transfer \
+  train.device=cuda eval.device=cuda \
+  eval.ckpt_path=/home/droid/project/roboimi/runs/<run_name>/checkpoints/vla_model_best.pt \
+  eval.num_episodes=10 \
+  eval.headless=true \
+  eval.verbose_action=false \
+  eval.save_summary_json=true \
+  eval.save_trajectory_image=true \
+  eval.trajectory_image_camera_name=front \
+  eval.artifact_dir=/tmp/roboimi_eval_front
+```
+
+### 8.6 并行离线评估
+
+```bash
+/home/droid/.conda/envs/roboimi/bin/python roboimi/demos/vla_scripts/eval_vla.py \
+  agent=resnet_transformer \
+  data.dataset_dir=/home/droid/project/diana_sim/sim_transfer \
+  train.device=cuda eval.device=cuda \
+  eval.ckpt_path=/home/droid/project/roboimi/runs/<run_name>/checkpoints/vla_model_best.pt \
+  eval.num_episodes=10 \
+  eval.num_workers=4 \
+  'eval.cuda_devices=[0]' \
+  eval.headless=true \
+  eval.verbose_action=false \
+  eval.save_summary_json=true \
+  eval.save_trajectory_image=true \
+  eval.trajectory_image_camera_name=front \
+  eval.artifact_dir=/tmp/roboimi_parallel_eval
+```
+
+### 8.7 训练内启用并行 GPU rollout
+
+```bash
+/home/droid/.conda/envs/roboimi/bin/python roboimi/demos/vla_scripts/train_vla.py \
+  agent=resnet_transformer \
+  data.dataset_dir=/home/droid/project/diana_sim/sim_transfer \
+  train.device=cuda \
+  train.batch_size=16 \
+  train.lr=0.0001 \
+  train.max_steps=100000 \
+  train.num_workers=4 \
+  train.rollout_val_freq_epochs=5 \
+  train.rollout_num_episodes=10 \
+  train.rollout_device=cuda \
+  train.rollout_num_workers=4 \
+  'train.rollout_cuda_devices=[0]' \
+  train.rollout_validate_on_checkpoint=false \
+  train.use_swanlab=true \
+  train.swanlab_project=roboimi-vla \
+  train.swanlab_run_name=<run_name> \
+  hydra.run.dir=/home/droid/project/roboimi/runs/<run_name>
+```
+
+### 8.8 重算统计文件
+
+```bash
+/home/droid/.conda/envs/roboimi/bin/python roboimi/vla/scripts/calculate_stats.py \
+  --dataset_dir /home/droid/project/diana_sim/sim_transfer
+```
+
+### 8.9 监控日志
+
+```bash
+tail -f runs/<run_name>/train_vla.log
+```
+
+如果你显式设置了 `hydra.run.dir`，优先直接 tail 对应绝对路径下的日志文件。
+
+---
+
+## 9. 操作建议
+
+- **优先固定 `hydra.run.dir`**，避免输出目录分散在 Hydra 自动生成路径里
+- 如果只需要常规验证，使用：
+  - `train.val_split > 0`
+- 如果需要稳定、可复现的 held-out 指标，使用：
+  - `train.val_split=0.0`
+  - `train.val_episode_indices=[...]`
+  - `train.action_mse_val_freq_epochs=1`
+- `train.num_workers` 是 DataLoader worker，不等于 rollout 并行度
+- rollout 并行优先看：
+  - `train.rollout_num_workers`
+  - `train.rollout_cuda_devices`
+  - `eval.num_workers`
+  - `eval.cuda_devices`
+- 数据集更新后记得重算 `dataset_stats.pkl`
+- 若同时设置了：
+  - `train.pretrained_ckpt`
+  - `train.resume_ckpt`
+  当前逻辑会优先走 `resume_ckpt`
+- 建议 run name 中带上关键信息：
+  - agent / horizon / batch size / lr / host / gpu / date
+- `experiment_suites/` 下的历史目录适合作为参考资料，但不要默认把某一条旧 suite 当作当前主流程的唯一标准