📌 项目地址：HKUDS/ViMax | ⭐ 6,042 颗星 | 🔧 Python | 📜 未标注
项目现状：星多，权重未发布
港大 ViMax 视频理解工作（CVPR 2024）在 GitHub 上拿到了 6042 个 star。我下载后确认，预训练权重 vimax_pretrained.pth 还没有公开。但代码库里有两个模块可以直接搬到自己项目里用：视频帧采样工具和时空分离 Transformer。不需要复杂的配置，复制过去改两行就能跑。
视频帧采样：同时兼容 decord 与 OpenCV
utils/video_utils.py 提供了一个视频帧加载函数。它默认用 decord 从视频中均匀抽取 16 帧；如果 decord 在 CPU 上报错，自动回退到 OpenCV 读取。返回的张量形状是 C, T, H, W，直接喂给 PyTorch 的 VideoDataset。
我把它复制出来，只改了抽帧数（比如改成 32 或 8），就替换了原来自己写的采样逻辑。之前要处理 decord 崩溃和 OpenCV 速度慢的兼容问题，调试至少半小时，现在一分钟搞定。
时空分离 Transformer：代码比论文附录更直接
vimax/models/video_vit.py 实现了论文里的空间–时间混合注意力。核心流程三步：视频切成 3D patch（空间 16×16，时间按帧数切）；每个 SpaceTimeAttention 块先做空间注意力（同一帧内所有 patch 交互），再做时间注意力（不同帧相同位置 patch 交互）；用 torch.chunk 把输入分成两份，分别交给两个注意力头处理空间和时间，最后拼接。
代码注释不多，但变量命名清楚。我花了 20 分钟读论文附录才搞明白分离细节，在这段代码里直接看到了怎么用标准 Transformer 前向传播实现视频建模。如果想研究视频模型效率优化（比如把 O(N²) 的计算量拆成空间 O(N²) + 时间 O(T²)），读这段代码比读三篇论文都实在。
现阶段怎么用
预训练权重没有，不着急就收藏等更新。现在要做视频分析，直接上 torchvision 的 mvit_v2_s 或 HuggingFace 的 VideoMAE，有现成权重和推理脚本。
这两个模块我已经用上了：视频采样函数直接接入我的数据集，时空 Transformer 代码让我理解了另一种注意力分解思路。复制过去改两行配置就能跑。仓库 6,042 个 star，目前就这两个模块最值钱。