Diffusers 文档
CogVideoX
并获得增强的文档体验
开始使用
CogVideoX
CogVideoX 是一个文本到视频生成模型,专注于创建与提示更一致的连贯视频。它通过几种方法实现这一点。
一个 3D 变分自编码器,可在空间和时间上压缩视频,从而提高压缩率和视频准确性。
一个专家 Transformer 块,用于帮助对齐文本和视频,以及一个 3D 全注意力模块,用于捕获和创建空间和时间上准确的视频。
视频指令维度的实际测试发现,CogVideoX 在主题一致性、动态信息、背景一致性、对象信息、平滑运动、颜色、场景、外观风格和时间风格方面具有良好的效果,但在人物动作、空间关系和多个对象方面无法取得良好的效果。
使用 Diffusers 进行微调可以帮助弥补这些不足。
数据准备
训练脚本接受两种格式的数据。
第一种格式适用于小规模训练,第二种格式使用 CSV 格式,更适合大规模训练的流数据。未来,Diffusers 将支持 <Video>
标签。
小规模格式
两个文件,其中一个文件包含以换行符分隔的提示,另一个文件包含以换行符分隔的视频数据路径(视频文件的路径必须相对于您在指定 --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
应该是本地文件夹的路径,或者是 load_dataset 兼容的托管在 Hub 上的数据集。假设您在 https://huggingface.co/datasets/my-awesome-username/minecraft-videos
有 Minecraft 游戏视频,您需要指定 my-awesome-username/minecraft-videos
。
当使用此格式时,--caption_column
必须是 <CAPTION_COLUMN>
,--video_column
必须是 <PATH_TO_VIDEO_COLUMN>
。
您不严格限于 CSV 格式。只要 load_dataset
方法支持文件格式以加载基本的 <PATH_TO_VIDEO_COLUMN>
和 <CAPTION_COLUMN>
,任何格式都可以工作。进行这些数据集组织技巧来加载视频数据的原因是 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 时,数据集中的所有视频应包含相同数量的视频帧。
训练
您需要通过安装必要的 requirements 来设置您的开发环境。以下软件包是必需的
- Torch 2.0 或更高版本,基于您正在使用的训练功能(对于量化/deepspeed 训练可能需要最新或 nightly 版本)
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 优化器进行训练
为了确保您可以成功运行最新版本的示例脚本,我们强烈建议从源代码安装并保持安装更新,因为我们会频繁更新示例脚本并安装一些示例特定的 requirements。为此,请在新虚拟环境中执行以下步骤
在运行脚本之前,请确保您从源代码安装了库
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(例如,notebook)
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
个训练 epochs - 100 个视频上的 4000 步对应于
40
个训练 epochs
#!/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
允许脚本执行一些验证推理运行。这使我们能够定性地检查训练是否按预期进行。
设置 <ID_TOKEN>
不是必需的。从一些有限的实验中,我们发现它比没有时效果更好(因为它类似于 Dreambooth 训练)。当提供时,<ID_TOKEN>
会附加到每个 prompt 的开头。因此,如果您的 <ID_TOKEN>
是 "DISNEY"
,而您的 prompt 是 "Spiderman swinging over buildings"
,则训练中使用的有效 prompt 将是 "DISNEY Spiderman swinging over buildings"
。当未提供时,您可以选择在没有任何额外 token 的情况下进行训练,或者可以在开始训练之前增强您的数据集以在您希望的位置应用 token。
[!NOTE] 您可以传递
--use_8bit_adam
以减少训练的内存需求。
[!IMPORTANT] 以下设置在添加 CogVideoX LoRA 训练支持时已进行测试
- 我们的测试主要在 CogVideoX-2b 上完成。我们将尽快研究 CogVideoX-5b 和 CogVideoX-5b-I2V
- 一个数据集包含 70 个分辨率为
200 x 480 x 720
(F x H x W) 的训练视频。由此,通过在数据预处理中使用帧跳过,我们创建了两个较小的 49 帧和 16 帧数据集,以便更快地进行实验,并且因为 CogVideoX 团队建议的最大限制是 49 帧。在 70 个视频中,我们创建了 10 个、25 个和 50 个视频的三个组。所有视频在训练的概念性质上都是相似的。- 25 个以上的视频最适合训练新概念和风格。
- 我们发现最好使用可以指定为
--id_token
的标识符 token 进行训练。这类似于 Dreambooth 式训练,但没有此类 token 的正常微调也有效。- 训练的概念在与完全不相关的 prompt 结合使用时似乎也能相当好地工作。我们预计如果对 CogVideoX-5B 进行微调,效果会更好。
- 原始存储库使用
lora_alpha
为1
。我们发现这在许多运行中不合适,可能是由于建模后端和训练设置的差异。我们的建议是将lora_alpha
设置为rank
或rank // 2
。- 如果您正在训练的数据的 captions 使用原始模型生成不良结果,则 64 及以上的
rank
是不错的选择,这也是 CogVideoX 背后的团队的建议。如果您的训练 captions 上的生成结果已经相当不错,则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 进行实验的推荐学习率在
1e-3
和1e-4
之间,对于 25 个以上视频的数据集。请注意,由于探索时间有限,我们的测试并不详尽。我们的建议是尝试不同的旋钮和刻度盘,以找到适合您数据的最佳设置。
推理
一旦你训练了一个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 Colabs 或内存较小的 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 推理 VRAM | FP16: 使用 diffusers 12.5GBINT8: 使用带有 torchao 的 diffusers 7.8GB | BF16: 使用 diffusers 20.7GBINT8: 使用带有 torchao 的 diffusers 11.4GB |
多 GPU 推理 VRAM | FP16: 使用 diffusers 10GB* | BF16: 使用 diffusers 15GB* |
推理速度 | 单 A100: ~90 秒, 单 H100: ~45 秒 | 单 A100: ~180 秒, 单 H100: ~90 秒 |
微调精度 | FP16 | BF16 |
微调 VRAM 消耗 | 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) |