企业官网建设流程全解析

vLLM-Omni 文生视频统一入口：text_to_video.py 多模型实战指南

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

本指南围绕 vLLM-Omni 仓库中examples/offline_inference/text_to_video/目录下的统一文生视频（Text-to-Video, T2V）脚本展开，它通过模型感知的默认参数为 Wan2.2、Wan2.1 VACE、LingBot-Video、LTX-2、HunyuanVideo-1.5、SANA-Video-2B、Cosmos3、Helios、MAGI-2 等主流视频生成模型提供同一套命令行入口。读完本文，你将掌握各模型的推荐生成参数、--extra-body模型专属参数通道、并行与显存优化手段，以及从文本提示词到最终 MP4 文件的完整调用链。

一、统一入口的设计思想：一份脚本驱动多种模型

text_to_video.py是 vLLM-Omni 离线推理示例中面向“文本 → 视频”任务的共享入口（位于 examples/offline_inference/text_to_video/text_to_video.py）。它并不为每个模型维护一套独立参数，而是通过三层机制实现“开箱即用”：

1. 内置模型预设表_MODEL_PRESETS：脚本内置了vace、wan、hunyuan、cosmos、cosmos3_edge、helios、lingbot、ltx2、ltx2_distilled、ltx23、sana_480p、sana_720p等预设，每个预设包含默认分辨率、帧数、采样步数、CFG scale、fps 与输出文件名。
2. 模型类名识别_detect_preset：脚本通过模型 ID 字符串与解析出的 pipeline 类名（resolve_model_class_name）自动匹配预设。例如匹配顺序上，Cosmos3-Edge 必须先于通用 cosmos 分支判断，否则会错误继承 Nano/Super 的 720p / guidance 6.0 / flow_shift 10.0 参数导致退化输出。
3. 模型声明式默认值VideoGenerationDefaults：仓库在 vllm_omni/model_extras/video_generation.py 定义了冻结数据类VideoGenerationDefaults（含 width、height、num_frames、num_inference_steps、fps、guidance_scale、flow_shift、default_negative_prompt 等字段），由各模型在 vllm_omni/model_extras/registry.py 的_EXTRA_SPECS注册表中声明（如Magi2Pipeline注册了video_generation_defaults_builder）。脚本通过get_video_generation_defaults获取声明值，并经由cli_defaults()注入命令行参数，实现“模型拥有默认值、脚本只负责兜底”。

用户未显式指定的--height/--width/--num-frames/--num-inference-steps/--guidance-scale/--fps/--output等参数，都会先填充预设或模型声明默认值，再进入采样参数构造流程。

二、支持的模型与默认参数矩阵

以下是脚本支持的主要 T2V 模型及其模型感知默认值（来自 text_to_video.md 与脚本预设表）：

MAGI-2 Preview 的原生部署方式、四卡拓扑、DLO 选择、请求约束与八卡验证状态，详见 recipes/SandAI/MAGI-2-preview-L20X.md。从该 recipe 可知：MAGI-2 Preview 固定输出 10 秒、125 帧 @ 12.5fps，原生支持272p（448x256）与540p（896x512）两档分辨率，音频为 44.1kHz 立体声。

三、运行前置条件

• 安装 vLLM-Omni 及其依赖（Diffusers、Torch、ffmpeg等），可参考 docs/getting_started 与 requirements；
• 目标模型权重需可通过 Hugging Face Hub 访问，或已下载到本地路径（--model同时支持模型 ID 与本地目录）；
• 显存需满足上表 VRAM 要求；显存不足时优先启用--vae-use-tiling、--quantization fp8或 offload 相关选项。

四、本地 CLI 用法

脚本统一通过python text_to_video.py <参数>调用，以下按模型逐一给出经过验证的推荐命令。

4.1 Wan2.2（默认模型）

--model缺省即为Wan-AI/Wan2.2-T2V-A14B-Diffusers，所以可直接省略：

python text_to_video.py \ --prompt "Two anthropomorphic cats in comfy boxing gear and bright gloves fight intensely on a spotlighted stage." \ --negative-prompt "<optional quality filter>" \ --height 480 \ --width 832 \ --num-frames 33 \ --guidance-scale 4.0 \ --guidance-scale-high 3.0 \ --flow-shift 12.0 \ --num-inference-steps 40 \ --fps 16 \ --output t2v_out.mp4

要点：

• --guidance-scale-high是 Wan2.2 专属参数，为高噪声阶段单独设置 CFG 系数，脚本内部会映射为采样参数的guidance_scale_2；
• --flow-shift与分辨率强相关：480p 推荐 12.0，720p 推荐 5.0（脚本参数帮助信息中已注明）；
• --boundary-ratio控制低/高噪声 DiT 的分界比例，默认 0.875。

4.2 Wan2.1 VACE（T2V）

VACE 文生视频复用同一入口；条件式 VACE 任务（I2V 等）则走共享的 image_to_video.py，由脚本根据媒体输入构造 pipeline 原生条件数据，无需显式模式参数：

python text_to_video.py \ --model Wan-AI/Wan2.1-VACE-1.3B-diffusers \ --prompt "A sleek, humanoid robot stands in a vast warehouse filled with neatly stacked cardboard boxes on industrial shelves." \ --seed 0 \ --height 480 \ --width 832 \ --num-frames 81 \ --num-inference-steps 30 \ --guidance-scale 5.0 \ --flow-shift 5.0 \ --vae-use-tiling \ --output vace_t2v_output.mp4

4.3 LingBot-Video

共享 runner 能自动识别官方 dense 与 MoE 检查点 ID，选择LingBotVideoPipeline并构造标准视频请求封装：

python text_to_video.py \ --model robbyant/lingbot-video-dense-1.3b \ --prompt "a robotic arm picks up a red block" \ --height 192 --width 320 --num-frames 9 --num-inference-steps 2 \ --guidance-scale 3.0 --flow-shift 3.0 --fps 24 \ --output lingbot_t2v.mp4

使用robbyant/lingbot-video-moe-30b-a3b即可切换到 MoE 检查点。注意：

• 请求帧数会被向上取整到因果 VAE 的4n+1网格；
• 若本地检查点路径名不包含lingbot，需显式传--model-class-name LingBotVideoPipeline；
• LingBot 专属参数如batch_cfg、output_type通过共享的 model-extra 通道传递（见下文--extra-body一节）：

python text_to_video.py \ --model robbyant/lingbot-video-dense-1.3b \ --extra-body '{"batch_cfg": true, "output_type": "np"}'

从 vllm_omni/model_extras/lingbot_video.py 可以看到，LingBot 还声明了duration、null_cond_clone_zero、offload_vae_during_denoise、refiner_sigma_tail_steps、resolution、ratio、shift、t_thresh等额外参数，均可经--extra-body传入；同时其输出张量范围在 vllm_omni/model_extras/registry.py 中声明为zero_to_one，脚本会据此直接钳位而不再做 [-1,1]→[0,1] 的换算。

4.4 LTX-2

python text_to_video.py \ --model Lightricks/LTX-2 \ --prompt "Cherry blossoms swaying gently in the breeze with synchronized ambient sound" \ --output ltx2_output.mp4

LTX-2 在 vllm_omni/model_extras/ltx2.py 声明了专属 extra 参数，并注册了LTX2Pipeline/LTX2TwoStagePipeline等多个 pipeline 类名（含蒸馏变体）；脚本预设还额外提供ltx2_distilled（1024x1536、8 步）与ltx23（512x768、30 步）两档快速预设。全部检查点、pipeline 选择、I2V、默认值与高级选项参见 recipes/LTX/LTX-2.md。

4.5 HunyuanVideo-1.5

480p：

python text_to_video.py \ --model hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v \ --prompt "A cat walks through a sunlit garden, flowers swaying gently in the breeze." \ --height 480 \ --width 832 \ --num-frames 121 \ --guidance-scale 6.0 \ --flow-shift 5.0 \ --num-inference-steps 50 \ --fps 24 \ --output hunyuan_video_15_output.mp4

720p：

python text_to_video.py \ --model hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_t2v \ --prompt "A serene lakeside sunrise with mist over the water." \ --height 720 \ --width 1280 \ --num-frames 121 \ --guidance-scale 6.0 \ --flow-shift 9.0 \ --num-inference-steps 50 \ --fps 24 \ --output hunyuan_720p.mp4

FP8 量化版：

python text_to_video.py \ --model hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v \ --prompt "A dog running across a field of golden wheat." \ --quantization fp8 \ --height 480 --width 832 --num-frames 121 \ --guidance-scale 6.0 --flow-shift 5.0 \ --output hunyuan_fp8.mp4

快速冒烟测试（更小分辨率、更少帧数）：

python text_to_video.py \ --model hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v \ --prompt "A serene lakeside sunrise with mist over the water." \ --height 320 --width 576 --num-frames 17 --num-inference-steps 30 \ --flow-shift 5.0 \ --output quick_test.mp4

4.6 SANA-Video-2B

原生 T2V pipeline 需要显式指定模型类名：

python text_to_video.py \ --model Efficient-Large-Model/SANA-Video_2B_480p_diffusers \ --model-class-name SanaVideoPipeline \ --prompt "A cinematic tracking shot of a sailboat crossing the ocean at sunset." \ --height 480 \ --width 832 \ --num-frames 81 \ --num-inference-steps 50 \ --guidance-scale 6.0 \ --extra-body '{"motion_score": 30}' \ --fps 16 \ --output sana_video_480p.mp4

720p 检查点只需切换模型为Efficient-Large-Model/SANA-Video_2B_720p_diffusers，并改用--height 704 --width 1280。实现层面值得注意：

• 480p 路径使用 vLLM-Omni 的DistributedAutoencoderKLWan包装（源码见 vllm_omni/diffusion/distributed/autoencoders/autoencoder_kl_wan.py），720p 路径使用DistributedAutoencoderKLLTX2Video（vllm_omni/diffusion/distributed/autoencoders/autoencoder_kl_ltx2.py），二者均保留底层 Diffusers 自编码器能力；
• pipeline 刻意使用 Diffusers 检查点兼容的DPMSolverMultistepScheduler；
• SANA 声明了clean_caption、motion_score、use_resolution_binning三个 extra 参数（vllm_omni/model_extras/sana_video.py）；
• 图像到视频请使用共享的 image_to_video.py，传--model-class-name SanaImageToVideoPipeline与--image <path>。

4.7 Cosmos3

python text_to_video.py \ --model nvidia/Cosmos3-Nano \ --prompt "A robot arm is cleaning a plate in the kitchen." \ --negative-prompt "blurry, distorted, low quality, jittery, deformed" \ --height 720 --width 1280 --num-frames 189 --fps 24 \ --num-inference-steps 35 --guidance-scale 6.0 \ --extra-body '{"flow_shift": 10.0, "max_sequence_length": 4096, "guardrails": false, "use_resolution_template": false, "use_duration_template": false}' \ --output cosmos3_t2v.mp4

实现细节：Cosmos3 的受门控（gated）guardrail 模型在构建期加载，因此guardrails属于引擎级配置，脚本会将--extra-body中的guardrails提取到omni_kwargs["model_config"]，作为离线场景下服务端--no-guardrails的对应物。Cosmos3 声明了非常完整的 extra 参数集（vllm_omni/model_extras/cosmos3.py），涵盖flow_shift、max_sequence_length、分辨率/时长模板开关、generate_sound/sound_duration（同步音效）、机器人动作控制（action_mode、action、action_fps等）与视频条件输入等字段。

4.8 Helios（T2V）

Helios 提供 Base / Mid / Distilled 三个变体，模型专属旋钮在 vllm_omni/model_extras/helios.py 中声明（金字塔采样、CFG-Zero*、蒸馏少步等），统一通过通用--extra-bodyJSON 传递。

Helios-Base（仅 Stage 1）：

python text_to_video.py \ --model BestWishYsh/Helios-Base \ --prompt "A dynamic time-lapse of scenery rushing past the window of a speeding train." \ --guidance-scale 5.0 \ --output helios_t2v_base.mp4

Helios-Mid（Stage 2 金字塔 + CFG-Zero*）：

python text_to_video.py \ --model BestWishYsh/Helios-Mid \ --prompt "A dynamic time-lapse of scenery rushing past the window of a speeding train." \ --guidance-scale 5.0 \ --extra-body '{"is_enable_stage2": true, "pyramid_num_inference_steps_list": [20, 20, 20], "use_cfg_zero_star": true, "use_zero_init": true, "zero_steps": 1}' \ --output helios_t2v_mid.mp4

Helios-Distilled（Stage 2 金字塔 + DMD，少步）：

python text_to_video.py \ --model BestWishYsh/Helios-Distilled \ --prompt "A dynamic time-lapse of scenery rushing past the window of a speeding train." \ --num-frames 240 \ --guidance-scale 1.0 \ --extra-body '{"is_enable_stage2": true, "pyramid_num_inference_steps_list": [2, 2, 2], "is_amplify_first_chunk": true}' \ --output helios_t2v_distilled.mp4

注意：Helios 的图像到视频（I2V）与视频到视频（V2V）需要图像/视频条件张量，无法通过 JSON 形式的--extra-body传递，不在本文本到视频示例的范围内。

五、--extra-body：模型专属参数的统一通道

这是脚本最重要的扩展机制。参数--extra-body接受一个 JSON 对象，其流转逻辑在 text_to_video.py 中清晰可见：

1. 构造OmniDiffusionSamplingParams（来自 vllm_omni/inputs/data.py）；
2. 通过get_extra_body_params(model_class_name)获取该模型声明的extra_body_params白名单；
3. 若模型有声明，调用apply_declared_extra_args(sampling_params, declared_extra_body_params, extra_body)（位于 vllm_omni/diffusion/utils/param_utils.py），将 JSON 中命中的键合并进sampling_params.extra_args，未声明的键会被丢弃；
4. 若模型无声明，则保留通用行为：把非空值原样并入extra_args。

这套“白名单过滤 + 合并到 extra_args”的设计，让一个通用示例脚本既能驱动 Helios、Cosmos3 这类参数丰富的模型，又不至于被未知键污染采样配置。

六、关键参数速查

6.1 通用参数

6.2 Wan2.2 专属

6.3 并行与显存扩展参数

脚本还暴露了完整的并行维度控制，这些参数会直接透传进Omni引擎构造参数：

• --ulysses-degree/--ring-degree：Ulysses 与 Ring 序列并行 GPU 数；
• --ulysses-mode：strict（要求可整除）或advanced_uaa；
• --cfg-parallel-size：CFG 并行卡数（仅 1 或 2）。CFG-Parallel 通过把正负 CFG 分支分发到不同 GPU 实现约 1.8 倍加速（详见 docs/user_guide/diffusion/parallelism/cfg_parallel.md），但注意蒸馏版 Cosmos3 检查点（如nvidia/Cosmos3-Super-Image2Video-4Step）无 CFG，启动时会拒绝--cfg-parallel-size大于 1；
• --vae-patch-parallel-size：VAE 解码的 patch/tile 并行卡数；
• --pipeline-parallel-size：流水线并行级数；
• --enable-expert-parallel：MoE 层专家并行；
• --use-hsdp/--hsdp-shard-size/--hsdp-replicate-size：Hybrid Sharded Data Parallel；
• --enable-distributed-layerwise-offload/--dlo-use-allgather/--dlo-resident-layers：分布式逐层 offload（含 host→device 权重流重叠、分片+AllGather 重建、常驻层数控制），MAGI-2 的 Rank-local DLO 配置即依赖这组参数。

6.4 HunyuanVideo-1.5 最优配置

6.5 性能剖析

脚本内置两档性能工具：

• --enable-diffusion-pipeline-profiler：展示各阶段耗时；
• --profiler-config '{"profiler":"torch","torch_profiler_dir":"./perf"}'：torch/cuda 级 profile，生成结束后逐 rank 打印 trace 路径。

七、从采样输出到 MP4：结果后处理管线

脚本在拿到引擎输出后还会执行一系列规范化的后处理，理解这段逻辑有助于排查输出异常：

1. 峰值显存上报：通过_extract_peak_memory_mb从 worker 结果中解析peak_memory_mb并打印（与vllm_omni/entrypoints/openai/serving_video.py的实现一致）；
2. 多模态输出拆包：处理OmniRequestOutput中可能携带的音频（multimodal_output["audio"]）、(frames, audio)元组、{"frames"|"video", "audio"}字典等三种形态，兼容 pipeline 输出与普通输出；
3. 张量归一化：_normalize_float_tensor依据模型声明的output_tensor_range（negative_one_to_one时执行clamp(-1,1)*0.5+0.5，zero_to_one时直接 clamp）将浮点帧归一化到 [0,1]；
4. 维度整理：_ensure_frame_list统一处理 5D/4D/3D 数组与列表嵌套，适配export_to_video期望的“[0,1] 帧列表”；
5. 音视频合成：若输出含音频（如 Cosmos3 的generate_sound、LTX-2 的同步环境音），调用 vllm_omni/diffusion/utils/media_utils.py 的mux_video_audio_bytes将 uint8 帧与音频按--fps与采样率封装；否则走 Diffusers 的export_to_video写出 MP4。

八、OOM 与质量问题的排查路径

原文档给出的通用建议，按优先级整理如下：

• 遇到 OOM，依次尝试--vae-use-slicing、--vae-use-tiling；
• 仍不足，通过--diffusion-offload-config做组件级 offload（VAE、文本编码器、DiT 按需选择），或用--enable-layerwise-offload对 DiT 逐层卸载；
• 追求极致显存压缩时使用--quantization fp8（HunyuanVideo-1.5 720p 即官方建议 FP8 + VAE tiling）；
• 多卡场景优先考虑--cfg-parallel-size 2（CFG 开启时约 1.8 倍加速）与--tensor-parallel-size（LTX2 等支持 TP 的模型），MAGI-2 类大模型则按 MAGI-2 recipe 的 SP4 / DLO 拓扑部署；
• 若为蒸馏少步模型（Helios-Distilled、LTX-2 distilled），务必使用guidance_scale 1.0级别的低 CFG 或关闭 CFG，并核对--extra-body中金字塔步数列表与num_inference_steps的对应关系；
• 帧数异常（如 LingBot 非4n+1）会被自动取整，属正常行为而非错误。

九、延伸阅读

• 图像到视频共享入口：examples/offline_inference/image_to_video/README.md
• 模型专属参数声明：vllm_omni/model_extras/目录下的 helios.py、cosmos3.py、magi2.py、lingbot_video.py、sana_video.py 等
• CFG-Parallel 原理与最佳实践：docs/user_guide/diffusion/parallelism/cfg_parallel.md
• 视频生成模型能力矩阵：docs/user_guide/diffusion_features.md 与 docs/models/supported_models.md
• LTX-2 全量检查点与高级选项：recipes/LTX/LTX-2.md
• MAGI-2 Preview 四卡部署：recipes/SandAI/MAGI-2-preview-L20X.md

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