Blame for data/s2_20pct/README.md

**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 个跳过。全量缓存构建需在接收方媒体和环境上执行。