Wan2.2-I2V 昇腾 NPU 推理 YAML 配置详解:从单卡基线到 CFG×Ulysses 多卡并行

原创2026-09-17 17:27:071,623 阅读
文章标签:人工智能大模型模型优化模型量化深度学习算子库多模态媒体生成示例工程Ascend

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 与平台启动互不影响。

八、实操检查清单与注意事项

  1. 修改权重与输入:打开所选 YAML,修改 model_args.ckpt_dir 指向已下载的权重目录;更换分辨率、帧数、图片或提示词时直接改 size、frame_num、image、prompt 字段。
  2. 环境准备:推理前先 source /usr/local/Ascend/ascend-toolkit/set_env.sh;PYTHONPATH 不应全局设置项目根路径,mm_function.sh 会在 torchrun 子进程中按需注入,避免影响 CANN TBE 编译器的内置 Python 解释器。
  3. 并行度核对:nproc_per_node == cfg_size * ulysses_size * ring_size;如需限定设备,先 export ASCEND_RT_VISIBLE_DEVICES=... 再执行 bash infer.sh。
  4. Dit-Cache 调参:FBCache 调 rel_l1_thresh(越大越快、质量损失越大);TeaCache 调 rel_l1_thresh(累积阈值)、coefficients(多项式重缩放系数,可参考 14b_single.yaml 注释中的默认组)、warmup(前 N 步强制完整计算)。
  5. 环境变量覆盖: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-recipes-infer