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