vLLM-Omni 离线图生视频实战：image_to_video.py 驱动 Wan2.2、LTX-2 与 SANA-Video 的 I2V 生成-二趣网

vLLM-Omni 离线图生视频实战：image_to_video.py 驱动 Wan2.2、LTX-2 与 SANA-Video 的 I2V 生成

【免费下载链接】vllm-omniA framework for efficient model inference with omni-modality models项目地址: https://gitcode.com/GitHub_Trending/vl/vllm-omni

本文围绕 vLLM-Omni 仓库中的离线推理示例 image_to_video.md 展开，介绍如何用统一的命令行脚本image_to_video.py从单张图像生成视频，覆盖 Wan2.2-I2V-A14B（MoE）、Wan2.2-TI2V-5B（统一式）、LTX-2 与 SANA-Video-2B 四类模型的完整运行命令、关键参数语义、内存优化开关，并结合示例脚本源码解析模型默认值、分辨率自动计算与extra-body过滤等底层机制。读完本文，你可以在本地复现上述模型的图生视频流程，并针对显存不足、多卡并行等实际问题进行针对性调优。

I2V 离线推理示例概览

vLLM-Omni 的图生视频（Image-to-Video, I2V）离线示例位于 examples/offline_inference/image_to_video/ 目录，核心是一个统一的 CLI 脚本 image_to_video.py。该脚本通过 vLLM-Omni 的离线推理入口Omni（定义于 vllm_omni/entrypoints/omni.py）加载 Diffusers 格式的 I2V 模型，将图像与文本提示组织成多模态请求，经扩散去噪后把帧序列导出为 MP4。

从脚本文件头部的使用说明（image_to_video.py第 4–14 行）看，该脚本实际支持的范围比文档标题更广，包括：

Wan2.2-I2V-A14B-Diffusers：带 CLIP 图像编码器的 MoE 模型，含低噪声/高噪声双阶段 DiT；
Wan2.2-TI2V-5B-Diffusers：统一 T2V+I2V 的 dense 5B 模型；
LTX2 / LTX-2.3：图生视频管线，支持音视频联合生成；
HunyuanVideo-1.5 I2V：SigLIP + VAE 双路图像条件；
SANA-Video 2B：480p / 720p 首帧潜变量条件；
Wan2.1 VACE：首帧/尾帧、修补（inpainting）与参考图条件。

无论选择哪个模型，请求的组织方式一致：脚本会把prompt、modalities: ["video"]、multi_modal_data（其中image键承载输入图像）以及可选的negative_prompt组装成规范请求信封（见build_image_to_video_prompt函数，image_to_video.py），再交由omni.generate()执行。

准备工作：下载示例图像

文档所有命令行示例都使用同一张示例图cherry_blossom.jpg（樱花场景，便于观察“花瓣飘落、微风摆动”等运动生成效果）：

wget https://vllm-public-assets.s3.us-west-2.amazonaws.com/vision_model_images/cherry_blossom.jpg

四个模型的实际运行命令

Wan2.2-I2V-A14B-Diffusers（MoE）

这是文档给出的默认模型。注意它比统一式模型多出两个 MoE 专属参数：--guidance-scale-high（高噪声阶段的独立 CFG 强度）与--boundary-ratio（两阶段边界切分比例）：

python image_to_video.py \ --model Wan-AI/Wan2.2-I2V-A14B-Diffusers \ --image cherry_blossom.jpg \ --prompt "Cherry blossoms swaying gently in the breeze, petals falling, smooth motion" \ --negative-prompt "<optional quality filter>" \ --height 480 \ --width 832 \ --num-frames 48 \ --guidance-scale 5.0 \ --guidance-scale-high 6.0 \ --num-inference-steps 40 \ --boundary-ratio 0.875 \ --flow-shift 12.0 \ --fps 16 \ --output i2v_output.mp4

从示例 README 的模型对照表（examples/offline_inference/image_to_video/README.md）看，I2V-A14B 基础单卡 BF16 占用约 60 GiB，属于较大规模模型；TI2V-5B则只需约 20–25 GiB，是四者中最轻量的 I2V 选项，适合快速验证流程。

Wan2.2-TI2V-5B-Diffusers（统一式）

统一式 T2V+I2V 模型不需要 MoE 的边界与双 CFG 参数，命令更简洁：

python image_to_video.py \ --model Wan-AI/Wan2.2-TI2V-5B-Diffusers \ --image cherry_blossom.jpg \ --prompt "Cherry blossoms swaying gently in the breeze, petals falling, smooth motion" \ --negative-prompt "<optional quality filter>" \ --height 480 \ --width 832 \ --num-frames 48 \ --guidance-scale 4.0 \ --num-inference-steps 40 \ --flow-shift 12.0 \ --fps 16 \ --output i2v_output.mp4

LTX-2

LTX-2 支持提示词驱动的同步环境声生成，命令只给最少参数即可，其余采样参数走模型内建默认值：

python image_to_video.py \ --model Lightricks/LTX-2 \ --image cherry_blossom.jpg \ --prompt "Cherry blossoms swaying gently in the breeze with synchronized ambient sound" \ --output ltx2_i2v_output.mp4

关于 LTX-2 的全部 checkpoint、管线选择、T2V 用法、默认值与高级选项，可进一步查阅仓库内的 LTX-2 recipe。

从源码看，LTX 系列在脚本中有专门的默认值分支：帧率 24、帧数 121、步数 40（LTX-2.3 为 30）、最大像素面积 512×768、维度需为 32 的倍数（image_to_video.py），且 LTX 系列不消费--flow-shift选项。

SANA-Video-2B

SANA-Video 的 checkpoint 元数据（model_index.json）声明的是上游 T2V 管线，因此 I2V 场景必须显式指定管线类名SanaImageToVideoPipeline：

python image_to_video.py \ --model Efficient-Large-Model/SANA-Video_2B_480p_diffusers \ --model-class-name SanaImageToVideoPipeline \ --image cherry_blossom.jpg \ --prompt "Cherry blossoms sway in the breeze as petals drift past the camera." \ --negative-prompt "blurry, low quality, temporal artifacts" \ --height 480 \ --width 832 \ --num-frames 81 \ --num-inference-steps 50 \ --guidance-scale 6.0 \ --extra-body '{"motion_score": 30}' \ --fps 16 \ --seed 42 \ --output sana_video_i2v_480p.mp4

文档对 SANA-Video 给出三条重要的适用边界，务必注意：

720p checkpoint 用法：改用Efficient-Large-Model/SANA-Video_2B_720p_diffusers并设置--height 704 --width 1280；
VAE 差异：原生 I2V 路径同时支持两个变体，480p checkpoint 使用 Wan VAE，720p checkpoint 使用 LTX-2 Video VAE；
时长边界：81 帧 @ 16 FPS 约等于五秒的标准 checkpoint 请求，不是分钟级长视频生成；分钟级 SANA 生成需要独立的 LongSANA/LongLive 自回归工作流，本管线未实现。

SANA-Video 的在线服务方式、后端边界与已验证硬件配置，见仓库中的 SANA-Video recipe。

关键参数详解

以下参数说明完整继承原文档，并结合 image_to_video.py 的argparse定义补充了默认值与取值约束：

--model：模型 ID 或本地路径（如 Wan I2V/TI2V、LTX-2、SANA-Video）。脚本默认值为Wan-AI/Wan2.2-I2V-A14B-Diffusers。
--model-class-name：显式管线类名覆盖。SANA-Video I2V 必须传SanaImageToVideoPipeline；LTX checkpoint 默认解析为LTX2Pipeline。
--image：输入图像路径（图生视频场景必需）。脚本还额外提供--last-image（尾帧条件）、--mask-image（修补掩码）与可重复的--reference-image（参考图），主要服务于 VACE 类模型。
--prompt：描述期望运动/动画的文本提示。
--height/--width：输出分辨率，不设置时根据输入图像自动计算并保持宽高比。Wan 维度应为 16 的倍数；LTX 维度应为 32 的倍数。
--num-frames：生成帧数（各模型有自己的默认值；LTX 风格模型取8k + 1形式效果最佳，如 121）。
--guidance-scale与--guidance-scale-high：CFG 强度；对 MoE 模型分别作用于低噪声/高噪声两个阶段。
--negative-prompt：可选，用于抑制伪影（如blurry, low quality, temporal artifacts）。
--boundary-ratio：两阶段 MoE 模型的边界切分比例，脚本默认0.875。
--flow-shift：调度器 flow shift（720p 用 5.0，480p 用 12.0；Wan 默认 5.0，Cosmos3 默认 10.0）。
--sample-solver：Wan2.2 采样求解器，默认unipc（多步求解器）；Lightning/Distill 蒸馏 checkpoint 应使用euler。取值为unipc/euler二选一。
--num-inference-steps：去噪步数（默认 50，各模型默认值不同：Wan 50、LTX2 40、Cosmos3 35）。
--fps：输出 MP4 的帧率（导出依赖diffusers的export_to_video）。
--frame-rate：生成帧率，部分管线（如 LTX2）需要；缺省时回退为--fps。
--audio-sample-rate：内嵌音频的兜底采样率，默认 24000。
--output：输出 MP4 路径，默认i2v_output.mp4。
--vae-use-slicing/--vae-use-tiling：VAE 切片/分块解码，用于显存优化。
--cfg-parallel-size：设为 2 可启用 CFG 并行（仅支持 1/2），更多示例见 cfg_parallel 用户指南。
--tensor-parallel-size：DiT 内部张量并行规模（对支持 TP 的模型生效，如 LTX2）。
--enable-cpu-offload：启用扩散模型权重 CPU offload。
--use-hsdp：启用 HSDP（Hybrid Sharded Data Parallel），把模型权重分片到多张 GPU。
--hsdp-shard-size：每个副本组内分片权重使用的 GPU 数，默认-1时自动计算为world_size / replicate_size。
--hsdp-replicate-size：HSDP 副本组数，每个副本持有一份完整分片拷贝；默认 1 即纯分片（无复制）。

此外，脚本源码中还提供了文档未逐一列举的实用开关：--ulysses-degree/--ring-degree（序列并行）、--vae-patch-parallel-size（VAE patch 并行）、--enable-layerwise-offload（DiT 逐层 offload）、--enable-distributed-layerwise-offload（带主机到设备权重流式重叠的分布式逐层 offload）、--cache-backend（cache_dit或tea_cache缓存加速）、--quantization（fp8/mxfp8/mxfp4/mxfp4_dualscale/int8量化）以及--lora-path/--lora-backend（PEFT 运行时 LoRA 或初始化期蒸馏 LoRA 融合）。

显存不足提示：如果生成过程遇到 OOM，优先尝试--vae-use-slicing与--vae-use-tiling降低解码显存；更大的模型可叠加--enable-cpu-offload或--enable-layerwise-offload。

源码机制：默认值、分辨率计算与 extra-body 过滤

理解脚本的几处关键实现，有助于解释“为什么可以少传参数”以及“为什么某些参数会被静默忽略”。

1. 按模型分派的生成默认值。脚本的main()中维护了按模型族分支的默认值元组（fps、guidance、帧数、步数、flow_shift、最大像素面积、维度倍数）：Cosmos3-Nano/Super 为 1280×720 面积、189 帧、35 步、flow_shift 10.0；Cosmos3-Edge 为 480×832、flow_shift 3.0（注释明确说明套用 Nano/Super 参数会产生退化输出）；SANA-Video 480p/720p 分别为 480×832 / 704×1280 面积、81 帧、50 步、flow_shift 5.0；Wan2.2 / HunyuanVideo-1.5 兜底为 16 fps、guidance 5.0、81 帧、50 步、flow_shift 5.0、480×832 面积（image_to_video.py）。这些默认值仅在对应 CLI 参数省略时生效，因此命令行显式传参始终优先。此外，vllm_omni/model_extras目录（如 sana_video.py、ltx2.py）中声明的模型自有默认值（VideoGenerationDefaults，见 video_generation.py）优先级更高。

2. 分辨率自动计算。未显式指定--height/--width时，calculate_dimensions函数以输入图像宽高比为约束、以目标像素面积（如 480×832）为约束，解出并向下取整到模型要求倍数（Wan 16 / LTX 32 / SANA-720p 32）的分辨率（image_to_video.py）。同时脚本会把输入图像 LANCZOS 重采样到目标分辨率后再送入管线（个别模型如 LingBot 保持原始几何，交由管线内部做 resize 与中心裁剪）。

3. 管线类名解析。未显式传--model-class-name时，脚本调用resolve_model_class_name（vllm_omni/diffusion/data.py）从 checkpoint 的model_index.json读取管线类名。这正是 SANA-Video I2V 必须显式覆盖的原因——其元数据声明的是 T2V 管线。

4. extra-body 白名单过滤。--extra-body接收 JSON 对象（如 SANA-Video 的{"motion_score": 30}、Cosmos3 的{"flow_shift": 10.0, "max_sequence_length": 4096, "guardrails": false}）。脚本通过apply_declared_extra_args把其中的键与vllm_omni/model_extras中该模型声明的extra_body_params做过滤，未被模型声明的键会被静默丢弃——这避免了把不适用的参数错误地下发到管线；对未声明任何 extra 参数的模型，则原样透传显式传入的 JSON。

5. 输出与音频混流。omni.generate()返回的OmniRequestOutput中若携带audio通道（如 LTX-2 的音视频联合生成），脚本会调用 vllm_omni/diffusion/utils/media_utils.py 的mux_video_audio_bytes把音频流混入 MP4（帧数组先裁剪 RGBA 到 RGB、量化为 uint8）；纯视频路径则直接用diffusers.utils.export_to_video导出。帧张量在导出前会做-1..1到0..1的归一化。

多卡并行与显存优化策略

文档与脚本把显存与吞吐优化收敛为一组开关，可组合使用：

VAE 解码侧：--vae-use-slicing/--vae-use-tiling是 OOM 场景的第一选择，--vae-patch-parallel-size进一步把 VAE 解码分片到多卡；
权重侧：--enable-cpu-offload做整模型 offload；--enable-layerwise-offload做 DiT 模块逐层 offload；--enable-distributed-layerwise-offload在多卡间流式搬运权重并可与 AllGather 分片重组配合（--dlo-use-allgather默认开启）；
计算侧：--cfg-parallel-size 2把 CFG 的正/负条件分支拆到两张卡；--tensor-parallel-size在支持 TP 的模型（如 LTX2）内切分 DiT；--ulysses-degree/--ring-degree提供序列并行维度；--use-hsdp+--hsdp-shard-size/--hsdp-replicate-size控制权重分片/复制拓扑。

各并行策略的系统性说明见 parallelism 用户指南。一个典型的高显存需求场景是 HunyuanVideo-1.5：示例 README 指出其默认设置约需 100 GiB，因此在 80 GiB 卡上的推荐命令会叠加--enable-cpu-offload --vae-use-tiling --vae-use-slicing（examples/offline_inference/image_to_video/README.md）。

Python API 快速示例

除了 CLI，同一套离线 API 也适合直接嵌入 Python 程序。以下是最小可用的 TI2V-5B 图生视频代码（取自示例目录 README）：

import PIL.Image import torch from vllm_omni.entrypoints.omni import Omni from vllm_omni.inputs.data import OmniDiffusionSamplingParams if __name__ == "__main__": image = PIL.Image.open("cherry_blossom.jpg").convert("RGB") image = image.resize((576, 320)) omni = Omni( model="Wan-AI/Wan2.2-TI2V-5B-Diffusers", flow_shift=12.0, ) outputs = omni.generate( { "prompt": "Cherry blossoms swaying gently in the breeze, petals falling", "multi_modal_data": {"image": image}, }, OmniDiffusionSamplingParams( height=320, width=576, num_frames=17, num_inference_steps=20, guidance_scale=4.0, generator=torch.Generator(device="cuda").manual_seed(42), ), ) from diffusers.utils import export_to_video frames = outputs[0].images export_to_video(frames, "quick_test_i2v.mp4", fps=16)

OmniDiffusionSamplingParams与 CLI 参数一一对应（height/width/num_frames/num_inference_steps/guidance_scale/fps/frame_rate等，见 vllm_omni/inputs/data.py），generator传入手动设种子的torch.Generator可保证采样可复现。

企业官网建设流程全解析