Diffusers 文档
CogVideoX
并获得增强的文档体验
开始使用
CogVideoX
CogVideoX 是一种文本到视频生成模型,致力于创建与提示更连贯的视频。它通过以下几种方法实现这一点:
一个 3D 变分自编码器,在空间和时间上压缩视频,提高压缩率和视频准确性。
一个专家 transformer 块,用于帮助文本和视频对齐,以及一个 3D 全注意力模块,用于捕获和创建空间和时间上准确的视频。
对视频指令维度进行的实际测试发现,CogVideoX 在主题一致性、动态信息、背景一致性、对象信息、平滑运动、颜色、场景、外观风格和时间风格方面表现良好,但在人物动作、空间关系和多对象方面无法取得良好效果。
通过 Diffusers 进行微调可以弥补这些不足。
数据准备
训练脚本接受两种数据格式。
第一种格式适用于小规模训练,第二种格式使用 CSV 格式,更适合大规模训练的数据流。未来,Diffusers 将支持 标签。
小格式
两个文件,其中一个文件包含按行分隔的提示,另一个文件包含按行分隔的视频数据路径(视频文件路径必须相对于您在指定 --instance_data_root
时传递的路径)。让我们通过一个示例来更好地理解这一点!
假设您已将 --instance_data_root
指定为 /dataset
,并且此目录包含以下文件:prompts.txt
和 videos.txt
。
prompts.txt
文件应包含按行分隔的提示。
A black and white animated sequence featuring a rabbit, named Rabbity Ribfried, and an anthropomorphic goat in a musical, playful environment, showcasing their evolving interaction.
A black and white animated sequence on a ship's deck features a bulldog character, named Bully Bulldoger, showcasing exaggerated facial expressions and body language. The character progresses from confident to focused, then to strained and distressed, displaying a range of emotions as it navigates challenges. The ship's interior remains static in the background, with minimalistic details such as a bell and open door. The character's dynamic movements and changing expressions drive the narrative, with no camera movement to distract from its evolving reactions and physical gestures.
...
videos.txt
文件应包含按行分隔的视频文件路径。请注意,路径应是相对于 --instance_data_root
目录的。
videos/00000.mp4
videos/00001.mp4
...
总的来说,如果您在数据集根目录上运行 `tree` 命令,您的数据集将如下所示:
/dataset
├── prompts.txt
├── videos.txt
├── videos
├── videos/00000.mp4
├── videos/00001.mp4
├── ...
使用此格式时,--caption_column
必须是 prompts.txt
,--video_column
必须是 videos.txt
。
流式格式
您可以使用单个 CSV 文件。在本示例中,假设您有一个 metadata.csv
文件。预期的格式是
<CAPTION_COLUMN>,<PATH_TO_VIDEO_COLUMN>
"""A black and white animated sequence featuring a rabbit, named Rabbity Ribfried, and an anthropomorphic goat in a musical, playful environment, showcasing their evolving interaction.""","""00000.mp4"""
"""A black and white animated sequence on a ship's deck features a bulldog character, named Bully Bulldoger, showcasing exaggerated facial expressions and body language. The character progresses from confident to focused, then to strained and distressed, displaying a range of emotions as it navigates challenges. The ship's interior remains static in the background, with minimalistic details such as a bell and open door. The character's dynamic movements and changing expressions drive the narrative, with no camera movement to distract from its evolving reactions and physical gestures.""","""00001.mp4"""
...
在这种情况下,--instance_data_root
应该是视频存储的位置,--dataset_name
应该是本地文件夹的路径,或者是一个在 Hub 上托管的 load_dataset 兼容数据集。假设您在 https://huggingface.co/datasets/my-awesome-username/minecraft-videos
上有 Minecraft 游戏视频,您需要指定 my-awesome-username/minecraft-videos
。
使用此格式时,`--caption_column` 必须是 `
您不严格限于 CSV 格式。只要 load_dataset
方法支持文件格式以加载基本的
和
,任何格式都适用。之所以在加载视频数据时要进行这些数据集组织上的调整,是因为 load_dataset
无法完全支持所有类型的视频格式。
[!NOTE] CogVideoX 在视频生成方面,搭配长而描述性的 LLM 增强提示,效果最佳。我们建议您先使用 VLM 生成摘要,然后使用 LLM 增强提示,对视频进行预处理。为了生成上述字幕,我们使用了 MiniCPM-V-26 和 Llama-3.1-8B-Instruct。这里有一个非常基础且不花哨的示例:这里。官方推荐的增强提示是 ChatGLM,并且 50-100 个词的长度被认为是比较好的。
[!NOTE] 您的数据集预计已预处理。如果没有,可以通过调整以下参数进行一些基本预处理:`--height`、`--width`、`--fps`、`--max_num_frames`、`--skip_frames_start` 和 `--skip_frames_end`。目前,当训练批次大小 > 1 时,数据集中所有视频应包含相同数量的视频帧。
训练
您需要通过安装必要的依赖项来设置开发环境。需要以下软件包:
- 根据您正在使用的训练功能,PyTorch 2.0 或更高版本(可能需要最新或 nightly 版本以进行量化/deepspeed 训练)
- `pip install diffusers transformers accelerate peft huggingface_hub` 用于所有与建模和训练相关的事项。
- `pip install datasets decord` 用于加载视频训练数据。
- `pip install bitsandbytes` 用于使用 8 位 Adam 或 AdamW 优化器进行内存优化训练。
- `pip install wandb` 可选,用于监控训练日志。
- `pip install deepspeed` 可选,用于 DeepSpeed 训练。
- `pip install prodigyopt` 可选,如果您想使用 Prodigy 优化器进行训练。
为了确保您能成功运行最新版本的示例脚本,我们强烈建议您**从源代码安装**并保持安装最新,因为我们会频繁更新示例脚本并安装一些特定于示例的依赖项。为此,请在新虚拟环境中执行以下步骤:
在运行脚本之前,请确保从源代码安装库
git clone https://github.com/huggingface/diffusers
cd diffusers
pip install -e .
然后导航到包含训练脚本的示例文件夹并安装您正在使用的脚本所需的依赖项
- PyTorch
cd examples/cogvideo
pip install -r requirements.txt
并通过以下命令初始化 🤗 Accelerate 环境:
accelerate config
或者,对于默认的 accelerate 配置,无需回答有关您的环境的问题,请使用:
accelerate config default
或者如果您的环境不支持交互式 shell(例如,笔记本),则
from accelerate.utils import write_basic_config
write_basic_config()
运行 `accelerate config` 时,如果使用 `torch.compile`,可以显著提高速度。PEFT 库用作 LoRA 训练的后端,因此请确保您的环境中安装了 `peft>=0.6.0`。
如果您想在训练完成后将模型推送到 Hub 并附带一份简洁的模型卡,请确保您已登录:
huggingface-cli login
# Alternatively, you could upload your model manually using:
# huggingface-cli upload my-cool-account-name/my-cool-lora-name /path/to/awesome/lora
请确保您的数据已按照数据准备中的描述进行准备。准备就绪后,即可开始训练!
假设您正在训练 50 个相似概念的视频,我们发现 1500-2000 步效果良好。然而,官方建议是 100 个视频,总共 4000 步。假设您在单个 GPU 上训练,`--train_batch_size` 为 `1`:
- 50个视频的1500步对应于30个训练 epoch。
- 4000步针对100个视频,相当于40个训练周期。
#!/bin/bash
GPU_IDS="0"
accelerate launch --gpu_ids $GPU_IDS examples/cogvideo/train_cogvideox_lora.py \
--pretrained_model_name_or_path THUDM/CogVideoX-2b \
--cache_dir <CACHE_DIR> \
--instance_data_root <PATH_TO_WHERE_VIDEO_FILES_ARE_STORED> \
--dataset_name my-awesome-name/my-awesome-dataset \
--caption_column <CAPTION_COLUMN> \
--video_column <PATH_TO_VIDEO_COLUMN> \
--id_token <ID_TOKEN> \
--validation_prompt "<ID_TOKEN> Spiderman swinging over buildings:::A panda, dressed in a small, red jacket and a tiny hat, sits on a wooden stool in a serene bamboo forest. The panda's fluffy paws strum a miniature acoustic guitar, producing soft, melodic tunes. Nearby, a few other pandas gather, watching curiously and some clapping in rhythm. Sunlight filters through the tall bamboo, casting a gentle glow on the scene. The panda's face is expressive, showing concentration and joy as it plays. The background includes a small, flowing stream and vibrant green foliage, enhancing the peaceful and magical atmosphere of this unique musical performance" \
--validation_prompt_separator ::: \
--num_validation_videos 1 \
--validation_epochs 10 \
--seed 42 \
--rank 64 \
--lora_alpha 64 \
--mixed_precision fp16 \
--output_dir /raid/aryan/cogvideox-lora \
--height 480 --width 720 --fps 8 --max_num_frames 49 --skip_frames_start 0 --skip_frames_end 0 \
--train_batch_size 1 \
--num_train_epochs 30 \
--checkpointing_steps 1000 \
--gradient_accumulation_steps 1 \
--learning_rate 1e-3 \
--lr_scheduler cosine_with_restarts \
--lr_warmup_steps 200 \
--lr_num_cycles 1 \
--enable_slicing \
--enable_tiling \
--optimizer Adam \
--adam_beta1 0.9 \
--adam_beta2 0.95 \
--max_grad_norm 1.0 \
--report_to wandb
为了更好地跟踪我们的训练实验,我们在上面的命令中使用了以下标志:
--report_to wandb
将确保训练运行在 Weights and Biases 上进行跟踪。要使用它,请务必使用pip install wandb
安装wandb
。- `validation_prompt` 和 `validation_epochs` 允许脚本执行几次验证推理运行。这使我们能够定性检查训练是否按预期进行。
设置
并非必需。从有限的实验来看,我们发现它比不设置效果更好(因为它类似于 Dreambooth 训练)。提供时,
会附加到每个提示的开头。因此,如果您的
是 "DISNEY"
,而您的提示是 "Spiderman swinging over buildings"
,那么训练中使用的有效提示将是 "DISNEY Spiderman swinging over buildings"
。如果未提供,您将在不带任何附加令牌的情况下进行训练,或者可以在开始训练之前增强数据集以应用您希望的令牌。
[!NOTE] 您可以传递 `--use_8bit_adam` 以减少训练的内存需求。
[!IMPORTANT] 在添加 CogVideoX LoRA 训练支持时,已测试以下设置:
- 我们的测试主要在 CogVideoX-2b 上完成。我们很快将着手于 CogVideoX-5b 和 CogVideoX-5b-I2V。
- 一个包含 70 个训练视频的数据集,分辨率为
200 x 480 x 720
(帧 x 高 x 宽)。通过在数据预处理中使用帧跳过,我们从中创建了两个较小的 49 帧和 16 帧数据集,以加快实验速度,并且因为 CogVideoX 团队建议的最大限制是 49 帧。在这 70 个视频中,我们创建了三组:10 个、25 个和 50 个视频。所有视频在训练概念的性质上都是相似的。- 25+ 个视频最适合训练新概念和风格。
- 我们发现使用可指定为 `--id_token` 的标识符令牌进行训练效果更好。这类似于 Dreambooth 式训练,但没有此类令牌的常规微调也有效。
- 训练出的概念与完全不相关的提示结合时,似乎表现不错。我们预计如果对 CogVideoX-5B 进行微调,结果会更好。
- 原始存储库使用
lora_alpha
为1
。我们发现这在许多运行中不适用,可能是由于建模后端和训练设置的差异。我们的建议是将lora_alpha
设置为rank
或rank // 2
。- 如果您在对使用原始模型生成不良结果的字幕数据进行训练,那么 rank 为 64 或以上是很好的,这也是 CogVideoX 团队的建议。如果您的训练字幕生成结果已经中等良好,那么 rank 为 16/32 应该可以。我们发现将 rank 设置得过低,例如 4,是不理想的,并且不会产生有希望的结果。
- CogVideoX 的作者和我们自己的有限实验都推荐总共 4000 个训练步和 100 个训练视频以获得最佳结果。虽然这可能会产生最佳结果,但我们发现 2000 个步和 25 个视频也可能足够。
- 当使用 Prodigy 优化器进行训练时,可以遵循 这篇博客 中的建议。Prodigy 倾向于快速过拟合。根据我非常有限的测试,我发现学习率
0.5
加上--prodigy_use_bias_correction
、prodigy_safeguard_warmup
和--prodigy_decouple
是合适的。- CogVideoX 作者以及我们使用 Adam/AdamW 进行实验的推荐学习率对于 25 个以上视频的数据集而言,介于
1e-3
和1e-4
之间。请注意,由于探索时间有限,我们的测试并不详尽。我们的建议是尝试不同的旋钮和拨盘,以找到适合您数据的最佳设置。
推理
一旦您训练了一个 LoRA 模型,推理可以通过简单地将 LoRA 权重加载到 `CogVideoXPipeline` 中来完成。
import torch
from diffusers import CogVideoXPipeline
from diffusers.utils import export_to_video
pipe = CogVideoXPipeline.from_pretrained("THUDM/CogVideoX-2b", torch_dtype=torch.float16)
# pipe.load_lora_weights("/path/to/lora/weights", adapter_name="cogvideox-lora") # Or,
pipe.load_lora_weights("my-awesome-hf-username/my-awesome-lora-name", adapter_name="cogvideox-lora") # If loading from the HF Hub
pipe.to("cuda")
# Assuming lora_alpha=32 and rank=64 for training. If different, set accordingly
pipe.set_adapters(["cogvideox-lora"], [32 / 64])
prompt = "A vast, shimmering ocean flows gracefully under a twilight sky, its waves undulating in a mesmerizing dance of blues and greens. The surface glints with the last rays of the setting sun, casting golden highlights that ripple across the water. Seagulls soar above, their cries blending with the gentle roar of the waves. The horizon stretches infinitely, where the ocean meets the sky in a seamless blend of hues. Close-ups reveal the intricate patterns of the waves, capturing the fluidity and dynamic beauty of the sea in motion."
frames = pipe(prompt, guidance_scale=6, use_dynamic_cfg=True).frames[0]
export_to_video(frames, "output.mp4", fps=8)
减少内存使用
在使用 diffusers 库进行测试时,所有包含在 diffusers 库中的优化都已启用。此方案尚未在除 **NVIDIA A100 / H100** 架构之外的设备上进行实际内存使用测试。通常,此方案可适用于所有 **NVIDIA Ampere 架构**及更高版本设备。如果禁用优化,内存消耗将增加,峰值内存使用量约为表中数值的 3 倍。然而,速度将提高约 3-4 倍。您可以选择性地禁用一些优化,包括:
pipe.enable_sequential_cpu_offload()
pipe.vae.enable_slicing()
pipe.vae.enable_tiling()
- 对于多 GPU 推理,需要禁用
enable_sequential_cpu_offload()
优化。 - 使用 INT8 模型会降低推理速度,这是为了适应内存较低的 GPU,同时将视频质量损失降至最低,尽管推理速度会显著下降。
- CogVideoX-2B 模型以
FP16
精度训练,所有 CogVideoX-5B 模型均以BF16
精度训练。我们建议在推理时使用模型训练时所用的精度。 - PytorchAO 和 Optimum-quanto 可用于量化文本编码器、Transformer 和 VAE 模块,以减少 CogVideoX 的内存需求。这使得模型可以在免费的 T4 Colab 或内存较小的 GPU 上运行!此外,请注意 TorchAO 量化与
torch.compile
完全兼容,这可以显著提高推理速度。FP8 精度必须在 NVIDIA H100 及以上设备上使用,需要从源代码安装torch
、torchao
、diffusers
和accelerate
Python 包。建议使用 CUDA 12.4。 - 推理速度测试也使用了上述内存优化方案。如果没有内存优化,推理速度会提高约10%。只有 `diffusers` 版本的模型支持量化。
- 该模型仅支持英文输入;其他语言可通过大型模型细化翻译成英文使用。
- 模型微调的内存使用在 `8 * H100` 环境中测试,程序自动使用 `Zero 2` 优化。如果表中标记了特定数量的 GPU,则微调必须使用该数量或更多的 GPU。
属性 | CogVideoX-2B | CogVideoX-5B |
---|---|---|
模型名称 | CogVideoX-2B | CogVideoX-5B |
推理精度 | FP16*(推荐),BF16,FP32,FP8*,INT8,不支持 INT4 | BF16(推荐)、FP16、FP32、FP8*、INT8,不支持 INT4 |
单GPU推理显存 | FP16:使用 diffusers 12.5GB*INT8:使用 diffusers 和 torchao 7.8GB* | BF16:使用 diffusers 20.7GB*INT8:使用 diffusers 和 torchao 11.4GB* |
多GPU推理显存 | FP16:使用 diffusers 10GB* | BF16:使用 diffusers 15GB* |
推理速度 | 单个 A100:~90 秒,单个 H100:~45 秒 | 单个 A100:~180 秒,单个 H100:~90 秒 |
微调精度 | FP16 | BF16 |
微调显存消耗 | 47 GB (bs=1, LORA) 61 GB (bs=2, LORA) 62GB (bs=1, SFT) | 63 GB (bs=1, LORA) 80 GB (bs=2, LORA) 75GB (bs=1, SFT) |