vLLM-Omni 离线推理实战基于 Wan2.2 S2V 的语音驱动数字人视频生成Speech-to-Video【免费下载链接】vllm-omniA framework for efficient model inference with omni-modality models项目地址: https://gitcode.com/GitHub_Trending/vl/vllm-omni本篇指南以 vLLM-Omni 仓库中的 speech_to_video 离线推理示例 为核心系统讲解如何使用 Wan2.2 Speech-to-VideoS2V14B 模型以一张参考人像与一段音频为输入自动生成与音频时长无缝对齐的数字人说话/唱歌视频。读完本文你将掌握完整的 CLI 启动方式、全部关键参数语义、多片段自回归生成原理以及分辨率/并行度/推理步数等维度的性能调优与管线剖析手段并了解其底层实现与测试验证。一、S2V 是什么在 vLLM-Omni 中如何工作Speech-to-Video 是 Wan2.2 系列中由语音驱动视频生成的任务形态输入一张参考图像人脸/肖像与一段音频wav/mp3输出一段说话或唱歌的头部视频。与常见的 Image-to-VideoI2V不同S2V 不是把参考图拼接到条件通道而是将参考图编码为独立的ref_latentstoken并通过 wav2vec2 音频特征注入 Transformer实现音画同步参见 pipeline_wan2_2_s2v.py 的类注释。S2V 的一个关键特性是多片段自回归生成整个音频被切分成若干 clip每个 clip 的去噪结果中末尾若干帧会作为下一个 clip 的运动上下文motion context重新编码为运动潜变量从而把多个片段无缝衔接成覆盖完整音频时长的连续视频。在 vLLM-Omni 中S2V 由离线推理入口Omni驱动示例脚本 speech_to_video.py 通过model_class_nameWanS2VPipeline指定管线并由注册表 registry.py 将模型名解析到Wan22S2VPipeline及其专属的预处理/后处理函数。模型元数据中WanS2VPipeline被标记为attention_mask_freeTrue、final_output_typevideo见 model_metadata.py。二、环境准备S2V 管线依赖librosa进行音频加载解码音频为波形decord用于视频相关处理。安装方式pip install librosa decord除此之外示例运行还需要 PyTorch 与仓库自身的 vLLM-Omni 安装环境仓库根目录 README.md 提供了整体安装说明。模型权重方面示例默认使用 HuggingFace 仓库 IDWan-AI/Wan2.2-S2V-14B也可使用本地目录仓库中另有配套的部署/配方文档 recipes/Wan-AI/Wan2.2-S2V.md 可供参考。三、快速上手命令行生成数字人视频3.1 准备输入素材由于 S2V 需要参考图 音频双输入运行前请自行准备一张参考人像图PNG/JPG建议正脸、清晰一段音频wav 或 mp3内容为想要说出/唱出的声音。3.2 480p 唱歌示例以下命令以 480p 分辨率、5 步去噪快速生成一段唱歌视频对应官方示例的五公里远唱段素材python speech_to_video.py \ --model Wan-AI/Wan2.2-S2V-14B \ --image Five Hundred Miles.png \ --audio Five Hundred Miles.MP3 \ --prompt A person singing \ --height 448 --width 832 \ --num-inference-steps 5 \ --output s2v_singing_480p.mp4脚本启动后会打印生成配置模型、参考图、音频、推理步数、每 clip 帧数、guidance scale、flow shift、是否首帧初始化、分辨率等随后调用omni.generate()执行完整 S2V 流程最终将视频帧与音频波形通过mux_video_audio_bytes位于 media_utils.py合成带声音的 MP4 保存到--output指定路径并在终端输出总生成时长、帧数与音轨信息。若未显式指定--height/--width分辨率会根据参考图宽高比自动计算见下文 4.4 节说明。四、关键参数详解下表完整覆盖 README.md 中给出的参数说明并补充了脚本源码speech_to_video.py中定义但未列入表格的进阶参数。参数默认值说明--model必填Wan2.2 S2V 模型路径本地目录或 HuggingFace ID--image必填参考图像路径人脸/肖像--audio必填音频文件路径wav/mp3--promptA person speaking naturally描述场景的文本提示词--negative-promptS2V 内置默认负向提示词未设置时使用内置中文质量过滤词见下文--height/--width自动输出分辨率未设置时按参考图宽高比自动计算需能被 64 整除--num-frames80每个 clip 的帧数需能被 4 整除--num-inference-steps40去噪步数--guidance-scale4.5无分类器引导CFG强度--flow-shift3.0Scheduler 的 flow shift 参数--seed42随机种子用于结果可复现--fps16保存 MP4 的帧率--init-first-frameFalse是否将参考图作为视频首帧--outputs2v_output.mp4输出视频文件路径--vae-use-slicingFalse开启 VAE slicing 以降低显存占用--vae-use-tilingFalse开启 VAE tiling 以降低显存占用--tensor-parallel-size1DiT 内部张量并行TP所用 GPU 数--cfg-parallel-size1CFG 并行 GPU 数1 或 2--vae-patch-parallel-size1VAE 解码 patch 并行所用 GPU 数--enable-cpu-offloadFalse开启 CPU offload--enable-layerwise-offloadFalse对 DiT 模块开启逐层blockwiseoffload--boundary-ratio按模型而定高低 DiT 阶段的分界切分比例S2V 专用默认随模型变化--ring-degree1环形序列并行ring sequence parallelismGPU 数--ulysses-degree1Ulysses 序列并行 GPU 数--use-hsdpFalse开启 Hybrid Sharded Data Parallel跨 GPU 切分模型权重--hsdp-shard-size-1每个副本组内切分权重的 GPU 数-1自动计算为 world_size / replicate_size--hsdp-replicate-size1HSDP 副本组数量默认 1 表示纯切分无复制--enforce-eagerFalse禁用 torch.compile强制 eager 执行--cache-backendNone加速缓存后端当前可选cache_dit--enable-cache-dit-summaryFalsediffusion 前向结束后打印 cache-dit 摘要日志--profiler-configNonetorch/cuda 剖析 JSON 配置如{profiler:torch,torch_profiler_dir:./perf}4.1 内置默认负向提示词若不传--negative-prompt管线会使用内置的中文质量过滤词定义于 pipeline_wan2_2_s2v.py内容涵盖画面模糊、最差质量、多余的手指、画得不好的手部/脸部、畸形肢体、静止不动的画面、杂乱背景等常见伪影描述。这意味着即使用户不写负向提示词CFG 也能获得一个质量下限保障。4.2 分辨率约束64 与 16 的说明README 要求--height/--width需能被 64 整除官方示例 448×832、720p 场景均满足。从源码看管线在check_inputs中实际校验的分辨率除数resolution_divisor由 VAE 空间下采样倍数8与 Transformer patch 空间步长2共同决定8 × 2 16见 pipeline_wan2_2_s2v.py。因此只要分辨率是 64 的倍数必然满足校验且示例默认值均取 64 的倍数可直接使用。4.3 cache_dit 加速配置脚本对--cache-backend cache_dit预置了一套缓存配置speech_to_video.pyFn_compute_blocks1、Bn_compute_blocks0、max_warmup_steps4、max_cached_steps20、residual_diff_threshold0.24、max_continuous_cached_steps3采用dynamic步数策略。其思路是让去噪过程在前几步充分 warmup 后基于残差差异阈值动态跳过可缓存的中间步骤从而减少冗余计算。4.4 分辨率的自动计算当未显式指定分辨率时预处理阶段会按参考图宽高比在720×1280最大面积约束内缩放并补齐到 64 的倍数_get_size_less_than_area见 pipeline_wan2_2_s2v.py随后对参考图执行ResizeCenterCrop到目标尺寸pipeline_wan2_2_s2v.py。五、OOM 时的内存优化路径README 明确给出显存不足OOM时的处理建议优先尝试--vae-use-slicing与--vae-use-tiling降低 VAE 编解码显存若仍不足使用--enable-cpu-offload做更激进的显存节省。从源码实现看S2V 的解码阶段会按 clip 逐个进行 VAE decode并在 clip 之间调用current_omni_platform.empty_cache()主动释放缓存pipeline_wan2_2_s2v.py开启 CPU offload 后DiT 在解码前会被移到 CPU 并清空缓存_should_release_dit_before_decodepipeline_wan2_2_s2v.py音频编码器casual_audio_encoder在 CPU offload 场景下会临时搬回 GPU 计算再搬回 CPUpipeline_wan2_2_s2v.py。对于更大的模型切分需求还可组合--use-hsdp权重切分、--tensor-parallel-size算子级并行与--cfg-parallel-size 2CFG 双分支并行等多卡方案。六、性能优化策略S2V 最主要的计算开销来自全序列自注意力在 720p 分辨率下 token 序列约 8 万文档估算值注意力复杂度随分辨率呈二次增长。README 给出的四条加速策略如下策略加速比实现方式降低分辨率480p~3.5x--height 448 --width 832—— token 数从约 80K 降至 33K张量并行2 GPU~1.4x--tensor-parallel-size 2—— 注意力/GEMM 拆分到多卡减少推理步数线性--num-inference-steps 5—— 以质量为代价换取速度组合以上全部~5x480p TP2 5 步从源码层面看张量并行的基础在于 S2V Transformer 中自注意力与跨注意力均基于 vLLM 的并行算子构建WanS2VSelfAttention使用QKVParallelLinearAttention输出投影使用RowParallelLinear并带 TP 感知的 QK 归一化DistributedRMSNorm详见 wan2_2_s2v_transformer.py。这意味着注意力与 GEMM 可以按 TP 语义天然拆分到多卡。此外--cfg-parallel-size 2可将 CFG 的正向/负向分支分卡执行--vae-patch-parallel-size可并行 VAE 解码 patch。需要说明的是上表加速比为官方文档基于典型硬件给出的估算值实际收益会随 GPU 型号、显存带宽与序列长度变化建议以自身环境实测为准。七、性能剖析Profiling7.1 内置管线剖析器添加--enable-diffusion-pipeline-profiler即可在运行结束后打印各阶段耗时python speech_to_video.py \ --model Wan-AI/Wan2.2-S2V-14B \ --image Five Hundred Miles.png \ --audio Five Hundred Miles.MP3 \ --prompt A person singing \ --height 448 --width 832 \ --num-inference-steps 5 \ --enable-diffusion-pipeline-profiler \ --output s2v_output.mp4该开关在管线初始化时调用setup_diffusion_pipeline_profilerpipeline_wan2_2_s2v.py并在每个去噪步通过record_denoise_step记录阶段时长pipeline_wan2_2_s2v.py可帮助定位瓶颈在编码、去噪还是 VAE 解码。7.2 Torch Profiler设备级剖析如需 GPU/XPU 内核级、可生成 Chrome trace 的详细剖析使用--profile-dir开启python speech_to_video.py \ --model Wan-AI/Wan2.2-S2V-14B \ --image Five Hundred Miles.png \ --audio Five Hundred Miles.MP3 \ --prompt A person singing \ --height 448 --width 832 \ --num-inference-steps 1 \ --profile-dir /tmp/s2v_profile \ --profile-record-shapes \ --profile-with-memory \ --profile-with-stack \ --output s2v_profiled.mp4剖析参数说明参数说明--profile-dir开启 torch profiler 并将 trace 保存到该目录--profile-record-shapes记录张量形状会增大 trace 体积--profile-with-stack记录调用栈会增加开销--profile-with-memory剖析内存使用--profile-with-flops估算算子 FLOPs输出文件trace_rank*.json.gz—— Chrome trace 文件可用chrome://tracing打开查看ops_rank*.xlsx—— 算子统计 Excel 工作簿提示剖析时使用--num-inference-steps 1可显著加快速度。一次 trace 已能覆盖完整的一个去噪步包含全部 Transformer block 与注意力算子。脚本会在omni.generate()前后调用start_profile()/stop_profile()并在结束时打印每个 rank 的 trace 路径speech_to_video.py。八、工作原理从输入到成片的完整流水线README 将 S2V 管线划分为六个阶段这里结合源码逐一展开1. 预处理Pre-process预处理函数get_wan22_s2v_pre_process_funcpipeline_wan2_2_s2v.py负责校验并加载参考图支持 PIL.Image 或路径字符串、校验音频路径、按参考图宽高比与最大面积计算目标分辨率、将参考图 Resize CenterCrop 到目标尺寸并把init_first_frame、audio_path等写入请求的additional_information。该函数还会为请求计算batch_compatibility_key基于init_first_frame、num_repeat与音频条件键用于保证同批请求可合并执行。2. 文本编码Text Encoding提示词经 UMT5umt5-xxl 架构文本编码器编码为prompt_embeds与可选的负向negative_prompt_embedsencode_promptpipeline_wan2_2_s2v.py。需要注意S2V 的原始 Wan2.2 checkpoint 使用扁平命名的 T5 编码器仓库在加载时通过_convert_wan_t5_state_dict将其状态字典键名转换为 HuggingFaceUMT5EncoderModel格式pipeline_wan2_2_s2v.py从而复用标准 Transformers 生态。3. 音频编码Audio Encodingencode_audiopipeline_wan2_2_s2v.py是本任务的核心差异点音频文件通过load_audio加载为 16 kHz 单声道波形或直接接受 numpy 数组经 wav2vec2Wav2Vec2ForCTC提取多层隐状态特征线性插值到 30 fps 的音频-视频基准帧率_AUDIO_VIDEO_RATE 30_get_audio_embed_bucket_fpspipeline_wan2_2_s2v.py按视频帧率默认 16 fps与每 clip 帧数默认 80把音频特征分桶对齐到视频帧并计算出两个关键量num_repeat覆盖全部音频所需的 clip 数ceil(audio_frames / (80 × 30/16))与target_video_frames与音频时长精确对应的视频帧数。音频长度直接决定了视频的 clip 数量这是 S2V视频长度跟随音频的根本机制。4. 参考图像编码Reference Image Encoding参考图经 VAE 编码为ref_latentsencode_ref_imagepipeline_wan2_2_s2v.py并进行 latent 归一化(latent - mean) / std对应原始 Wan2.1 VAE 的行为。与 I2V 将参考帧拼接到条件通道不同S2V 把参考图作为独立的ref_latentstoken 输入 Transformer。5. 多片段自回归去噪Multi-clip Denoising这是 S2V 的生成主循环pipeline_wan2_2_s2v.py对每个 clip 依次执行用 clip 专属生成器种子 主种子 clip 序号_make_clip_generators生成随机噪声潜变量从音频嵌入中切出当前 clip 对应的片段audio_emb[..., r*infer_frames : (r1)*infer_frames]通过WanModel_S2V即WanS2VPipeline中的transformer预测噪声音频特征经casual_audio_encoder注入开启 CFG 时对正向/负向提示词分别前向并用FlowUniPCMultistepScheduler配合flow_shift更新潜变量diffusepipeline_wan2_2_s2v.pyVAE 解码当前 clip 像素帧首 clip 若开启--init-first-frame则在 motion 潜变量末尾 6 帧放置参考图实现首帧即参考图自回归衔接当前 clip 末尾motion_frames默认 73帧被保留为videos_last_frames重新 VAE 编码为motion_latents作为下一 clip 的运动上下文pipeline_wan2_2_s2v.py。clip 间还会清空显存缓存。Transformer 侧S2V 变体支持多卡并行算子WanS2VSelfAttention/WanS2VCrossAttention/WanS2VTransformerBlock见 wan2_2_s2v_transformer.py并配有针对性的旋转位置编码RotaryEmbeddingS2VGrid等。6. 后处理Post-process所有 clip 按时间维拼接为完整视频torch.cat(clips, dim2)后处理函数get_wan22_s2v_post_process_funcpipeline_wan2_2_s2v.py将视频张量还原为像素空间默认np输出同时把管线返回的音频波形、采样率与 fps16一并打包进输出供示例脚本调用mux_video_audio_bytes合成带声音的 MP4。九、输出处理与结果验证示例脚本在拿到OmniRequestOutput后做了三件事speech_to_video.py从output.multimodal_output中提取音频波形、fps 与音频采样率默认 16000 Hz将视频帧规整为(T, H, W, C)的 uint8 numpy 数组自动处理 5 维/4 维/列表等不同形态用mux_video_audio_bytes将帧序列与波形合成 MP4 写入输出路径并打印帧数、时长与音轨信息。若输出中不含视频帧脚本会抛出ValueError(No video frames found in OmniRequestOutput.)便于第一时间发现管线异常。十、相关资源与进一步阅读官方示例说明examples/offline_inference/speech_to_video/README.md可运行示例脚本examples/offline_inference/speech_to_video/speech_to_video.pyS2V 管线实现vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_s2v.pyS2V Transformer含 TP 算子vllm_omni/diffusion/models/wan2_2/wan2_2_s2v_transformer.py模型注册表pre/post-process 挂载vllm_omni/diffusion/registry.pyS2V 管线单元测试覆盖批量约束、种子、输出切分等tests/diffusion/models/wan2_2/test_wan22_s2v_pipeline.py模型配方文档recipes/Wan-AI/Wan2.2-S2V.md音视频合成工具vllm_omni/diffusion/utils/media_utils.py其中单元测试从工程层面印证了本文所述的几个关键约束批量请求的num_repeat、音频嵌入时间长度、init_first_frame与原始音频 shape/采样率必须一致否则管线会显式抛出ValueError参见test_s2v_forward_rejects_*系列用例这些约束正源于多片段自回归衔接对同批请求的强一致要求。【免费下载链接】vllm-omniA framework for efficient model inference with omni-modality models项目地址: https://gitcode.com/GitHub_Trending/vl/vllm-omni创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
vLLM-Omni 离线推理实战基于 Wan2.2 S2V 的语音驱动数字人视频生成Speech-to-Video【免费下载链接】vllm-omniA framework for efficient model inference with omni-modality models项目地址: https://gitcode.com/GitHub_Trending/vl/vllm-omni本篇指南以 vLLM-Omni 仓库中的 speech_to_video 离线推理示例 为核心系统讲解如何使用 Wan2.2 Speech-to-VideoS2V14B 模型以一张参考人像与一段音频为输入自动生成与音频时长无缝对齐的数字人说话/唱歌视频。读完本文你将掌握完整的 CLI 启动方式、全部关键参数语义、多片段自回归生成原理以及分辨率/并行度/推理步数等维度的性能调优与管线剖析手段并了解其底层实现与测试验证。一、S2V 是什么在 vLLM-Omni 中如何工作Speech-to-Video 是 Wan2.2 系列中由语音驱动视频生成的任务形态输入一张参考图像人脸/肖像与一段音频wav/mp3输出一段说话或唱歌的头部视频。与常见的 Image-to-VideoI2V不同S2V 不是把参考图拼接到条件通道而是将参考图编码为独立的ref_latentstoken并通过 wav2vec2 音频特征注入 Transformer实现音画同步参见 pipeline_wan2_2_s2v.py 的类注释。S2V 的一个关键特性是多片段自回归生成整个音频被切分成若干 clip每个 clip 的去噪结果中末尾若干帧会作为下一个 clip 的运动上下文motion context重新编码为运动潜变量从而把多个片段无缝衔接成覆盖完整音频时长的连续视频。在 vLLM-Omni 中S2V 由离线推理入口Omni驱动示例脚本 speech_to_video.py 通过model_class_nameWanS2VPipeline指定管线并由注册表 registry.py 将模型名解析到Wan22S2VPipeline及其专属的预处理/后处理函数。模型元数据中WanS2VPipeline被标记为attention_mask_freeTrue、final_output_typevideo见 model_metadata.py。二、环境准备S2V 管线依赖librosa进行音频加载解码音频为波形decord用于视频相关处理。安装方式pip install librosa decord除此之外示例运行还需要 PyTorch 与仓库自身的 vLLM-Omni 安装环境仓库根目录 README.md 提供了整体安装说明。模型权重方面示例默认使用 HuggingFace 仓库 IDWan-AI/Wan2.2-S2V-14B也可使用本地目录仓库中另有配套的部署/配方文档 recipes/Wan-AI/Wan2.2-S2V.md 可供参考。三、快速上手命令行生成数字人视频3.1 准备输入素材由于 S2V 需要参考图 音频双输入运行前请自行准备一张参考人像图PNG/JPG建议正脸、清晰一段音频wav 或 mp3内容为想要说出/唱出的声音。3.2 480p 唱歌示例以下命令以 480p 分辨率、5 步去噪快速生成一段唱歌视频对应官方示例的五公里远唱段素材python speech_to_video.py \ --model Wan-AI/Wan2.2-S2V-14B \ --image Five Hundred Miles.png \ --audio Five Hundred Miles.MP3 \ --prompt A person singing \ --height 448 --width 832 \ --num-inference-steps 5 \ --output s2v_singing_480p.mp4脚本启动后会打印生成配置模型、参考图、音频、推理步数、每 clip 帧数、guidance scale、flow shift、是否首帧初始化、分辨率等随后调用omni.generate()执行完整 S2V 流程最终将视频帧与音频波形通过mux_video_audio_bytes位于 media_utils.py合成带声音的 MP4 保存到--output指定路径并在终端输出总生成时长、帧数与音轨信息。若未显式指定--height/--width分辨率会根据参考图宽高比自动计算见下文 4.4 节说明。四、关键参数详解下表完整覆盖 README.md 中给出的参数说明并补充了脚本源码speech_to_video.py中定义但未列入表格的进阶参数。参数默认值说明--model必填Wan2.2 S2V 模型路径本地目录或 HuggingFace ID--image必填参考图像路径人脸/肖像--audio必填音频文件路径wav/mp3--promptA person speaking naturally描述场景的文本提示词--negative-promptS2V 内置默认负向提示词未设置时使用内置中文质量过滤词见下文--height/--width自动输出分辨率未设置时按参考图宽高比自动计算需能被 64 整除--num-frames80每个 clip 的帧数需能被 4 整除--num-inference-steps40去噪步数--guidance-scale4.5无分类器引导CFG强度--flow-shift3.0Scheduler 的 flow shift 参数--seed42随机种子用于结果可复现--fps16保存 MP4 的帧率--init-first-frameFalse是否将参考图作为视频首帧--outputs2v_output.mp4输出视频文件路径--vae-use-slicingFalse开启 VAE slicing 以降低显存占用--vae-use-tilingFalse开启 VAE tiling 以降低显存占用--tensor-parallel-size1DiT 内部张量并行TP所用 GPU 数--cfg-parallel-size1CFG 并行 GPU 数1 或 2--vae-patch-parallel-size1VAE 解码 patch 并行所用 GPU 数--enable-cpu-offloadFalse开启 CPU offload--enable-layerwise-offloadFalse对 DiT 模块开启逐层blockwiseoffload--boundary-ratio按模型而定高低 DiT 阶段的分界切分比例S2V 专用默认随模型变化--ring-degree1环形序列并行ring sequence parallelismGPU 数--ulysses-degree1Ulysses 序列并行 GPU 数--use-hsdpFalse开启 Hybrid Sharded Data Parallel跨 GPU 切分模型权重--hsdp-shard-size-1每个副本组内切分权重的 GPU 数-1自动计算为 world_size / replicate_size--hsdp-replicate-size1HSDP 副本组数量默认 1 表示纯切分无复制--enforce-eagerFalse禁用 torch.compile强制 eager 执行--cache-backendNone加速缓存后端当前可选cache_dit--enable-cache-dit-summaryFalsediffusion 前向结束后打印 cache-dit 摘要日志--profiler-configNonetorch/cuda 剖析 JSON 配置如{profiler:torch,torch_profiler_dir:./perf}4.1 内置默认负向提示词若不传--negative-prompt管线会使用内置的中文质量过滤词定义于 pipeline_wan2_2_s2v.py内容涵盖画面模糊、最差质量、多余的手指、画得不好的手部/脸部、畸形肢体、静止不动的画面、杂乱背景等常见伪影描述。这意味着即使用户不写负向提示词CFG 也能获得一个质量下限保障。4.2 分辨率约束64 与 16 的说明README 要求--height/--width需能被 64 整除官方示例 448×832、720p 场景均满足。从源码看管线在check_inputs中实际校验的分辨率除数resolution_divisor由 VAE 空间下采样倍数8与 Transformer patch 空间步长2共同决定8 × 2 16见 pipeline_wan2_2_s2v.py。因此只要分辨率是 64 的倍数必然满足校验且示例默认值均取 64 的倍数可直接使用。4.3 cache_dit 加速配置脚本对--cache-backend cache_dit预置了一套缓存配置speech_to_video.pyFn_compute_blocks1、Bn_compute_blocks0、max_warmup_steps4、max_cached_steps20、residual_diff_threshold0.24、max_continuous_cached_steps3采用dynamic步数策略。其思路是让去噪过程在前几步充分 warmup 后基于残差差异阈值动态跳过可缓存的中间步骤从而减少冗余计算。4.4 分辨率的自动计算当未显式指定分辨率时预处理阶段会按参考图宽高比在720×1280最大面积约束内缩放并补齐到 64 的倍数_get_size_less_than_area见 pipeline_wan2_2_s2v.py随后对参考图执行ResizeCenterCrop到目标尺寸pipeline_wan2_2_s2v.py。五、OOM 时的内存优化路径README 明确给出显存不足OOM时的处理建议优先尝试--vae-use-slicing与--vae-use-tiling降低 VAE 编解码显存若仍不足使用--enable-cpu-offload做更激进的显存节省。从源码实现看S2V 的解码阶段会按 clip 逐个进行 VAE decode并在 clip 之间调用current_omni_platform.empty_cache()主动释放缓存pipeline_wan2_2_s2v.py开启 CPU offload 后DiT 在解码前会被移到 CPU 并清空缓存_should_release_dit_before_decodepipeline_wan2_2_s2v.py音频编码器casual_audio_encoder在 CPU offload 场景下会临时搬回 GPU 计算再搬回 CPUpipeline_wan2_2_s2v.py。对于更大的模型切分需求还可组合--use-hsdp权重切分、--tensor-parallel-size算子级并行与--cfg-parallel-size 2CFG 双分支并行等多卡方案。六、性能优化策略S2V 最主要的计算开销来自全序列自注意力在 720p 分辨率下 token 序列约 8 万文档估算值注意力复杂度随分辨率呈二次增长。README 给出的四条加速策略如下策略加速比实现方式降低分辨率480p~3.5x--height 448 --width 832—— token 数从约 80K 降至 33K张量并行2 GPU~1.4x--tensor-parallel-size 2—— 注意力/GEMM 拆分到多卡减少推理步数线性--num-inference-steps 5—— 以质量为代价换取速度组合以上全部~5x480p TP2 5 步从源码层面看张量并行的基础在于 S2V Transformer 中自注意力与跨注意力均基于 vLLM 的并行算子构建WanS2VSelfAttention使用QKVParallelLinearAttention输出投影使用RowParallelLinear并带 TP 感知的 QK 归一化DistributedRMSNorm详见 wan2_2_s2v_transformer.py。这意味着注意力与 GEMM 可以按 TP 语义天然拆分到多卡。此外--cfg-parallel-size 2可将 CFG 的正向/负向分支分卡执行--vae-patch-parallel-size可并行 VAE 解码 patch。需要说明的是上表加速比为官方文档基于典型硬件给出的估算值实际收益会随 GPU 型号、显存带宽与序列长度变化建议以自身环境实测为准。七、性能剖析Profiling7.1 内置管线剖析器添加--enable-diffusion-pipeline-profiler即可在运行结束后打印各阶段耗时python speech_to_video.py \ --model Wan-AI/Wan2.2-S2V-14B \ --image Five Hundred Miles.png \ --audio Five Hundred Miles.MP3 \ --prompt A person singing \ --height 448 --width 832 \ --num-inference-steps 5 \ --enable-diffusion-pipeline-profiler \ --output s2v_output.mp4该开关在管线初始化时调用setup_diffusion_pipeline_profilerpipeline_wan2_2_s2v.py并在每个去噪步通过record_denoise_step记录阶段时长pipeline_wan2_2_s2v.py可帮助定位瓶颈在编码、去噪还是 VAE 解码。7.2 Torch Profiler设备级剖析如需 GPU/XPU 内核级、可生成 Chrome trace 的详细剖析使用--profile-dir开启python speech_to_video.py \ --model Wan-AI/Wan2.2-S2V-14B \ --image Five Hundred Miles.png \ --audio Five Hundred Miles.MP3 \ --prompt A person singing \ --height 448 --width 832 \ --num-inference-steps 1 \ --profile-dir /tmp/s2v_profile \ --profile-record-shapes \ --profile-with-memory \ --profile-with-stack \ --output s2v_profiled.mp4剖析参数说明参数说明--profile-dir开启 torch profiler 并将 trace 保存到该目录--profile-record-shapes记录张量形状会增大 trace 体积--profile-with-stack记录调用栈会增加开销--profile-with-memory剖析内存使用--profile-with-flops估算算子 FLOPs输出文件trace_rank*.json.gz—— Chrome trace 文件可用chrome://tracing打开查看ops_rank*.xlsx—— 算子统计 Excel 工作簿提示剖析时使用--num-inference-steps 1可显著加快速度。一次 trace 已能覆盖完整的一个去噪步包含全部 Transformer block 与注意力算子。脚本会在omni.generate()前后调用start_profile()/stop_profile()并在结束时打印每个 rank 的 trace 路径speech_to_video.py。八、工作原理从输入到成片的完整流水线README 将 S2V 管线划分为六个阶段这里结合源码逐一展开1. 预处理Pre-process预处理函数get_wan22_s2v_pre_process_funcpipeline_wan2_2_s2v.py负责校验并加载参考图支持 PIL.Image 或路径字符串、校验音频路径、按参考图宽高比与最大面积计算目标分辨率、将参考图 Resize CenterCrop 到目标尺寸并把init_first_frame、audio_path等写入请求的additional_information。该函数还会为请求计算batch_compatibility_key基于init_first_frame、num_repeat与音频条件键用于保证同批请求可合并执行。2. 文本编码Text Encoding提示词经 UMT5umt5-xxl 架构文本编码器编码为prompt_embeds与可选的负向negative_prompt_embedsencode_promptpipeline_wan2_2_s2v.py。需要注意S2V 的原始 Wan2.2 checkpoint 使用扁平命名的 T5 编码器仓库在加载时通过_convert_wan_t5_state_dict将其状态字典键名转换为 HuggingFaceUMT5EncoderModel格式pipeline_wan2_2_s2v.py从而复用标准 Transformers 生态。3. 音频编码Audio Encodingencode_audiopipeline_wan2_2_s2v.py是本任务的核心差异点音频文件通过load_audio加载为 16 kHz 单声道波形或直接接受 numpy 数组经 wav2vec2Wav2Vec2ForCTC提取多层隐状态特征线性插值到 30 fps 的音频-视频基准帧率_AUDIO_VIDEO_RATE 30_get_audio_embed_bucket_fpspipeline_wan2_2_s2v.py按视频帧率默认 16 fps与每 clip 帧数默认 80把音频特征分桶对齐到视频帧并计算出两个关键量num_repeat覆盖全部音频所需的 clip 数ceil(audio_frames / (80 × 30/16))与target_video_frames与音频时长精确对应的视频帧数。音频长度直接决定了视频的 clip 数量这是 S2V视频长度跟随音频的根本机制。4. 参考图像编码Reference Image Encoding参考图经 VAE 编码为ref_latentsencode_ref_imagepipeline_wan2_2_s2v.py并进行 latent 归一化(latent - mean) / std对应原始 Wan2.1 VAE 的行为。与 I2V 将参考帧拼接到条件通道不同S2V 把参考图作为独立的ref_latentstoken 输入 Transformer。5. 多片段自回归去噪Multi-clip Denoising这是 S2V 的生成主循环pipeline_wan2_2_s2v.py对每个 clip 依次执行用 clip 专属生成器种子 主种子 clip 序号_make_clip_generators生成随机噪声潜变量从音频嵌入中切出当前 clip 对应的片段audio_emb[..., r*infer_frames : (r1)*infer_frames]通过WanModel_S2V即WanS2VPipeline中的transformer预测噪声音频特征经casual_audio_encoder注入开启 CFG 时对正向/负向提示词分别前向并用FlowUniPCMultistepScheduler配合flow_shift更新潜变量diffusepipeline_wan2_2_s2v.pyVAE 解码当前 clip 像素帧首 clip 若开启--init-first-frame则在 motion 潜变量末尾 6 帧放置参考图实现首帧即参考图自回归衔接当前 clip 末尾motion_frames默认 73帧被保留为videos_last_frames重新 VAE 编码为motion_latents作为下一 clip 的运动上下文pipeline_wan2_2_s2v.py。clip 间还会清空显存缓存。Transformer 侧S2V 变体支持多卡并行算子WanS2VSelfAttention/WanS2VCrossAttention/WanS2VTransformerBlock见 wan2_2_s2v_transformer.py并配有针对性的旋转位置编码RotaryEmbeddingS2VGrid等。6. 后处理Post-process所有 clip 按时间维拼接为完整视频torch.cat(clips, dim2)后处理函数get_wan22_s2v_post_process_funcpipeline_wan2_2_s2v.py将视频张量还原为像素空间默认np输出同时把管线返回的音频波形、采样率与 fps16一并打包进输出供示例脚本调用mux_video_audio_bytes合成带声音的 MP4。九、输出处理与结果验证示例脚本在拿到OmniRequestOutput后做了三件事speech_to_video.py从output.multimodal_output中提取音频波形、fps 与音频采样率默认 16000 Hz将视频帧规整为(T, H, W, C)的 uint8 numpy 数组自动处理 5 维/4 维/列表等不同形态用mux_video_audio_bytes将帧序列与波形合成 MP4 写入输出路径并打印帧数、时长与音轨信息。若输出中不含视频帧脚本会抛出ValueError(No video frames found in OmniRequestOutput.)便于第一时间发现管线异常。十、相关资源与进一步阅读官方示例说明examples/offline_inference/speech_to_video/README.md可运行示例脚本examples/offline_inference/speech_to_video/speech_to_video.pyS2V 管线实现vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_s2v.pyS2V Transformer含 TP 算子vllm_omni/diffusion/models/wan2_2/wan2_2_s2v_transformer.py模型注册表pre/post-process 挂载vllm_omni/diffusion/registry.pyS2V 管线单元测试覆盖批量约束、种子、输出切分等tests/diffusion/models/wan2_2/test_wan22_s2v_pipeline.py模型配方文档recipes/Wan-AI/Wan2.2-S2V.md音视频合成工具vllm_omni/diffusion/utils/media_utils.py其中单元测试从工程层面印证了本文所述的几个关键约束批量请求的num_repeat、音频嵌入时间长度、init_first_frame与原始音频 shape/采样率必须一致否则管线会显式抛出ValueError参见test_s2v_forward_rejects_*系列用例这些约束正源于多片段自回归衔接对同批请求的强一致要求。【免费下载链接】vllm-omniA framework for efficient model inference with omni-modality models项目地址: https://gitcode.com/GitHub_Trending/vl/vllm-omni创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
