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
  1. posttrain trainer 主流程
  • src/psi/trainers/posttrain.py
  • src/psi/trainers/trainer.py
  1. 数据层(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)
  1. 模型层(VLM + action expert)
  • src/psi/config/model_psi0.py
  • src/psi/models/psi0.py(重点:Psi0Model.forward, ActionTransformerModel, ObservationProjection)
  1. 数据预处理脚本(参考)
  • 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)
  1. 新增一个 DataConfig(例如 data_boneseed.py)和一个训练 config(例如 posttrain_boneseed_psi0_config.py):
  • transform.repack: 你的 BoneSeedRepackTransform
  • transform.field: 复用 ActionStateTransform
  • transform.model: 先复用 Psi0ModelTransform
  1. 新增训练脚本(仿 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。
  1. PaddedCollatorForTogether:
  • pixel_values/image_grid_thw 改成可选字段(存在才 stack)。
  1. 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 类统一封装)。
  1. 保持 output_hidden_states=True,继续取最后一层 hidden states 作为 action expert 条件。

  2. 校对 hidden size,并同步 --model.view_feature_dim。

你当前环境可用性(已验证):

  1. .venv-psi 下 transformers==4.57.0。
  2. 可 import:
  • Qwen2_5OmniForConditionalGeneration
  • Qwen2_5OmniProcessor

建议你自己再做一次快速确认:

.venv-psi/bin/python - <<'PY'
from transformers import Qwen2_5OmniForConditionalGeneration, Qwen2_5OmniProcessor
print("ok")
PY

再确认 hidden size(用于 view_feature_dim):

.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,先简化问题。
  1. 做 dataset 适配(最关键):
  • 先写 BoneSeedDataset.__getitem__,把每个样本变成统一结构。
  • 确保 states/actions 维度稳定。
  • caption 映射到 instruction。
  1. 生成统计文件(归一化必需):
  • ActionStateTransform 需要 stat_path。
  • 至少包含 action 键下的 min/max 或 q01/q99,维度 36。
  1. 新建专用 config 与训练脚本:
  • 先复用 posttrain trainer,不要改训练循环。
  • 参数先直接对齐:action_dim=36, odim=36, pad_*_dim=36。
  1. 再换 VLM 到 Omni:
  • 先只做“文本+占位图”跑通。
  • 然后再做严格 text-only 可选字段改造。
  1. 最后做 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
  • 如果你复用这段逻辑,先修掉。
  1. 评估指标分组写死(对 36 维不语义一致):
  • np.split(..., [7,14,21])
  • 位置:src/psi/trainers/posttrain.py:512-517
  • 训练不一定受影响,但日志会误导。
  1. 当前 collator/forward 对视觉字段是强依赖:
  • 不改的话,text-only 会在 batch 组装处报错。
  • 位置:src/psi/trainers/qwen3vl_mixin.py:115-125, src/psi/models/psi0.py:1604-1622
  1. 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。