English

本项目提供了一个高效的工具，用于从视频中提取潜在特征，为后续的视频生成和处理任务做准备。

• 支持各种视频格式和分辨率
• 多GPU并行处理，提高效率
• 支持多种宽高比
• 高性能VAE模型用于特征提取
• 自动跳过已处理的视频，支持断点续传功能

输入的视频元数据文件(meta_file.list)应为JSON文件路径的列表，每个JSON文件包含以下字段：

meta_file.list的格式（例如，./assets/demo/i2v_lora/train_dataset/meta_file.list）如下：

/path/to/0.json
/path/to/1.json
/path/to/2.json
...

重要: 确保每个视频的名字是唯一的!!!

/path/to/0.json的格式（例如，./assets/demo/i2v_lora/train_dataset/meta_data.json）如下：

{
  "video_path": "/path/to/video.mp4",
  "raw_caption": {
    "long caption": "视频的详细描述文本"
  }
}

在hyvideo/hyvae_extract/vae.yaml中配置参数：

vae_path: "./ckpts/hunyuan-video-i2v-720p/vae" # VAE模型路径
video_url_files: "/path/to/meta_file.list"     # 视频元数据文件列表
output_base_dir: "/path/to/output/directory"   # 输出目录
sample_n_frames: 129                           # 采样帧数
target_size:                                   # 目标尺寸
  - bucket_size
  - bucket_size
enable_multi_aspect_ratio: True                # 启用多种宽高比
use_stride: True                               # 使用步长采样

target_size参数定义了分辨率桶大小。以下是不同质量级别的推荐值：

质量	桶大小	典型分辨率
720p	960	1280×720或类似
540p	720	960×540或类似
360p	480	640×360或类似

当enable_multi_aspect_ratio设置为True时，系统将使用这些桶大小作为基础来生成多种宽高比的桶。为了获得最佳性能，请根据您的硬件能力选择平衡质量和内存使用的桶大小。

# 设置环境变量
export HOST_GPU_NUM=8  # 设置要使用的GPU数量

# 运行提取脚本
cd HunyuanVideo-I2V
bash hyvideo/hyvae_extract/start.sh

cd HunyuanVideo-I2V
export PYTHONPATH=${PYTHONPATH}:`pwd`
export HOST_GPU_NUM=1
CUDA_VISIBLE_DEVICES=0 python3 -u hyvideo/hyvae_extract/run.py --local_rank 0 --config 'hyvideo/hyvae_extract/vae.yaml'

程序在指定的输出目录中生成以下文件：

1. {video_id}.npy - 视频的潜在特征数组
2. json_path/{video_id}.json - 包含视频元数据的JSON文件，包括：
   • video_id: 视频ID
   • latent_shape: 潜在特征的形状
   • video_path: 原始视频路径
   • prompt: 视频描述/提示
   • npy_save_path: 保存潜在特征的路径

output_base_dir/
│
├── {video_id_1}.npy # 视频1的潜在特征数组
├── {video_id_2}.npy # 视频2的潜在特征数组
├── {video_id_3}.npy # 视频3的潜在特征数组
│ ...
├── {video_id_n}.npy # 视频n的潜在特征数组
│
└── json_path/ # 包含元数据JSON文件的目录
      ├── {video_id_1}.json # 视频1的元数据
      ├── {video_id_2}.json # 视频2的元数据
      ├── {video_id_3}.json # 视频3的元数据
      │ ...
      └── {video_id_n}.json # 视频n的元数据

当enable_multi_aspect_ratio设置为True时，系统会选择最接近视频原始宽高比的目标尺寸，而不是强制将其裁剪为固定尺寸。这有助于保持视频内容的完整性。

当use_stride设置为True时，系统会根据视频的帧率自动调整采样步长：

• 当帧率 >= 50fps时，步长为2
• 当帧率 < 50fps时，步长为1