HunyuanVideo 文生视频模型实践
flyfish
运行 HunyuanVideo 模型使用文本生成视频的推荐配置（batch size = 1）：
| 模型 | 分辨率 (height/width/frame) | 峰值显存 |
|---|---|---|
| HunyuanVideo | 720px1280px129f | 60G |
| HunyuanVideo | 544px960px129f | 45G |
- 本项目适用于使用 NVIDIA GPU 和支持 CUDA 的设备
- 模型在单张 80G GPU 上测试
- 运行 720px1280px129f 的最小显存要求是 60GB，544px960px129f 的最小显存要求是 45GB。
- 测试操作系统：Linux
HunyuanVideo: A Systematic Framework For Large Video Generation Model
HunyuanVideo/ckpts/文件夹下的模型
HunyuanVideo
├──ckpts
│ ├──README.md
│ ├──hunyuan-video-t2v-720p
│ │ ├──transformers
│ │ │ ├──mp_rank_00_model_states.pt
│ │ │ ├──mp_rank_00_model_states_fp8.pt
│ │ │ ├──mp_rank_00_model_states_fp8_map.pt
├ │ ├──vae
│ ├──text_encoder
│ ├──text_encoder_2
├──...
关键配置项：
| 参数 | 默认值 | 描述 |
|:----------------------:|:---------:|:-----------------------------------------:|
| `--prompt` | None | 用于生成视频的 prompt |
| `--video-size` | 720 1280 | 生成视频的高度和宽度 |
| `--video-length` | 129 | 生成视频的帧数 |
| `--infer-steps` | 50 | 生成时采样的步数 |
| `--embedded-cfg-scale` | 6.0 | 文本的控制强度 |
| `--flow-shift` | 7.0 | 推理时 timestep 的 shift 系数，值越大，高噪区域采样步数越多 |
| `--flow-reverse` | False | If reverse, learning/sampling from t=1 -> t=0 |
| `--neg-prompt` | None | 负向词 |
| `--seed` | 0 | 随机种子 |
| `--use-cpu-offload` | False | 启用 CPU offload，可以节省显存 |
| `--save-path` | ./results | 保存路径 |
## 结果
```csharp
(HunyuanVideo) sss@sss-Super-Server:~/source/HunyuanVideo$ python3 sample_video.py \
--video-size 544 960 \
--video-length 129 \
--infer-steps 50 \
--prompt "A cat walks on the grass, realistic style." \
--flow-reverse \
--use-cpu-offload \
--save-path ./results
Namespace(model='HYVideo-T/2-cfgdistill', latent_channels=16, precision='bf16', rope_theta=256, vae='884-16c-hy', vae_precision='fp16', vae_tiling=True, text_encoder='llm', text_encoder_precision='fp16', text_states_dim=4096, text_len=256, tokenizer='llm', prompt_template='dit-llm-encode', prompt_template_video='dit-llm-encode-video', hidden_state_skip_layer=2, apply_final_norm=False, text_encoder_2='clipL', text_encoder_precision_2='fp16', text_states_dim_2=768, tokenizer_2='clipL', text_len_2=77, denoise_type='flow', flow_shift=7.0, flow_reverse=True, flow_solver='euler', use_linear_quadratic_schedule=False, linear_schedule_end=25, model_base='ckpts', dit_weight='ckpts/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states.pt', model_resolution='540p', load_key='module', use_cpu_offload=True, batch_size=1, infer_steps=2, disable_autocast=False, save_path='./results', save_path_suffix='', name_suffix='', num_videos=1, video_size=[544, 960], video_length=129, prompt='A cat walks on the grass, realistic style.', seed_type='auto', seed=None, neg_prompt=None, cfg_scale=1.0, embedded_cfg_scale=6.0, use_fp8=False, reproduce=False, ulysses_degree=1, ring_degree=1)
2024-12-21 21:50:51.616 | INFO | hyvideo.inference:from_pretrained:154 - Got text-to-video model root path: ckpts
2024-12-21 21:50:51.616 | INFO | hyvideo.inference:from_pretrained:189 - Building model...
2024-12-21 21:50:52.098 | INFO | hyvideo.inference:load_state_dict:340 - Loading torch model ckpts/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states.pt...
/home/sss/tool/HunyuanVideo/hyvideo/inference.py:341: FutureWarning: You are using `torch.load` with `weights_only=False` (the current default value), which uses the default pickle module implicitly. It is possible to construct malicious pickle data which will execute arbitrary code during unpickling (See https://github.com/pytorch/pytorch/blob/main/SECURITY.md#untrusted-models for more details). In a future release, the default value for `weights_only` will be flipped to `True`. This limits the functions that could be executed during unpickling. Arbitrary objects will no longer be allowed to be loaded via this mode unless they are explicitly allowlisted by the user via `torch.serialization.add_safe_globals`. We recommend you start setting `weights_only=True` for any use case where you don't have full control of the loaded file. Please open an issue on GitHub for any issues related to this experimental feature.
state_dict = torch.load(model_path, map_location=lambda storage, loc: storage)
2024-12-21 21:51:05.739 | INFO | hyvideo.vae:load_vae:29 - Loading 3D VAE model (884-16c-hy) from: ./ckpts/hunyuan-video-t2v-720p/vae
/home/sss/tool/HunyuanVideo/hyvideo/vae/__init__.py:39: FutureWarning: You are using `torch.load` with `weights_only=False` (the current default value), which uses the default pickle module implicitly. It is possible to construct malicious pickle data which will execute arbitrary code during unpickling (See https://github.com/pytorch/pytorch/blob/main/SECURITY.md#untrusted-models for more details). In a future release, the default value for `weights_only` will be flipped to `True`. This limits the functions that could be executed during unpickling. Arbitrary objects will no longer be allowed to be loaded via this mode unless they are explicitly allowlisted by the user via `torch.serialization.add_safe_globals`. We recommend you start setting `weights_only=True` for any use case where you don't have full control of the loaded file. Please open an issue on GitHub for any issues related to this experimental feature.
ckpt = torch.load(vae_ckpt, map_location=vae.device)
2024-12-21 21:51:07.546 | INFO | hyvideo.vae:load_vae:55 - VAE to dtype: torch.float16
2024-12-21 21:51:07.577 | INFO | hyvideo.text_encoder:load_text_encoder:28 - Loading text encoder model (llm) from: ./ckpts/text_encoder
Loading checkpoint shards: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████| 4/4 [00:01<00:00, 2.42it/s]
2024-12-21 21:51:10.888 | INFO | hyvideo.text_encoder:load_text_encoder:50 - Text encoder to dtype: torch.float16
2024-12-21 21:51:10.890 | INFO | hyvideo.text_encoder:load_tokenizer:64 - Loading tokenizer (llm) from: ./ckpts/text_encoder
2024-12-21 21:51:11.263 | INFO | hyvideo.text_encoder:load_text_encoder:28 - Loading text encoder model (clipL) from: ./ckpts/text_encoder_2
2024-12-21 21:51:11.331 | INFO | hyvideo.text_encoder:load_text_encoder:50 - Text encoder to dtype: torch.float16
2024-12-21 21:51:11.332 | INFO | hyvideo.text_encoder:load_tokenizer:64 - Loading tokenizer (clipL) from: ./ckpts/text_encoder_2
2024-12-21 21:51:11.454 | INFO | hyvideo.inference:predict:580 - Input (height, width, video_length) = (544, 960, 129)
2024-12-21 21:51:11.469 | DEBUG | hyvideo.inference:predict:640 -
height: 544
width: 960
video_length: 129
prompt: ['A cat walks on the grass, realistic style.']
neg_prompt: ['Aerial view, aerial view, overexposed, low quality, deformation, a poor composition, bad hands, bad teeth, bad eyes, bad limbs, distortion']
seed: None
infer_steps: 50
num_videos_per_prompt: 1
guidance_scale: 1.0
n_tokens: 67320
flow_shift: 7.0
embedded_guidance_scale: 6.0
100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 50/50 [01:25<00:00, 42.71s/it]
2024-12-21 21:54:32.410 | INFO | hyvideo.inference:predict:669 - Success, time: 200.9416298866272
huggingface/tokenizers: The current process just got forked, after parallelism has already been used. Disabling parallelism to avoid deadlocks...
To disable this warning, you can either:
- Avoid using `tokenizers` before the fork if possible
- Explicitly set the environment variable TOKENIZERS_PARALLELISM=(true | false)
2024-12-21 21:54:34.807 | INFO | __main__:main:55 - Sample save to: ./results/seed452372_A cat walks on the grass, realistic style.mp4
代码
import os
import time
from pathlib import Path
from loguru import logger
from datetime import datetime
from hyvideo.utils.file_utils import save_videos_grid
from hyvideo.config import parse_args
from hyvideo.inference import HunyuanVideoSampler
def main():
# 解析命令行参数
args = parse_args()
# 打印解析得到的参数，方便调试和查看输入信息
print(args)
# 将模型的根路径转换为 Path 对象，方便后续路径操作
models_root_path = Path(args.model_base)
# 检查模型根路径是否存在，如果不存在则抛出异常
if not models_root_path.exists():
raise ValueError(f"`models_root` 不存在: {models_root_path}")
# 创建保存样本的文件夹
# 如果 save_path_suffix 为空，则使用 save_path 作为保存路径，否则将后缀添加到 save_path 后
save_path = args.save_path if args.save_path_suffix == "" else f'{args.save_path}_{args.save_path_suffix}'
# 若保存路径不存在，则创建该目录，exist_ok=True 表示如果目录已存在不会引发异常
if not os.path.exists(args.save_path):
os.makedirs(save_path, exist_ok=True)
# 从预训练模型的路径加载 HunyuanVideoSampler 模型，并传入解析得到的命令行参数
hunyuan_video_sampler = HunyuanVideoSampler.from_pretrained(models_root_path, args=args)
# 获取更新后的参数，可能是因为加载模型时对参数进行了某些调整
args = hunyuan_video_sampler.args
# 开始采样
# TODO: 批量推理检查，这里可能需要后续完善批量推理的检查逻辑
outputs = hunyuan_video_sampler.predict(
# 输入的提示信息，用于引导视频生成
prompt=args.prompt,
# 视频的高度
height=args.video_size[0],
# 视频的宽度
width=args.video_size[1],
# 视频的长度
video_length=args.video_length,
# 随机种子，用于保证结果的可重复性
seed=args.seed,
# 负向提示信息，可能用于引导模型避免生成某些内容
negative_prompt=args.neg_prompt,
# 推理的步数，可能影响生成视频的质量和细节
infer_steps=args.infer_steps,
# 引导规模，可能影响生成结果与提示的符合程度
guidance_scale=args.cfg_scale,
# 每个提示对应的视频数量
num_videos_per_prompt=args.num_videos,
# 可能与视频流的偏移有关的参数
flow_shift=args.flow_shift,
# 推理的批量大小
batch_size=args.batch_size,
# 可能是嵌入的引导规模参数
embedded_guidance_scale=args.embedded_cfg_scale
)
# 从输出中获取采样得到的样本，可能是生成的视频数据
samples = outputs['samples']
# 保存样本
# 检查是否处于分布式环境或当前进程是否是主进程，可能用于分布式训练时的保存操作
if 'LOCAL_RANK' not in os.environ or int(os.environ['LOCAL_RANK']) == 0:
for i, sample in enumerate(samples):
# 为当前样本添加一个维度，可能是为了满足后续保存操作的格式要求
sample = samples[i].unsqueeze(0)
# 获取当前时间并格式化为字符串，作为时间戳
time_flag = datetime.fromtimestamp(time.time()).strftime("%Y-%m-%d-%H:%M:%S")
# 构建保存样本的路径，包含时间戳、种子信息和提示信息
save_path = f"{save_path}/{time_flag}_seed{outputs['seeds'][i]}_{outputs['prompts'][i][:100].replace('/','')}.mp4"
# 使用 save_videos_grid 函数保存视频，帧率为 24
save_videos_grid(sample, save_path, fps=24)
# 记录样本保存的路径信息，方便查看保存位置
logger.info(f'样本保存到: {save_path}')
if __name__ == "__main__":
main()
VAE 理解
VAE即变分自编码器（Variational Autoencoder），是一种生成模型，以下是对其的详细介绍：
基本架构
• 编码器：将输入数据编码成潜在空间中的概率分布参数，通常是输出一个均值向量和一个方差向量，这两个向量共同描述了潜在变量的正态分布。
• 解码器：从潜在空间的概率分布中采样得到潜在变量，然后将其解码还原为与输入数据相似的输出。
工作原理
• 编码过程：输入数据通过编码器网络，编码器学习到输入数据的潜在特征，并将这些特征表示为潜在空间中的概率分布参数，即均值和方差。
• 重参数化技巧：由于概率分布无法直接进行梯度下降优化，VAE采用重参数化技巧，将潜在变量的采样过程转化为可微分的操作。具体来说，通过引入一个随机噪声变量，将其与均值和方差相结合，从而得到潜在变量的样本，这样就可以在反向传播过程中计算梯度并更新网络参数。
• 解码过程：采样得到的潜在变量输入到解码器网络，解码器根据这些潜在特征尝试重建原始输入数据。
• 损失函数：VAE的损失函数由两部分组成，一部分是重建误差，衡量重建数据与原始数据之间的差异，通常使用均方误差等指标；另一部分是KL散度，衡量编码器输出的概率分布与先验分布（一般为标准正态分布）之间的差异，通过最小化KL散度，使潜在空间的分布更加平滑和连续，有助于生成更高质量的新样本。
特点
• 生成能力：能够学习数据的潜在分布，从而生成与训练数据相似但又不完全相同的全新样本，可用于图像生成、文本生成等任务。
• 连续且有结构的隐空间：在潜在空间中学习到的表示是连续且有结构的，这使得样本插值和生成更加自然，也便于进行各种基于潜在空间的操作，如插值、算术运算等，以探索数据的不同特征和属性。
• 概率建模：通过最大化似然函数，能够有效地捕捉数据的复杂分布，为数据建模提供了一种概率视角，有助于更好地理解和解释数据的生成过程。
应用场景
• 图像生成：可以生成各种类型的图像，如手写数字、人脸图像、自然景观等，通过调整潜在变量的值，可以控制生成图像的不同特征，如人脸的表情、年龄、性别等。
• 数据增强：在训练数据有限的情况下，利用VAE生成与原始数据相似的新样本，扩充数据集，提高模型在分类、回归等任务上的性能和泛化能力。
• 异常检测：先学习正常数据的分布，然后对测试数据进行重建，如果重建误差较大，则认为该数据是异常数据，可用于工业设备故障检测、网络安全入侵检测等领域。
• 特征学习与降维：通过编码器将高维数据压缩成低维的潜在表示，这些潜在特征可以用于后续的机器学习任务，如分类、聚类等，同时也可以实现数据的可视化降维。
variational 理解
在变分自编码器（Variational Autoencoder，VAE）中，“variational”一词主要来源于其采用的变分推断（Variational Inference）方法，以下是对其具体理解：
“variational”体现了VAE在建模过程中对数据不确定性的一种变分处理方式，通过引入变分分布并利用变分推断方法来近似难以直接计算的真实后验分布，从而能够在潜在空间中学习到数据的概率分布，实现有效的数据生成和特征学习。这种变分的思想使得VAE在生成模型领域具有独特的优势，能够生成具有多样性且符合数据分布的新样本。
变分推断的引入背景
• 在传统的自编码器中，编码器将输入数据编码为一个确定性的低维表示，即一个固定向量。然而，这种表示方式无法捕捉数据的不确定性信息，也不利于生成新的样本。而VAE的目标是学习数据的概率分布，以便能够生成与训练数据相似的新样本，这就需要引入概率模型和推断方法来处理数据的不确定性，变分推断便应运而生。
变分推断的基本思想
• 概率图模型框架：VAE可以看作是一个概率图模型，其中输入数据x与潜在变量z之间存在某种概率关系。理想情况下，我们希望直接计算后验分布p(z|x)，即给定输入数据x时潜在变量z的分布，从而了解数据的内在结构和不确定性。然而，这个后验分布往往难以直接计算，因为它涉及到复杂的积分运算。
• 变分分布的引入：变分推断通过引入一个变分分布q(z|x)，来近似真实的后验分布p(z|x)。这个变分分布q(z|x)是参数化的，其参数可以通过优化过程来学习，使其尽可能地接近真实的后验分布。在VAE中，编码器的作用就是学习这个变分分布q(z|x)的参数，通常是输出潜在变量z的均值和方差，从而定义了一个以这些参数为特征的正态分布作为变分分布。
优化过程与KL散度
• 证据下界（ELBO）：为了衡量变分分布q(z|x)与真实后验分布p(z|x)之间的相似程度，变分推断定义了一个证据下界（Evidence Lower BOund，ELBO），它是模型对数似然函数的一个下界。ELBO由两部分组成，一部分是重建误差，衡量解码器根据潜在变量z重建输入数据x的质量；另一部分是KL散度，衡量变分分布q(z|x)与先验分布p(z)之间的差异。
• 优化目标：VAE的训练目标就是最大化ELBO，这等价于最小化变分分布q(z|x)与真实后验分布p(z|x)之间的KL散度，同时最大化重建误差。通过这种方式，编码器学习到的变分分布能够更好地近似真实的后验分布，使得潜在变量z能够有效地捕捉输入数据x的不确定性信息，为生成新样本提供有力支持。
