VideoTuna

🤗🤗🤗 VideoTuna 是一个用于文本到视频应用的实用代码库。
🌟 VideoTuna 是首个整合了多种 AI 视频生成模型的仓库，包括“文本到视频 (T2V)”、“图像到视频 (I2V)”、“文本到图像 (T2I)”以及“视频到视频 (V2V)”等生成任务，可用于模型推理与微调（据我们所知）。
🌟 VideoTuna 也是首个提供全面视频生成流水线的仓库，涵盖从微调到预训练、持续训练以及后训练对齐等全流程（据我们所知）。

🔆 特性

🌟 一体化框架： 支持各类最新预训练视频生成模型的推理与微调。
🌟 持续训练： 可利用新数据不断优化您的模型。
🌟 微调： 将预训练模型适配到特定领域。
🌟 人类偏好对齐： 利用 RLHF 技术使模型更符合人类偏好。
🌟 后处理： 使用视频到视频增强模型对生成的视频进行优化和修正。

🔆 更新

• [2025-04-22] 🐟 支持 Wan2.1 和 Step Video 的 推理，以及 HunyuanVideo T2V 的 微调，并采用统一的代码库架构。
• [2025-02-03] 🐟 通过 PR#27 支持自动代码格式化。感谢 @samidarko!
• [2025-02-01] 🐟 迁移到 Poetry 以简化依赖管理和脚本运行（PR#25）。感谢 @samidarko!
• [2025-01-20] 🐟 支持 Flux-T2I 的 微调。
• [2025-01-01] 🐟 在 VideoVAEPlus 仓库 中发布了 VideoVAE+ 的 训练。
• [2025-01-01] 🐟 支持 Hunyuan Video 和 Mochi 的 推理。
• [2024-12-24] 🐟 发布了 VideoVAE+：一款 SOTA 视频 VAE 模型——现已在 此仓库 中可用！其视频重建效果优于 NVIDIA 的 Cosmos-Tokenizer。
• [2024-12-01] 🐟 支持 ModelScope 提供的 CogVideoX-1.5-T2V&I2V 和 视频到视频增强 的 推理。
• [2024-12-01] 🐟 支持 CogVideoX 的 微调。
• [2024-11-01] 🐟 🎉 发布了 VideoTuna v0.1.0！
  初始支持包括对 VideoCrafter1-T2V&I2V、VideoCrafter2-T2V、DynamiCrafter-I2V、OpenSora-T2V、CogVideoX-1-2B-T2V、CogVideoX-1-T2V、Flux-T2I 的推理，以及对 VideoCrafter、DynamiCrafter 和 Open-Sora 的训练与微调。

🔆 开始使用

1. 准备环境

(1) 如果您使用 Linux 和 Conda（推荐）

conda create -n videotuna python=3.10 -y
conda activate videotuna
pip install poetry
poetry install

• ↑ 大约需要 3 分钟。

可选：安装 Flash-attn

Hunyuan 模型使用它来减少内存占用并加速推理。如果未安装，模型将以正常模式运行。可通过以下命令安装 flash-attn：

poetry run install-flash-attn 

• ↑ 大约需要 1 分钟。

可选：视频到视频增强

poetry run pip install "modelscope[cv]" -f https://modelscope.oss-cn-beijing.aliyuncs.com/releases/repo.html

• 如果此命令 ↑ 卡住，终止后重新运行即可解决问题。

(2) 如果您使用 Linux 和 Poetry（不使用 Conda）：

poetry config virtualenvs.in-project true # 可选但建议，确保虚拟环境创建在项目根目录
poetry config virtualenvs.create true # 启用此参数以确保虚拟环境创建在项目根目录
poetry env use python3.10 # 将创建虚拟环境，可通过 `ls -l .venv` 检查。
poetry env activate # 可选，因为 Poetry 命令（例如 `poetry install` 或 `poetry run <command>`）会自动加载虚拟环境。
poetry install

poetry run install-flash-attn

poetry run pip install "modelscope[cv]" -f https://modelscope.oss-cn-beijing.aliyuncs.com/releases/repo.html

(3) 如果您使用 MacOS

docker compose build videotuna

export HOST_UID=$(id -u)
export HOST_GID=$(id -g)

docker compose run --remove-orphans videotuna poetry env use /usr/local/bin/python
docker compose run --remove-orphans videotuna poetry run python -m pip install --upgrade pip setuptools wheel
docker compose run --remove-orphans videotuna poetry install
docker compose run --remove-orphans videotuna poetry run pip install "modelscope[cv]" -f https://modelscope.oss-cn-beijing.aliyuncs.com/releases/repo.html

docker compose run --remove-orphans videotuna poetry add wheel

docker compose run --remove-orphans videotuna poetry run pip freeze

docker compose run --remove-orphans videotuna poetry run format

docker compose run -it --remove-orphans videotuna bash

2. 准备检查点

• 请按照 docs/checkpoints.md 下载模型检查点。
• 下载完成后，应将模型检查点放置于 检查点结构 中。

3. 推理最先进的 T2V/I2V/T2I 模型

运行以下命令进行模型推理： 它将根据 inputs/t2v/prompts.txt 中的提示自动生成 T2V/T2I，并根据 inputs/i2v/576x1024 中的图像和提示生成 I2V。

T2V

I2V

T2I

4. 微调 T2V 模型

(1) 准备数据集

请按照 docs/datasets.md 中的说明，尝试使用提供的玩具数据集，或构建您自己的数据集。

(2) 微调

所有训练命令均在 H800 80G 显卡上测试通过。
T2V

I2V

T2I

5. 评估

我们支持 VBench 评估，用于评价 T2V 的生成性能。 详细信息请参阅 eval/README.md。

贡献

Git 钩子

Git 钩子由 pre-commit 库管理。

安装钩子

运行以下命令以在 commit 时安装钩子。它们将检查格式、代码风格和类型注解。

poetry run pre-commit install
poetry run pre-commit install --hook-type commit-msg

在不提交的情况下运行钩子

poetry run pre-commit run --all-files

致谢

我们感谢以下项目分享了他们优秀的模型和代码！

• Wan2.1: Wan：开放且先进的大规模视频生成模型。
• HunyuanVideo: 大规模视频生成模型的系统化框架。
• Step-Video: 一个拥有300亿参数的文本到视频预训练模型，能够生成长达204帧的视频。
• Mochi: 开源视频生成领域的最新SOTA模型。
• VideoCrafter2: 克服数据限制，打造高质量视频扩散模型。
• VideoCrafter1: 开放的高质量视频生成扩散模型。
• DynamiCrafter: 利用视频扩散先验动画化开放领域图像。
• Open-Sora: 让高效视频制作惠及所有人。
• CogVideoX: 具有专家级Transformer的文本到视频扩散模型。
• VADER: 通过奖励梯度实现视频扩散对齐。
• VBench: 视频生成模型的全面基准测试套件。
• Flux: Black Forest Labs 的文本到图像模型。
• SimpleTuner: 文本到图像生成的微调工具包。

一些资源

• LLMs-Meet-MM-Generation: 一篇关于利用大语言模型进行多模态生成（图像、视频、3D和音频）的论文合集。
• MMTrail: 一个多模态预告片视频数据集，包含语言和音乐描述。
• Seeing-and-Hearing: 一个用于联合VA生成、V2A、A2V和I2A的多功能框架。
• Self-Cascade: 一种用于更高分辨率图像和视频生成的自级联模型。
• ScaleCrafter 和 HiPrompt: 用于更高分辨率图像和视频生成的免费方法。
• FreeTraj 和 FreeNoise: 用于视频轨迹控制和更长视频生成的免费方法。
• Follow-Your-Emoji、Follow-Your-Click 和 Follow-Your-Pose: 一系列可控视频生成工具。
• Animate-A-Story: 一个用于故事性视频生成的框架。
• LVDM: 用于长视频生成和文本到视频生成的潜在视频扩散模型。

🍻 贡献者

📋 许可证

请遵守 CC-BY-NC-ND 许可协议。如需许可授权，请联系项目负责人 Yingqing He (yhebm@connect.ust.hk) 和 Yazhou Xing (yxingag@connect.ust.hk)。

😊 引用

@software{videotuna,
  author = {Yingqing He and Yazhou Xing and Zhefan Rao and Haoyu Wu and Zhaoyang Liu and Jingye Chen and Pengjun Fang and Jiajun Li and Liya Ji and Runtao Liu and Xiaowei Chi and Yang Fei and Guocheng Shao and Yue Ma and Qifeng Chen},
  title = {VideoTuna: 一款功能强大的视频生成工具包，支持模型微调和后训练优化},
  month = {Nov},
  year = {2024},
  url = {https://github.com/VideoVerses/VideoTuna}
}

星标历史

VideoTuna 快速上手指南

VideoTuna 是一个集成了多种主流 AI 视频生成模型（如文生视频 T2V、图生视频 I2V、文生图 T2I 等）的一站式框架，支持从推理、微调到持续训练的全流程。

1. 环境准备

系统要求

• 操作系统: Linux (推荐) 或 macOS (需使用 Docker)
• Python 版本: 3.10
• 依赖管理工具: Conda (推荐) 或 Poetry
• GPU: 建议使用 NVIDIA GPU，显存需求视具体模型而定（详见使用示例）

前置说明

本项目使用 Poetry 管理依赖。国内用户若遇到网络问题，可配置 Poetry 使用国内源（可选）：

poetry config repositories.pypi https://pypi.tuna.tsinghua.edu.cn/simple

2. 安装步骤

方案 A：Linux + Conda (推荐)

1. 创建并激活虚拟环境

   conda create -n videotuna python=3.10 -y
   conda activate videotuna
   

2. 安装 Poetry 并部署项目

   pip install poetry
   poetry install
   

   预计耗时约 3 分钟。

3. 可选优化组件

   • 安装 Flash-attn (用于 Hunyuan 等模型加速及显存优化):

     poetry run install-flash-attn
     

   • 安装视频增强功能 (基于 ModelScope):

     poetry run pip install "modelscope[cv]" -f https://modelscope.oss-cn-beijing.aliyuncs.com/releases/repo.html
     

     注：若命令卡住，请终止后重新运行即可。

方案 B：macOS (Apple Silicon)

由于部分依赖不支持 arm64 架构，macOS 用户需通过 Docker Compose 运行。

1. 构建镜像

   docker compose build videotuna
   

2. 设置权限变量

   export HOST_UID=$(id -u)
   export HOST_GID=$(id -g)
   

3. 安装依赖

   docker compose run --remove-orphans videotuna poetry env use /usr/local/bin/python
   docker compose run --remove-orphans videotuna poetry run python -m pip install --upgrade pip setuptools wheel
   docker compose run --remove-orphans videotuna poetry install
   docker compose run --remove-orphans videotuna poetry run pip install "modelscope[cv]" -f https://modelscope.oss-cn-beijing.aliyuncs.com/releases/repo.html
   

   注：若 swissarmytransformer 安装挂起，重试一次通常可解决。

3. 基本使用

第一步：准备模型权重

请参照官方文档 docs/checkpoints.md 下载所需模型的 Checkpoint，并按照指定目录结构存放。

第二步：运行推理 (Inference)

VideoTuna 会自动读取 inputs/ 目录下的提示词或图片进行生成。以下是常用模型的快速启动命令：

文生视频 (T2V)

图生视频 (I2V)

文生图 (T2I) - Flux

# 标准模式 (高显存)
poetry run inference-flux-dev

# 低显存模式 (开启 VAE Tiling 和 CPU Offload)
poetry run inference-flux-dev --enable_vae_tiling --enable_sequential_cpu_offload

第三步：微调模型 (Fine-tuning)

在微调前，请先按照 docs/datasets.md 准备数据集。以下以 Wan Video 的 LoRA 微调为例：

# 文生视频 (T2V) LoRA 微调
poetry run train-wan2-1-t2v-lora

# 图生视频 (I2V) LoRA 微调
poetry run train-wan2-1-i2v-lora

注：更多模型的微调命令及详细参数配置（如 Hunyuan, CogVideoX, Flux 等）请参考项目根目录下的 docs/ 文档。所有训练命令已在 H800 80G GPU 上验证。