5 分钟跑通 V-JEPA：自监督视频表征学习新手实战指南

5 分钟跑通 V-JEPA自监督视频表征学习新手实战指南【免费下载链接】jepaPyTorch code and models for V-JEPA self-supervised learning from video.项目地址: https://gitcode.com/GitHub_Trending/je/jepaV-JEPAVideo Joint Embedding Predictive Architecture是 Meta 开源的视频自监督表征学习框架不标注、不重建像素只靠看视频帧就能学出可用的视觉特征。这篇指南带你完成环境安装、本地启动预训练、跑通 frozen 探针评测三步并把真正影响行为的配置参数逐行讲清楚。三步跑通 V-JEPA克隆、安装、单卡起训环境准备与安装项目要求 Python ≥ 3.9依赖在 requirements.txt 里核心是 PyTorch 2.x、decord视频解码、submitit分布式提交git clone https://gitcode.com/GitHub_Trending/je/jepa cd jepa conda create -n jepa python3.9 pip conda activate jepa python setup.py install # 会按 requirements.txt 安装全部依赖仓库结构很克制四个顶层目录各司其职README 中的 Code Structure 一节app/ 唯一允许写训练循环的地方入口在 app/main.py evals/ 冻结骨干的探针评测入口在 evals/main.py src/ 数据集、模型、掩码、工具包 configs/ 唯一允许放配置文件的地方pretrain/ 与 evals/ 分开放所有实验参数都通过 YAML 配置文件传入没有命令行超参——这一点决定了你调参的方式是改 YAML而不是加 --xxx。准备视频数据 CSVV-JEPA 预训练是无监督的数据侧只需要一个 CSV 索引文件格式为绝对路径 任意整数标签预训练阶段标签列会被直接忽略填 0 即可/path/to/video1.mp4 0 /path/to/video2.mp4 0 /path/to/video3.mp4 0注意两点路径必须是绝对路径如果要跑有监督的视频分类评测evals/video_classification_frozen/则必须把这一列换成真实类别标签。改配置并启动本地预训练以最小的 configs/pretrain/vith16.yaml 为例启动前只需改三处路径data: datasets: - /your_path/to/video_index.csv # 你上面准备的 CSV 索引 logging: folder: /your/absolute/path/logs # 日志与 checkpoint 目录必须是存在的绝对路径然后在仓库根目录执行官方示例app/main.py 会为每张卡 spawn 一个进程python -m app.main \ --fname configs/pretrain/vith16.yaml \ --devices cuda:0 cuda:1 cuda:2跑起来后你会在logging.folder下看到params-pretrain.yaml实际生效配置的回写和逐步保存的 checkpoint。一个诚实的提醒官方在 README 中明确说明本地单机的作用是调试代码与数据管线复现论文结果需要 16 节点 × 8 GPU 的分布式训练nodes: 16, tasks_per_node: 8那部分见文末进阶一节。原理速览为什么 V-JEPA 不用像素重建用三句话说清核心机制从视频里随机挖掉若干时空块剩下的区域叫 context被挖掉的叫 target编码器只把 context 区域编码成特征一个更小的 predictor 网络在潜在空间里预测被挖区域的特征损失算在特征空间预测特征 vs. 目标编码器给出的真值特征全程不接触像素重建、负样本或文本标注。这就是 JEPAJoint-Embedding Predictive Architecture的思想落到视频上的版本模型学到的是视频接下来会发生什么的表征级理解而不是逐像素拟合。掩码的生成逻辑在 src/masks/模型定义在 src/models/。预训练配置逐行拆解data、mask、model、optimization下面按 configs/pretrain/vith16.yaml 拆四组真正影响行为的参数。data 段决定模型看到什么data: num_frames: 16 # 每个片段取 16 帧 tubelet_size: 2 # 时序管片大小每 2 帧合并成一个 patch sampling_rate: 4 # 帧采样间隔 crop_size: 224 # 空间裁剪分辨率 patch_size: 16 # 空间 patch 大小 batch_size: 24 # 每卡 batch size显存不够时优先调它 filter_short_videos: false # 是否过滤过短视频16 帧 ÷ tubelet 2 8 个时序位置空间 224 ÷ 16 14×14即每个视频约 1568 个 token。mask 段决定挖掉多少默认是两级掩码对应data.mask_type: multiblock3d实现在 src/masks/multiblock3d.pymask: - num_blocks: 8 # 挖 8 个小块 spatial_scale: [0.15, 0.15] # 每块空间占比约 15%细粒度 temporal_scale: [1.0, 1.0] # 覆盖全部时间整段都要预测 - num_blocks: 2 # 再挖 2 个大块 spatial_scale: [0.7, 0.7] # 每块空间占比 70%粗粒度细块 大块的双尺度设计让模型同时学局部纹理和整段运动。想换另一种策略随机时间管状掩码把data.mask_type改成random_tube即可对应实现是 src/masks/random_tube.py。model 段决定多大多小model: model_name: vit_huge # 骨干规格可选 vit_tiny~vit_gigantic pred_depth: 12 # predictor 层数 pred_embed_dim: 384 # predictor 隐层宽度比骨干窄省算力 use_mask_tokens: true # 用 2 个可学习 mask token 作为预测输入骨干选项在 src/models/vision_transformer.py 中定义vit_tiny到vit_giganticpredictor 在 src/models/predictor.py。改model_name就能换骨干规模是显存紧张时最直接的开关。optimization 与 meta 段调度与精度optimization: epochs: 300 # 训练轮数 warmup: 40 # 学习率线性预热轮数 lr: 0.000625 # 峰值学习率 clip_grad: 10.0 # 梯度裁剪阈值 ema: [0.998, 1.0] # 双 EMA 的衰减率区间 meta: use_sdpa: true # 使用 PyTorch 缩放点积注意力省显存 dtype: bfloat16 # 混合精度A100 及以上推荐老卡改 float32实战场景冻结骨干 轻量探针评测V-JEPA 落地时的标准姿势是骨干完全冻结只训一个 attentive probe。这比端到端微调便宜一个数量级且能直接复用官方 checkpoint。场景一Kinetics-400 视频分类下载官方 pretrained checkpointvith16.pth.tarREADME 的 MODEL ZOO 一节有链接放到本地目录准备 K400 训练/验证的 CSV 索引这次标签列必须写真实类别修改 configs/evals/vith16_k400_16x8x3.yaml 中的data.dataset_train、data.dataset_val和pretrain.folder本地起评测python -m evals.main \ --fname configs/evals/vith16_k400_16x8x3.yaml \ --devices cuda:0 cuda:1配置里eval_name: video_classification_frozen指定了用 evals/video_classification_frozen/eval.pyframes_per_clip: 16, num_segments: 8, num_views_per_segment: 3即 16 帧 × 8 段 × 3 视图的评测协议这也是文件名后缀16x8x3的来历。场景二换骨干 / 换分辨率收益有多大下面这张表直接来自 README 的 MODEL ZOOfrozen 骨干 attentive probe 的 top-1 accuracy单位 %可以当作改造前 vs 改造后的选型参考数据集ViT-L 224ViT-H 224ViT-H 384K40016x8x380.882.081.9SSv216x2x369.571.472.2ImageNet-1K74.875.977.4Places20560.361.762.8iNat2167.867.972.6结论很清晰分类密集、语义细的任务SSv2、iNat21对分辨率更敏感224→384 能拿到 0.8~4.7 个点动作分类K400上换 ViT-H 反而略低于 384 版选型要看任务。对应的五个数据集评测配置都在 configs/evals/ 下各有一个vith16_*.yaml改pretrain.checkpoint路径即可复用。常见问题速查现象原因解决方式启动即报params-pretrain.yaml写失败logging.folder不存在或不是绝对路径app/main.py 启动时就写这个文件先手动创建目录改为绝对路径README 明确要求启动前更新配置内所有路径视频加载崩溃 / 解出空帧decord 不支持该编码或视频被截断损坏换 mp4 等通用容器格式把data.filter_short_videos设为true过滤异常样本训练 OOM默认batch_size: 24× 16 帧 × 224 分辨率占用较高先降data.batch_size再考虑降model_name或crop_sizebfloat16相关报错老 GPUAmpere 之前对 bf16 支持不全把meta.dtype改为float32app/vjepa/train.py 中会自动关闭混合精度跑有监督评测时标签全是 0CSV 标签列沿用预训练的占位 0按 README 要求把标签列替换为真实类别标签本地跑和论文数字对不上官方复现依赖 16 节点 × 8 GPU 分布式本地版仅用于调试接受本地只验证管线复现数字走 SLURM 分布式见进阶进阶分布式提交与掩码策略扩展SLURM 三步起分布式训练入口是 app/main_distributed.py基于 submitit--folder指定 stdout/stderr 落盘目录--partition指定队列评测同理用 evals/main_distributed.py。加掩码变体mask段是列表追加一条num_blocksspatial_scale组合即可增加一个尺度每个字段语义见 src/masks/multiblock3d.py 中_MaskGenerator的参数如max_temporal_keep控制 context 可保留的最大时间比例。换骨干规模model.model_name支持vit_tiny / vit_small / vit_base / vit_large / vit_huge / vit_giant / vit_gigantic配套配置参照 configs/pretrain/ 下三份 YAML 的写法。官方三个 pretrained checkpointViT-L 224、ViT-H 224、ViT-H 384均训于 90K iterations、VideoMix2M及全部探针 checkpoint 的下载地址都列在 README 的 MODEL ZOO 一节配合上面的评测配置可以直接复现表中数字。【免费下载链接】jepaPyTorch code and models for V-JEPA self-supervised learning from video.项目地址: https://gitcode.com/GitHub_Trending/je/jepa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考