Add S2 20% data manifests and standalone frame cache handoff

Publish the current 147,718 image and 220,011 video training records, unique media lists, 64-frame cache source indices, standalone CPU frame extraction code, and usage instructions.

data/s2_20pct/README.md

@@ -0,0 +1,147 @@
+**S2 20% 训练数据与 64 帧缓存交接包**
+
+本包导出于 2026-11-08，包含 VisionEncoder 当前 Qwen S2 20% 配方实际使用的图像、视频名单与问答，以及生成对应视频帧缓存所需的代码。媒体文件从原始数据集中按名单提取。
+
+**下载**
+
+[完整交接包](https://huggingface.co/xiaomoguhzz/VisionEncoder/resolve/main/data/s2_20pct/s2_20pct_handoff_20261108.tar.gz?download=true) · [图像名单](https://huggingface.co/xiaomoguhzz/VisionEncoder/resolve/main/data/s2_20pct/image_files.txt?download=true) · [视频名单](https://huggingface.co/xiaomoguhzz/VisionEncoder/resolve/main/data/s2_20pct/video_files.txt?download=true)
+
+```bash
+curl -L --fail \
+  'https://huggingface.co/xiaomoguhzz/VisionEncoder/resolve/main/data/s2_20pct/s2_20pct_handoff_20261108.tar.gz?download=true' \
+  -o s2_20pct_handoff_20261108.tar.gz
+tar -xzf s2_20pct_handoff_20261108.tar.gz
+cd s2_20pct_handoff_20261108
+```
+
+后续命令均在解压后的目录中执行。
+
+**数据范围**
+
+| 类型 | 训练记录数 | 唯一媒体数 | 原始数据集 |
+|---|---:|---:|---|
+| 图像 | 147,718 | 122,247 张 | LLaVA-NeXT-Data |
+| 视频 | 220,011 | 105,108 个 | LLaVA-Video-178K |
+
+“20%”是历史数据档名称，以标注记录为单位。图像随机采样，视频按来源等额目标采样。视频的一个来源数量不足，因此历史过滤前的 220,038 条记录约占合并标注池的 19.37%。当前版本剔除了 12 个解码不完整视频对应的 27 条问答，保留 220,011 条记录。
+
+训练记录数与唯一媒体数不同，同一图像或视频可以对应多条训练记录。本包保留当前训练数据的全部问答、记录重复次数和相对顺序。105,108 个唯一视频均有对应的采帧索引。
+
+原始视频标注池使用 caption 与开放式 QA。现有名单已经确定具体子集，使用时直接按名单提取媒体，并使用包内问答，无需重新随机采样或合并原始标注。
+
+**文件说明**
+
+| 文件 | 用途 |
+|---|---|
+| `image_files.txt` | 去重图像名单，每行一个相对路径 |
+| `video_files.txt` | 去重视频名单，每行一个相对路径 |
+| `image_train.jsonl` | 147,718 条图像训练记录，含 `messages` 和相对路径 `images` |
+| `video_train.jsonl` | 220,011 条视频训练记录，含 `messages` 和相对路径 `videos` |
+| `video_frames_source.jsonl` | 唯一视频的相对路径、总帧数、帧率和 64 个采样索引 |
+| `prepare_paths.py` | 根据本机数据根目录生成绝对路径问答与采帧索引 |
+| `frames.yaml` | 64 帧、384×384、JPEG quality 95 的缓存配置 |
+| `requirements.txt` | 已通过单视频检查的环境依赖版本 |
+| `declip_qwenvit/`、`configs/` | 抽帧、分片写入和配置读取所需的代码子集 |
+| `counts.json` | 样本数、媒体数与视频来源统计 |
+
+问答为 `role` / `content` 格式。图像占位符为 `<image>`，视频占位符为 `<video>`。这些 JSONL 是问答级数据，未携带特定模型的 tokenizer、packing 或 `lengths` 缓存。
+
+**1. 从原始数据集提取媒体**
+
+准备一个同时包含以下两个数据集目录的数据根目录，保留各数据集内部的原始路径：
+
+```text
+/path/to/full_datasets/
+  LLaVA-NeXT-Data/
+    llava_next_raw_format/
+      coco/...
+      ...
+  LLaVA-Video-178K/
+    0_30_s_youtube_v0_1/...
+    0_30_s_academic_v0_1/...
+    ...
+```
+
+替换以下两个路径。`RAW_DATA_ROOT` 指向完整原始数据的父目录，`S2_DATA_ROOT` 指向要保存提取结果的目录：
+
+```bash
+RAW_DATA_ROOT=/path/to/full_datasets
+S2_DATA_ROOT=/path/to/s2_datasets
+
+mkdir -p "$S2_DATA_ROOT"
+rsync -a --files-from=image_files.txt "$RAW_DATA_ROOT/" "$S2_DATA_ROOT/"
+rsync -a --files-from=video_files.txt "$RAW_DATA_ROOT/" "$S2_DATA_ROOT/"
+```
+
+名单中的部分视频文件没有扩展名，按名单原样保留即可。复制后的目录仍以 `LLaVA-NeXT-Data/` 和 `LLaVA-Video-178K/` 开头。
+
+如果直接使用已解压好的原始媒体，可以把后续的 `S2_DATA_ROOT` 设为原始数据根目录，省略复制。
+
+**2. 安装环境并替换本机路径**
+
+使用 Linux、Python 3.11 环境。抽帧在 CPU 上完成，依赖 PyTorch，但不需要 GPU 或模型权重。`requirements.txt` 固定了本次检查所用的版本，其中 PyAV 为 15.1.0。
+
+```bash
+python -m pip install -r requirements.txt
+
+python prepare_paths.py \
+  --data-root "$S2_DATA_ROOT"
+```
+
+生成文件位于 `prepared/`：
+
+- `image_train.local.jsonl`：图像问答与本机绝对路径。
+- `video_train.local.jsonl`：视频问答与本机绝对路径。
+- `video_frames.local.jsonl`：本机绝对路径、总帧数和采帧索引。
+
+训练时使用两份 `*_train.local.jsonl`，即可保留当前 S2 的问答集合和顺序。训练框架仍按所用模型执行自己的预处理。
+
+**3. 先检查一个视频**
+
+以下命令只处理一个视频，写入单独的输出目录：
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 python -m declip_qwenvit.data_prep.tasks frames \
+  --config frames.yaml \
+  --limit 1 \
+  --num-workers 1 \
+  --output frame_cache_smoke/384/64
+```
+
+正常结果应为 `RGB cache: 1 records, 0 skipped`。如有失败，查看日志中的具体视频路径和错误。
+
+**4. 构建全部视频帧缓存**
+
+单视频检查通过后执行：
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 python -m declip_qwenvit.data_prep.tasks frames \
+  --config frames.yaml \
+  --num-workers 8
+```
+
+默认使用 8 个 CPU worker，每个解码器 1 个线程。按机器 CPU 和存储能力调整 `--num-workers`。
+
+缓存采用当前记录的 64 个均匀采帧索引，通过 PyAV seek 解码，使用双三次插值将每帧缩放到 384×384，再把 64 帧拼为 4×16 的 JPEG 图，quality 为 95。每个 JPEG 对应一个唯一视频，JPEG 保存在 TAR 分片内。默认每片处理 256 个视频。
+
+输出目录为 `frame_cache/384/64/`：
+
+- `part-*.tar`：JPEG 帧拼图分片。
+- `part-*.done.json`：各分片完成记录。
+- `index.jsonl`：视频路径、分片、字节偏移、大小、帧索引与帧率。
+- `metadata.json`：帧数、分辨率和拼图布局。
+- `failures.jsonl`：失败视频及错误，成功完成时应为空。
+
+完整成功时，最终日志应报告 `105108 records, 0 skipped`。缓存读取方需支持上述 TAR 索引格式，并将 JPEG 拼图还原为 64 帧。
+
+**5. 中断后续跑**
+
+保持输入、配置和输出目录一致，重新运行全量命令即可。现有实现会复用同时存在 TAR 和完成记录的分片，未完成分片重新生成。单视频检查目录与全量目录分开使用。
+
+**代码与验证范围**
+
+代码来自 VisionEncoder 现有的帧缓存构建实现。交接包仅调整了本地视频解码的 Swift 文件读取、日志和环境变量依赖，使本流程可独立运行，采帧、缩放与写入逻辑沿用原实现。
+
+`configs/utils/loader.py` 保留其 MMEngine 来源与 Apache-2.0 声明，对应许可证副本为 `LICENSE-APACHE-2.0`。
+
+2026-11-08 已从当前训练缓存导出记录并核对媒体数量，全部 105,108 个视频均有采帧索引。独立代码包已在一个真实视频上完成抽帧，结果为 1 个成功、0 个跳过。全量缓存构建需在接收方媒体和环境上执行。

data/s2_20pct/counts.json

@@ -0,0 +1,28 @@
+{
+  "image": {
+    "training_records": 147718,
+    "unique_media": 122247
+  },
+  "video": {
+    "training_records": 220011,
+    "unique_media": 105108,
+    "frame_index_records": 105108,
+    "paths_without_frame_index": 0,
+    "unique_media_by_source": {
+      "0_30_s_academic_v0_1": 11639,
+      "0_30_s_youtube_v0_1": 24441,
+      "1_2_m_academic_v0_1": 4627,
+      "1_2_m_youtube_v0_1": 17575,
+      "2_3_m_academic_v0_1": 3122,
+      "2_3_m_youtube_v0_1": 17620,
+      "30_60_s_academic_v0_1": 10200,
+      "30_60_s_youtube_v0_1": 15884
+    }
+  },
+  "frame_cache": {
+    "frames": 64,
+    "resolution": 384,
+    "jpeg_quality": 95,
+    "sheet_cols": 16
+  }
+}

data/s2_20pct/s2_20pct_handoff_20261108.tar.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e9d1223f077ccc8965d30d9abc6638506048d992dba8d913920d63fce0880eb6
+size 126493982