# 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 数据上）：
```bash
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/`。