Wan2.2-I2V 昇腾 NPU 推理 YAML 配置详解:从单卡基线到 CFG×Ulysses 多卡并行
Wan2.2-I2V 昇腾 NPU 推理 YAML 配置详解:从单卡基线到 CFG×Ulysses 多卡并行
本文围绕 CANN 优化样例仓库中 Wan2.2-I2V 图生视频样例的 config/*.yaml 配置体系展开,完整解析推理参数、并行度约束、DiT 缓存(Dit-Cache)调参与启动链路。读者读完可掌握如何基于 config 目录 下的模板快速切换单卡/多卡场景,理解 model_args 如何透传给 generate.py,并学会按需调整 FBCache / TeaCache 参数以权衡推理速度与视频质量。
一、配置体系总览:三个默认 YAML 各司其职
Wan2.2-I2V 的推理参数全部集中在 config/*.yaml 中维护,infer.sh 默认使用 14b_cfg2_ulysses4.yaml 启动推理。仓库预置了三份配置模板,分别对应不同场景:
| YAML 文件 | 卡数 | 适用场景 |
|---|---|---|
14b_single.yaml |
1 | 单卡基线;dit_cache.method 可选 NoCache / FBCache / TeaCache,YAML 内有注释展示各方法参数 |
14b_single_platform.yaml |
1 | CANNLab 一站式开发平台专用模板,由 infer_platform.sh 读取并生成临时本地权重配置 |
14b_cfg2_ulysses4.yaml |
8 | CFG 并行 × 2 + Ulysses 序列并行 × 4 + VAE 并行,支持 1280*720*81、832*480*61 等原生规格(cfg_size / ulysses_size / ring_size 可按需调整,乘积等于 world_size 即可) |
重要约束:多卡推理与 Dit-Cache 互斥,多卡配置里
dit_cache.method固定为NoCache。
二、YAML 顶层结构与启动链路
配置文件的顶层键由 executor/scripts/mm_function.sh 中的 mm_validate_yaml 校验,白名单包含 model_name、world_size、master_port、entry_script、launcher、launcher_args、env_vars、dit_cache、sparse、model_args,其中 model_name、world_size、entry_script 为必填项。启动时 infer.sh 仅需指定 YAML_FILE_NAME 一行即可切换配置:
# 默认:8 卡多卡推理
export YAML_FILE_NAME=14b_cfg2_ulysses4.yaml
# 单卡(dit_cache.method 改为 FBCache / TeaCache 即启用对应缓存)
# export YAML_FILE_NAME=14b_single.yaml
随后 mm_launch 会按固定流水线执行:mm_check_launch(检查 YAML 存在)→ mm_validate_yaml(结构/枚举校验,快速失败)→ mm_parse_yaml(解析 model_name、world_size、master_port、entry_script、launcher)→ mm_setup_env(设置 NPU 优化环境变量与 HCCL 通信配置,并自动创建 res/<YYYYMMDD>/<model_name>/ 日志目录)→ mm_generate_cache_config(若 YAML 含 dit_cache 段,将其作为缓存配置通过 --cache_config <yaml> 透传给 Python 侧 CacheManager)→ mm_launch_task(调用 torchrun --master_port=<master_port> --nproc_per_node=<world_size> 拉起 entry_script,输出 tee 到 log_<timestamp>.log)。
三、model_args 字段全解析(核心参数表)
以 14b_single.yaml 为例,完整的 model_args 段如下,注释标注了取值约束:
model_args:
ckpt_dir: "/path/to/Wan2.2-I2V-14B"
# Weight directory.
image: "examples/i2v_input.JPG" # Input image path for I2V.
prompt: "Summer beach ..." # Text prompt.
task: "i2v-A14B" # Task. Options: ["t2v-A14B", "i2v-A14B", "ti2v-5B", "animate-14B", "s2v-14B"].
size: "640*360" # Output size. Options: ["720*1280", "1280*720", "480*832", "832*480", "640*360", "360*640", "704*1280", "1280*704", "1024*704", "704*1024"].
frame_num: 61 # Output frame count. Constraint: 4n+1.
sample_steps: 40 # Number of denoising steps.
sample_solver: "unipc" # Sampling solver. Options: ["unipc", "dpm++"].
sample_shift: null # FlowMatch shift. null means task default.
sample_guide_scale: null # CFG guidance scale. null means task default.
base_seed: 100 # Random seed.
convert_model_dtype: true # Whether to cast model parameters for inference. Options: [false, true].
offload_model: null # Whether to offload model to CPU. Options: [false, true, null].
cfg_size: 1 # CFG parallel degree. Current CFG parallel values: 1 or 2.
ulysses_size: 1 # Ulysses sequence parallel degree. Must divide the task head count.
ring_size: 1 # Ring attention parallel degree.
tp_size: 1 # Tensor parallel degree. Current code only accepts 1.
dit_fsdp: true # Whether to enable DiT FSDP. Options: [false, true].
t5_fsdp: true # Whether to enable T5 FSDP. Options: [false, true].
t5_cpu: false # Whether to place T5 on CPU. Options: [false, true].
vae_parallel: true # Whether to enable VAE parallelism. Options: [false, true].
use_prompt_extend: false # Whether to enable prompt extension. Options: [false, true].
prompt_extend_method: "local_qwen"
# Prompt extension method. Options: ["dashscope", "local_qwen"].
prompt_extend_target_lang: "zh" # Prompt extension target language. Options: ["zh", "en"].
quant_mode: 0 # Quantization workflow. Options: [0, 1, 2, 3].
model_name: "wan2.2-i2v" # Model name. Options: ["wan2.2-i2v"].
world_size: 1 # Number of launched processes. Must equal cfg_size * ulysses_size * ring_size * tp_size.
master_port: 29600 # torchrun master port.
entry_script: "generate.py" # Entry script. Options: ["generate.py"].
env_vars:
PYTORCH_NPU_ALLOC_CONF: "expandable_segments:True"
# NPU memory allocator config.
TASK_QUEUE_ENABLE: "2" # NPU task queue config.
CPU_AFFINITY_CONF: "1" # CPU affinity config.
3.1 任务与生成规格字段
task:任务类型,Wan2.2-I2V 样例固定为i2v-A14B。在 generate.py 中_validate_args会校验task必须存在于WAN_CONFIGS与EXAMPLE_PROMPT,i2v 任务还强制要求提供image路径,否则直接抛错。size:输出分辨率,从SIZE_CONFIGS中取值,I2V 任务的输出宽高比会跟随输入图片;frame_num生成帧数必须满足4n+1(如 61、81),这是 Wan 视频潜在空间时序下采样结构决定的。sample_steps:去噪步数,默认 40;sample_solver采样器可选unipc/dpm++;sample_shift与sample_guide_scale置null时使用任务默认值(在WAN_CONFIGS[task]中定义)。base_seed:随机种子,多卡场景下由 rank 0 通过dist.broadcast_object_list广播,保证各卡一致;-1表示随机生成。
3.2 精度与显存相关字段
convert_model_dtype: true:单卡场景将模型权重转换到推理精度,降低显存占用(对应generate.py的--convert_model_dtype)。offload_model:是否在前向后将模型卸载回 CPU,null时按world_size自动推导——单卡默认True,多卡默认False。dit_fsdp/t5_fsdp:分别为 DiT 与 T5 使能 FSDP(Fully Sharded Data Parallel)以降低显存占用,注意 generate.py 在非分布式环境下(world_size == 1)若开启这两个开关会直接报错。t5_cpu:将 T5 文本编码器放置到 CPU 上运行。quant_mode:量化工作流开关,0 表示不量化直接推理,1 导出校准数据,2 导出量化模型,3 使用量化模型推理(对应generate.py的--quant_mode与--quant_data_dir)。
3.3 并行度字段与约束
cfg_size(CFG 并行度,当前仅支持 1 或 2)、ulysses_size(Ulysses 序列并行度,必须能整除任务头数 cfg.num_heads,代码中会显式校验)、ring_size(Ring attention 并行度)、tp_size(张量并行度,当前代码 raise NotImplementedError,仅接受 1)。序列并行总约束为 world_size == cfg_size * ulysses_size * ring_size * tp_size,torchrun 会按此拉起 --nproc_per_node 个进程。指定参与推理的设备需在启动前设置:export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7。
四、model_args → generate.py 参数透传规则
mm_build_args 定义了 YAML 到命令行参数的转换规则,理解这条规则才能准确书写配置:
| YAML 类型 | 命令行效果 | 示例 |
|---|---|---|
| 字符串/数字 | --key value |
sample_steps: 40 → --sample_steps 40 |
布尔 true |
--key(flag) |
dit_fsdp: true → --dit_fsdp |
布尔 false |
忽略 | dit_fsdp: false → 不添加 |
| 列表 | --key v1 v2 … |
video-size: [720, 1280] → --video-size 720 1280 |
需要强制将布尔以字面量传给解析器时(如 pyrallis/Hydra),用加引号的字符串:
key: "False"→--key False。
该规则在 executor/scripts/mm_function.sh 的 mm_build_args 函数中实现,列表值使用 shlex.quote 逐项引用后拼接。generate.py 中 _parse_args 定义了与上表一一对应的 argparse 参数(如 --size 的 choices=list(SIZE_CONFIGS.keys())、--sample_solver 的 choices=['unipc', 'dpm++']),若 YAML 传入非法取值会在子进程启动前被 argparse 拒绝,实现快速失败。
五、dit_cache 缓存配置与调参
dit_cache 段控制 DiT(去噪 Transformer)的推理缓存策略,适用于单卡配置:
dit_cache:
method: "NoCache" # DiT cache method. Options: ["NoCache", "FBCache", "TeaCache"].
enable_separate_cfg: true # Whether to cache CFG branches separately. Options: [false, true].
params:
# FBCache / TeaCache
rel_l1_thresh: 0.05 # Relative L1 threshold.
# TeaCache
coefficients: [] # TeaCache polynomial coefficients.
warmup: 2 # Number of initial full-compute steps.
配置加载逻辑在 module/dit_cache/cache_method.py 的 load_cache_config 中:读取 YAML 的 dit_cache 段后与 DEFAULT_CACHE_CONFIG 合并——FBCache 默认 rel_l1_thresh=0.05、TeaCache 默认 rel_l1_thresh=0.15 且系数 coefficients=[733.226126, -401.131952, 67.5869174, -3.149879, 0.0961237896]、warmup=2,用户 params 会覆盖对应默认值。enable_separate_cfg 表示对 CFG 两个分支(条件/无条件)分别缓存判断,配合 generate.py 中 cache_manager.from_config(config_path=args.cache_config, cache_params={"num_steps": args.sample_steps}) 使用。
5.1 三种缓存方法的行为差异
- NoCache:不做任何缓存,所有步数全量计算,是单卡基线模式,也是多卡配置的固定取值。
- FBCache(First-Block Cache):以第一个 DiT block 的输入特征为判据,计算相邻两步的相对 L1 差异
mean(|cur - prev|) / (mean(|cur|) + 1e-8),低于rel_l1_thresh则复用上一步的残差previous_residual + ori_latent跳过本轮计算。阈值越大跳过越多、速度越快,但质量损失越大。 - TeaCache:使用多项式重缩放函数
np.poly1d(coefficients)对相对 L1 距离做重缩放后累积判断(accumulated_rel_l1 < rel_l1_thresh才复用),warmup指定前 N 步强制完整计算(代码中同时保证最后ret_steps步强制计算以稳定收尾)。
值得注意,FBCache 与 TeaCache 内部通过 _sync_scalar_for_sp 对差异标量做序列并行组内 all_reduce 取均值,保证多卡场景下缓存决策一致;但多卡配置仍被禁止启用缓存(见下文)。缓存策略会在推理结束时通过 print_statistics 输出 skip rate 等统计,便于量化加速收益。
5.2 多卡与缓存互斥
在 generate.py 中,当 world_size > 1 时会强制将 cache_manager.cache_method 重置为 NoCache() 并打印提示 Cannot enable both Multi-NPU and DIT-Cache。因此多卡配置中 dit_cache.method 必须保持 NoCache,这是 14b_cfg2_ulysses4.yaml 的设计约束。
六、多卡并行实战:14b_cfg2_ulysses4.yaml 解读
8 卡配置的并行组合为 cfg_size=2(CFG 并行:条件/无条件分支各占 4 卡)× ulysses_size=4(Ulysses 序列并行)× ring_size=1,同时开启 dit_fsdp、t5_fsdp、vae_parallel,world_size=8 满足乘积约束。该组合支持 1280*720*81、832*480*61 等原生规格的高清推理,generate.py 中会构造 ParallelConfig(sp_degree=4, ulysses_degree=4, ring_degree=1, tp_degree=1, use_cfg_parallel=True, world_size=8) 并调用 init_parallel_env 初始化序列并行环境。vae_parallel 使能多卡 VAE 并行,与 module/vae_patch_parallel.py 中的实现对应。
七、CANNLab 一站式平台模板:14b_single_platform.yaml
14b_single_platform.yaml 是 CANNLab 一站式开发平台的单卡模板,由 infer_platform.sh 读取,在运行时把 model_args.ckpt_dir 原地替换为本地 ModelScope 权重路径并生成临时 YAML 再拉起推理。脚本本身依次完成:source CANN 环境脚本 → 安装 torch / torch_npu(校验版本为 2.7.1)→ 以固定 commit 合入上游 Wan2.2 源码(非覆盖模式 cp -rn)→ 安装项目依赖 → 通过 ModelScope 下载权重(Wan-AI/Wan2.2-I2V-A14B-BF16)→ 生成指向本地权重的临时 YAML → 启动单卡推理,各步骤均幂等、可重复执行。使用前需按平台实际路径修改脚本顶部的 WEIGHTS_DIR 与 CANN_SET_ENV 两个变量。普通 infer.sh 与平台启动互不影响。
八、实操检查清单与注意事项
- 修改权重与输入:打开所选 YAML,修改
model_args.ckpt_dir指向已下载的权重目录;更换分辨率、帧数、图片或提示词时直接改size、frame_num、image、prompt字段。 - 环境准备:推理前先
source /usr/local/Ascend/ascend-toolkit/set_env.sh;PYTHONPATH不应全局设置项目根路径,mm_function.sh会在torchrun子进程中按需注入,避免影响 CANN TBE 编译器的内置 Python 解释器。 - 并行度核对:
nproc_per_node == cfg_size * ulysses_size * ring_size;如需限定设备,先export ASCEND_RT_VISIBLE_DEVICES=...再执行bash infer.sh。 - Dit-Cache 调参:FBCache 调
rel_l1_thresh(越大越快、质量损失越大);TeaCache 调rel_l1_thresh(累积阈值)、coefficients(多项式重缩放系数,可参考 14b_single.yaml 注释中的默认组)、warmup(前 N 步强制完整计算)。 - 环境变量覆盖:
PYTORCH_NPU_ALLOC_CONF(可扩展内存段,降低 OOM)、TASK_QUEUE_ENABLE=2(task_queue 二级流水)、CPU_AFFINITY_CONF=1(粗粒度绑核)由 executor/scripts/mm_function.sh 设置默认值,YAML 的env_vars可覆盖;HCCL 相关HCCL_IF_IP / HCCL_IF_BASE_PORT / HCCL_CONNECT_TIMEOUT / HCCL_EXEC_TIMEOUT也会自动配置。
九、关联资源
- 权重目录结构说明与 CANN 环境安装指引见 Wan2.2-I2V 样例 README(A2/A3 需 CANN ≥ 8.5.0、Atlas 950 需 CANN ≥ 9.0.0,依赖清单见 requirements.txt)
- NPU 优化点(npu_fused_infer_attention_score、npu_rotary_mul、npu_rms_norm、npu_layer_norm_eval 融合算子,多卡 VAE 并行、CFG 并行、Ring Attention 序列并行与通算掩盖)详见 wan2.2-i2v_optimization.md
- 通用多模态启动函数
mm_function.sh位于 executor/scripts/mm_function.sh,DiT 缓存实现位于 module/dit_cache/cache_method.py