HunyuanVideo 昇腾 NPU 推理 YAML 配置完全指南从单卡基线到多卡稀疏加速【免费下载链接】cann-recipes-infer本项目针对LLM与多模态模型推理业务中的典型模型、加速算法提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-inferHunyuanVideo 是腾讯开源的多模态文生视频 DiT 模型本仓库在昇腾 Atlas A2/A3/950 环境下完成了 NPU 适配与推理优化。本指南以models/hunyuan-video/config/README.md为骨架结合config/*.yaml预置配置、hyvideo/config.py参数解析源码与 executor/scripts/mm_function.sh 拉起逻辑逐段讲解 HunyuanVideo 推理 YAML 的每个字段含义、可选值、默认值与组合约束。读完本文你将能够独立完成单卡基线推理、FP8 量化推理、块稀疏 AttentionTopK/SVG推理、Ulysses/Ring 多卡序列并行推理以及 DiT CacheFBCache/TeaCache/TaylorSeer的参数调优。一、配置体系总览一份 YAML 驱动一次推理HunyuanVideo 推理参数全部维护在models/hunyuan-video/config/*.yaml中通过infer.sh中的YAML_FILE_NAME选择具体配置后执行bash infer.sh拉起。config/README.md给出的默认配置与适用场景如下YAML 文件卡数适用场景single.yaml1单卡基线dit_cache.method可选NoCache / FBCache / TeaCache / TaylorSeersp8.yaml88 卡 Ulysses 序列并行 VAE 并行原生规格720*1280*129single_fp8.yaml1单卡 MXFP8 量化950PRsingle_sparse.yaml1单卡 块稀疏 Attention默认 SVG可切 TopK720*1280*129规格sp8_sparse.yaml88 卡 Ulysses 块稀疏 Attention默认 SVG与 Dit-Cache 互斥sp8_sparse_overlap.yaml88 卡 Ring 块稀疏 Attention overlap默认 TopK720*1280*129规格single_platform.yaml1CANNLab 一站式开发平台模板默认 81 帧360*640一个典型的推理 YAML 由四段组成model_args推理主参数、顶层字段model_name/world_size/master_port/entry_script、dit_cacheDiT Cache 加速与sparse稀疏 Attention。其中dit_cache与sparse均为可选段缺省时分别走NoCache与no_sparse分支。二、model_args推理主参数逐字段详解model_args下每个键都会被mm_function.sh转换为sample_video.py的命令行参数透传规则见第五节hyvideo/config.py中的add_inference_args/add_parallel_args等函数定义了这些参数的默认值与约束。以下为完整字段说明model_args: model-base: ckpts # 权重根目录。相对路径基于 models/hunyuan-video/ 解析 prompt: A cat walks ... # 文生视频的文本提示词 video-size: [720, 1280] # 输出视频尺寸 [H, W] video-length: 129 # 输出帧数约束为 4n1 infer-steps: 50 # 去噪步数 seed: 42 # 随机种子 embedded-cfg-scale: 6.0 # Embedded CFG 引导强度 flow-shift: 7.0 # FlowMatch 时间步 shift 因子 flow-reverse: true # 是否使用反向 flow 调度可选 [false, true] use-cpu-offload: true # 是否启用 CPU offload可选 [false, true] extract_q_k_data: false # 是否为稀疏 Attention 离线 profiling 导出 QK 数据可选 [false, true] extract_path: path/to/qk_dir # QK 数据导出目录extract_q_k_data 为 true 时必填 ulysses-degree: 8 # Ulysses 序列并行度多卡配置使用 ring-degree: 1 # Ring Attention 并行度稀疏配置当前要求为 1 use-vae-parallel: true # 是否启用 VAE 并行可选 [false, true] fa-mxfp8: true # 是否启用 MXFP8 FA 激活量化可选 [false, true] mm-mxfp8: true # 是否启用 MXFP8 矩阵乘量化可选 [false, true] dit-weight: /abs/path/ckpt.pt # 可选 DiT 权重路径如 FP8 checkpoint model: HYVideo-T/2-cfgdistill # DiT 架构可选 [HYVideo-T/2, HYVideo-T/2-cfgdistill] model-resolution: 720p # 模型分辨率预设可选 [540p, 720p] precision: bf16 # DiT 精度可选 [fp32, fp16, bf16] seed-type: auto # 种子来源可选 [file, random, fixed, auto]2.1 视频规格与去噪调度video-size与video-length视频尺寸与帧数。video-length因 3D VAE 的时序约束必须满足4n1如 129 帧、81 帧。源码中add_inference_args对该参数有注释说明if using 3d vae, the number should be 4n1hyvideo/config.py。infer-stepsFlow Matching 去噪步数默认 50预置 YAML 均为 50。flow-shift与flow-reverse对应add_denoise_schedule_args中--flow-shift默认 7.0与--flow-reverse。flow-reversetrue表示从 t1 向 t0 采样If reverse, learning/sampling from t1 - t0。embedded-cfg-scaleEmbedded Classifier-Free Guidance 引导强度默认 6.0。2.2 权重路径控制model-base所有模型权重的根目录默认ckpts相对路径从models/hunyuan-video/解析。从源码看hyvideo/constants.py在导入时会读取MODEL_BASE环境变量并将其烘焙进VAE_PATH / TEXT_ENCODER_PATH / TOKENIZER_PATH因此 executor/scripts/mm_function.sh 会自动将model_args.model-base导出为MODEL_BASE环境变量YAML 中env_vars显式设置优先避免用户重复配置两处。dit-weight单独指定 DiT 权重。默认为hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states.pt相对路径在加载时与model-base拼接当使用 FP8 量化 checkpoint 等自定义权重时应配置为绝对路径见 hyvideo/config.py 中--dit-weight注释。model与model-resolutionDiT 架构HYVideo-T/2或HYVideo-T/2-cfgdistill与分辨率预设540p/720p。precisionDiT 精度可选fp32 / fp16 / bf16默认bf16。2.3 随机性与量化开关seed与seed-typeseed-type决定种子来源fixed使用--seed给定值random随机生成file从 CSV 的 seed 列读取auto在 CSV 场景优先使用 seed 列、否则回退到固定seedprompt 场景直接用固定 seed。fa-mxfp8/mm-mxfp8950PR 平台量化开关。fa-mxfp8对 Flash Attention 做 MXFP8 激活量化mm-mxfp8对 matmul 做 MXFP8 A8W8 量化per-channel 直转。量化支持多卡推理但仅支持 950PR。2.4 稀疏 profiling 开关extract_q_k_data/extract_path用于生成稀疏 Attention 离线 profiling 所需的 QK 数据。置extract_q_k_data: true时必须配置一个可写的extract_path目录。三、顶层字段进程数与启动入口model_name: hunyuan-video # 模型名可选 [hunyuan-video] world_size: 1 # 启动进程数多卡配置要求 world_size ulysses-degree * ring-degree master_port: 29600 # torchrun master 端口 entry_script: sample_video.py # 入口脚本可选 [sample_video.py]mm_function.sh的mm_validate_yaml会做启动前校验model_name / world_size / entry_script为必填顶层键world_size必须是正整数master_port必须是整数dit_cache.method与sparse.method必须命中白名单未知顶层键会直接报错退出失败即快速失败不会拉起任何子进程。随后mm_parse_yaml将这四个字段解析为环境变量mm_launch_task再以torchrun --master_portmaster_port --nproc_per_nodeworld_size启动sample_video.py。此外 YAML 还可选配env_vars段覆盖默认环境变量、launcher/launcher_args段切换到accelerate启动器本样例默认使用torchrun。四、dit_cacheDiT Cache 加速配置dit_cache段控制去噪过程中跳过冗余 DiT 时间步的缓存方案可选方法为NoCache / FBCache / TeaCache / TaylorSeer各方法通过params子块传入特有参数未配置时使用内置默认值dit_cache: method: NoCache # [NoCache, FBCache, TeaCache, TaylorSeer] params: # FBCache / TeaCache rel_l1_thresh: 0.05 # 相对 L1 阈值越大越快但可能降低画质 # TeaCache coefficients: [] # TeaCache 多项式重缩放系数 warmup: 2 # 前 N 步强制完整计算 # TaylorSeer n_derivatives: 3 # Taylor 展开阶数 skip_interval_steps: 4 # 完整计算间隔步数 cutoff_steps: 1 # 末尾强制完整计算步数 offload: true # 是否将 TaylorSeer 历史状态 offload 到 CPU可选 [false, true]4.1 各方法原理与调参要点FBCache缓存两次 DiT 时间步的残差使用第一个 DiT Block 的输出判断能否复用残差。rel_l1_thresh0.1时 DiT 加速比约 2.0阈值越大越快精度损失越大。TeaCache与 FBCache 类似但使用第一个 img modulate 的输出判断。三要素为累积 L1 阈值rel_l1_thresh、多项式重缩放系数coefficients参考值[733.226126, -401.131952, 67.5869174, -3.149879, 0.0961237896]与前 N 步强制完整计算的warmup。rel_l1_thresh0.1约 1.6 倍加速0.15约 2.1 倍加速。TaylorSeer基于 Taylor 展开预测跳步参数为展开阶数n_derivatives、跳算间隔skip_interval_steps、末尾强制完整计算的cutoff_steps以及是否将历史状态 offload 到 CPU 的offload。注意720*1280*129规格开启 offload 需保证 400GB 以上主机内存。single.yaml/sp8.yaml内已注释好各方法的示例参数块切换方法时取消对应注释即可参考 config/single.yaml。4.2 内存提示开启 DiT Cache 后内存占用会略增。若剩余可用内存过低如不足 100MB可在 YAML 的env_vars中移除或改写PYTORCH_NPU_ALLOC_CONF并在model_args中启用use-cpu-offload: true。五、sparse块稀疏 Attention 配置在启动 YAML 顶层加sparse:段即可启用稀疏 Attentionmethod可选no_sparse / TopK / SVG无sparse:段或method: no_sparse时稀疏分支关闭。block_size_Q / block_size_K / model以及params.TopK / params.SVG的策略参数全部内联到同一份 YAML不再依赖独立配置文件sparse: method: SVG # [no_sparse, TopK, SVG] block_size_Q: 128 # Q 轴分块大小 block_size_K: 512 # K 轴分块大小 model: HunyuanVideo # 稀疏模块模型类型可选 [HunyuanVideo] params: TopK: sparse_time_step: 10-49 # 稀疏生效的去噪步范围格式 start-end sparsity_files_path: ./sparsity/720x1280x129/v3 # 离线 profiling 生成的稀疏文件目录 CAC_threshold: 0.66 # TopK 阈值 SVG: sparse_time_step: 14-49 # 稀疏生效的去噪步范围格式 start-end sparsity: 0.8 # SVG 稀疏率 sample_mse_max_row: 5000 # MSE 采样的最大行数 context_length: 256 # SVG 上下文长度5.1 TopK 与 SVG 使用要点TopK 前置要求必须先用 module/blockwise_sparse/offline_profiling/offline_profiling_hyvideo.py 离线生成 sparsity 文件路径由sparse.params.TopK.sparsity_files_path指定且文件规格须与video-size / video-length一致单卡默认320*480*65多卡默认720*1280*129。注意 config/sp8_sparse_overlap.yaml 中 TopK 还额外支持ring_sparse_overlap: true开启 Ring TopK 计算与通信 overlap。SVG基于 Sparse-VideoGen 的自适应稀疏方法无需预生成文件通过sparsity比率与sample_mse_max_row等参数在线选择需要计算的分块。算子依赖块稀疏 Attention 基于blitz_sparse_attention算子实现运行前需参照其文档编译算子库详见 models/hunyuan-video/README.md 的依赖安装章节。并行适配hyvideo/sparse/sparse_block.py已适配 Ulysses 序列并行的 all-to-all 通信sample_video.py在ulysses_degree 1时自动调用apply_head_reorder_for_load_balance做 head 级负载均衡。Ring TopK 支持普通与 overlap 两条路径Ring SVG overlap 暂复用普通 Ring SVG 路径。5.2 与 DiT Cache 的互斥约束启用sparse时sample_video.py会替换所有double/single block 的 forward从而覆盖 FBCache / TeaCache / TaylorSeer 设置的 block forward两者同时启用时只有 sparse 生效。因此稀疏配置如single_sparse.yaml/sp8_sparse.yaml必须固定dit_cache.method: NoCache。六、YAML → 命令行透传规则与拉起流程model_args会按mm_function.sh中mm_build_args的规则透传给sample_video.pyYAML 值类型命令行效果示例字符串/数字--key valueinfer-steps: 50→--infer-steps 50布尔true--keyflag不携带值flow-reverse: true→--flow-reverse布尔false忽略不添加该参数argparse 用默认值use-cpu-offload: false→ 不添加列表--key v1 v2 …展开适配nargsvideo-size: [720, 1280]→--video-size 720 1280若需把布尔值作为显式值传递例如给 pyrallis/Hydra 风格解析器可在 YAML 中写成字符串key: False→--key False。此外当 YAML 含dit_cache段时会追加--cache-config yaml模型名为 hunyuan-video 时参数名为cache-config含sparse段时会追加--sparse-method method --sparse-attention-config yaml分别对应 hyvideo/config.py 中add_cache_args与add_sparse_args定义的入口。bash infer.sh拉起时自动完成校验并解析 YAML → 设置通用 NPU 优化环境变量PYTORCH_NPU_ALLOC_CONFexpandable_segments:True、TASK_QUEUE_ENABLE2、CPU_AFFINITY_CONF1、TOKENIZERS_PARALLELISMfalse与 HCCL 通信配置HCCL_IF_IP / HCCL_IF_BASE_PORT / HCCL_CONNECT_TIMEOUT / HCCL_EXEC_TIMEOUT→ 在res/YYYYMMDD/model_name/下创建日志目录并将输出 tee 到log_timestamp.log→ 以torchrun --nproc_per_nodeworld_size启动sample_video.py。生成视频默认保存到./results/time_flag_seedseed/prompt.mp4若 YAML 配置了save-path则保存到对应目录。七、多卡并行约束与配置组合ulysses-degree与ring-degree组合实现 Ulysses / Ring Attention 两种序列并行多卡推理需满足三条约束混合并行策略约束world_size ulysses-degree * ring-degree视频规格约束H % 16 % SP number 0 or W % 16 % SP number 0序列并行度约束head num % SP number 0HunyuanVideo 的head num 24。自定义并行组合时复制sp8.yaml并修改world_size / ulysses-degree / ring-degree / video-size / video-length即可仓库验证过部分组合video-sizevideo-lengthulysses-degree × ring-degreeworld_size1280 720 或 720 12801298x1, 4x2, 2x4, 1x881280 720 或 720 12801291x551280 720 或 720 12801294x1, 2x2, 1x441280 720 或 720 12801293x1, 1x331280 720 或 720 12801292x1, 1x22960 9601296x1, 3x2, 2x3, 1x66960 9601294x1, 2x2, 1x44960 544 或 544 9601296x1, 3x2, 2x3, 1x66720 7201291x55720 7201293x1, 1x33VAE 并行多卡 YAML 中置use-vae-parallel: true即可启用对应--use-vae-parallel通过 tiling 节省 NPU 内存。UAAUlysses Anything Attention置ulysses-anything: true可解除上述规格整除约束与head num % SP number 0约束支持head num大于SP number。UAA 仅支持纯 Ulysses不支持 Ulysses Ring Attention 混合序列并行。八、配置注意事项速查稀疏与 DiT Cache 互斥稀疏配置保持dit_cache.method: NoCache否则只有 sparse 生效TopK 文件规格TopK的 sparsity 文件必须与video-size和video-length严格匹配QK 数据导出extract_q_k_data: true用于生成稀疏 Attention 离线 profiling 的 QK 数据需同时配置可写的extract_pathTaylorSeer 内存大分辨率、长帧数场景下 TaylorSeer 可能占用大量主机内存720*1280*129规格开启 offload 建议保证 400GB 以上主机内存量化平台限制fa-mxfp8/mm-mxfp8量化特性仅支持 950PR性能分析在model_args中添加prof-dit: true可启用 Ascend PyTorch Profiler 性能分析分析文件默认保存在.prof路径支持多卡。九、延伸阅读优化原理与性能数据详见 docs/models/hunyuan-video/hunyuan_video_optimization.md完整推理步骤环境准备、权重下载、依赖安装models/hunyuan-video/README.md统一拉起脚本实现executor/scripts/mm_function.shYAML 校验、参数透传、环境变量、torchrun 启动参数定义源码models/hunyuan-video/hyvideo/config.pyadd_inference_args/add_parallel_args/add_cache_args/add_sparse_args。【免费下载链接】cann-recipes-infer本项目针对LLM与多模态模型推理业务中的典型模型、加速算法提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-infer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考