code-Psi0-yth-v21 / plan_0.md
Tinghong-Ye22's picture
Add files using upload-large-folder tool
d8aa1ac verified
|
Raw History Blame Contribute Delete
12.9 kB
# Psi0 改造成 Text-to-Humanoid-Motion 计划(最小改动版)
## 0) 目标与约束
你的目标可以抽象成:
1. 输入:文本 caption(先不使用图像/音频)。
2. 输出:机器人动作序列(你定义为每帧 36 维,`29 dof + xyz + wxyz`)。
3. 训练策略:不走 pretrain,直接用 posttrain 框架,冻结 VLM,只训练 action expert(扩散动作头)。
4. 未来扩展:VLM 换到 `Qwen-2.5-Omni-3B`,当前先做 text-only smoke test。
5. 工程要求:尽可能少改现有代码。
下面的方案按这个目标严格展开。
---
## 1) 建议先看的代码(阅读顺序)
按这个顺序看,最快建立全局心智模型:
1. 训练主入口与配置注入
- `scripts/train.py`(训练循环、配置解析入口)
- `src/psi/config/config.py`(`LaunchConfig/TrainConfig/DataConfig/ModelConfig`)
- `src/psi/config/train/posttrain_he_psi0_config.py`
- `src/psi/config/train/posttrain_mix_psi0_config.py`
- `scripts/train/psi0/posttrain-he-psi0.sh`
2. posttrain trainer 主流程
- `src/psi/trainers/posttrain.py`
- `src/psi/trainers/trainer.py`
3. 数据层(raw -> transform -> batch)
- `src/psi/config/data_he.py`
- `src/psi/data/humanoid/he_raw_dataset.py`
- `src/psi/data/dataset.py`
- `src/psi/config/transform.py`(重点:`HEPosttrainRepackTransform`, `ActionStateTransform`, `Psi0ModelTransform`)
- `src/psi/trainers/qwen3vl_mixin.py`(`PaddedCollatorForTogether`)
4. 模型层(VLM + action expert)
- `src/psi/config/model_psi0.py`
- `src/psi/models/psi0.py`(重点:`Psi0Model.forward`, `ActionTransformerModel`, `ObservationProjection`)
5. 数据预处理脚本(参考)
- `scripts/data/raw_he_to_psi0.py`
- `scripts/data/raw_to_lerobot.py`
- `scripts/data/calc_modality_stats.py`
- `scripts/data/raw_dexmate_psi0.py`
---
## 2) 当前 posttrain 数据流和训练流(从数据处理开始)
## 2.1 训练入口与实例化
1. `scripts/train.py` 根据命令行第一个参数动态导入 config 模块(例如 `posttrain_he_psi0_config`)。
2. `Trainer.instantiate` 会按 `cfg.train.name` 选择 `psi.trainers.posttrain.PosttrainTrainer`。
3. 流程是固定的:`init_models -> create_datasets -> create_dataloaders -> create_optimizer_and_scheduler -> prepare -> training loop`。
对应代码:
- `scripts/train.py:169-219, 233-314, 350-360`
## 2.2 数据集原始样本(HE 例子)
`HERawDataset.__getitem__` 输出 raw dict,核心字段:
1. `observation.images.egocentric`: `(To, 3, H, W)`,默认 `To=1`。
2. `observation.hand_joints`, `observation.arm_joints`。
3. 展平后的 action 字段(例如 `action.joint_angles`)。
4. `task`(instruction 文本),`action_mask`,`obs_mask`。
对应代码:
- `src/psi/data/humanoid/he_raw_dataset.py:176-237`
## 2.3 三段 transform:repack -> field -> model
`MapStyleDataset.__getitem__` 会执行:
1. `repack`:把 raw 字段整理成统一结构。
2. `field`:做动作/状态归一化、padding、反归一化逻辑。
3. `model`:把图像+文本喂给 processor,生成 `input_ids/pixel_values/...`。
对应代码:
- `src/psi/data/dataset.py:23-26`
- `src/psi/config/transform.py`(`DataTransform.__call__`)
### repack(posttrain HE)
`HEPosttrainRepackTransform` 做的事:
1. 构造 `states`、`actions`。
2. 如果 `use_delta_actions=True`,将动作转成 delta(`actions[1:] - actions[:-1]`)。
3. 按 `pad_action_dim/pad_state_dim` 补齐。
4. 输出统一字段:`observations`, `states`, `actions`, `instruction`, `actions_mask` 等。
对应代码:
- `src/psi/config/transform.py:705-767`
### field(动作归一化)
`ActionStateTransform`:
1. 从 `stat_path` 读 `min/max` 或 `q01/q99`。
2. 对 `actions` 归一化到 `[-1,1]`。
3. 保留 `raw_actions`,给评估和反归一化使用。
对应代码:
- `src/psi/config/transform.py:408-578`
### model(构造 VLM 输入)
`Psi0ModelTransform`:
1. 图像 resize/crop/aug。
2. 构造 chat message:`[images] + text instruction`。
3. `vlm_processor(...)` 得到 `input_ids`, `attention_mask`, `pixel_values`, `image_grid_thw`。
4. 附带 `actions/states/actions_mask/raw_actions` 回传。
对应代码:
- `src/psi/config/transform.py:797-888`
## 2.4 collator 到 batch
`PaddedCollatorForTogether` 负责:
1. 对 `input_ids` padding。
2. 组装 `attention_mask`。
3. 强制 stack `pixel_values` 和 `image_grid_thw`。
4. stack `actions/states/actions_mask`。
这意味着目前代码路径默认“有视觉输入字段”。
对应代码:
- `src/psi/trainers/qwen3vl_mixin.py:87-157`
## 2.5 模型 forward(posttrain)
`PosttrainTrainer.forward_and_loss` 里调用:
1. 从 GT 动作加噪(flow 或 ddpm)。
2. `Psi0Model.forward(...)` 输入:
- `input_ids`, `attention_mask`, `pixel_values`, `image_grid_thw`
- `action_samples`(噪声动作)
- `states`
- `timestep`
3. `Psi0Model` 先跑 VLM 拿最后一层 hidden states,再喂 action expert(扩散动作头)。
4. 输出 `action_pred`,与目标噪声/速度算 MSE。
对应代码:
- `src/psi/trainers/posttrain.py:525-584`
- `src/psi/models/psi0.py:1602-1639`
## 2.6 训练损失与评估
1. loss 是动作维度 MSE,加 `actions_mask` 后按维度加权汇总。
2. `action_dim != 7` 时,默认均匀权重(你的 36 维会走这个分支)。
3. 评估里目前有固定分组切分 `[7,14,21]`,这是历史结构假设,对你的 36 维语义不一定成立。
对应代码:
- `src/psi/trainers/posttrain.py:55-64`
- `src/psi/trainers/posttrain.py:505-517`
---
## 3) 输入输出维度分别在哪里定义
### 3.1 动作/状态主维度
1. `--model.action-dim`:动作维度(你要设 36)。
2. `--model.odim`:状态维度(要和最终 `states` 最后一维一致)。
3. `--model.action-chunk-size`:每次预测 horizon(`Tp`)。
4. `--data.transform.repack.pad-action-dim`:repack 后动作 pad 到多少维。
5. `--data.transform.repack.pad-state-dim`:repack 后状态 pad 到多少维。
6. `--data.transform.field.pad-action-dim`:归一化统计也按这个维度对齐。
7. `--data.transform.field.pad-state-dim`:同上。
参考:
- `scripts/train/psi0/posttrain-he-psi0.sh:55-75`
- `src/psi/config/model_psi0.py:17-37`
- `src/psi/models/psi0.py:592-594, 757-761, 788, 1499-1503`
### 3.2 VLM hidden size 与 view_feature_dim
1. `ObservationProjection.views_proj = Linear(view_feature_dim -> hidden_dim)`。
2. 这里的 `view_feature_dim` 必须等于 VLM 最后一层 hidden size。
3. 当前脚本用 `--model.view_feature_dim=2048`(对应现有 Qwen3-VL-2B 配置)。
参考:
- `src/psi/models/psi0.py:499`
- `src/psi/models/psi0.py:1624, 1632`
- `scripts/train/psi0/posttrain-he-psi0.sh:75`
### 3.3 典型 batch 形状(当前 posttrain he 脚本)
1. `actions`: `(B, 16, 36)`
2. `states`: `(B, 1, 36)`(`observation_horizon=1`)
3. `input_ids`: `(B, L)`
4. `attention_mask`: `(B, L)`
5. `pixel_values`, `image_grid_thw`: 由 processor 决定
---
## 4) 面向你目标的最小改造方案
下面给两条路径,我建议先 A 再 B。
## 路径 A(最小改动,优先跑通)
核心思想:先保留现有视觉字段接口,不做“真正 text-only 张量路径”;数据侧喂一个固定占位图(dummy image),让模型主要学 text->motion。这样能最大复用 `Psi0ModelTransform + Collator + Psi0Model.forward`,代码改动最小。
你需要做:
1. 新增 `BoneSeedDataset`(或在现有 dataset 适配)输出统一字段:
- `observations`: 放一个固定 PIL 图(例如纯黑 240x320)
- `states`: `(To, 36)`,通常 `To=1`
- `actions`: `(Tp, 36)`
- `instruction`: caption
- `actions_mask`: `(Tp, 36)`
2. 新增一个 `DataConfig`(例如 `data_boneseed.py`)和一个训练 config(例如 `posttrain_boneseed_psi0_config.py`):
- `transform.repack`: 你的 `BoneSeedRepackTransform`
- `transform.field`: 复用 `ActionStateTransform`
- `transform.model`: 先复用 `Psi0ModelTransform`
3. 新增训练脚本(仿 `posttrain-he-psi0.sh`):
- 维度全设 36
- 先设置 `n_conditions=0`
- `tune_vlm=False`
- `noise_scheduler=flow`
优点:
1. 几乎不动模型与 trainer 主干。
2. 能最快 smoke test。
代价:
1. 严格来说不是“纯 text-only”实现,只是视觉分支恒定输入。
## 路径 B(真正 text-only)
需要改 3 个点:
1. `Psi0ModelTransform.build_qwenvl_inputs`:
- 允许 `imgs=[]`。
- `process_vision_info` 返回 `None` 时,仍可仅返回 text tokens。
2. `PaddedCollatorForTogether`:
- `pixel_values/image_grid_thw` 改成可选字段(存在才 stack)。
3. `Psi0Model.forward`:
- `pixel_values=None, image_grid_thw=None` 时也能调用 VLM。
- 对应 forward 参数改成 optional。
这是更“干净”的 text-to-motion 路径,但改动比 A 稍大。
---
## 5) Qwen-2.5-Omni-3B 替换要点
当前 posttrain 写死了 Qwen3 类:
1. `src/psi/trainers/posttrain.py` 里 import `Qwen3VLForConditionalGeneration`。
2. `src/psi/models/psi0.py` 类型标注也是 `Qwen3VLForConditionalGeneration`。
要换 Omni,最小做法:
1. 在 posttrain 里改成可切换 VLM 构造:
- `Qwen2_5OmniForConditionalGeneration` + `Qwen2_5OmniProcessor`(或 Auto 类统一封装)。
2. 保持 `output_hidden_states=True`,继续取最后一层 hidden states 作为 action expert 条件。
3. 校对 hidden size,并同步 `--model.view_feature_dim`。
你当前环境可用性(已验证):
1. `.venv-psi` 下 `transformers==4.57.0`。
2. 可 import:
- `Qwen2_5OmniForConditionalGeneration`
- `Qwen2_5OmniProcessor`
建议你自己再做一次快速确认:
```bash
.venv-psi/bin/python - <<'PY'
from transformers import Qwen2_5OmniForConditionalGeneration, Qwen2_5OmniProcessor
print("ok")
PY
```
再确认 hidden size(用于 `view_feature_dim`):
```bash
.venv-psi/bin/python - <<'PY'
from transformers import AutoConfig
cfg = AutoConfig.from_pretrained("Qwen/Qwen2.5-Omni-3B")
print("thinker hidden:", getattr(getattr(cfg, "thinker_config", None), "hidden_size", None))
print("hidden:", getattr(cfg, "hidden_size", None))
PY
```
---
## 6) 从数据处理开始的落地步骤(建议执行顺序)
1. 先定动作语义:
- 你的 36 维是绝对量还是 delta。
- 如果你数据已经是重定向后的绝对关节+位姿,优先 `use_delta_actions=False`,先简化问题。
2. 做 dataset 适配(最关键):
- 先写 `BoneSeedDataset.__getitem__`,把每个样本变成统一结构。
- 确保 `states/actions` 维度稳定。
- caption 映射到 `instruction`。
3. 生成统计文件(归一化必需):
- `ActionStateTransform` 需要 `stat_path`。
- 至少包含 `action` 键下的 `min/max` 或 `q01/q99`,维度 36。
4. 新建专用 config 与训练脚本:
- 先复用 posttrain trainer,不要改训练循环。
- 参数先直接对齐:`action_dim=36`, `odim=36`, `pad_*_dim=36`。
5. 再换 VLM 到 Omni:
- 先只做“文本+占位图”跑通。
- 然后再做严格 text-only 可选字段改造。
6. 最后做 smoke test:
- 1-2 个 batch overfit(`overfit_single_batch=True`)先看 loss 能不能快速下降。
---
## 7) 你现在就要注意的风险点
1. `HEPosttrainRepackTransform` 里有明显 typo:
- `obs_mask": datpa["obs_mask"]`,`datpa` 未定义。
- 位置:`src/psi/config/transform.py:766`
- 如果你复用这段逻辑,先修掉。
2. 评估指标分组写死(对 36 维不语义一致):
- `np.split(..., [7,14,21])`
- 位置:`src/psi/trainers/posttrain.py:512-517`
- 训练不一定受影响,但日志会误导。
3. 当前 collator/forward 对视觉字段是强依赖:
- 不改的话,text-only 会在 batch 组装处报错。
- 位置:`src/psi/trainers/qwen3vl_mixin.py:115-125`, `src/psi/models/psi0.py:1604-1622`
4. `view_feature_dim` 和 VLM hidden size 必须一致:
- 不一致会在线性层处 shape mismatch。
- 位置:`src/psi/models/psi0.py:499`
---
## 8) 最小改造文件清单(建议)
建议新增(而不是改老逻辑):
1. `src/psi/data/humanoid/boneseed_dataset.py`
2. `src/psi/config/data_boneseed.py`
3. `src/psi/config/train/posttrain_boneseed_psi0_config.py`
4. `scripts/train/psi0/posttrain-boneseed-psi0.sh`
如要做严格 text-only,再改:
1. `src/psi/config/transform.py`(`Psi0ModelTransform`)
2. `src/psi/trainers/qwen3vl_mixin.py`(`PaddedCollatorForTogether`)
3. `src/psi/models/psi0.py`(`Psi0Model.forward` optional vision args)
4. `src/psi/trainers/posttrain.py`(VLM 类替换成 Omni)
---
## 9) 一句话执行策略
先用“占位图 + 冻结 VLM + 只训 action expert”把 36 维 caption->motion 流程跑通,再把视觉输入改成 truly optional(text-only),最后替换到 Qwen2.5-Omni 并校准 `view_feature_dim`。