hao-ai-lab/FastVideo · 上手攻略

  • 仓库：hao-ai-lab/FastVideo
  • 链接：https://github.com/hao-ai-lab/FastVideo
  • 分类：multimodal / llm-infra（视频生成推理与训练）
  • 作者：spark
  • 更新：2026-07-21

是什么

FastVideo 是 MBZUAI Hao Zhang 实验室主导的"统一视频生成推理 + 后训练（蒸馏/微调）框架"。它不是某个视频生成模型本身，而是一套面向 DiT 类视频扩散模型（Wan、Mochi、Hunyuan、CausalWan 等）的训练-蒸馏-推理一站式底座，目标是让视频生成既能微调，又能跑得快、跑得便宜。

仓库内同时包含 4 个层次的产出：

  1. 推理栈：fastvideo Python 包，提供 VideoGenerator 高层 API、CLI、多后端 attention（VSA、Sliding Tile Attention、FlashAttention 等）、sequence parallelism 等。
  2. 后训练栈：LoRA/全参微调、DMD2 步数蒸馏、Sparse Distillation（>50× 加速）、Causal Self-Forcing 蒸馏、Attn-QAT（注意力量化感知训练）。
  3. Dreamverse 应用：apps/dreamverse/，实时"vibe directing"流式视频生成/编辑，部署形态覆盖本地 GPU、自建 B200、Docker、Modal serverless。
  4. 数据流水线：视频/图像/文本数据预处理脚本，对应 HF 上的 FastVideo Synthetic Wan2.1/Wan2.2 数据集。

最新里程碑：2026-06-23 发布的 FastWan-QAD 在 1 张消费级 GPU 上 1.8 秒端到端生成 5 秒视频（FP8 / 1.3B），是该仓库目前的旗舰卖点。

解决什么问题

视频扩散模型的两大痛点：

  • 慢：一个 5 秒 720p 视频通常需要数十秒到几分钟，Diffusion 步数 + attention 的 O(n²) 是双重重负。
  • 难训：DiT 类模型动辄数十亿参数，单卡装不下；从零训练或领域微调门槛高。

FastVideo 对应的解法：

  • 推理侧：用 Video Sparse Attention (VSA, arXiv 2505.13389)、Sliding Tile Attention (STA, arXiv 2502.04507)、多卡 Sequence Parallelism，把 attention 计算量降到稀疏/亚线性，再叠加 FP8/INT8 量化，达到几十倍加速。
  • 训练侧：FSDP2 + 序列并行 + selective activation checkpointing 让 5B/14B 模型能在中等集群上微调；DMD2 蒸馏把 50 步去噪压到 4 步；Causal Self-Forcing 支持自回归式 I2V 蒸馏。
  • 实时生成：Dreamverse 把上面所有东西串成"边播边算"的视频流体验。

快速安装

官方推荐 uv（替代 conda，安装更快）。

# 1) 准备 uv + Python 3.12
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv --python 3.12 --seed
source .venv/bin/activate

# 2) NVIDIA GPU + CUDA 12
UV_TORCH_BACKEND=cu126 uv pip install fastvideo
# CUDA 13 换 cu130；Apple Silicon 走 MPS 安装指引
# https://hao-ai-lab.github.io/FastVideo/getting_started/installation/mps/

# 3) DGX Spark / GB10 (ARM64 + CUDA 13) 没有 ARM 预编译 wheel，需要源码 editable 装
UV_TORCH_BACKEND=cu130 uv pip install -e .

# 4) 验证
python -c "import fastvideo, torch; print('cuda', torch.cuda.is_available())"
fastvideo --help

硬件支持矩阵见 docs/inference/support_matrix/：H100、A100、4090 主流；Linux/Windows/macOS 均可。注意：使用 VSA/Sliding Tile 自定义 CUDA kernel 必须先按 attention 安装页编译；纯 Python attention 后端可跳过。

核心用法

1) 一行命令生成视频

# example.py
import os
from fastvideo import VideoGenerator

os.environ["FASTVIDEO_ATTENTION_BACKEND"] = "VIDEO_SPARSE_ATTN"

generator = VideoGenerator.from_pretrained(
    "FastVideo/FastWan2.1-T2V-1.3B-Diffusers",
    num_gpus=1,
)

video = generator.generate_video(
    "A curious raccoon peers through a vibrant field of yellow sunflowers.",
    output_path="my_videos/",
    save_video=True,
)

python example.py

模型 FastVideo/FastWan2.1-T2V-1.3B-Diffusers 是稀疏蒸馏后的 Wan2.1，单卡 4090 就能出 480p。

2) FP8 极限加速（FastWan-QAD）

generator = VideoGenerator.from_pretrained(
    "FastVideo/FastWan-QAD-FP8-1.3B",
    num_gpus=1,
)
# 5s 视频 E2E ~1.8s

需安装 FP8 兼容的 PyTorch + transformer-engine，参考 docs 安装页。FastWan-QAD 是仓库当前最推荐的实时/边缘部署模型。

3) 用 Dreamverse 实时"vibe direct"

# 本地 GPU
cd apps/dreamverse
dreamverse-server --port 8080    # 自带 Web UI
# 或部署到 B200
dreamverse-server --remote ssh://user@b200-host
# 或 Modal serverless
modal deploy scripts/modal/deploy.py

打开浏览器即可像 Sora 早期 demo 那样拖动方向键实时改写镜头。

4) LoRA 微调自己的视频风格

参考 examples/distill/Wan2.1-T2V/ 与 docs/distillation/dmd/。最小步骤：

fastvideo train \
  --model FastVideo/FastWan2.1-T2V-1.3B-Diffusers \
  --dataset FastVideo/Wan-Syn_77x448x832_600k \
  --output_dir ./ckpts/my-lora \
  --lora_rank 64 --lora_alpha 64 \
  --fsdp --sp --mixed_precision fp16

训完直接 VideoGenerator.from_pretrained("./ckpts/my-lora") 即可推理。

5) 多卡 Sequence Parallelism 推理大模型

generator = VideoGenerator.from_pretrained(
    "FastVideo/CausalWan2.2-I2V-A14B-Preview-Diffusers",
    num_gpus=4,
    sp_size=4,            # 序列并行
    attention_backend="SLIDING_TILE_ATTN",
)

典型适用场景

  • 短视频/广告批量化：要在 4090/H100 上每天成百上千条 5-10s 视频，FastWan 系列 + VSA/STA 是当前开源里最经济的组合。
  • 风格/品牌 LoRA 微调：把品牌视觉、模特、动画风格用 LoRA 注入，30 分钟训一个 1.3B base 即可上线。
  • 实时互动内容：Dreamverse 让直播/互动叙事/展览里"边说边生成"成为可能。
  • 学术加速算法落地：想做新 attention/蒸馏算法，FastVideo 的 FSDP+SP 训练栈 + 多 backend 抽象是好起手。
  • 边缘/移动端：FastWan-QAD FP8 1.3B 跑在笔记本 GPU 也能做到近实时。

坑与注意

  • CUDA kernel 自编译：VSA / Sliding Tile Attention 不是纯 Python，缺 ninja/cuda-toolkit 会卡住；先装系统级 CUDA，再让 pip install fastvideo 编译。
  • DGX Spark/ARM64：没有 ARM wheel，必须 pip install -e . 源码编译，FlashAttention 也得另装 ARM 兼容 wheel。
  • 量化生效依赖硬件：FP8 INT8 在 Ada/Hopper 上才完整；4090（Ada）支持 FP8，V100/A30 等旧卡只到 FP16。
  • 生态很新：版本号 0.0.1.dev0（PyPI 早期），API 与 CLI 在快速演进，跨版本升级务必看 release notes 与 docs 的 "Migration"。
  • 模型卡与 license：FastWan 系列用 Wan2.1/2.2 的衍生权重，商用前要看 Hugging Face model card 的 license 条款；CausalWan2.2 I2V A14B 是 Preview 状态，效果未完全冻结。
  • Stars/周增：仓库卡片 Stars 3862 / 周增 +7，活跃度处于上升期，issue/PR 响应比一线项目慢，复杂问题去 Slack/WeChat 群更直接。
  • AGENTS.md：仓库里给 Claude Code / Cursor 等编码 agent 写好了"自动检测平台 + 按指引安装"的 prompt，可以直接用。

与同类对比

维度 FastVideo xDiT Diffusers + xformers SGLang-diffusion
视频专项 ★★★ ★★ ★（通用） ★
推理优化深度 ★★★（VSA/STA/FP8/SP） ★★（并行） ★★（kernel 库） ★★
后训练/蒸馏 ★★★（DMD2/Causal/Attn-QAT） × × ×
实时流式 ★★★（Dreamverse） × × ★
Dreamverse 应用 ★★★ × × ×

定位差异：FastVideo 是"视频生成版 vLLM + Diffusers + 蒸馏套件"三合一；xDiT 更偏推理侧的并行调度；SGLang 在 2025-09 fork 了 FastVideo 做 diffusion 推理；纯学术 attention 研究直接看 STA/VSA 论文即可，不必走仓库。

一句话推荐

如果你的团队要在 2026 年把视频生成从 demo 推到生产（尤其在乎单卡实时、稀疏 attention、蒸馏微调），FastVideo 是当下最完整的开源视频生成框架，从底层 kernel 到上层 Dreamverse 应用一应俱全；只想要"开箱出图"则 diffusers + Wan2.1 流水线更轻。

不确定处：PyPI 上 fastvideo 仍处于 0.0.1.dev0，稳定版发布时间表未在 README 中给出；FastWan-QAD FP8 模型的具体推理显存峰值未公开，留待实测。