ascend-robot[Docs] Modify current repository URLs to relative paths

HunyuanVideo1.5 使用指南

HunyuanVideo1.5 使用指南

版本说明

参考实现

【T2V 任务 & I2V 任务】

url=https://github.com/Tencent-Hunyuan/HunyuanVideo-1.5
commit_id=bf576ef1d5ddc643cf814b1dff4f4dcc9a7581c7

【推理】

url=https://github.com/Tencent-Hunyuan/HunyuanVideo-1.5
commit_id=bf576ef1d5ddc643cf814b1dff4f4dcc9a7581c7

变更记录

2026.03.06: 首次支持HunyuanVideo1.5 T2V推理、I2V训练&推理任务

2026.02.12: 首次发布HunyuanVideo1.5 T2V训练任务

环境安装

【模型开发时推荐使用配套的环境版本】

请参考安装指南

1. 仓库拉取

拉取MindSpeed MM代码仓，并进入代码仓根目录：

git clone --branch 26.0.0 https://gitcode.com/Ascend/MindSpeed-MM.git
cd MindSpeed-MM

2. 环境搭建

执行如下指令：

bash scripts/install.sh --megatron --msid 96bc0a3bf3398bf45ac26e0bded95ee174ac449b && pip install -r examples/hunyuanvideo_1.5/requirements.txt

3. Decord搭建

【X86版安装】

pip install decord==0.6.0

【ARM版安装】

apt方式安装请参考链接

yum方式安装请参考脚本

权重下载

下载预训练的DiT和VAE权重

mkdir HunyuanVideo1.5
hf download tencent/HunyuanVideo-1.5 --local-dir ./HunyuanVideo1.5

离线链接：

tencent/HunyuanVideo-1.5

下载文本编码器

hf download Qwen/Qwen2.5-VL-7B-Instruct --local-dir ./HunyuanVideo1.5/text_encoder/llm
hf download google/byt5-small --local-dir ./HunyuanVideo1.5/text_encoder/byt5-small
modelscope download --model AI-ModelScope/Glyph-SDXL-v2 --local_dir ./HunyuanVideo1.5/text_encoder/Glyph-SDXL-v2

离线链接：

下载视觉编码器

hf download black-forest-labs/FLUX.1-Redux-dev --local-dir ./ckpts/vision_encoder/siglip --token <your_hf_token>

离线链接：

black-forest-labs/FLUX.1-Redux-dev

最终文件结构如下：

MindSpeed-MM/HunyuanVideo1.5
├── text_encoder
│   ├── Glyph-SDXL-v2
│   │   ├── assets
│   │   │   ├── color_idx.json
│   │   │   ├── multilingual_10-lang_idx.json
│   │   │   └── ...
│   │   └── checkpoints
│   │       ├── byt5_model.pt
│   │       └── ...
│   ├── llm
│   └── byt5-small
└─  scheduler
└─  transformer
│   ├── 720p_t2v
│   │   ├── config.json
│   │   ├── diffusion_pytorch_model.safetensors
└─  vae
└─  scheduler
└─  vision_encoder
└─  upsampler

预训练

数据预处理

将数据处理成如下格式

</your_dataset_dir>
  ├──data.json
  ├──videos
  │  ├──video0001.mp4
  │  ├──video0002.mp4

其中，videos/下存放视频，data.json中包含该数据集中所有的视频-文本对信息，具体示例如下：

[
    {
        "path": "videos/video0001.mp4",
        "cap": "Video discrimination1.",
        "num_frames": 81,
        "fps": 24,
        "resolution": {
            "height": 480,
            "width": 832
        }
    },
    {
        "path": "videos/video0002.mp4",
        "cap": "Video discrimination2.",
        "num_frames": 81,
        "fps": 24,
        "resolution": {
            "height": 480,
            "width": 832
        }
    },
    ......
]

修改文件MindSpeed-MM/examples/hunyuanvideo_1.5/data.txt，其中每一行表示一个数据集，包含两个参数。第一个参数表示数据文件夹的路径，即上述文件夹 </your_dataset_dir> 的绝对路径地址，第二个参数表示data.json文件的路径，用,分隔，示例如下：

/your_dataset_dir,/your_dataset_dir/data.json

训练

准备工作

在开始之前，请确认环境准备、模型权重下载、数据预处理已完成。

参数配置

检查数据集路径、模型权重路径、并行参数配置等是否完成

配置文件	修改字段	修改说明
examples/hunyuanvideo_1.5/{task}/data.json	from_pretrained	修改为下载的Tokenizers: llm,byt5-small的权重所对应的路径
examples/hunyuanvideo_1.5/{task}/data.json	color_ann_path	修改为下载的Glyph-SDXL-v2模型中color_idx.json文件所对应的路径
examples/hunyuanvideo_1.5/{task}/data.json	font_ann_path	修改为下载的Glyph-SDXL-v2模型中multilingual_10-lang_idx.json文件所对应的路径
examples/hunyuanvideo_1.5/{task}/data.json	num_frames	视频的帧数,帧数建议满足4n+1
examples/hunyuanvideo_1.5/{task}/data.json	min_num_frames	最小视频帧数，最小为4*1+1
examples/hunyuanvideo_1.5/{task}/model_hunyuanvideo_15.json	from_pretrained	修改为下载的权重所对应路径（包括vae, text_encoder）
examples/hunyuanvideo_1.5/{task}/model_hunyuanvideo_15.json	byT5_ckpt_path	修改为下载的byt5_model.pt所对应路径
examples/hunyuanvideo_1.5/{task}/model_hunyuanvideo_15.json	color_ann_path	修改为下载的Glyph-SDXL-v2模型中color_idx.json文件所对应的路径
examples/hunyuanvideo_1.5/{task}/model_hunyuanvideo_15.json	font_ann_path	修改为下载的Glyph-SDXL-v2模型中multilingual_10-lang_idx.json文件所对应的路径
examples/hunyuanvideo_1.5/{task}/pretrain_hunyuanvideo_15.sh	NPUS_PER_NODE	每个节点的卡数
examples/hunyuanvideo_1.5/{task}/pretrain_hunyuanvideo_15.sh	NNODES	节点数量
examples/hunyuanvideo_1.5/{task}/pretrain_hunyuanvideo_15.sh	LOAD_PATH	预训练DiT权重路径,下面一级目录包含config文件
examples/hunyuanvideo_1.5/{task}/pretrain_hunyuanvideo_15.sh	SAVE_PATH	训练过程中保存的权重路径

上述配置文件中{task} = i2v or t2v，请根据训练任务自主选择。

注：当前LOAD_PATH路径无效时，MindSpeed会对模型随机初始化从头训练。为防止加载失败，请留意日志中的warning信息，或者自行确认路径合法。

【并行化配置参数说明】：

fsdp2
- 使用场景：在模型参数规模较大时，可以通过开启fsdp2降低静态内存，默认开启。
- 使能方式：examples/hunyuanvideo_1.5/{task}/pretrain_*.sh的GPT_ARGS中加入--use-torch-fsdp2，--fsdp2-config-path ${fsdp2_config}，--untie-embeddings-and-output-weights以及--ckpt-format torch_dcp，其中fsdp2_config配置请参考：FSDP2说明

启动训练

【T2V 任务】

bash examples/hunyuanvideo_1.5/t2v/pretrain_*.sh

【I2V 任务】

bash examples/hunyuanvideo_1.5/i2v/pretrain_*.sh

推理

准备工作

在开始之前，请确认环境准备、模型权重下载已完成

参数配置

检查模型权重路径、并行参数等配置是否完成

配置文件	修改字段	修改说明
examples/hunyuanvideo_1.5/{task}/inference_model_15.json	from_pretrained	修改为下载的权重所对应路径，包括VAE、Tokenizer、Text Encoder、DiT、Siglip（I2V）
examples/hunyuanvideo_1.5/{task}/inference_model_15.json	color_ann_path	修改为下载的Glyph-SDXL-v2模型中color_idx.json文件所对应的路径
examples/hunyuanvideo_1.5/{task}/inference_model_15.json	font_ann_path	修改为下载的Glyph-SDXL-v2模型中multilingual_10-lang_idx.json文件所对应的路径
examples/hunyuanvideo_1.5/{task}/inference_model_15.json	byT5_ckpt_path	修改为下载的byt5_model.pt所对应路径
examples/hunyuanvideo_1.5/{task}/inference_model_15.json	input_size	生成视频的分辨率，格式为 [t, h, w], 分别是视频帧数、高、宽，常用分辨率为480p、720p (9:16)
examples/hunyuanvideo_1.5/{task}/inference_model_15.json	save_path	生成视频的保存路径
examples/hunyuanvideo_1.5/{task}/samples_prompts.txt	文件内容	可自定义自己的prompt，一行为一个prompt
examples/hunyuanvideo_1.5/i2v/samples_images.txt	图片	可自定义自己的image，一行为一个图片地址
examples/hunyuanvideo_1.5/{task}/inference_hunyuanvideo.sh	MM_MODEL	用来控制生成参数的配置文件路径

上述配置文件中{task} = i2v or t2v，请根据训练任务自主选择。

启动推理

【T2V 任务】

bash examples/hunyuanvideo_1.5/t2v/inference_*.sh

【I2V 任务】

bash examples/hunyuanvideo_1.5/i2v/inference_*.sh

环境变量声明

环境变量	描述	取值说明
`ASCEND_SLOG_PRINT_TO_STDOUT`	是否开启日志打印	`0`: 关闭日志打屏 `1`: 开启日志打屏
`ASCEND_GLOBAL_LOG_LEVEL`	设置应用类日志的日志级别及各模块日志级别，仅支持调试日志	`0`: 对应DEBUG级别 `1`: 对应INFO级别 `2`: 对应WARNING级别 `3`: 对应ERROR级别 `4`: 对应NULL级别，不输出日志
`TASK_QUEUE_ENABLE`	用于控制开启task_queue算子下发队列优化的等级	`0`: 关闭 `1`: 开启Level 1优化 `2`: 开启Level 2优化
`COMBINED_ENABLE`	设置combined标志。设置为0表示关闭此功能；设置为1表示开启，用于优化非连续两个算子组合类场景	`0`: 关闭 `1`: 开启
`CPU_AFFINITY_CONF`	控制CPU端算子任务的处理器亲和性，即设定任务绑核	设置`0`或未设置: 表示不启用绑核功能 `1`: 表示开启粗粒度绑核 `2`: 表示开启细粒度绑核
`HCCL_CONNECT_TIMEOUT`	用于限制不同设备之间socket建链过程的超时等待时间	需要配置为整数，取值范围`[120,7200]`，默认值为`120`，单位`s`
`PYTORCH_NPU_ALLOC_CONF`	控制缓存分配器行为	`expandable_segments:<value>`: 使能内存池扩展段功能，即虚拟内存特征
`HCCL_EXEC_TIMEOUT`	控制设备间执行时同步等待的时间，在该配置时间内各设备进程等待其他设备执行通信同步	需要配置为整数，取值范围`[68,17340]`，默认值为`1800`，单位`s`
`ACLNN_CACHE_LIMIT`	配置单算子执行API在Host侧缓存的算子信息条目个数	需要配置为整数，取值范围`[1, 10,000,000]`，默认值为`10000`
`TOKENIZERS_PARALLELISM`	用于控制Hugging Face的transformers库中的分词器（tokenizer）在多线程环境下的行为	`False`: 禁用并行分词 `True`: 开启并行分词
`MULTI_STREAM_MEMORY_REUSE`	配置多流内存复用是否开启	`0`: 关闭多流内存复用 `1`: 开启多流内存复用
`NPU_ASD_ENABLE`	控制是否开启Ascend Extension for PyTorch的特征值检测功能	设置`0`或未设置: 关闭特征值检测 `1`: 表示开启特征值检测，只打印异常日志，不告警 `2`:开启特征值检测，并告警 `3`:开启特征值检测，并告警，同时会在device侧info级别日志中记录过程数据
`ASCEND_LAUNCH_BLOCKING`	控制算子执行时是否启动同步模式	`0`: 采用异步方式执行 `1`: 强制算子采用同步模式运行
`NPUS_PER_NODE`	配置一个计算节点上使用的NPU数量	整数值（如 `1`, `8` 等）