Wan2.2 使用指南

Wan2.2 使用指南

版本说明

参考实现

【预训练任务】

5B:

url=https://github.com/modelscope/DiffSynth-Studio.git
commit_id=f0ea049

A14B:

url=https://github.com/modelscope/DiffSynth-Studio.git
commit_id=833ba1e

【推理】

url=https://github.com/huggingface/diffusers/tree/v0.35.1

变更记录

2025.10.11: 首次支持Wan2.2模型

任务支持列表

模型大小	任务类型	预训练	在线T2V推理	在线I2V推理
5B	t2v	✔	✔
5B	ti2v	✔		✔
A14B	t2v	✔	✔
A14B	i2v	✔		✔

环境安装

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

请参考安装指南

仓库拉取

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

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

环境搭建

执行如下指令：

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

Decord搭建

【X86版安装】

pip install decord==0.6.0

【ARM版安装】

apt方式安装请参考链接

yum方式安装请参考脚本

权重下载及转换

Diffusers权重下载

模型	Hugging Face下载链接
5B	https://huggingface.co/Wan-AI/Wan2.2-TI2V-5B-Diffusers
T2V-14B	https://huggingface.co/Wan-AI/Wan2.2-T2V-A14B-Diffusers
I2V-14B	https://huggingface.co/Wan-AI/Wan2.2-I2V-A14B-Diffusers

权重转换

需要对下载后的Wan2.2模型权重transformer部分进行权重转换，运行权重转换脚本：

mm-convert WanConverter hf_to_mm \
 --cfg.source_path ./weights/Wan-AI/Wan2.2-{TI2V/T2V/I2V}-{5/A14}B-Diffusers/transformer* \
 --cfg.target_path ./weights/Wan-AI/Wan2.2-{TI2V/T2V/I2V}-{5/A14}B-Diffusers/transformer*

通过进一步将权重转换为DCP格式，启动时分布式加载ckpt，可以降低对host侧的内存峰值压力（可选）。转换命令如下：

mm-convert WanConverter mm_to_dcp \
 --cfg.source_path ./weights/Wan-AI/Wan2.2-{TI2V/T2V/I2V}-{5/A14}B-Diffusers/transformer* \
 --cfg.target_path ./weights/Wan-AI/Wan2.2-{TI2V/T2V/I2V}-{5/A14}B-Diffusers/transformer*

权重转换脚本的参数说明如下：

参数	含义
--cfg.source_path	原始权重路径
--cfg.target_path	转换或切分后权重保存路径

如需转回Hugging Face格式，需运行权重转换脚本：

注： wan2.2使用fsdp2进行训练，需首先进行其训练权重后处理，再进行如下操作：

mm-convert WanConverter mm_to_hf \
 --cfg.source_path path_for_your_saved_weight \
 --cfg.target_path ./converted_weights/Wan-AI/Wan2.2-{TI2V/T2V/I2V}-{5/A14}B-Diffusers/transformer* \
 --cfg.hf_dir weights/Wan-AI/Wan2.2-{TI2V/T2V/I2V}-{5/A14}B-Diffusers/transformer*

权重转换脚本的参数说明如下：

参数	含义
--cfg.source_path	MindSpeed MM保存的权重路径
--cfg.target_path	转换后的Hugging Face权重路径
--cfg.hf_dir	原始Hugging Face权重路径，需要从该目录下获取原始huggingface配置文件

注：对A14B模型，hugging face diffusers权重中包含两个transformer权重，后缀中transformer对应高噪声（high）模型，transformer_2对应低噪声（low）模型。

预训练

数据预处理

将数据处理成如下格式

</dataset>
  ├──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
        }
    },
    ......
]

修改examples/wan2.2/data.txt文件，其中每一行表示一个数据集，第一个参数表示数据文件夹的路径，第二个参数表示data.json文件的路径，用,分隔

训练

准备工作

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

参数配置

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

配置文件	修改字段	修改说明
examples/wan2.2/{model_size}/{task}/data.json	from_pretrained	修改为下载的tokenizer的权重所对应的路径
examples/wan2.2/{model_size}/{task}/pretrain_model*.json	from_pretrained	修改为下载的权重所对应路径（包括vae, text_encoder）
examples/wan2.2/{model_size}/{task}/pretrain*.sh	NPUS_PER_NODE	每个节点的卡数
examples/wan2.2/{model_size}/{task}/pretrain*.sh	NNODES	节点数量
examples/wan2.2/{model_size}/{task}/pretrain*.sh	LOAD_PATH	权重转换后的预训练权重路径
examples/wan2.2/{model_size}/{task}/pretrain*.sh	SAVE_PATH	训练过程中保存的权重路径
examples/wan2.2/{model_size}/{task}/pretrain*.sh	CP	训练时的CP size（建议根据训练时设定的分辨率调整）

注：

当前LOAD_PATH路径无效时，MindSpeed会对模型随机初始化从头训练。为防止加载失败，请留意日志中的warning信息，或者自行确认路径合法。
使用断点续训功能时，需删去'--downcast-to-bf16'、'--no-load-optim'、'--no-load-rng'、'--no-save-optim'、'--no-save-rng'几项配置

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

CP: 序列并行。
- 使用场景：在视频序列（分辨率X帧数）较大时，可以开启来降低内存占用。
- 使能方式：在启动脚本中设置 CP > 1，如：CP=2；
- 限制条件：head 数量需要能够被CP整除（在examples/wan2.2/{model_size}/{task}/pretrain_model*.json中配置，参数为num_heads）
- 默认使能方式为Ulysses序列并行。
- DiT-RingAttention：DiT RingAttention序列并行请参考文档
- DiT-USP: DiT USP混合序列并行（Ulysses + RingAttention）请参考文档
- 注：wan2.2使用full attention，对应general，即--attention-mask-type general。

fsdp2

使用场景：在模型参数规模较大时，可以通过开启fsdp2降低静态内存。
使能方式：examples/wan2.2/{model_size}/{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说明

训练权重后处理：使用该特性训练时，保存的权重需要使用下面的转换脚本进行后处理才能用于推理：

# 训练结束后保存的权重路径
save_path="./wandit_weight_save"
iter_dir="$save_path/iter_$(printf "%07d" $(cat $save_path/latest_checkpointed_iteration.txt))"
# 权重转换的目标路径
convert_dir="./dcp_to_torch"
mkdir -p $convert_dir/release/mp_rank_00
cp $save_path/latest_checkpointed_iteration.txt $convert_dir/
echo "release" > $convert_dir/latest_checkpointed_iteration.txt
python -m torch.distributed.checkpoint.format_utils dcp_to_torch "$iter_dir" "$convert_dir/release/mp_rank_00/model_optim_rng.pt"

Encoder Interleaved Offload: Encoder 交替卸载
- 使用场景：在NPU内存瓶颈的训练场景中，可以一次性编码多步训练输入数据然后卸载编码器至cpu上，使得文本编码器无需常驻内存，减少内存占用。故可在不增加内存消耗的前提下实现在线训练，避免手动离线提取特征。T2V、I2V任务均支持。
- 使能方式：在xxx_model.json中，设置 encoder_offload_interval > 1. 建议设置根据实际场景设置大于10，可以分摊卸载带来的性能损耗
- 限制条件：启用时建议调大num_worker以达最佳性能; 支持与Encoder-DP同时开启。

启动训练

【5B】

bash examples/wan2.2/{model_size}/{task}/pretrain.sh

【A14B】

bash examples/wan2.2/{model_size}/{task}/pretrain_{type}.sh

LoRA微调

当前已支持fsdp2场景下 Wan2.2 A14B t2v模型的lora微调，请按以下步骤进行准备：

准备工作

数据处理、权重下载及转换同预训练章节。

LoRA权重转换（可选）

若需加载从Diffsynth保存的lora预训练权重，需要先对lora权重完成以下权重转换

mm-convert WanConverter lora_hf_to_mm \
 --cfg.source_path ./weights/Wan-AI/Wan2.2-T2V-A14B-lora \
 --cfg.target_path ./weights/Wan-AI/Wan2.2-T2V-A14B-lora-mm

再将权重转换为DCP格式，转换命令如下：

mm-convert WanConverter mm_to_dcp \
 --cfg.source_path ./weights/Wan-AI/Wan2.2-T2V-A14B-lora-mm \
 --cfg.target_path ./weights/Wan-AI/Wan2.2-T2V-A14B-lora-dcp

权重转换脚本的参数说明如下：

参数	含义
--cfg.source_path	原始权重路径
--cfg.target_path	转换或切分后权重保存路径

参数配置

参数配置同训练章节，除此之外，涉及lora微调特有参数：

配置文件	修改字段	修改说明
examples/wan2.2/A14B/t2v/finetune_lora_{low/high}.sh	lora-r	lora更新矩阵的维度
examples/wan2.2/A14B/t2v/finetune_lora_{low/high}.sh	lora-alpha	lora-alpha 调节分解后的矩阵对原矩阵的影响程度
examples/wan2.2/A14B/t2v/finetune_lora_{low/high}.sh	lora-target-modules	应用lora的模块列表

LoRA权重加载（可选）

若需加载从Diffsynth保存的lora预训练权重，需在启动脚本examples/wan2.2/A14B/t2v/finetune_lora_{low/high}.sh中添加转换后的LoRA预训练权重路径并修改GPT_ARGS，相关配置修改如下：

LOAD_PATH="./weights/Wan-AI/Wan2.2-T2V-A14B-Diffusers/transformer/"
LORA_PATH="./weights/Wan-AI/Wan2.2-T2V-A14B-lora-dcp"

# 原始的 --load $LOAD_PATH \ 需替换为 --load-base-model $LOAD_PATH \
GPT_ARGS="
...
  --load-base-model $LOAD_PATH \
  --load $LORA_PATH \
...
"

启动微调

bash examples/wan2.2/A14B/t2v/finetune_lora_{low/high}.sh

微调完成后，需首先对保存的lora权重进行训练权重后处理，再使用权重转换工具，将训练好的lora权重与原始权重进行合并

mm-convert WanConverter merge_lora_to_base \
 --cfg.source_path <./converted_weights/Wan-AI/Wan2.2-T2V-14B-Diffusers/transformer*/> \
 --cfg.target_path <./converted_weights/Wan-AI/Wan2.2-T2V-14B-Diffusers/transformer_merge/> \
 --cfg.lora_path <lora_save_path> \
 --lora_alpha 32 \
 --lora_rank 32

权重合并脚本的参数说明如下：

参数	含义
--cfg.source_path	原始权重路径
--cfg.target_path	合并后后权重保存路径
--cfg.lora_path	lora权重保存路径
--lora_alpha	调节分解后的矩阵对原矩阵的影响程度
--lora_rank	lora更新矩阵的维度

推理

准备工作

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

参数配置

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

配置文件	修改字段	修改说明
examples/wan2.2/{model_size}/{task}/inference_model.json	from_pretrained	修改为下载的权重所对应路径（包括vae、tokenizer、text_encoder）
examples/wan2.2/samples_t2v_prompts.txt	文件内容	T2V推理任务的prompt，可自定义，一行为一个prompt
examples/wan2.2/samples_i2v_prompts.txt	文件内容	I2V推理任务的prompt，可自定义，一行为一个prompt
examples/wan2.2/samples_i2v_images.txt	文件内容	I2V推理任务的首帧图片路径，可自定义，一行为一个图片路径
examples/wan2.2/{model_size}/{task}/inference_model.json	save_path	生成视频的保存路径
examples/wan2.2/{model_size}/{task}/inference_model.json	input_size	生成视频的分辨率，格式为 [t, h, w]
examples/wan2.2/{model_size}/{task}/inference_model.json	low_noise_predictor	转换之后的transformer_2（低噪声）部分权重路径，仅A14B模型涉及
examples/wan2.2/{model_size}/{task}/inference.sh	LOAD_PATH	转换之后的transformer部分权重路径，对A14B模型对应高噪声模型

启动推理

bash examples/wan2.2/{model_size}/{task}/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` 等）