镜像自地址
https://github.com/MINT-SJTU/Evo-RL.git
已同步 2026-11-20 18:17:06 +00:00
docs(evo1): add handoff notes
这个提交包含在:
@ -1,20 +1,51 @@
|
||||
# Evo1 Known Issues
|
||||
|
||||
## Current scope
|
||||
## 尚未完善的部分
|
||||
|
||||
- Evo1 in Evo-RL only targets new LeRobot-format checkpoints saved with `config.json`, `model.safetensors`, and processor configs.
|
||||
- Legacy Evo1 / DeepSpeed checkpoints are intentionally out of scope and are no longer supported by this integration.
|
||||
- 多 embodiment 训练目前还没有完整打通。
|
||||
- 模型侧保留了 `embodiment_id`、`num_categories`、`default_embodiment_id` 这些接口。
|
||||
- 但当前常用数据集没有稳定的 `embodiment_id` 字段,训练时实际上仍然会回落到单一 `default_embodiment_id=0`。
|
||||
- 如果后续要做多机器人/多 embodiment 联训,还需要同时补齐:
|
||||
- 数据集里的稳定 `embodiment_id` 来源
|
||||
- 多 embodiment 的归一化统计,而不是单份聚合 stats
|
||||
- training config 层面对多数据源联训的明确支持
|
||||
|
||||
## Precision
|
||||
- 目前接入主要面向 Evo-RL / LeRobot 风格的 checkpoint。
|
||||
- 也就是带有 `config.json`、`model.safetensors`、`policy_preprocessor.json`、`policy_postprocessor.json` 的目录。
|
||||
- 原始 Evo1 / DeepSpeed checkpoint 没有直接作为 Evo-RL 训练续训格式来兼容。
|
||||
|
||||
- Evo1 training is expected to run with `bf16` mixed precision to match the original Evo1 recipe.
|
||||
- Use the dedicated accelerate config in this directory when launching training to keep the precision path aligned.
|
||||
- 当前验证过、最稳定的训练路径是 4 卡 bf16。
|
||||
- 目录里只保留了四卡 accelerate 配置。
|
||||
- 单卡、双卡虽然理论上可以再配,但当前没有作为维护目标继续保留。
|
||||
|
||||
## Multi-embodiment training
|
||||
- 图像增强路径当前不作为默认推荐配置。
|
||||
- 已验证训练命令里默认使用 `dataset.image_transforms.enable=false`。
|
||||
- 原因不是 Evo1 算法本身依赖关闭增强,而是当前实验环境里的 transforms 路径没有作为稳定组合继续维护。
|
||||
|
||||
- The model path still accepts `embodiment_id` and `num_categories`, but the current towel dataset does not contain an `embodiment_id` field.
|
||||
- With the current data, Evo1 training always falls back to `default_embodiment_id=0`.
|
||||
- Multi-repo multi-robot training is still blocked at the training config layer.
|
||||
- A full multi-embodiment setup would still need:
|
||||
- a stable `embodiment_id` field in the dataset or a deterministic mapping from dataset identity
|
||||
- per-robot normalization instead of a single aggregated stats table
|
||||
## 相比原始 Evo1 的工程差异
|
||||
|
||||
- 训练入口不再走原始 Evo1 的“大训练脚本”。
|
||||
- 现在是把 Evo1 接到了 LeRobot 统一训练框架里,通过 `lerobot_train` 启动。
|
||||
- `stage1/stage2`、checkpoint 保存、processor、dataset 读取、日志和训练配置都尽量复用 LeRobot 现有基础设施。
|
||||
|
||||
- `stage1 -> stage2` 的衔接方式改成了 Evo-RL 里的 `resume_pretrain=true` 语义。
|
||||
- 含义是:只加载权重,不恢复 optimizer / scheduler / global step。
|
||||
- 这和原始 Evo1 的“两阶段训练切换”意图是一致的,但实现方式更贴近 LeRobot 的配置体系。
|
||||
|
||||
- 混合精度执行边界比原始 Evo1 更统一。
|
||||
- 原始 Evo1 里,VLM embedding 和后面的 action head 前向不在同一个统一的训练 AMP 作用域里。
|
||||
- 现在 Evo-RL 版是在更大的 `accelerator.autocast()` 范围中执行整个 policy forward。
|
||||
- 这属于工程上的规整化,主要影响的是执行路径、速度和数值边界;在 `stage2` finetune VLM 时尤其值得注意。
|
||||
|
||||
- 分布式训练实现不同。
|
||||
- 原始 Evo1 训练主要依赖 DeepSpeed。
|
||||
- 现在的 Evo-RL 接入版默认走 Accelerate bf16 配置。
|
||||
- 这不改变 Evo1 的核心模型结构和两阶段训练思路,但会让工程实现、混精边界、分布式包装方式与原始仓库有所不同。
|
||||
|
||||
- processor / preprocessor / postprocessor 被纳入了 LeRobot 的标准保存格式。
|
||||
- 这样推理、录制和训练可以复用同一套加载接口。
|
||||
- 也意味着 Evo1 不再只是一套训练脚本,而是完整地成为 LeRobot policy registry 里的一个 policy。
|
||||
|
||||
- 数据读取不再依赖原始 Evo1 自己的大型 dataset 训练脚本。
|
||||
- 当前训练直接复用 LeRobot 数据集接口。
|
||||
- 为了对照复现原始 Evo1 时,额外写过一个 v3.0 数据到原始 Evo1 loader 可读格式的适配脚本;但这条适配链不是 Evo-RL 日常训练的默认路径。
|
||||
|
||||
117
src/lerobot/policies/evo1/移植说明.md
普通文件
117
src/lerobot/policies/evo1/移植说明.md
普通文件
@ -0,0 +1,117 @@
|
||||
# Evo1 移植说明
|
||||
|
||||
这份说明主要给后续接手同学快速了解:Evo1 是怎么接入到 Evo-RL / LeRobot 训练体系里的,以及这次移植时主要做了什么。
|
||||
|
||||
## 1. 总体思路
|
||||
|
||||
这次移植没有重写 Evo1 的模型主体,而是沿用了原始 Evo1 已经比较贴近 LeRobot 的那一部分设计:
|
||||
|
||||
- policy 本体仍然是 Evo1
|
||||
- VLM 仍然是 InternVL3
|
||||
- action head 仍然是 flow matching
|
||||
- `stage1 / stage2` 两阶段训练逻辑仍然保留
|
||||
|
||||
真正的工作重点不在“改模型”,而在于把原始仓库里那套比较集中的训练逻辑,拆开并接到 LeRobot 现有训练基础设施里。
|
||||
|
||||
## 2. 为什么训练接入相对自然
|
||||
|
||||
原始 Evo1 在推理侧本来就已经有一些 LeRobot 风格的组织方式,比如:
|
||||
|
||||
- policy / processor 的概念是比较明确的
|
||||
- checkpoint 也能整理成标准的模型目录
|
||||
- 两阶段训练本身就是围绕同一个 policy 展开的
|
||||
|
||||
所以这次接入并不是从零抽象一个新 policy,而更像是:
|
||||
|
||||
1. 保留 Evo1 模型实现
|
||||
2. 把原始大训练脚本中的训练逻辑抽出来
|
||||
3. 接到 LeRobot 的 `make_policy`、`lerobot_train`、processor 保存与加载、dataset 接口、checkpoint 体系里
|
||||
|
||||
## 3. 具体做了什么
|
||||
|
||||
可以把这次工作理解为三层。
|
||||
|
||||
### 模型层
|
||||
|
||||
- 在 `src/lerobot/policies/evo1/` 下接入 Evo1 config、model、processor、flow matching action head。
|
||||
- 保留了原始 Evo1 的关键配置项,比如:
|
||||
- `training_stage`
|
||||
- `vlm_model_name`
|
||||
- `num_layers`
|
||||
- `chunk_size`
|
||||
- `n_action_steps`
|
||||
- `max_action_dim`
|
||||
- `max_state_dim`
|
||||
|
||||
### 训练层
|
||||
|
||||
- 不再使用原始 Evo1 那个集中的训练脚本作为日常训练入口。
|
||||
- 改为通过 LeRobot 统一训练入口 `lerobot_train` 启动 Evo1。
|
||||
- 在训练配置层面补了:
|
||||
- `stage1`
|
||||
- `stage2`
|
||||
- `resume_pretrain`
|
||||
|
||||
其中:
|
||||
|
||||
- `stage1`:冻结 VLM,只训练 action head
|
||||
- `stage2`:继续训练 VLM + action head
|
||||
- `resume_pretrain=true`:用于从 stage1 权重切到 stage2,但不恢复 optimizer / scheduler / step
|
||||
|
||||
### 工程集成层
|
||||
|
||||
- Evo1 被接进了 LeRobot 的 policy registry
|
||||
- 训练、推理、record 都能通过统一的 `make_policy` / processor 体系加载
|
||||
- checkpoint 会保存成 LeRobot 标准格式:
|
||||
- `config.json`
|
||||
- `model.safetensors`
|
||||
- `policy_preprocessor.json`
|
||||
- `policy_postprocessor.json`
|
||||
|
||||
这样后面:
|
||||
|
||||
- 训练完成后直接推理
|
||||
- human-in-loop record 里加载 policy
|
||||
- stage1 切 stage2
|
||||
|
||||
都会更自然,不需要再写很多原始 Evo1 仓库特有的胶水代码。
|
||||
|
||||
## 4. 与原始 Evo1 训练实现的关系
|
||||
|
||||
要注意,这次移植不是逐行复刻原始训练脚本,而是做了“语义尽量一致、工程上接入 LeRobot”的版本。
|
||||
|
||||
换句话说:
|
||||
|
||||
- 核心模型和两阶段训练思路是沿用原始 Evo1 的
|
||||
- 但训练执行框架已经变成 Evo-RL / LeRobot 这套
|
||||
|
||||
这意味着:
|
||||
|
||||
- 训练配置方式不同
|
||||
- checkpoint 组织方式不同
|
||||
- mixed precision / distributed wrapper 的工程边界也会和原始仓库不完全一样
|
||||
|
||||
所以如果后续要做“原始 Evo1 vs 接入版 Evo-RL Evo1”的严格对照实验,需要把:
|
||||
|
||||
- 数据
|
||||
- batch size
|
||||
- 卡数
|
||||
- precision
|
||||
- stage 切换方式
|
||||
|
||||
都尽量对齐后再看结果。
|
||||
|
||||
## 5. 当前建议的理解方式
|
||||
|
||||
最适合把现在这版 Evo1 接入看成:
|
||||
|
||||
- **不是一个临时脚本适配**
|
||||
- 而是把 Evo1 真正注册成了 LeRobot 里的一个 policy
|
||||
|
||||
这样后续无论是:
|
||||
|
||||
- 继续补多 embodiment
|
||||
- 对齐原始 Evo1 的训练细节
|
||||
- 修复 processor / tokenizer / checkpoint 可移植性问题
|
||||
|
||||
都可以在 LeRobot 统一框架里继续演进,而不用回到原始仓库那种“大而全训练脚本”上反复打补丁。
|
||||
在新工单中引用
屏蔽一个用户