File size: 12,894 Bytes
d8aa1ac | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 | # 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`。
|