docs/RAPTOR_MODELS.md

RAPTOR 模型 / 脚本 / 数据 命名总表

模型名：RAPTOR — Refining Actions via Predicted Tactile Outcome Rollouts。 两级：Stage 1 = Track-Guided Coarse Planner（Wan2.2 DiT，video+track+action 联合流）； Stage 2 = Force–Action Joint Refiner（未来力与动作后缀共去噪，λ_f=0.5）。

四个规范模型

VARIANT	结构	关键 hydra 开关	角色
full	track + joint 力共去噪 (λ_f=0.5)	stage2_arch=joint + force_future_loss_weight=0.5 + memory_token_scope=obs_act	主模型
no_track	full − track 通路	上行 + use_track=false (policy+diffusion)	消融：track 的贡献
no_force	full − 整个 Stage 2	use_force=false + require_force_inputs=false	消融：精修阶段的贡献
vq_force	力经 VQ 离散化仅作条件输入	无 joint 开关（原 T-Rex Stage 2）	消融：连续 vs 离散力（T-Rex 基线）

训练脚本（scripts/train/）

脚本	用途
raptor_train.sh	统一入口：VARIANT=<四选一> TREX_DATA_ROOT=… OUTPUT_DIR=… bash raptor_train.sh；小规模默认 6000 步
raptor_full.sh [GPUS]	生产跑：full 模型，data/trex_full_force → checkpoints/raptor_full，100k 步。GPUS=数量("4"→卡0-3)或列表("2,3")；省略=全部可见卡。Resume 自动取 OUTPUT_DIR 里最新 checkpoint-*；PRETRAINED_CKPT=<dir> 只加载权重 warm start
trex_track_force_training_wan22.sh	底层引擎入口（数据校验、权重下载、torchrun）——两者的共同后端，勿直接删改

示例（四个消融在 small 数据上）：

for V in full no_track no_force vq_force; do
  VARIANT=$V TREX_DATA_ROOT=data/trex_small_force \
  OUTPUT_DIR=checkpoints/raptor_${V}_small6k CUDA_VISIBLE_DEVICES=0 \
  bash scripts/train/raptor_train.sh
done

数据集

目录	内容
data/trex_full	原始采集（5349 eps，32 列：58 维关节、60 维力、23 路视频；无 track/eef62/训练统计）
data/trex_full_force	可训练版 = trex_full 经 scripts/data/prepare_trex_track_force_training.sh（+track npz/列、+eef62 FK 列、+stats/manifest/ready）
data/trex_small / trex_small_force	100-episode 子集的同样一对（硬链接，视频不占双份）

现有 checkpoint

目录	是什么	状态
raptor_full	生产 full 模型（8 卡，trex_full_force，训练中）	含 optimizer states
raptor_full_small6k	full @ small 6k（灵巧度研究优胜配置）	仅推理权重
raptor_vq_force_small6k	vq_force @ small 6k（T-Rex 式基线）	仅推理权重
raptor_full_lf1_small6k	full 但 λ_f=1.0（研究对照，勿新用）	仅推理权重
ablate_{full,notrack,noforce,deform}_3k	mini-era A/B/C/D 消融存档（VQ 时代结构）	仅推理权重
trex_track_force_wan22_lora	T-Rex 96k 生产模型（历史基线）	完整（唯一全份）
dreamzero_trex_wan22_lora	更早的无 track/force 模型	仅推理权重

评测：scripts/eval/trex_ablation_eval.py（通用）与 trex_dexterity_eval.py（灵巧度专项）， 结果存 ablation_runs/。