video_datasets_api：统一加载EPIC-Kitchens与Something-V1的视频数据集工具

简介这是一套面向计算机视觉研究者与深度学习开发者的视频数据集工具库聚焦EPIC-Kitchens、Something-Something-V1、HMDB-51等主流动作识别基准数据集的标准化接入与预处理。资源提供统一API接口、帧提取脚本、标注解析模块及训练/验证集划分工具显著降低多数据集实验环境搭建门槛特别适合算法复现、模型微调与跨数据集对比研究。压缩包共41个文件含27个Python核心模块如something_something_v1、epic_tools、hmdb_tools等、10个Shell自动化脚本支持视频解帧、RAR解压、目标检测图像生成等、2个Markdown说明文档及基础配置文件整体仅44KB轻量易集成。已有878人学习下载用户可直接调用NUM_CLASSES等常量、复用extract_frames.sh等成熟流程、参考object_detector.py等示例实现快速启动目录按数据集分层组织结构清晰开箱即用。1. 为什么你下载了 EPIC-Kitchens 和 Something-Something-V1 却跑不起来训练这个 API 工具包就是为解决「数据加载黑匣子」而生的你花两小时配好 PyTorch又花三小时调通模型结构结果DataLoader一启动就报KeyError: participant_id或OSError: No such file or directory: S1/P01/rgb_frames/...——不是代码写错了是视频数据集的组织逻辑和你默认的ImageFolder思维根本不在一个维度。EPIC-Kitchens 的动作标注嵌在 CSV 里帧路径要拼 participant video_id timestampSomething-Something-V1 的每个样本是独立.webm文件但标签名和文件名映射关系藏在labels.json和train_videofolder.txt两个不同格式的元数据中。更麻烦的是官方提供的脚本只支持单机单卡、固定分辨率预处理一旦你要做多尺度裁剪、时序采样对齐、或跨数据集联合训练比如用 Something-V1 做预训练、EPIC 做下游微调就得重写整套数据流水线。video_datasets_api就是把这种重复劳动封装成可插拔模块的工具它不替换 PyTorch DataLoader而是提供统一Dataset接口、预置解析器、可组合的 transform 链以及关键的「元数据缓存机制」——首次加载后生成.pkl索引后续秒级重建数据集实例。适合正在做视频理解、动作识别、时序建模的算法工程师和研究生尤其当你已经卡在「数据准备阶段超过三天」时它不是锦上添花是止损刚需。2. 用 video_datasets_api 在本地跑通 EPIC-Kitchens 和 Something-Something-V1 的最小命令2.1 安装与环境校验避开 CUDA 版本错位导致的视频解码静默失败video_datasets_api不依赖特定深度学习框架但底层视频 I/O 依赖decord推荐或torchvision.io。实测发现若系统已装torchvision0.15.2cu118但decord编译时链接的是cuda-11.7则VideoReader在读取 EPIC-Kitchens 的 H.264 编码.mp4时会返回空帧且不报错——这是最隐蔽的翻车点。因此安装必须显式指定 CUDA 版本对齐# 先确认 nvcc 版本 nvcc --version # 输出应为 Cuda compilation tools, release 11.8, V11.8.89 # 卸载冲突的 decord pip uninstall decord -y # 从源码编译确保 CUDA_PATH 正确 git clone https://github.com/dmlc/decord.git cd decord make -j$(nproc) USE_CUDA1 CUDA_PATH/usr/local/cuda-11.8 cd python pip install -e . cd ../..提示USE_CUDA1必须开启否则decord默认用 CPU 解码EPIC-Kitchens 单个视频 3000 帧会拖慢数据加载 5 倍以上。验证是否生效from decord import VideoReader vr VideoReader(path/to/epic_video.mp4, ctxdecord.gpu(0)) # 成功即返回 decord._ffi.runtime.NDArray object2.2 初始化 EPIC-Kitchens 数据集解析 annotation CSV 并构建 frame-level 索引EPIC-Kitchens 的核心难点在于其「三级目录 多表关联」结构EPIC_100_train.csv包含participant_id,video_id,start_frame,stop_frame,noun_class,verb_class而实际帧文件存于frames_rgb_resized/P01/P01_01/000001.jpg。video_datasets_api通过EpicKitchensDataset类自动完成路径拼接与时间戳对齐from video_datasets_api.epic_kitchens import EpicKitchensDataset from torch.utils.data import DataLoader # 关键参数说明 # root_dir: 指向 EPIC-Kitchens 数据根目录含 frames_rgb_resized/ 和 annotations/ 子目录 # split: train / validation / test决定读取哪个 CSV # frame_rate: 实际采样帧率非原始帧率如设为 1.0 则每秒取 1 帧 # num_frames: 每个 clip 提取的帧数如 16用于 SlowFast 输入 dataset EpicKitchensDataset( root_dir/data/epic_kitchens, splittrain, frame_rate1.0, num_frames16, transformNone # 后续章节详述 transform 链 ) # 验证索引是否正确生成首次运行会生成 cache/epic_kitchens_train.pkl print(fDataset size: {len(dataset)}) # 应输出 EPIC_100_train.csv 行数 sample dataset[0] print(fSample keys: {sample.keys()}) # 应含 video, label, metadata print(fVideo shape: {sample[video].shape}) # torch.Size([16, 3, 224, 224])逻辑说明EpicKitchensDataset.__getitem__内部执行三步操作① 根据participant_id和video_id拼出帧目录绝对路径② 用start_frame和stop_frame计算该动作片段总帧数按frame_rate等间隔采样num_frames个索引③ 调用decord.VideoReader批量读取对应帧并转为 tensor。注意frame_rate是逻辑采样率与视频原始帧率无关——EPIC-Kitchens 原始帧率是 50fps但你设frame_rate1.0时系统会从start_frame到stop_frame均匀选 16 个点再用最近邻法取帧避免因帧率不整除导致的时序偏移。2.3 初始化 Something-Something-V1 数据集处理 webm 文件与 label 映射的双重异构Something-Something-V1 的挑战在于「文件即样本」范式每个.webm是一个完整动作视频但标签不存于文件名而需查labels.jsonid→label name和train_videofolder.txt文件路径→label id。video_datasets_api的SomethingV1Dataset将此过程抽象为LabelMapperfrom video_datasets_api.something_something import SomethingV1Dataset # root_dir: 指向 something-something-v1/ 目录含 20bn-something-something-v1/ 子目录 # split: train / val / test # label_map_path: 可选若未提供则自动从 labels.json 构建 dataset SomethingV1Dataset( root_dir/data/something-something-v1, splittrain, label_map_path/data/something-something-v1/labels.json, num_frames8, frame_rate6.0, # Something 视频平均时长 3s6fps → 18帧取前8帧 transformNone ) # 检查 label 映射是否准确 print(fLabel count: {len(dataset.label_map)}) # 应为 174 print(fFirst 3 labels: {list(dataset.label_map.items())[:3]}) # 输出示例[(0, adjust), (1, assemble), (2, clean)]参数说明frame_rate6.0是经验值——Something 视频无固定时长但统计显示 95% 视频在 2.5~3.5 秒间设 6fps 可保证多数样本能采够 8 帧若视频过短1.5sSomethingV1Dataset会自动循环填充repeat mode避免IndexError。关键细节train_videofolder.txt中的路径是相对路径如1234567890/1234567890.webmSomethingV1Dataset会自动拼接到root_dir/20bn-something-something-v1/下无需手动调整。3. 把 EPIC 和 Something 数据集喂进模型可复用的 transform 链与 batch 组织策略3.1 视频专用 transform为什么不能直接用 torchvision.transforms普通图像 transform如RandomHorizontalFlip作用于单帧但视频需要「时序一致性」同一 clip 内所有帧必须应用相同的随机翻转、裁剪参数否则模型看到的是「前半段人脸朝左、后半段朝右」的诡异序列。video_datasets_api提供VideoTransform基类其子类RandomResizedCropVideo和ColorJitterVideo通过get_params()预生成随机种子再广播到所有帧from video_datasets_api.transforms import ( RandomResizedCropVideo, ColorJitterVideo, NormalizeVideo, ToTensorVideo ) # 定义 transform 链顺序执行 train_transform [ RandomResizedCropVideo( size(224, 224), scale(0.5, 1.0), # 随机缩放比例 ratio(0.75, 1.333), # 随机宽高比 interpolationbilinear ), ColorJitterVideo( brightness0.2, contrast0.2, saturation0.2, hue0.1 ), ToTensorVideo(), # [T,H,W,C] → [T,C,H,W] NormalizeVideo( mean[0.485, 0.456, 0.406], std[0.229, 0.224, 0.225] ) ] # 注意必须用 ComposeVideo 包裹而非 torchvision.transforms.Compose from video_datasets_api.transforms import ComposeVideo transform ComposeVideo(train_transform) # 应用到数据集 dataset EpicKitchensDataset( root_dir/data/epic_kitchens, splittrain, transformtransform, num_frames16 )逻辑说明RandomResizedCropVideo.get_params()在__call__首次被调用时生成(i, j, h, w)四元组裁剪起始坐标与尺寸后续对[T,C,H,W]tensor 的每帧都复用该参数确保时序连续性。ToTensorVideo与NormalizeVideo的区别在于前者将uint8转float32并除以 255后者仅做均值方差归一化——二者不可合并因为ColorJitterVideo需要float32输入。3.2 DataLoader 的 batch 组织解决视频 tensor 形状不一致的 padding 策略视频数据天然存在长度差异EPIC-Kitchens 动作片段从 20 帧到 500 帧不等Something-V1 视频从 10 帧到 200 帧。若直接collate_fndefault_collatePyTorch 会因形状不匹配报RuntimeError: invalid argument 0: Sizes of tensors must match。video_datasets_api提供VideoCollator其核心是「动态 padding mask」from video_datasets_api.collators import VideoCollator # 创建 collatorpad_value0 表示用黑色帧填充 collator VideoCollator( pad_value0, max_len32, # 所有 batch 内视频统一 pad 到 32 帧 return_maskTrue # 返回 attention_mask标记有效帧位置 ) dataloader DataLoader( datasetdataset, batch_size8, shuffleTrue, num_workers4, collate_fncollator # 替换默认 collate_fn ) for batch in dataloader: video batch[video] # [B, T, C, H, W]T32 mask batch[mask] # [B, T]True 表示原始帧False 表示 pad 帧 label batch[label] # [B] print(fBatch video shape: {video.shape}, mask shape: {mask.shape}) break参数说明max_len32是平衡内存与效率的经验值——EPIC-Kitchens 99% 动作片段 ≤30 帧Something-V1 95% ≤25 帧设 32 可覆盖绝大多数样本padding 帧数极少。return_maskTrue对 transformer 类模型至关重要mask可直接输入nn.MultiheadAttention的key_padding_mask参数让模型忽略 pad 帧的注意力权重。3.3 跨数据集联合训练用 DatasetWrapper 统一接口避免 if-else 分支当你要用 Something-V1 预训练、EPIC-Kitchens 微调时传统写法需在训练循环中加if dataset_name something判断极易出错。video_datasets_api的DatasetWrapper提供统一字段协议from video_datasets_api.wrappers import DatasetWrapper # 封装两个数据集 something_dataset SomethingV1Dataset( root_dir/data/something-something-v1, splittrain, num_frames8, transformtransform ) epic_dataset EpicKitchensDataset( root_dir/data/epic_kitchens, splittrain, num_frames16, transformtransform ) # 用 Wrapper 标准化字段名 wrapped_something DatasetWrapper( datasetsomething_dataset, video_keyvideo, label_keylabel, metadata_keys[video_id, duration] # Something 有 video_idEPIC 有 participant_id ) wrapped_epic DatasetWrapper( datasetepic_dataset, video_keyvideo, label_keylabel, metadata_keys[participant_id, video_id] ) # 合并数据集按需加权重 from torch.utils.data import ConcatDataset combined_dataset ConcatDataset([wrapped_something, wrapped_epic]) # 现在所有样本都有统一结构 sample combined_dataset[0] print(fUnified keys: {sample.keys()}) # {video, label, metadata} print(fMetadata keys: {sample[metadata].keys()}) # {video_id} or {participant_id, video_id}逻辑说明DatasetWrapper不修改原始数据集仅在__getitem__返回前重命名字段并注入metadata字典。ConcatDataset能无缝衔接因为wrapped_something和wrapped_epic的__len__和__getitem__接口完全一致。血泪经验不要试图用Subset对两个数据集做等长采样——EPIC 样本数约 10 万Something 约 11 万但类别分布极不均衡强行等长会导致某些 EPIC 动作类别在 batch 中消失。4. 避坑EPIC-Kitchens 和 Something-Something-V1 数据加载的 4 个高频翻车点4.1 现象FileNotFoundError: [Errno 2] No such file or directory: P01/P01_01/000001.jpg原因EPIC-Kitchens 官方提供的frames_rgb_resized目录结构是frames_rgb_resized/P01/P01_01/000001.jpg但部分镜像站如 Kaggle下载后解压为frames_rgb_resized/P01_01/000001.jpg缺失P01/一级目录。EpicKitchensDataset按标准路径拼接自然找不到。解决检查root_dir/frames_rgb_resized/下是否存在P01/子目录。若不存在执行修复脚本cd /data/epic_kitchens/frames_rgb_resized for d in P*_*; do if [[ -d $d ]] [[ ! -d ${d%%_*} ]]; then mkdir ${d%%_*} mv $d ${d%%_*}/ fi done4.2 现象decord._ffi.base.DECORDError: [11:59:23] /decord/src/video/video_reader.cc:123: Check failed: stream-is_open() Failed to open video stream原因decord无法解码.webm文件常见于 Something-Something-V1。根本原因是libvpx编解码器未正确链接——decord编译时若未找到libvpx-dev会回退到ffmpeg但ffmpeg对 webm 支持不稳定。解决重新编译decord并强制启用libvpxsudo apt-get install libvpx-dev libvpx7 cd decord make clean make -j$(nproc) USE_CUDA1 USE_VPX1 cd python pip install -e .4.3 现象ValueError: Expected more than 1 value per channel when training, got input size torch.Size([1, 3, 224, 224])原因BatchNorm2d层在 batch_size1 时失效而 EPIC-Kitchens 的某些稀有动作如verb_class237在 train split 中仅出现 1 次DataLoader的shuffleTrue可能导致该样本独占一个 batch。解决在DataLoader中设置drop_lastTrue或改用SyncBatchNorm分布式训练时。更稳妥的是在数据集层面过滤低频类别# 统计 EPIC train split 中 verb_class 频次 from collections import Counter verb_freq Counter([item[verb_class] for item in pd.read_csv(/data/epic_kitchens/annotations/EPIC_100_train.csv)[verb_class]]) # 过滤频次 50 的 verb_class valid_verbs set([v for v, c in verb_freq.items() if c 50]) # 在 EpicKitchensDataset.__init__ 中添加 filter_func dataset EpicKitchensDataset( ..., filter_funclambda x: x[verb_class] in valid_verbs )4.4 现象RuntimeError: stack expects each tensor to be equal size, but got [16, 3, 224, 224] at entry 0 and [8, 3, 224, 224] at entry 1原因ConcatDataset合并 EPIC16帧和 Something8帧时default_collate无法堆叠不同 T 的 tensor。即使你用了VideoCollator但如果两个数据集的num_frames参数不一致VideoCollator的max_len会按各自num_frames设置导致 batch 内 tensor 形状仍不一致。解决必须在初始化数据集时统一num_frames。EPIC-Kitchens 用 16 帧SlowFast 标准Something-V1 也设为 16 帧并调整frame_rate保证覆盖全视频# Something-V1原视频平均 3s设 frame_rate5.33 → 16帧 something_dataset SomethingV1Dataset( ..., num_frames16, frame_rate5.33 # 3s * 5.33fps ≈ 16帧 ) # EPIC-Kitchens保持原参数 epic_dataset EpicKitchensDataset( ..., num_frames16, frame_rate1.0 )5. 进阶技巧用元数据缓存加速 10 倍数据集加载以及自定义动作分割策略5.1 元数据缓存机制详解.pkl文件里到底存了什么video_datasets_api的核心性能优化是「元数据缓存」。首次初始化数据集时它会遍历所有 annotation 文件解析出每个样本的绝对路径、帧数、时长、标签 ID并序列化为.pkl文件如cache/epic_kitchens_train.pkl。后续加载跳过耗时的 CSV 解析和路径拼接直接反序列化。我们来解剖这个缓存文件import pickle import pandas as pd # 加载缓存文件 with open(/data/epic_kitchens/cache/epic_kitchens_train.pkl, rb) as f: cache pickle.load(f) print(fCache keys: {cache.keys()}) # 输出dict_keys([samples, label_map, version, timestamp]) # samples 是核心列表每个元素是字典 sample0 cache[samples][0] print(fSample0 keys: {sample0.keys()}) # 输出dict_keys([video_path, start_frame, end_frame, verb_class, noun_class, participant_id, video_id]) # 验证 video_path 是否真实存在 import os print(fPath exists: {os.path.exists(sample0[video_path])}) # True print(fFrame count: {sample0[end_frame] - sample0[start_frame] 1}) # 如 120缓存内容说明video_path是拼接后的绝对路径如/data/epic_kitchens/frames_rgb_resized/P01/P01_01/start_frame/end_frame是动作起止帧号verb_class/noun_class是整数标签。关键洞察video_path指向目录而非文件因为 EPIC-Kitchens 以帧序列形式存储EpicKitchensDataset在__getitem__中才根据start_frame/end_frame读取具体帧文件。这比缓存所有帧路径更节省空间一个目录路径 100 字节 vs 100 帧路径 10KB。5.2 自定义动作分割用TemporalSegmentSampler替代固定帧采样EPIC-Kitchens 的start_frame/end_frame定义了精确动作区间但固定采样如每秒 1 帧可能错过关键帧。video_datasets_api提供TemporalSegmentSampler将动作区间划分为 N 个 segment每个 segment 内随机采 1 帧增强时序鲁棒性from video_datasets_api.samplers import TemporalSegmentSampler # 初始化 sampler将动作区间分成 16 个 segment每个 segment 采 1 帧 sampler TemporalSegmentSampler( num_segments16, num_frames_per_segment1, random_shiftTrue # segment 边界随机偏移 ±10% 区间长度 ) # 在 EpicKitchensDataset 中使用 dataset EpicKitchensDataset( root_dir/data/epic_kitchens, splittrain, temporal_samplersampler, # 替代 frame_rate/num_frames 参数 transformtransform )工作原理假设某动作start_frame100,end_frame200共 101 帧num_segments16→ 每个 segment 长度约 6.3 帧。random_shiftTrue会让 segment 1 的范围在[100, 106±0.6]内浮动然后在此范围内随机选 1 帧。相比固定采样它能覆盖动作全过程的微小变化实测在 EPIC-Kitchens 上提升 top-1 准确率 0.8%。5.3 验证数据加载正确性三步黄金检查法在投入 GPU 训练前必须验证数据流无误。我总结的三步法如下第一步检查样本内容sample dataset[0] print(fVideo dtype: {sample[video].dtype}) # torch.float32 print(fVideo range: [{sample[video].min():.2f}, {sample[video].max():.2f}]) # 应在 [0.0, 1.0] 归一化后 print(fLabel type: {type(sample[label])}) # int 或 torch.tensor第二步可视化前 3 帧import matplotlib.pyplot as plt import numpy as np # 取第一帧C,H,W→ (H,W,C) → uint8 frame0 (sample[video][0].permute(1,2,0).numpy() * 255).astype(np.uint8) plt.figure(figsize(12,4)) for i in range(3): plt.subplot(1,3,i1) plt.imshow((sample[video][i].permute(1,2,0).numpy() * 255).astype(np.uint8)) plt.title(fFrame {i}) plt.show()提示若图像全黑检查NormalizeVideo是否在ToTensorVideo前调用顺序错误会导致负值被截断。第三步检查 batch 统计batch next(iter(dataloader)) print(fBatch video shape: {batch[video].shape}) # [B, T, C, H, W] print(fLabel shape: {batch[label].shape}) # [B] print(fMask sum: {batch[mask].sum(dim1)}) # 每个样本的有效帧数应接近 num_frames # 示例输出tensor([16, 16, 16, 16, 16, 16, 16, 16])这三步能在 2 分钟内定位 90% 的数据加载问题。我曾在一个项目中因ToTensorVideo和NormalizeVideo顺序颠倒导致模型 loss 一直为 nan用第三步检查发现batch[video]的值域是[-2.5, 2.5]立刻修正。希望帮到你。现在你可以把 EPIC-Kitchens 和 Something-Something-V1 当作两个普通Dataset对象来用了——不用再为路径拼错、帧数不一致、标签映射混乱而反复调试。真正的挑战应该留给模型结构和损失函数设计。本文还有配套的精品资源点击获取