|
Download plan_0.md from Tinghong-Ye22/code-Psi0-yth-v21: direct link, hf CLI and curl.
- Browser
- Download file 12.9 kB
-
https://huggingface.co/Tinghong-Ye22/code-Psi0-yth-v21/resolve/main/plan_0.md
- Command line
-
hf download hf://Tinghong-Ye22/code-Psi0-yth-v21/plan_0.md
-
curl -L -o plan_0.md https://huggingface.co/Tinghong-Ye22/code-Psi0-yth-v21/resolve/main/plan_0.md
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`。 | |