这是 Pyramid Flow 的官方仓库，它是一种基于 流匹配 的高效训练型 自回归视频生成 方法。仅通过在 开源数据集 上进行训练，即可生成高质量的 768p 分辨率、24 FPS 的 10 秒视频，并且自然支持图像到视频的生成。

10s, 768p, 24fps	5s, 768p, 24fps	Image-to-video

最新消息

• 2024.11.13 🚀🚀🚀 我们发布了 768p miniFLUX 检查点（最长 10 秒）。

  我们已将模型结构从 SD3 切换为 mini FLUX，以解决人体结构问题。请尝试我们的 1024p 图像检查点、384p 视频检查点（最长 5 秒）以及 768p 视频检查点（最长 10 秒）。新的 miniflux 模型在人体结构和运动稳定性方面有了显著提升。

• 2024.10.29 ⚡️⚡️⚡️ 我们发布了 VAE 训练代码、DiT 微调代码以及使用 FLUX 结构从头开始训练的新模型检查点（Hugging Face）。

• 2024.10.13 ✨✨✨ 支持 多 GPU 推理 和 CPU 张量卸载。只需不到 8GB 的 GPU 内存即可运行，在多 GPU 上还能获得显著加速。

• 2024.10.11 🤗🤗🤗 Hugging Face 演示 已上线。感谢 @multimodalart 的贡献！

• 2024.10.10 🚀🚀🚀 我们发布了 Pyramid Flow 的 技术报告、项目主页 以及 模型检查点。

目录

• 简介
• 安装
• 推理
  1. Gradio 快速入门
  2. 推理代码
  3. 多 GPU 推理
  4. 使用技巧
• 训练
  1. 训练 VAE
  2. 微调 DiT
• 作品展示
• 对比
• 致谢
• 引用

简介

现有的视频扩散模型通常以全分辨率运行，大量计算资源都耗费在噪声极高的潜在空间上。相比之下，我们的方法利用流匹配的灵活性（Lipman 等, 2023；Liu 等, 2023；Albergo & Vanden-Eijnden, 2023），在不同分辨率和噪声水平的潜在空间之间进行插值，从而实现视觉内容的同时生成与解压缩，计算效率更高。整个框架采用端到端优化设计，仅使用一个 DiT 模型（Peebles & Xie, 2023），在 20.7k A100 GPU 训练小时内，即可生成 768p 分辨率、24 FPS 的高质量 10 秒视频。

安装

我们建议使用 conda 来搭建环境。当前代码库使用 Python 3.8.10 和 PyTorch 2.1.2（指南），我们正在积极适配更多版本的支持。

git clone https://github.com/jy0205/Pyramid-Flow
cd Pyramid-Flow

# 使用 conda 创建环境
conda create -n pyramid python==3.8.10
conda activate pyramid
pip install -r requirements.txt

然后，从 Hugging Face 下载模型（有两种版本：miniFLUX 或 SD3）。miniFLUX 模型支持 1024p 图像、384p 和 768p 视频生成，而基于 SD3 的模型则支持 768p 和 384p 视频生成。384p 检查点可生成 5 秒、24 FPS 的视频，768p 检查点则可生成最长 10 秒、24 FPS 的视频。

from huggingface_hub import snapshot_download

model_path = 'PATH'   # 用于保存下载检查点的本地目录
snapshot_download("rain1011/pyramid-flow-miniflux", local_dir=model_path, local_dir_use_symlinks=False, repo_type='model')

推理

1. Gradio 快速入门

要开始使用，首先安装 Gradio，将模型路径设置为 #L36，然后在本地运行：

python app.py

Gradio 演示将在浏览器中打开。感谢 @tpc2233 的贡献，详情请参见 #48。

或者，您也可以在 @multimodalart 创建的 Hugging Face Space 🤗 上轻松试用。由于 GPU 限制，此在线演示每次只能生成 25 帧（以 8 FPS 或 24 FPS 导出）。您可以复制该空间来生成更长的视频。

Google Colab 快速入门

要在 Google Colab 上快速试用 Pyramid Flow，请运行以下代码：

# 设置
!git clone https://github.com/jy0205/Pyramid-Flow
%cd Pyramid-Flow
!pip install -r requirements.txt
!pip install gradio

# 此代码下载 miniFLUX
from huggingface_hub import snapshot_download

model_path = '/content/Pyramid-Flow'
snapshot_download("rain1011/pyramid-flow-miniflux", local_dir=model_path, local_dir_use_symlinks=False, repo_type='model')

# 启动
!python app.py

2. 推理代码

要使用我们的模型，请按照此链接中的 video_generation_demo.ipynb 推理代码进行操作。我们强烈建议您尝试最新发布的 pyramid-miniflux，它在人体结构和运动稳定性方面有显著提升。请将参数 model_name 设置为 pyramid_flux 即可使用。我们进一步将其简化为以下两步流程。首先，加载下载的模型：

import torch
from PIL import Image
from pyramid_dit import PyramidDiTForVideoGeneration
from diffusers.utils import load_image, export_to_video

torch.cuda.set_device(0)
model_dtype, torch_dtype = 'bf16', torch.bfloat16   # 使用 bf16（暂不支持 fp16）

model = PyramidDiTForVideoGeneration(
    'PATH',                                         # 下载的检查点目录
    model_name="pyramid_flux",
    model_dtype=model_dtype,
    model_variant='diffusion_transformer_768p',
)

model.vae.enable_tiling()
# model.vae.to("cuda")
# model.dit.to("cuda")
# model.text_encoder.to("cuda")

# 如果不使用顺序卸载，请取消注释上面的几行 ^
model.enable_sequential_cpu_offload()

然后，您可以根据自己的提示词尝试文本到视频的生成。请注意，384p 版本目前仅支持 5 秒视频（temp 最高设置为 16）！

prompt = "一部电影预告片，讲述一位身穿红色羊毛针织摩托车头盔的30岁太空人的冒险故事，蓝天、盐碱沙漠，电影风格，采用35毫米胶片拍摄，色彩鲜艳"

# 用于384p模型版本
# width = 640
# height = 384

# 用于768p模型版本
width = 1280
height = 768

with torch.no_grad(), torch.cuda.amp.autocast(enabled=True, dtype=torch_dtype):
    frames = model.generate(
        prompt=prompt,
        num_inference_steps=[20, 20, 20],
        video_num_inference_steps=[10, 10, 10],
        height=height,     
        width=width,
        temp=16,                    # temp=16: 5秒，temp=31: 10秒
        guidance_scale=7.0,         # 第一帧的指导权重，384p版本设为7
        video_guidance_scale=5.0,   # 其他视频潜变量的指导权重
        output_type="pil",
        save_memory=True,           # 如果GPU显存充足，可设为`False`以提高VAE解码速度
    )

export_to_video(frames, "./text_to_video_sample.mp4", fps=24)

作为自回归模型，我们的模型还支持（文本条件下的）图像到视频生成：

# 用于384p模型版本
# width = 640
# height = 384

# 用于768p模型版本
width = 1280
height = 768

image = Image.open('assets/the_great_wall.jpg').convert("RGB").resize((width, height))
prompt = "FPV视角飞越长城"

with torch.no_grad(), torch.cuda.amp.autocast(enabled=True, dtype=torch_dtype):
    frames = model.generate_i2v(
        prompt=prompt,
        input_image=image,
        num_inference_steps=[10, 10, 10],
        temp=16,
        video_guidance_scale=4.0,
        output_type="pil",
        save_memory=True,           # 如果GPU显存充足，可设为`False`以提高VAE解码速度
    )

export_to_video(frames, "./image_to_video_sample.mp4", fps=24)

CPU卸载

我们还支持两种CPU卸载方式，以降低GPU显存需求。请注意，这些方法可能会牺牲效率。

• 在生成函数中添加 cpu_offloading=True 参数，即可在低于12GB的GPU显存下进行推理。该功能由 @Ednaordinary 贡献，详情请参见 #23。
• 在上述步骤之前调用 model.enable_sequential_cpu_offload()，则可在低于8GB的GPU显存下进行推理。该功能由 @rodjjo 贡献，详情请参见 #75。

MPS后端

感谢 @niw，Apple Silicon 用户（例如配备 M2 24GB 的 MacBook Pro）也可以使用 MPS 后端来体验我们的模型！详情请参见 #113。

3. 多GPU推理

对于拥有多个GPU的用户，我们提供了一个推理脚本，它利用序列并行技术来节省每张GPU上的显存。这也能带来显著的速度提升，仅需2.5分钟即可在4张A100 GPU上生成一段5秒、768p、24fps的视频（相比之下，单张A100 GPU需要5.5分钟）。您可以通过以下命令在2张GPU上运行该脚本：

CUDA_VISIBLE_DEVICES=0,1 sh scripts/inference_multigpu.sh

目前该脚本支持2或4张GPU（适用于SD3版本），更多配置可在原始脚本中找到。此外，您还可以启动由 @tpc2233 创建的多GPU Gradio演示，详情请参见 #59。

剧透：我们在训练过程中甚至没有使用序列并行技术，这都要归功于我们高效的金字塔流设计。

4. 使用技巧

• guidance_scale 参数控制视觉质量。我们建议在768p检查点的文本到视频生成中使用[7, 9]之间的指导权重，而在384p检查点中使用7。
• video_guidance_scale 参数控制运动效果。较高的值会增加动态程度并缓解自回归生成带来的退化，而较低的值则会使视频更加稳定。
• 对于10秒视频的生成，我们推荐使用7的指导权重和5的视频指导权重。

训练

1. VAE训练

训练VAE的硬件要求至少需要8张A100 GPU。请参考本文档。这是一个类似MAGVIT-v2的连续3D VAE，应该具有相当高的灵活性。您可以基于这部分VAE训练代码构建自己的视频生成模型。

2. DiT微调

微调DiT的硬件要求至少需要8张A100 GPU。请参考本文档。我们提供了针对自回归和非自回归版本的金字塔流的训练说明。前者更偏向研究用途，后者则更为稳定（但在缺乏时序金字塔的情况下效率较低）。

作品集

以下视频示例以5秒、768p、24fps的规格生成。如需更多结果，请访问我们的项目页面。

对比

在VBench（Huang等，2024）上，我们的方法超越了所有对比的开源基线模型。即使仅使用公开视频数据，其性能也与Kling（快手，2024）和Gen-3 Alpha（Runway，2024）等商业模型相当，尤其是在质量得分（84.74 vs. Gen-3的84.11）和运动流畅度方面表现突出。

我们还进行了一项包含20多名参与者的用户研究。结果显示，我们的方法在运动流畅性等方面明显优于Open-Sora（GitHub）和CogVideoX-2B（THUDM）等开源模型。

致谢

在实现Pyramid Flow的过程中，我们受益于以下优秀项目：

• SD3 Medium 和 Flux 1.0：基于流匹配的最先进图像生成模型。
• Diffusion Forcing 和 GameNGen：将下一帧预测与全序列扩散相结合。
• WebVid-10M、OpenVid-1M 和 Open-Sora Plan：用于文本到视频生成的大规模数据集。
• CogVideoX：一款开源的文本到视频生成模型，共享许多训练细节。
• Video-LLaMA2：用于视频重述的开源视频大语言模型。

引用

如果您觉得本仓库对您的研究有所帮助，请为它点赞，并在您的论文中引用Pyramid Flow：

@article{jin2024pyramidal,
  title={Pyramidal Flow Matching for Efficient Video Generative Modeling},
  author={Jin, Yang and Sun, Zhicheng and Li, Ningyuan and Xu, Kun and Xu, Kun and Jiang, Hao and Zhuang, Nan and Huang, Quzhe and Song, Yang and Mu, Yadong and Lin, Zhouchen},
  jounal={arXiv preprint arXiv:2410.05954},
  year={2024}
}

Pyramid-Flow 快速上手指南

Pyramid-Flow 是一种基于流匹配（Flow Matching）的高效自回归视频生成模型。它仅使用开源数据集训练，能够生成高质量的 10 秒长、768p 分辨率、24 FPS 的视频，并原生支持图生视频功能。最新发布的 miniFLUX 版本在人体结构和运动稳定性上有了显著提升。

环境准备

• 操作系统: Linux (推荐), macOS (支持 MPS 后端)
• Python: 3.8.10 (当前代码库主要验证版本)
• PyTorch: 2.1.2 (需匹配 CUDA 版本)
• GPU 显存:
  • 基础推理：建议 12GB+
  • 开启 CPU Offload 后：可低至 8GB
  • 多卡推理：支持序列并行以节省单卡显存
• 依赖库: git, conda (推荐用于环境管理)

注意：目前模型推理主要支持 bf16 精度，暂不支持 fp16。

安装步骤

1. 创建虚拟环境并安装依赖

建议使用 Conda 管理环境，以确保依赖兼容性。

git clone https://github.com/jy0205/Pyramid-Flow
cd Pyramid-Flow

# 创建并激活 conda 环境
conda create -n pyramid python==3.8.10
conda activate pyramid

# 安装 Python 依赖
pip install -r requirements.txt

2. 下载模型权重

项目提供两种主要变体，推荐使用 miniFLUX 以获得更好的人体结构表现。

• miniFLUX: 支持 1024p 图像、384p/768p 视频（最长 10 秒）。
• SD3: 支持 384p/768p 视频。

以下命令演示如何下载 miniFLUX 模型（请确保网络通畅，或使用国内镜像加速）：

from huggingface_hub import snapshot_download

# 设置本地保存路径
model_path = './models/pyramid-flow-miniflux' 

# 下载模型权重
snapshot_download("rain1011/pyramid-flow-miniflux", local_dir=model_path, local_dir_use_symlinks=False, repo_type='model')

基本使用

方式一：使用 Gradio 快速体验（推荐新手）

这是最简单的启动方式，会自动在浏览器中打开交互界面。

1. 修改 app.py 文件第 36 行，将模型路径指向你刚才下载的目录。
2. 运行以下命令启动服务：

python app.py

方式二：使用 Python 代码推理

如果你需要集成到自己的项目中，可以使用以下代码进行文生视频或图生视频。

1. 加载模型

import torch
from PIL import Image
from pyramid_dit import PyramidDiTForVideoGeneration
from diffusers.utils import load_image, export_to_video

# 设置设备
torch.cuda.set_device(0)
model_dtype, torch_dtype = 'bf16', torch.bfloat16   # 必须使用 bf16

# 初始化模型
model = PyramidDiTForVideoGeneration(
    './models/pyramid-flow-miniflux',               # 模型下载路径
    model_name="pyramid_flux",                      # 推荐使用 miniFLUX
    model_dtype=model_dtype,
    model_variant='diffusion_transformer_768p',     # 可选：768p 或 384p
)

# 启用 VAE 分块以节省显存
model.vae.enable_tiling()

# 启用顺序 CPU Offload，可将显存需求降至 8GB 以下（若显存充足可注释此行以提升速度）
model.enable_sequential_cpu_offload()

2. 文生视频 (Text-to-Video)

prompt = "A movie trailer featuring the adventures of the 30 year old space man wearing a red wool knitted motorcycle helmet, blue sky, salt desert, cinematic style, shot on 35mm film, vivid colors"

# 分辨率设置
# 384p 模型: width=640, height=384
# 768p 模型: width=1280, height=768
width = 1280
height = 768

with torch.no_grad(), torch.cuda.amp.autocast(enabled=True, dtype=torch_dtype):
    frames = model.generate(
        prompt=prompt,
        num_inference_steps=[20, 20, 20],
        video_num_inference_steps=[10, 10, 10],
        height=height,     
        width=width,
        temp=16,                    # 帧数控制时长：temp=16 (约 5 秒), temp=31 (约 10 秒)
        guidance_scale=7.0,         # 首帧引导系数，768p 建议 7-9，384p 建议 7
        video_guidance_scale=5.0,   # 后续视频帧引导系数
        output_type="pil",
        save_memory=True,           # 显存不足时设为 True
    )

export_to_video(frames, "./output_text2video.mp4", fps=24)

3. 图生视频 (Image-to-Video)

# 准备输入图片并调整大小
image = Image.open('assets/the_great_wall.jpg').convert("RGB").resize((width, height))
prompt = "FPV flying over the Great Wall"

with torch.no_grad(), torch.cuda.amp.autocast(enabled=True, dtype=torch_dtype):
    frames = model.generate_i2v(
        prompt=prompt,
        input_image=image,
        num_inference_steps=[10, 10, 10],
        temp=16,
        video_guidance_scale=4.0,
        output_type="pil",
        save_memory=True,
    )

export_to_video(frames, "./output_img2video.mp4", fps=24)

进阶提示：多卡加速

如果你拥有多张 GPU（如 2 张或 4 张 A100），可以使用序列并行脚本大幅缩短生成时间（4 卡生成 5 秒视频仅需约 2.5 分钟）：

CUDA_VISIBLE_DEVICES=0,1 sh scripts/inference_multigpu.sh