docs(evo1): add handoff notes

这个提交包含在:
javadcc_mac
2026-03-24 23:38:57 +08:00
父节点 26d1bd40d4
当前提交 a50887e846
共有 2 个文件被更改,包括 161 次插入 和 13 次删除

查看文件

@ -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 日常训练的默认路径。

查看文件

@ -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 统一框架里继续演进,而不用回到原始仓库那种“大而全训练脚本”上反复打补丁。