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`。