docs/FACT_MODEL_zh.md

FACT：无 track、预测未来状态、从头训练的 T-Rex 策略（finalized 2026-10-13）

FACT（Force-Aware Causal Transformer）是 trex_track_force 的轻量替代：

	trex_track_force (A)	trex notrack (B)	FACT base (finalized)	FACT small
coarse 去噪器	Wan2.2-TI2V-5B DiT，d=3072，30 层，LoRA r=4	同左，无 track token	从头训练 DiT 风格 block-causal transformer，d=1024，12 层，16 头，FFN 4096	d=768，8 层，12 头，FFN 3072
预测目标	动作 + 未来视频 latent + 250 点 track	动作 + 未来视频 latent	动作 + 未来 16 步 EEF62 状态	同左
条件	当前帧 VAE latent、state、umT5 文本、CLIP 图像	同左	当前帧 VAE latent（离线冻结 tokenizer）、state、可学习 task token	同左
force 阶段	ForceOnlyTransformer 768/6 层	同左	原样复用（coarse memory 1024→768）	同左
部署参数量	5.69 B（另加冻结 umT5-XXL / CLIP ViT-H / VAE 在线）	5.68 B	209 M（全部可训练；只有 VAE 离线冻结）	109 M
可训练参数	120 M（LoRA 11.6M + 新模块 60.7M + force 47.9M）	109 M	209 M	109 M
训练方式	LoRA 微调	LoRA 微调	从头训练	从头训练

缩小比例：部署参数 5686 M → 209 M（27×），small 版 → 109 M（52×）。

1. 结构

每个 autoregressive block（0.8 s）打包 83 个 token：[obs 50][state 1][action 16][future-state 16]， 前面一个可学习 task token。训练时 K=4 个 block（3.2 s）一次前向，block-causal mask：block k 只能读 blocks [k-4, k] 和 task token（与基线 max_chunk_size=4 一致）；在线 K=1。

• obs：当前帧三视角按 DreamZero 2×2 网格（head | right ; left | black）拼到 160×320，Wan2.2 VAE 编码成 48×10×20 latent，2×2 patch → 50 个 token，Linear(192→d)。VAE 冻结，训练前离线缓存。
• state：62 维 EEF62 补零到 64，MLP 到 d。clean，τ=0。
• action：16×62 delta-base 动作（与基线完全相同的归一化与参考系），补零 64，Linear(64→d)；noisy，τ 按 block 采样 Beta(1.5,1)。
• future state：block anchor 之后 1..16 步（20 Hz）的 EEF62 状态，相对 block 参考状态做 delta-base，用动作统计量归一化；noisy，与 action 共用 τ。
• 位置信息：slot embedding（83 个槽位）+ block embedding + token-type embedding（无 RoPE）。
• 每个 token 自己的 τ → sinusoidal(256) → MLP → per-token adaLN-zero（6 个调制向量，与 Wan 一样 可让不同模态处于不同噪声水平）；qk-RMSNorm；最终 adaLN + 两个线性 head（action flow / future-state flow）。
• coarse memory：最后一层 hidden state 中 block k 可见的全部 token（在线 K=1 时 84 个），交给 force 阶段。
• force 阶段：trex_track_force.force.ForceOnlyTransformer 原样复用（16 action + 10 F6 + 10 VQ history
  • memory），τ 0.4→0 四步、suffix-only、offset 0/4/8/12、tactile dropout 0.1、VQ/commitment loss 不变。

Loss：action_flow_mse + state_flow_mse + force_flow_mse + vq + 0.25·commitment，权重全为 1。 采样：6 步 coarse Euler（τ 1→0.4）→ τ=0.4 边界前向取 memory 与 clean future state → 4 步 force 精修；coarse_to_zero 模式用 coarse 模型自己走完 τ→0。

2. Benchmark（与 scripts/eval/trex_ablation_eval.py 相同协议）

data/trex_mini_force（trex_full_force 第 49 集，902 帧，“Past the block, use your left hand to pick up the lipstick from the table.”），全部 537 个 K=4 anchor 训练 3000 步，开环评测 16 个 K=1 anchor （seed 500+i），归一化 62 维 delta-base 动作 MSE。FACT：batch 8，lr 2e-4 cosine，AdamW，bf16，单块 PPU 约 45 min。

模型	参数	cascade ↓	coarse_only (τ=0.4 读出) ↓	coarse_to_zero ↓	arm / hand (cascade)
A trex_track_force	5.69 B	0.2054	0.3859	—	0.291 / 0.171
B trex notrack	5.68 B	0.2300	0.3834	—	0.298 / 0.202
D deform+force	5.69 B	0.2016	0.3860	—	0.286 / 0.167
FACT base (seed 42)	209 M	0.0049	0.2408	0.0048	0.007 / 0.004
FACT base (seed 7)	209 M	0.0045	0.2405	0.0045	0.007 / 0.004
FACT base, 无 future-state	209 M	0.0045	0.2388	0.0043	0.007 / 0.004
FACT small (768/8)	109 M	0.0076	0.2425	0.0049	0.013 / 0.005

固定 τ 的 action flow MSE（τ=0.2）：基线 0.75，FACT 0.039。

注意：这个 benchmark 和基线 ablation 一样是单集过拟合（评测 anchor 来自训练集），衡量的是在相同 预算下的拟合能力，不是泛化。为此额外做了 held-out 探针（只用前 80% 时间段的 417 个 anchor 训练， 评测最后 20% 的 16 个从未见过的 anchor）：

模型 (held-out)	cascade	coarse_only	coarse_to_zero	arm / hand
FACT base	0.504	0.613	0.479	0.278 / 0.596
FACT base 无 future-state	0.516	0.586	0.477	0.309 / 0.600
FACT small	0.491	0.582	0.442	0.285 / 0.575

读法：单集内 6 s 的 held-out 段是任务的另一阶段（hand 维误差 0.6），任何只见过一集的模型都不可能 泛化好；三者差异在 anchor 间标准差（±0.15）之内，不足以区分结构。future-state 在 arm 维略好 （0.278 vs 0.309）。force 精修在 held-out 上略差于 coarse_to_zero，说明 46 M 的 tactile 精修器在单集 数据上过拟合——它的价值（接触后的触觉反应）需要多集/真机才能体现。基线没有 held-out 数字，不可比。

3. Finalized 结构

scripts/fact/configs/fact_base.json（d=1024/12 层，预测 future state，force 阶段保留）。 理由：在正式协议上两种 seed 都是最优（0.0045–0.0049，比 A 好 42×、比 B 好 47×）， future-state 保留了与 T-Rex 一致的"预测未来"接口且在 held-out arm 上不劣，force 阶段保留 T-Rex 的 5 Hz 触觉刷新路径。fact_small.json（109 M）作为资源受限时的替代，正式协议 0.0076，held-out 略优。

4. 代码与运行

groot/vla/model/fact/model.py   FactConfig / FactCoarseTransformer / FactPolicy（forward_core, sample, refine_action_suffix）
groot/vla/model/fact/data.py    FactEpisode（parquet + 统计量 + latent 缓存）/ FactAnchorDataset
scripts/fact/build_cache.py     冻结 VAE 离线编码整集帧（0.9 s/集）
scripts/fact/train.py           从头训练；--config-json / --dim / --layers / --no-future-state / --no-force / --train-fraction
scripts/fact/eval.py            基线协议开环评测；--heldout-fraction
scripts/fact/param_count.py     参数量对比（meta device）
scripts/fact/run_exp.sh         cache → train → eval 一条龙；scripts/fact/collect.py 汇总表

source /mnt/workspace/zhicao/dreamzero/.fact_env          # PPU SDK + .venv_ppu
bash scripts/fact/run_exp.sh fact_base 8 --config-json "$(cat scripts/fact/configs/fact_base.json)" \
     --steps 3000 --batch 8 --lr 2e-4 --bf16 --workers 4
HELDOUT=0.2 bash scripts/fact/run_exp.sh probe 9 ... --train-fraction 0.8   # held-out 探针
python scripts/fact/collect.py fact_runs                                     # 汇总所有 eval.json

已训练的 checkpoint：fact_runs/v1_d1024_l12/final（finalized base，seed 42）、fact_runs/v1_d768_l8/final（small）。

5. 在 T-Rex-100（data/trex_small_force）上 16 卡从头全量训练（2026-10-13 新增）

多任务训练需要语言条件：fact_base_text.json 在 base 结构上加了冻结 umT5-XXL 的 token embedding 作为 clean prefix（64 token，LayerNorm+Linear(4096→d)，padding 用 attention mask 屏蔽）， 其余结构不变（209 M + 4.3 M 文本投影）。

scripts/train/fact_full_training_trex100.sh     入口（对标 trex_track_force_training_wan22.sh）
scripts/fact/build_cache_dataset.py             离线缓存：VAE latent（16 卡分片并行）+ umT5 文本
scripts/fact/train_ddp.py                       torchrun DDP 训练；wandb 标量 + 周期监控视频 + checkpoint/resume
scripts/fact/configs/fact_base_text.json        finalized base + 文本条件
groot/vla/model/fact/data.py                    FactMultiEpisodeDataset（100 集、mmap latent、文本缓存）

tmux attach -t fact
source /mnt/workspace/zhicao/dreamzero/.fact_env        # PPU SDK + .venv_ppu
wandb login                                              # 可选；没有 key 时脚本自动 WANDB_MODE=offline
bash scripts/train/fact_full_training_trex100.sh         # 16 卡、100k 步、每 10k 存一次

默认：global batch 16×8=128（每个样本 4 个 AR block）、lr 3e-4 cosine（warmup 2000）、wd 0.01、bf16、 输出 checkpoints/fact_trex100_full/（checkpoint-N/、train.log、loss_log.jsonl、eval_videos/）。 缓存在 fact_runs/cache/trex_small_force/（首次自动构建，约 67k 帧；之后直接复用）。 断点续训：再跑同一条命令即可（--resume auto 读 latest）。 可用环境变量覆盖：OUTPUT_DIR NUM_GPUS PER_DEVICE_BATCH LR MAX_STEPS SAVE_STEPS VIDEO_STEPS WANDB_PROJECT FACT_CONFIG。

W&B：train/*（loss、action/state/force/vq loss、grad_norm、lr、sec_per_it）；每 VIDEO_STEPS（默认 1000）步 在第 0 集连续 4 个 chunk 上采样，记录 eval/openloop_cascade_mse、eval/openloop_coarse_only_mse、 eval/future_state_mse 和 eval/predicted_video（左：head 相机 GT 帧按 20 Hz 推进；右：动作与未来状态 的预测 vs GT 曲线，黑 GT / 红 cascade / 蓝 coarse τ=0.4 / 绿 future-state）。FACT 不预测视频，所以 "视频重建"展示的是状态/动作重建。本地同样保存到 OUTPUT_DIR/eval_videos/train_step_XXXXXX.mp4。

注意：启动器必须用 venv 的 python -m torch.distributed.run（系统 torchrun 指向系统 python，缺 diffusers）； rank-0 单独采样时要关掉 tactile VQ 的 perplexity all-reduce（train_ddp.py 已处理），否则其它 rank 会卡死。