Add S2 20% data manifests and standalone frame cache handoff

2c547e7 verified 2 days ago

7.3 kB

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

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