TencentARC/Looking-Ahead · 上手攻略

  • 仓库：TencentARC/Looking-Ahead
  • 链接：https://github.com/TencentARC/Looking-Ahead
  • 分类：多模态 / 视频生成 · 世界模型
  • 作者：spark
  • 更新：2026-10-25

一句话结论

如果你在自研自回归视频生成模型，这是目前公开可用的、把"物理一致性"训练目标讲得最清楚的一套完整配方（含代码 + 1.3B/5B 权重 + TF 基线对照）；但它的定位是研究用训练范式，不是开箱即用的产品级生成器——只有 5 秒训练长度、无反漂移技术、硬件门槛高、文档还在演化。做世界模型研究必读，拿来直接产片不合适。

§0 三证自检

项 状态 说明
GitHub URL ✅ 已 fetch 2026-10-25 抓取 README、docs/inference.md、pyproject.toml、configs/*.yaml、run.sh
论文 anchor ✅ 已核实 arXiv:2610.29989（v1，2026-10-21 提交，cs.CV），项目页 hellorpg.github.io/looking-ahead
README 子模块 anchor ✅ 已核实 官方 README 明确基于上游 Wan2.1-T2V-1.3B / Wan2.2-TI2V-5B；HF 权重 TencentARC/Looking-Ahead
权重可用性 ✅ HF 仓库含 4 个 model_ema.pt（tf/fcp × 1.3B/5B）+ SHA256SUMS + manifest.json

机构归属：南京大学 + 腾讯 IEG ARC Lab + 浙江大学，通讯作者 Limin Wang，项目负责人 Yukun Huang（据 arXiv 作者块与个人主页）。

二、它是什么

Looking Ahead: Modeling Future Evolution in Autoregressive Video Generation（arXiv:2610.29989）的官方代码库，配套 1.3B 和 5B 两档自回归「文+图生视频」（TI2V）模型的训练与推理代码。

核心贡献是 Future Chunk Prediction（FCP） 这个辅助训练目标：

  • 自回归视频扩散模型按 chunk 逐段生成，但"能续得像"不等于"懂场景怎么演化"。
  • 在 teacher forcing 训练下，相邻 chunk 视觉冗余太强，模型可以靠局部时间捷径（复制上一帧的纹理/运动）来降低当前 chunk 的去噪损失，从而根本不用学底层动力学。
  • FCP 的做法：开一路辅助分支，从当前 chunk 的中间层特征出发，在拿不到中间那段视觉上下文的前提下，直接预测时间上相隔较远的未来 chunk。
  • 关键工程性质：监督信号直接来自训练视频像素，不需要额外的预训练视觉编码器（不像很多同类方案要挂 CLIP/DINO 之类），也完全不改变自回归推理流程——推理时辅助分支不参与，纯白拿收益。

论文 abstract 声称（verbatim）："Our method achieves superior physical plausibility over standard teacher-forced autoregressive training with a lower overall training compute budget"，并且 "FCP fosters a more structured representation space, which may be valuable for building autoregressive world models"。

三、解决什么问题

痛点 FCP 的解法
生成视频"看着连贯、实则不守物理"（杯子穿模、液体倒错方向） 强制模型从中间层特征预测远端 chunk，无法靠像素级复制蒙混过关
teacher forcing 的时间冗余导致「捷径学习」 远端预测分支的监督误差无法用局部连续性抵消
加辅助目标往往推高训练成本 FCP 论文声称在更低总训练算力预算下达到更好的物理合理性
额外视觉编码器带来的成本与流程负担 FCP 只用视频像素监督，无额外预训练编码器
想验证"方法本身"是否有效 vs 单纯堆算力 仓库同时放出 TF（teacher forcing baseline） 与 FCP 两套同参数量权重，可直接 A/B 对比

代码层面也印证了这套设计。以 configs/fcp_wan22_ti2v_5b.yaml 为例，与同名的 tf_wan22_ti2v_5b.yaml 逐行 diff，唯一差异就是 future_prediction 段：

future_prediction:
  enabled: true
  future_offsets: [1, 2, 3, 4, 5]     # 预测未来第 1~5 个 offset 处的 chunk
  source_layers: [2, 11, 20, 29]        # 从主 DiT 的这 4 层取中间特征
  source_layer_fusion:
    mode: mlp
    hidden_ratio: 2.0
    activation: gelu
  mini_dit_depth: 3                     # 辅助分支是个 3 层的小 DiT
  offset_loss_weights: [0.5, 0.5, 0.5, 0.5, 0.5]
  init_mode: copy
  init_source: [27, 28, 29]              # 从主 DiT 末三层拷贝初始化
  aux_future_timestep_range: [0.0, 1000.0]
  source_context:
    streams: [clean, noisy]
separate_predictive_grad_clip: true
max_predictive_grad_norm: 0.1

也就是说：辅助分支是一个从主模型最后几层拷贝初始化、深度仅 3 层的小 DiT，预测未来 5 个不同 offset 的 chunk，损失权重各 0.5，且与主分支的梯度分开裁剪（max_predictive_grad_norm: 0.1）以防辅助目标把主干带偏。这是"轻量、可插拔、不改推理"的完整落地形态。

四、快速安装

官方测试环境：Linux + NVIDIA H200 + Python 3.12.3 + PyTorch 2.10.0+cu128 (CUDA 12.8)。README 明确写了「compatibility with other environments has not been tested」，所以非 H200 环境属于未验证区。

方式 A：uv（推荐，README 首推）

# Ubuntu / Debian 先装 FFmpeg（视频解码需要）
sudo apt-get update
sudo apt-get install -y ffmpeg

# 仓库根目录执行
UV_CACHE_DIR=.uv-cache uv sync --python 3.12
source .venv/bin/activate

方式 B：conda + pip

⚠️ README 里这一节目前是空的——原文标注 🚧 TODO: Installation instructions will be added here.。想走 pip 路线的话，需要自己按 pyproject.toml 的 dependencies 手工装。

依赖（来自 pyproject.toml）：

torch==2.10.0          torchvision==0.25.0        torchcodec==0.10.0
flash-attn-4>=4.0.0b5   diffusers>=0.37.1          transformers>=5.5.3
accelerate>=1.13.0     omegaconf>=2.3.0           webdataset>=1.0.2
einops>=0.8.2           ftfy>=6.3.1               huggingface-hub>=1.10.1
safetensors>=0.4.3     sentencepiece>=0.2.1      tokenizers>=0.22.2
wandb>=0.25.1           matplotlib>=3.10.8        numpy>=1.26.4  pillow>=10.0.0
regex>=2024.0.0         tqdm>=4.67.3

torch / torchvision 通过 uv 的 pytorch-cu128 显式索引安装。注意 flash-attn-4 是预发布版（4.0.0b5），需要匹配的 CUDA 工具链，编译失败是常见第一道坎。

拉取模型资产

需要两套东西：上游 base 模型（提供 VAE、text encoder、tokenizer）+ 本项目的 EMA 权重。

# 上游 base（1.3B 用 T2V-1.3B，5B 用 TI2V-5B）
hf download Wan-AI/Wan2.1-T2V-1.3B \
  --local-dir weights/Wan-AI/Wan2.1-T2V-1.3B

hf download Wan-AI/Wan2.2-TI2V-5B \
  --local-dir weights/Wan-AI/Wan2.2-TI2V-5B

# 本项目 4 份最终权重（tf/fcp × 1.3B/5B）
hf download TencentARC/Looking-Ahead --local-dir weights/Looking-Ahead

预期目录结构（缺一不可）：

weights/Wan-AI/Wan2.1-T2V-1.3B/           # base：权重 + config + text encoder + tokenizer + VAE
weights/Wan-AI/Wan2.2-TI2V-5B/
weights/Looking-Ahead/
├── tf_wan21_t2v_1.3b/model_ema.pt
├── fcp_wan21_t2v_1.3b/model_ema.pt
├── tf_wan22_ti2v_5b/model_ema.pt
└── fcp_wan22_ti2v_5b/model_ema.pt

如果 base 模型不放默认位置，设置 WAN_ROOT 指向包含模型文件夹的父目录。两份 base 都要下（约 1.3B + 5B 全量），磁盘和带宽提前算好。

五、核心用法

5.1 推理：文+视频生视频（TV2V，续写一段视频）

python inference.py \
  --config fcp_wan22_ti2v_5b \
  --checkpoint_path weights/Looking-Ahead/fcp_wan22_ti2v_5b/model_ema.pt \
  --use_ema \
  --video_path examples/inference/v2v/milk_pouring.mp4 \
  --prompt_file examples/inference/v2v/milk_pouring.txt \
  --duration 5s --seed 42 --sink 3 \
  --output_path outputs/v2v/fcp_milk_pouring

5.2 推理：文+图生视频（TI2V，让一张图动起来）

python inference.py \
  --config fcp_wan21_t2v_1.3b \
  --checkpoint_path weights/Looking-Ahead/fcp_wan21_t2v_1.3b/model_ema.pt \
  --use_ema \
  --image_path examples/inference/i2v/sailboat_lake.png \
  --prompt_file examples/inference/i2v/sailboat_lake.txt \
  --duration 5s --seed 42 \
  --output_path outputs/example_inference

仓库自带 6 组 i2v 样例：sailboat_lake、cat_window、paper_fan_open、book_page_turn、can_crush、pendulum（其中 fan/book/can 是按 5B 选的，pendulum 是按 1.3B 选的）。另有 examples/inference/v2v/ 下的 milk_pouring 与 dominoes。

5.3 关键参数速查（来自 docs/inference.md）

参数 默认 说明
--config 必填 recipe 名称或 YAML 路径
--checkpoint_path — 显式 checkpoint 路径；配 --use_ema 加载 EMA
--use_ema 关闭 释放的权重是 EMA，必须带这个 flag，否则加载失败
--image_path / --video_path — 二选一，自动决定 TI2V / TV2V 模式
--prompt_file / --prompt — 互斥；prompt 文件或内联文本
--duration 5s 总输出长度，包含上下文段；支持 s/m/h
--num_output_frames -1 正整数优先于 duration
--seed 42 0 ~ 2³²−1
--sink / --sink_size 3 attention sink 保留的 latent 帧数；不是 TV2V 上下文长度；0 关闭
--v2v_context_latents 自动 手动指定上下文长度 K（latent 帧数）
--output_path — 换输入或改参数务必换新目录，主 MP4 已存在会被直接跳过
--i2v / --data_path — 批量图片模式，配合 --test_sample_limit

采样超参用 key=value 形式覆盖（注意与显式 flag 冲突时 flag 优先）：

sampling_steps=50        sample_solver=unipc|dpm++    guidance_scale=3.0
timestep_shift=5.0       negative_prompt='...'        fps=16(1.3B)|24(5B)
long_inference_threshold=256   vae_decode_chunk=32

5.4 上下文长度 K 的算法（容易踩）

自动模式选的是最长的合法尾段（从原视频末尾往回取），而不是从头取。公式：

K = 1 + 3 × M,  M >= 1        # VAE 时间步长 4，chunk 3 latent 帧，首帧独立
条件像素帧数 = 1 + 4 × (K - 1)

合法 K 为 4, 7, 10, ...，对应条件帧 13, 25, 37, ...。K 是 latent 帧数，不是像素帧也不是秒。

官方两个 bundled MP4 都是 24 FPS、25 帧，5 秒输出的实际结果：

Recipe FPS 自动 K 条件帧 选取的源时间戳
24（5B） 7 25 0.0–1.0 s
16（1.3B） 4 13 0.25–1.0 s

⚠️ 显式 K 的语义与自动模式不同：显式 --v2v_context_latents 7 取的是视频开头的 25 帧（explicit_prefix），自动模式取的是结尾段的 25 帧（auto_tail）。这个不对称很容易让 A/B 实验做错。

5.5 批量图片推理

python inference.py \
  --config fcp_wan21_t2v_1.3b \
  --checkpoint_path weights/Looking-Ahead/fcp_wan21_t2v_1.3b/model_ema.pt \
  --use_ema --i2v \
  --data_path examples/inference/i2v_batch \
  --test_sample_limit 2 --duration 5s --seed 42 \
  --output_path outputs/i2v/fcp_batch

需要 target_crop_info_<suffix>.json + 同名 <suffix>/ 图片子目录。JSON 字段含 file_name、caption、target_crop、type、origin_width、origin_height；但元数据里的 bbox 不会覆盖实际的缩放/中心裁剪变换。

5.6 训练

先下载 demo 数据集：

hf download TencentARC/Looking-Ahead --repo-type dataset \
  --local-dir release_assets/dataset_demo

放到仓库根目录下对应路径（1.3B → release_assets/dataset_demo/wan21_t2v_1.3b/，5B → release_assets/dataset_demo/wan22_ti2v_5b/），保持 source_a/ 与 source_b/ 子目录结构。数据路径写在 configs/*.yaml 的 data_sources 里（data_path 指向 latent_shards/，annotation_path 指向 annotations.jsonl），换了位置就改这两个字段。

启动训练：

# 默认用所有可见 GPU，开 W&B
bash run.sh train fcp_wan21_t2v_1.3b

# 指定 GPU
CUDA_VISIBLE_DEVICES=0,1,2,3 bash run.sh train fcp_wan21_t2v_1.3b

# 关 W&B / 指定输出目录
bash run.sh train fcp_wan21_t2v_1.3b --disable_wandb
bash run.sh train fcp_wan21_t2v_1.3b --exp_dir outputs/my_experiment

把 config 名换成 tf_wan21_t2v_1.3b / fcp_wan22_ti2v_5b / tf_wan22_ti2v_5b 即可训别的变体。

run.sh 是自研的多机启动器，会自动推导 nproc_per_node、构建 rdzv_id、分配 torchrun 参数。几个环境变量：DEBUG=1（单卡调试，会启用 causal mask 可视化，且多机下直接报错）、WORLD_SIZE、MASTER_ADDR/MASTER_PORT、OMP_NUM_THREADS（默认 8）。多机必须走 rdzv，MASTER_ADDR 必须是可路由地址。

训练配置关键项（5B recipe）：max_iters: 25000、batch_size: 1、lr: 1e-05（AdamW，beta1=0.0）、ema_weight: 0.9995、ema_start_step: 2000、gradient_checkpointing: true、num_frame_per_block: 3、image_or_video_shape: [1, 31, 48, 36, 64]、mixed_precision: true。

六、典型适用场景

  1. 自研自回归视频模型，想引入"物理一致性"训练目标——FCP 几乎是最小侵入的实现：加一路 3 层小 DiT，权重从主干拷贝初始化，推理链路一行不改。这是仓库最大的实用价值。
  2. 需要一个干净的 A/B 对照实验——TF 与 FCP 的同名 config 差异仅在 future_prediction 段，权重都公开了，可以直接跑"同参数量、同结构、只换训练目标"的对比。
  3. 世界模型方向的前瞻性实验——论文提到 FCP 训练出的表征空间更结构化，值得用来验证"表征可解释性"类猜想。
  4. 视频续写 / 长时序一致性的基线——TV2V 的上下文选择算法、K 的对齐规则写得很清楚，可作为同类实现的对标参考。
  5. 想复现"辅助未来预测能提升物理合理性"这个结论——demo 数据集 + 完整训练代码都给了，可以从 1.3B 起步。

不适用：短平快的内容生产、需要几十秒长视频、只有消费级显卡的环境。

七、坑与注意

  1. --use_ema 不加就加载失败。发布的权重全是 model_ema.pt，EMA 加载顺序是"先找同名兄弟文件 model_ema.pt，再找文件内嵌的 generator_ema"，都没有就直接报错。README 的所有示例都带了这个 flag，别漏。
  2. --duration 含上下文，不是纯生成时长。5B 的 5 秒输出 = 120 帧 = 25 帧上下文 + 95 帧续写；1.3B 是 13 帧 + 67 帧。算"我要生成多少秒"时容易差 20%–40%。
  3. 输出目录被占用会静默跳过。文档明确写了 "An existing main MP4 is skipped based on its presence alone. Its companion files are not regenerated or repaired."——改了参数但没换目录，你会拿到上一次的旧结果。换输入/换权重/换参数一律换新目录。
  4. 显式 K 与自动 K 的取段方向不同（explicit_prefix 开头 vs auto_tail 结尾），且显式 K 永远不会悄悄缩短——对齐不对、输入不够长、或输出里没有可见续写，都会直接失败而不是降级。
  5. 输入图像会被居中裁剪，边缘内容可能丢。流程是"等比放大到覆盖目标分辨率（尺寸向上取整）→ 居中裁剪 → float32 归一化到 [-1,1] → VAE 编码"，双线性 + antialiasing。想保留主体请自己先裁好。
  6. 长 rollout 没有反漂移保证。官方 CAUTION 原文：模型在 5 秒片段上训练，"not specifically optimized for longer rollouts, and generation quality beyond the training duration is not guaranteed"。默认用三项兜底：受限 latent 上下文（KV cache 最多保留训练长度，1.3B 为 22、5B 为 31）、attention sink（默认 3）、窗口相对时序 RoPE（位置随窗口滚动并重算，超界则回退并 clamp）。作者提到引入 Helios 风格的简单反漂移技术能改善稳定性，但仍是 preliminary，未系统化。
  7. seed 不保证跨环境可复现。文档原话 "Seed alone does not guarantee identical results across runtime environments."
  8. conda + pip 安装路径是空的（TODO），pip 用户得自己对着 pyproject.toml 装。
  9. 硬件与版本门槛高且只验证过 H200。flash-attn-4>=4.0.0b5 是 beta，PyTorch 2.10.0+cu128 较新，驱动/CUDA 不匹配时安装即失败。
  10. 仓库很新、迭代快。创建于 2026-10-21，最近推送 2026-10-23，README 自己写着 "The documentation is also evolving"。config 名、目录结构都可能变，建议 pin 到具体 commit。
  11. 训练数据形态有前置依赖。data_path 指向的是 latent_shards/——即预先算好的 latent 分片，不是原始视频。要换自己的数据集，得先跑 VAE 编码出 latent 分片并生成 annotations.jsonl，这部分脚本 README 未展开说明（tools/ 目录可能有，需自行翻）。
  12. 模型许可需留意。GitHub 仓库根 LICENSE 是 Tencent 定制条款（"Tencent is pleased to support the open source community by making Looking Ahead available"，仓库卡片标注 NOASSERTION），而 HF 权重仓库的 metadata 标的是 apache-2.0，各子目录另有独立 LICENSE/NOTICE。商用前务必逐个目录核对真实许可，别只信 HF 标签。
  13. 权重来源需要区分：weights/Wan-AI/* 是上游 Wan 的权重，weights/Looking-Ahead/* 才是本项目训练产物，两者必须配套使用，混搭会加载失败或出静默错结果。
  14. HF 模型仓库 downloads 计数为 0、likes 仅 4（2026-10-25 抓取时），项目非常新，社区验证度低，踩坑基本没有先例可查。

八、与同类对比

维度 Looking-Ahead (FCP) 传统 teacher forcing 基线 需要额外视觉编码器的辅助监督方案 端到端视频生成模型（非自回归）
推理成本增加 0（辅助分支不参与推理） 0 视方案而定 0
训练成本增加 轻量：3 层小 DiT，主干拷贝初始化 0 显著（多一个大模型前向） 0
额外预训练编码器 不需要（纯像素监督） 不需要 通常需要（CLIP/DINO 等） 不需要
目标 建模场景演化 / 物理一致性 局部视觉连续性 表征对齐/语义一致性 端到端条件生成
长视频一致性 受限（无反漂移，5s 训练长度） 同样受限 视方案 通常更好（有全局注意力）
权重与代码 ✅ 全公开（1.3B/5B，TF+FCP 对照） ✅ 随本仓库提供 多为论文级 各自仓库
适合自研自回归模型 ✅ 直接抄 ✅ ⚠️ 成本高 ❌ 架构不同

横向看，本仓库的独特位置是：它不是提出一个更大的模型，而是提出一个"训练目标"并把它做成可插拔、可消融、可直接对比的工程实现。同类工作里不少方案停留在论文阶段或需要挂额外大模型；FCP 的"无额外编码器 + 推理零开销 + TF 对照权重齐全"三点组合，对做自回归视频的团队来说实用度很高。

九、待核 / 不确定处

  • ⚠️ 论文中的具体量化指标未核实：abstract 只给了定性表述（"superior physical plausibility"、"lower overall training compute budget"），本篇未取到 FVD / VBench / 物理一致性评分的具体数值与对比表，不要引用未核实的数字。
  • ⚠️ 训练数据规模与来源未公开核实：demo 数据集的具体内容、量级、来源视频，README 未说明。
  • ⚠️ tools/ 目录中"原始视频 → latent_shards"的预处理脚本未逐个核实，自定义数据的完整链路需自行验证。
  • ⚠️ 非 H200 / 非 CUDA 12.8 环境的兼容性未验证，官方只测了 H200 + PyTorch 2.10.0+cu128。
  • ⚠️ 许可口径不统一（GitHub 根 LICENSE 为 Tencent 定制，HF metadata 标 apache-2.0），实际使用条款待确认。
  • ⚠️ flash-attn-4 beta 版本在非官方 CUDA 环境下的可用性未验证。
  • 版本浮动提示：本篇所依据的仓库状态为 2026-10-23 最后推送、HF 权重 sha cee092c2cd6986c93461641338a1c084e310558f。README 明确会持续更新（config 名、路径、参数都可能变），复现时请 pin 到具体 commit，勿直接照抄本文命令。

十、来源清单

  • GitHub README（2026-10-25 fetch）：https://github.com/TencentARC/Looking-Ahead
  • docs/inference.md（2026-10-25 fetch）：https://raw.githubusercontent.com/TencentARC/Looking-Ahead/main/docs/inference.md
  • configs/fcp_wan22_ti2v_5b.yaml 与 configs/tf_wan22_ti2v_5b.yaml（diff 逐行核对）
  • pyproject.toml（依赖与索引配置）、run.sh（多机启动逻辑）
  • arXiv:2610.29989 abstract（2026-10-25 fetch）：https://arxiv.org/abs/2610.29989
  • Hugging Face 模型仓库元数据与文件清单（2026-10-25 fetch）：https://huggingface.co/TencentARC/Looking-Ahead
  • 项目页：https://hellorpg.github.io/looking-ahead/
  • 仓库卡片：organized/repo_cards/4622-tencentarc-looking-ahead.md