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
Psi0 改造成 Text-to-Humanoid-Motion 计划(最小改动版)
0) 目标与约束
你的目标可以抽象成:
- 输入:文本 caption(先不使用图像/音频)。
- 输出:机器人动作序列(你定义为每帧 36 维,
29 dof + xyz + wxyz)。 - 训练策略:不走 pretrain,直接用 posttrain 框架,冻结 VLM,只训练 action expert(扩散动作头)。
- 未来扩展:VLM 换到
Qwen-2.5-Omni-3B,当前先做 text-only smoke test。 - 工程要求:尽可能少改现有代码。
下面的方案按这个目标严格展开。
1) 建议先看的代码(阅读顺序)
按这个顺序看,最快建立全局心智模型:
- 训练主入口与配置注入
scripts/train.py(训练循环、配置解析入口)src/psi/config/config.py(LaunchConfig/TrainConfig/DataConfig/ModelConfig)src/psi/config/train/posttrain_he_psi0_config.pysrc/psi/config/train/posttrain_mix_psi0_config.pyscripts/train/psi0/posttrain-he-psi0.sh
- posttrain trainer 主流程
src/psi/trainers/posttrain.pysrc/psi/trainers/trainer.py
- 数据层(raw -> transform -> batch)
src/psi/config/data_he.pysrc/psi/data/humanoid/he_raw_dataset.pysrc/psi/data/dataset.pysrc/psi/config/transform.py(重点:HEPosttrainRepackTransform,ActionStateTransform,Psi0ModelTransform)src/psi/trainers/qwen3vl_mixin.py(PaddedCollatorForTogether)
- 模型层(VLM + action expert)
src/psi/config/model_psi0.pysrc/psi/models/psi0.py(重点:Psi0Model.forward,ActionTransformerModel,ObservationProjection)
- 数据预处理脚本(参考)
scripts/data/raw_he_to_psi0.pyscripts/data/raw_to_lerobot.pyscripts/data/calc_modality_stats.pyscripts/data/raw_dexmate_psi0.py
2) 当前 posttrain 数据流和训练流(从数据处理开始)
2.1 训练入口与实例化
scripts/train.py根据命令行第一个参数动态导入 config 模块(例如posttrain_he_psi0_config)。Trainer.instantiate会按cfg.train.name选择psi.trainers.posttrain.PosttrainTrainer。- 流程是固定的:
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,核心字段:
observation.images.egocentric:(To, 3, H, W),默认To=1。observation.hand_joints,observation.arm_joints。- 展平后的 action 字段(例如
action.joint_angles)。 task(instruction 文本),action_mask,obs_mask。
对应代码:
src/psi/data/humanoid/he_raw_dataset.py:176-237
2.3 三段 transform:repack -> field -> model
MapStyleDataset.__getitem__ 会执行:
repack:把 raw 字段整理成统一结构。field:做动作/状态归一化、padding、反归一化逻辑。model:把图像+文本喂给 processor,生成input_ids/pixel_values/...。
对应代码:
src/psi/data/dataset.py:23-26src/psi/config/transform.py(DataTransform.__call__)
repack(posttrain HE)
HEPosttrainRepackTransform 做的事:
- 构造
states、actions。 - 如果
use_delta_actions=True,将动作转成 delta(actions[1:] - actions[:-1])。 - 按
pad_action_dim/pad_state_dim补齐。 - 输出统一字段:
observations,states,actions,instruction,actions_mask等。
对应代码:
src/psi/config/transform.py:705-767
field(动作归一化)
ActionStateTransform:
- 从
stat_path读min/max或q01/q99。 - 对
actions归一化到[-1,1]。 - 保留
raw_actions,给评估和反归一化使用。
对应代码:
src/psi/config/transform.py:408-578
model(构造 VLM 输入)
Psi0ModelTransform:
- 图像 resize/crop/aug。
- 构造 chat message:
[images] + text instruction。 vlm_processor(...)得到input_ids,attention_mask,pixel_values,image_grid_thw。- 附带
actions/states/actions_mask/raw_actions回传。
对应代码:
src/psi/config/transform.py:797-888
2.4 collator 到 batch
PaddedCollatorForTogether 负责:
- 对
input_idspadding。 - 组装
attention_mask。 - 强制 stack
pixel_values和image_grid_thw。 - stack
actions/states/actions_mask。
这意味着目前代码路径默认“有视觉输入字段”。
对应代码:
src/psi/trainers/qwen3vl_mixin.py:87-157
2.5 模型 forward(posttrain)
PosttrainTrainer.forward_and_loss 里调用:
- 从 GT 动作加噪(flow 或 ddpm)。
Psi0Model.forward(...)输入:input_ids,attention_mask,pixel_values,image_grid_thwaction_samples(噪声动作)statestimestep
Psi0Model先跑 VLM 拿最后一层 hidden states,再喂 action expert(扩散动作头)。- 输出
action_pred,与目标噪声/速度算 MSE。
对应代码:
src/psi/trainers/posttrain.py:525-584src/psi/models/psi0.py:1602-1639
2.6 训练损失与评估
- loss 是动作维度 MSE,加
actions_mask后按维度加权汇总。 action_dim != 7时,默认均匀权重(你的 36 维会走这个分支)。- 评估里目前有固定分组切分
[7,14,21],这是历史结构假设,对你的 36 维语义不一定成立。
对应代码:
src/psi/trainers/posttrain.py:55-64src/psi/trainers/posttrain.py:505-517
3) 输入输出维度分别在哪里定义
3.1 动作/状态主维度
--model.action-dim:动作维度(你要设 36)。--model.odim:状态维度(要和最终states最后一维一致)。--model.action-chunk-size:每次预测 horizon(Tp)。--data.transform.repack.pad-action-dim:repack 后动作 pad 到多少维。--data.transform.repack.pad-state-dim:repack 后状态 pad 到多少维。--data.transform.field.pad-action-dim:归一化统计也按这个维度对齐。--data.transform.field.pad-state-dim:同上。
参考:
scripts/train/psi0/posttrain-he-psi0.sh:55-75src/psi/config/model_psi0.py:17-37src/psi/models/psi0.py:592-594, 757-761, 788, 1499-1503
3.2 VLM hidden size 与 view_feature_dim
ObservationProjection.views_proj = Linear(view_feature_dim -> hidden_dim)。- 这里的
view_feature_dim必须等于 VLM 最后一层 hidden size。 - 当前脚本用
--model.view_feature_dim=2048(对应现有 Qwen3-VL-2B 配置)。
参考:
src/psi/models/psi0.py:499src/psi/models/psi0.py:1624, 1632scripts/train/psi0/posttrain-he-psi0.sh:75
3.3 典型 batch 形状(当前 posttrain he 脚本)
actions:(B, 16, 36)states:(B, 1, 36)(observation_horizon=1)input_ids:(B, L)attention_mask:(B, L)pixel_values,image_grid_thw: 由 processor 决定
4) 面向你目标的最小改造方案
下面给两条路径,我建议先 A 再 B。
路径 A(最小改动,优先跑通)
核心思想:先保留现有视觉字段接口,不做“真正 text-only 张量路径”;数据侧喂一个固定占位图(dummy image),让模型主要学 text->motion。这样能最大复用 Psi0ModelTransform + Collator + Psi0Model.forward,代码改动最小。
你需要做:
- 新增
BoneSeedDataset(或在现有 dataset 适配)输出统一字段:
observations: 放一个固定 PIL 图(例如纯黑 240x320)states:(To, 36),通常To=1actions:(Tp, 36)instruction: captionactions_mask:(Tp, 36)
- 新增一个
DataConfig(例如data_boneseed.py)和一个训练 config(例如posttrain_boneseed_psi0_config.py):
transform.repack: 你的BoneSeedRepackTransformtransform.field: 复用ActionStateTransformtransform.model: 先复用Psi0ModelTransform
- 新增训练脚本(仿
posttrain-he-psi0.sh):
- 维度全设 36
- 先设置
n_conditions=0 tune_vlm=Falsenoise_scheduler=flow
优点:
- 几乎不动模型与 trainer 主干。
- 能最快 smoke test。
代价:
- 严格来说不是“纯 text-only”实现,只是视觉分支恒定输入。
路径 B(真正 text-only)
需要改 3 个点:
Psi0ModelTransform.build_qwenvl_inputs:
- 允许
imgs=[]。 process_vision_info返回None时,仍可仅返回 text tokens。
PaddedCollatorForTogether:
pixel_values/image_grid_thw改成可选字段(存在才 stack)。
Psi0Model.forward:
pixel_values=None, image_grid_thw=None时也能调用 VLM。- 对应 forward 参数改成 optional。
这是更“干净”的 text-to-motion 路径,但改动比 A 稍大。
5) Qwen-2.5-Omni-3B 替换要点
当前 posttrain 写死了 Qwen3 类:
src/psi/trainers/posttrain.py里 importQwen3VLForConditionalGeneration。src/psi/models/psi0.py类型标注也是Qwen3VLForConditionalGeneration。
要换 Omni,最小做法:
- 在 posttrain 里改成可切换 VLM 构造:
Qwen2_5OmniForConditionalGeneration+Qwen2_5OmniProcessor(或 Auto 类统一封装)。
保持
output_hidden_states=True,继续取最后一层 hidden states 作为 action expert 条件。校对 hidden size,并同步
--model.view_feature_dim。
你当前环境可用性(已验证):
.venv-psi下transformers==4.57.0。- 可 import:
Qwen2_5OmniForConditionalGenerationQwen2_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) 从数据处理开始的落地步骤(建议执行顺序)
- 先定动作语义:
- 你的 36 维是绝对量还是 delta。
- 如果你数据已经是重定向后的绝对关节+位姿,优先
use_delta_actions=False,先简化问题。
- 做 dataset 适配(最关键):
- 先写
BoneSeedDataset.__getitem__,把每个样本变成统一结构。 - 确保
states/actions维度稳定。 - caption 映射到
instruction。
- 生成统计文件(归一化必需):
ActionStateTransform需要stat_path。- 至少包含
action键下的min/max或q01/q99,维度 36。
- 新建专用 config 与训练脚本:
- 先复用 posttrain trainer,不要改训练循环。
- 参数先直接对齐:
action_dim=36,odim=36,pad_*_dim=36。
- 再换 VLM 到 Omni:
- 先只做“文本+占位图”跑通。
- 然后再做严格 text-only 可选字段改造。
- 最后做 smoke test:
- 1-2 个 batch overfit(
overfit_single_batch=True)先看 loss 能不能快速下降。
7) 你现在就要注意的风险点
HEPosttrainRepackTransform里有明显 typo:
obs_mask": datpa["obs_mask"],datpa未定义。- 位置:
src/psi/config/transform.py:766 - 如果你复用这段逻辑,先修掉。
- 评估指标分组写死(对 36 维不语义一致):
np.split(..., [7,14,21])- 位置:
src/psi/trainers/posttrain.py:512-517 - 训练不一定受影响,但日志会误导。
- 当前 collator/forward 对视觉字段是强依赖:
- 不改的话,text-only 会在 batch 组装处报错。
- 位置:
src/psi/trainers/qwen3vl_mixin.py:115-125,src/psi/models/psi0.py:1604-1622
view_feature_dim和 VLM hidden size 必须一致:
- 不一致会在线性层处 shape mismatch。
- 位置:
src/psi/models/psi0.py:499
8) 最小改造文件清单(建议)
建议新增(而不是改老逻辑):
src/psi/data/humanoid/boneseed_dataset.pysrc/psi/config/data_boneseed.pysrc/psi/config/train/posttrain_boneseed_psi0_config.pyscripts/train/psi0/posttrain-boneseed-psi0.sh
如要做严格 text-only,再改:
src/psi/config/transform.py(Psi0ModelTransform)src/psi/trainers/qwen3vl_mixin.py(PaddedCollatorForTogether)src/psi/models/psi0.py(Psi0Model.forwardoptional vision args)src/psi/trainers/posttrain.py(VLM 类替换成 Omni)
9) 一句话执行策略
先用“占位图 + 冻结 VLM + 只训 action expert”把 36 维 caption->motion 流程跑通,再把视觉输入改成 truly optional(text-only),最后替换到 Qwen2.5-Omni 并校准 view_feature_dim。