JEPA4Japan · 教程
ZH

第 21 章——官方仓库地图

1,176字 4分钟阅读 #LeVJEPA#JEPA#视频自监督学习#SIGReg

定位 main.py、module.py、data/loader.py、Hydra 配置、两个 notebook、许可证与固定代码快照。

课程进度 课程大纲 已发布 34/34 课

第 0 部分——先拿到地图

  1. 01 第 0 章——开始之前：这门课承诺什么 已发布
  2. 02 第 1 章——同一段视频，两扇不同的窗 已发布
  3. 03 第 2 章——沿着 Yann LeCun 的科研路线走一遍 已发布
  4. 04 第 3 章——别被名字绕晕：JEPA 家族树 已发布

第 1 部分——为什么简单目标会学会看视频

  1. 05 第 4 章——视频可以自己出题 已发布
  2. 06 第 5 章——保留意思，不重画每个像素 已发布
  3. 07 第 6 章——两张卡要相同，但不能全变成白纸 已发布
  4. 08 第 7 章——SIGReg：从许多影子检查一团点云 已发布
  5. 09 第 8 章——只用一行目标函数读懂 LeVJEPA 已发布

第 2 部分——把一段视频送进单编码器

  1. 10 第 9 章——全局视图与局部视图怎样配对 已发布
  2. 11 第 10 章——把视频切成时空小方块 已发布
  3. 12 第 11 章——一台编码器、一个投影头、一张摘要卡 已发布
  4. 13 第 12 章——一次完整前向传播 已发布
  5. 14 第 13 章——为什么扔掉 95% 反而更会看 已发布
  6. 15 第 14 章——块因果注意力：同一帧互看，未来不能偷看 已发布
  7. 16 第 15 章——RoPE、逐帧 token 与意外长出的密集特征 已发布

第 3 部分——会读实验，才算读懂论文

  1. 17 第 16 章——四组消融究竟回答了什么 已发布
  2. 18 第 17 章——相同轮数不等于相同花费 已发布
  3. 19 第 18 章——ImageNet、K400、SSv2 各考什么 已发布
  4. 20 第 19 章——把论文结果记成一本账 已发布
  5. 21 第 20 章——哪些结论现在还不能说 已发布

第 4 部分——从官方仓库到自己的实验

  1. 22 第 21 章——官方仓库地图 当前课程
  2. 23 第 22 章——Walking Tours：十段长视频怎样变成训练数据 已发布
  3. 24 第 23 章——读懂默认配置并启动训练 已发布
  4. 25 第 24 章——先跑一个不会骗人的冒烟测试 已发布
  5. 26 第 25 章——不用训练：加载公开权重提取特征 已发布
  6. 27 第 26 章——在自己的视频上做冻结评估 已发布

第 5 部分——把表征接回世界模型路线

  1. 28 第 27 章——重要边界：LeVJEPA 不是规划器 已发布
  2. 29 第 28 章——怎样把 LeVJEPA 接到下一代世界模型 已发布
  3. 30 第 29 章——十个从入门到论文级的研究项目 已发布

附录——随用随查的技术背包

  1. 31 附录 A——最低限度数学工具箱 已发布
  2. 32 附录 B——完整张量形状表 已发布
  3. 33 附录 C——术语表与论文时间线 已发布
  4. 34 附录 D——复现与审阅检查清单 已发布

先给工具箱的抽屉贴标签

  1. README先看入口与边界
  2. main.py把零件接起来
  3. module.py编码器与 SIGReg
  4. data/把长视频变成 clip
  5. conf/保存实验配方
读仓库像参观厨房：先固定地址，再分清菜谱、厨具、食材与账单。

报错时，地图比乱拧螺丝有用

拿到一只“会看视频”的工具箱，先给抽屉贴标签：main.py 是总开关，module.py 放核心计算，data/loader.py 管食材，conf/ 是菜谱。这样遇到报错，能先判断它来自数据、模型还是配方，而不是把所有螺丝都拧一遍。

先把仓库地址钉在 3ea0dda

本系列核对的是 2026-09-02 的提交 3ea0dda。复制下面命令会得到可追踪的代码，而不是随时间变化的 main：

git clone https://github.com/MLO-lab/LeVJEPA.git
cd LeVJEPA
git checkout 3ea0dda16030bc0fd6472bf809fc0a0ad836a812
git rev-parse HEAD
uv sync

最后一条输出应完整等于上述哈希。项目要求 Python 3.12+，uv.lock 固定依赖；构建数据另用 uv sync --extra data，运行两个 notebook 用 uv sync --extra notebook。仓库不是 Python 包，命令应从根目录运行。

地图如下：main.py 组装 loader、共享 encoder、projector、SIGReg、优化器和 Lightning trainer；module.py 实现 ViT、随机 token dropping、RoPE、块因果 mask、projector 与 SIGReg；data/loader.py 从 Lance 抽 clip 并生成一张全局视图和多张局部视图；callbacks.py 保存 weight decay 调度与只供评估的 EMA 权重；conf/config.yaml 是 Hydra 默认配方，conf/data/ 保存数据路径；scripts/ 下载、转码，slurm/ 是集群入口。training_workshop.ipynb 用小模型拆开训练，feature_visualization.ipynb 查看发布权重的 patch 特征。

第一次追代码只走一条主路：main() 先调用 build_video_loader()；transform 产出 [B,T,C,H,W] 的全局与 [B,V,T,C,H,W] 的局部张量；multiview_forward() 把它们换轴成 [B,C,T,H,W]，局部视图折进 batch，共享 encoder 后只拿索引 0 的 [CLS]；projector 映射所有摘要，最后算视图 MSE 与 0.02 × SIGReg。沿这条链下断点，能分辨“数据错位”“编码器错误”和“loss 错误”，也能亲眼确认 global 没有 .detach()。

两个 notebook 是学习入口，不是论文评估脚本。workshop 把完整默认值缩成 tiny 模型、少帧和较高保留率；feature notebook 只展示冻结特征。若实验从 notebook 起步，把被缩小的设置写进报告，读者就能分清教学运行与论文复现。paper.md 是论文源稿副本，其中仍有草案 TODO；正式主张要回到 arXiv v1 与发布页面交叉核对。

许可证要按文件看：仓库主体是 MIT；由 Meta V-JEPA 改写的 module.py 明示 CC BY-NC 4.0，公开模型权重同样标为 CC BY-NC 4.0。依赖、Walking Tours 的链接视频还有各自条款，所以根目录的 MIT 文件只覆盖它实际授权的部分。

做一次只证明“环境能导入”的检查

运行 git status --short，刚 checkout 后应无输出；再运行 uv run python -c "from module import SIGReg, vit_tiny; print('imports ok')"，预期打印 imports ok。这只证明环境与导入成功，不证明模型训练结果。

这张仓库地图的图例

离开工具箱前记住

  1. 完整提交哈希让实验代码可以被精确重访；“最新 main”会随时间移动。
  2. main.py 管组装，module.py 管核心计算，conf/ 管可变配方。
  3. 仓库并非所有文件都由 MIT 覆盖；模型与核心改写文件是非商业 CC BY-NC 4.0。

找到该开的抽屉

  1. 为什么要记录完整提交哈希？
  2. EMA 代码在哪一类文件里，它是不是 target encoder？
  3. 根目录有 MIT 文件，能否据此宣布权重可商用？
查看答案
  1. 它让代码、配置和结论能被精确重访。
  2. 在 callbacks.py；它保存评估用权重平均，不产生训练目标。
  3. 不能；module.py 与发布权重另标 CC BY-NC 4.0，还要核对数据和依赖条款。