# Data 本文只描述当前使用的 v4 数据体系。早期 v1 dense-text 数据和 v2 direct-K/V 数据已经完成其历史实验， 不再作为后续训练的数据标准。 ## 1. 数据集总览 当前训练数据集名称为 `hyworldplay_predictor_prefeature_v4`，schema 为 `predictor_context_prefeature_bf16_v1`。 | 项目 | 数值 | | --- | ---: | | 图文 pair | 100 | | 每个 pair 的动作轨迹 | 4 | | 轨迹总数 | 400 | | 每个视频帧数 | 125 | | latent frames | 32 | | 每条轨迹 chunks | 8 | | 每个 chunk latent frames | 4 | | 每个 chunk 去噪步 | 4 | | 完整 manifest records | 3200 | | 可训练 records | 2800 | | 每个 record 的监督 pair | `0→1`、`1→2`、`2→3` | | 训练 pair 总数 | 8400 | | Context blocks | `[0,1,52,53]` | | 保存精度 | BF16 safetensors | | 实际 NVMe 占用 | 约 1.3 TB | `train_eval_manifest.jsonl` 排除 chunk 0，因为 v4 需要前一 chunk 的 same-timestep hidden； `predictor-disca` 为保持相同训练分布也沿用这 2800 条记录，但不会加载 previous-chunk hidden 或 Context pre-feature。 ## 2. 数据来源和图像预处理 训练图文 pair 来自： ```text /mnt/s3files/s3-us-west2-default/zoubin/cz/projects/VBench/ vbench2_beta_i2v/data/origin ``` 选择方法： 1. 按路径名排序全部图片； 2. 使用 Python `random.Random(0).sample(...)` 随机选择 100 张； 3. caption 使用源图片文件名去掉扩展名后的文本； 4. 图像先保持宽高比，用 Lanczos 放大至覆盖目标区域，再做中心裁剪； 5. 保存为 832×480 JPEG，quality 95、无 chroma subsampling。 预处理入口： ```bash python tools/prepare_predictor_prefeature_cases.py ``` 输出为 `cases.jsonl`、`dataset_config.json` 和 `input_images/case_XXXX.jpg`。 ## 3. 动作与视频配置 四种动作轨迹固定为： | action_id | 名称 | pose | | ---: | --- | --- | | 0 | `w_s` | `w-15,s-16` | | 1 | `a_d` | `a-15,d-16` | | 2 | `up_down` | `up-15,down-16` | | 3 | `left_right` | `left-15,right-16` | 生成配置为 seed 0、480×832、125 帧、32 latent frames、8 chunks、每 chunk 4 latent frames、 每个 chunk 4 个去噪步。构建训练 tensor 的同时保存每条轨迹对应的 125 帧 MP4，作为训练集 Full-DiT 评测参考视频。 ## 4. Teacher 数据语义 Teacher 使用 HY-WorldPlay action-distilled AR checkpoint： ```text /mnt/s3files/s3-us-west2-default/zoubin/cz/checkpoints/hy_worldplay/ huggingface/hub/models--tencent--HY-WorldPlay/snapshots/ f4c29235647707b571479a69b569e4166f9f5bf8/ ar_distilled_action_model/diffusion_pytorch_model.safetensors ``` 数据构建使用精确 Full-DiT 路径： - 四个去噪步都运行完整 54 层； - 保留正式 WorldPlay text K/V 和 AR history vision memory； - 关闭 denoise cache、history cache reuse、Context pooling/pruning； - 关闭 sparse attention、SageAttention 和 FP8 GEMM； - `prompt_rewrite=false`； - Transformer 与落盘 feature 使用 BF16； - offloading 只影响显存，不改变模型定义。 Context prefill 的语义是 `joint_noncausal_full_dit_prefill`：同一目标 chunk 选中的历史帧作为完整窗口 联合、非因果计算。因此深层 pre-feature 与目标窗口绑定，不能将历史 chunk 跨窗口去重。 ## 5. 文件组织 ```text hyworldplay_predictor_prefeature_v4/ ├── dataset_config.json ├── cases.jsonl ├── manifest.jsonl # 3200 records ├── train_eval_manifest.jsonl # 2800 records，排除 chunk 0 ├── input_images/ # 100 张 832×480 图像 ├── cases/ # 100 个 case tensors ├── text_kv_exact_all54_bf16/ # 100 个 Full Teacher 54 层 Text K/V ├── steps/ # 3200 个 chunk step tensors │ └── case_XXXX/action_YY/chunk_ZZ.safetensors ├── context_prefeature/ # 12800 个 pre-feature tensors │ ├── block_00/ │ ├── block_01/ │ ├── block_52/ │ └── block_53/ ├── videos/ # 400 个 Full-DiT MP4 ├── manifests/ # 8 个 worker manifests └── logs/ ``` 实际空间分布： | 目录 | 文件数 | 大小 | | --- | ---: | ---: | | `cases/` | 100 | 2.97 GB | | `text_kv_exact_all54_bf16/` | 100 | 37.20 GiB | | `steps/` | 3200 | 337.60 GB | | `context_prefeature/` | 12800 | 1022.63 GB | | `videos/` | 400 | 0.40 GB | | `input_images/` | 100 | 0.02 GB | ## 6. Tensor schema ### 6.1 Case tensor 每个 case 只保存一次图像条件和四个候选 block 的 Text K/V： ```text image_condition_latent [1,32,1,30,52] BF16 block_{00,01,52,53}_k_txt [1,16,903,128] BF16 block_{00,01,52,53}_v_txt [1,16,903,128] BF16 text_valid_mask [1,903] bool ``` Text K/V 在磁盘中补齐到 903 tokens，真实长度由 `text_valid_mask` 指示。 ### 6.2 Full Teacher Text K/V `text_kv_exact_all54_bf16/` 是离线数据集的一部分，不是 pre-feature，也不是 rollout sidecar。每个 case 一个文件： ```text case_XXXX_text_kv_exact_all54_bf16.safetensors block_{00..53}_k_txt [1,16,903,128] BF16 block_{00..53}_v_txt [1,16,903,128] BF16 text_valid_mask [1,903] bool ``` 真实有效长度为 739–751 tokens，训练读取时按 `text_valid_mask` 去掉补零区，再交给 Teacher/Predictor。 构建会将 blocks `0、1、52、53` 与原 case tensor 逐元素比对，确保它来自相同的 frozen text prefill。 ### 6.3 Step tensor 每个 chunk 保存共享动作/相机/RoPE 信息，以及四个去噪步的监督目标： ```text action_labels [1,4] int64 target_viewmats [1,4,4,4] BF16 target_Ks [1,4,3,3] BF16 rope_temporal_size [1] int64 start_rope_start_idx [1] int64 step_{0..3}_timestep [1] FP32 step_{0..3}_noisy_sample [1,32,4,30,52] BF16 step_{0..3}_frame_condition [1,4,2048] BF16 step_{0..3}_final_hidden [1,6240,2048] BF16 step_{0..3}_velocity [1,32,4,30,52] BF16 ``` 65 通道 Predictor 输入不重复落盘。Dataset 使用 noisy sample、case-level image latent 和 I2V mask 重建 `[B,65,4,30,52]` 输入。 ### 6.4 Context pre-feature 每个 record、每个 block 保存 K/V 线性投影之前的 `img_modulated`： ```text img_modulated [1,S_context,2048] BF16 context_valid_mask [1,S_context] bool selected_frame_indices [context_frames] int64 context_viewmats [1,context_frames,4,4] BF16 context_Ks [1,context_frames,3,3] BF16 rope_temporal_size [1] int64 start_rope_start_idx [1] int64 ``` `S_context = context_frames × 30 × 52`。八个 chunks 的 Context frames 依次为 `0,4,8,12,16,20,20,20`。磁盘文件保持变长且不 padding；v4 collate 按 batch 最大 Context 长度 动态 padding，并用 valid mask 屏蔽补齐部分。 训练时由冻结的 Teacher `img_attn_k`、`img_attn_v`、`img_attn_k_norm` 和相同的 RoPE/ProPE 路径 重建 Context Vision K/V。直接 K/V 与重建 K/V 的验收阈值为 relative L2 ≤ 5e-3、cosine ≥ 0.9999。 ## 7. Manifest 关系 主键是 `(case_id, action_id, chunk_id)`。每条记录包含 case、step、四个 Context 文件的相对路径， 以及 caption、源图、动作、seed、分辨率、Teacher checkpoint 和 Context frame 数。 合并 manifest 时： - 检查 3200 个主键唯一； - 验证所有引用文件存在； - chunk 1–7 增加 `previous_chunk_id` 和 `previous_step_tensor_file`； - `manifest.jsonl` 保留全部 3200 条； - `train_eval_manifest.jsonl` 保留 chunk 1–7，共 2800 条。 ## 8. 构建、恢复和持久化 NVMe 是构建和训练读取位置，S3 是持久化 source of truth： ```text NVMe: /mnt/local_nvme/zoubin/cz/hyworldplay_predictor_prefeature_v4 S3: s3://s3-us-west2-default/zoubin/cz/projects/ HY-WorldPlay-DEV-Predictor/datasets/hyworldplay_predictor_prefeature_v4 项目挂载路径: /mnt/s3files/s3-us-west2-default/zoubin/cz/projects/ HY-WorldPlay-DEV-Predictor/datasets/hyworldplay_predictor_prefeature_v4 ``` 完整构建流程： ```bash python tools/prepare_predictor_prefeature_cases.py bash tools/launch_predictor_prefeature_build.sh ``` 第二条命令使用 8 个 GPU worker，先写 NVMe，随后合并 manifest 并同步到 S3。writer 支持按 `case/action/chunk` 跳过完整文件，任务中断后可重新执行。 全 54 层精确 Text K/V 单独构建并持久化到同一数据集： ```bash bash tools/launch_predictor_text_kv_all54_build.sh ``` 新机器训练前执行： ```bash bash tools/ensure_predictor_prefeature_nvme.sh ``` 需要全层 Text K/V 的 rollout 训练再执行： ```bash bash tools/ensure_predictor_text_kv_all54_nvme.sh ``` 如果 NVMe 不完整，该脚本使用 `aws s3 sync` 从持久前缀恢复并重新检查数量。手动将合法更新同步回 S3 使用： ```bash bash tools/sync_predictor_prefeature_to_s3.sh ``` 不要把 NVMe 当作唯一副本，也不要在未核对目标前缀时使用 `aws s3 sync --delete`。 ## 9. 完整性验收 ```bash python tools/validate_predictor_prefeature_dataset.py ``` 验收条件： - 100 case tensors； - 3200 step tensors； - 12800 Context pre-feature tensors； - 400 个 125 帧、832×480 视频； - 3200 条无重复 manifest records 和 2800 条训练 records； - 所有 tensor shape、dtype、finite、mask 和 Context frame 数正确； - 四个 block 的 selected frame indices 一致； - frozen final layer 能由 final hidden 与 frame condition 复现 velocity； - 抽样重建的 65 通道输入与 Teacher 实际输入一致。 ## 10. Validation/Test holdout 独立评估集为 `hyworldplay_predictor_vbench_val25_test50`： - VBench metadata 共 355 个 pair； - 排除训练集 100 个 pair 后剩 255 个； - 使用 seed `20260718` 随机选择 75 个； - validation 25 个、test 50 个，两者互斥且均与训练集互斥； - 每个 pair 生成四种动作； - 已保存 300 个 Full-DiT 和 300 个 Reuse 视频； - Full 为 steps `[0,1,2,3]`，Reuse 为 Full `[0,3]`、复用 `[1,2]`。 入口： ```bash bash tools/launch_vbench_holdout_full_reuse.sh ``` 持久目录： ```text datasets/hyworldplay_predictor_vbench_val25_test50 ```