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。它并不为每个模型维护一套独立参数而是通过三层机制实现“开箱即用”内置模型预设表_MODEL_PRESETS脚本内置了vace、wan、hunyuan、cosmos、cosmos3_edge、helios、lingbot、ltx2、ltx2_distilled、ltx23、sana_480p、sana_720p等预设每个预设包含默认分辨率、帧数、采样步数、CFG scale、fps 与输出文件名。模型类名识别_detect_preset脚本通过模型 ID 字符串与解析出的 pipeline 类名resolve_model_class_name自动匹配预设。例如匹配顺序上Cosmos3-Edge 必须先于通用 cosmos 分支判断否则会错误继承 Nano/Super 的 720p / guidance 6.0 / flow_shift 10.0 参数导致退化输出。模型声明式默认值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 与脚本预设表模型默认分辨率默认帧数默认步数GuidanceVRAMBF16Wan-AI/Wan2.1-VACE-1.3B-diffusers480x83281305.0~20 GiBRTX 5090VAE tilingWan-AI/Wan2.2-T2V-A14B-Diffusers720x128081404.0~60 GiBrobbyant/lingbot-video-dense-1.3b/robbyant/lingbot-video-moe-30b-a3b192x320923.0~68 GiBMoE smokeLightricks/LTX-2512x76812140video 3.0 / audio 7.0取决于模型hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v480x832121506.01×A100 80GBhunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_t2v720x1280121506.0需 FP8 VAE tilingnvidia/Cosmos3-Nano720x1280189356.0~46 GiB峰值720pBestWishYsh/Helios-Base/Helios-Mid/Helios-Distilled384x64099505.0 / 5.0 / 1.0—sand-ai/MAGI-2-preview512x896125100模型固定原生四卡 TP/SP默认 resident SP4支持 DLOEfficient-Large-Model/SANA-Video_2B_480p_diffusers480x83281506.0BF16 DiT FP32 Wan VAE wrapperEfficient-Large-Model/SANA-Video_2B_720p_diffusers704x128081506.0BF16 DiT LTX-2 Video VAE wrapperMAGI-2 Preview 的原生部署方式、四卡拓扑、DLO 选择、请求约束与八卡验证状态详见 recipes/SandAI/MAGI-2-preview-L20X.md。从该 recipe 可知MAGI-2 Preview 固定输出 10 秒、125 帧 12.5fps原生支持272p448x256与540p896x512两档分辨率音频为 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.0720p 推荐 5.0脚本参数帮助信息中已注明--boundary-ratio控制低/高噪声 DiT 的分界比例默认 0.875。4.2 Wan2.1 VACET2VVACE 文生视频复用同一入口条件式 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.mp44.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 的4n1网格若本地检查点路径名不包含lingbot需显式传--model-class-name LingBotVideoPipelineLingBot 专属参数如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-2python text_to_video.py \ --model Lightricks/LTX-2 \ --prompt Cherry blossoms swaying gently in the breeze with synchronized ambient sound \ --output ltx2_output.mp4LTX-2 在 vllm_omni/model_extras/ltx2.py 声明了专属 extra 参数并注册了LTX2Pipeline/LTX2TwoStagePipeline等多个 pipeline 类名含蒸馏变体脚本预设还额外提供ltx2_distilled1024x1536、8 步与ltx23512x768、30 步两档快速预设。全部检查点、pipeline 选择、I2V、默认值与高级选项参见 recipes/LTX/LTX-2.md。4.5 HunyuanVideo-1.5480ppython 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.mp4720ppython 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.mp4FP8 量化版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.mp44.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.mp4720p 检查点只需切换模型为Efficient-Large-Model/SANA-Video_2B_720p_diffusers并改用--height 704 --width 1280。实现层面值得注意480p 路径使用 vLLM-Omni 的DistributedAutoencoderKLWan包装源码见 vllm_omni/diffusion/distributed/autoencoders/autoencoder_kl_wan.py720p 路径使用DistributedAutoencoderKLLTX2Videovllm_omni/diffusion/distributed/autoencoders/autoencoder_kl_ltx2.py二者均保留底层 Diffusers 自编码器能力pipeline 刻意使用 Diffusers 检查点兼容的DPMSolverMultistepSchedulerSANA 声明了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 Cosmos3python 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 的受门控gatedguardrail 模型在构建期加载因此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 HeliosT2VHelios 提供 Base / Mid / Distilled 三个变体模型专属旋钮在 vllm_omni/model_extras/helios.py 中声明金字塔采样、CFG-Zero*、蒸馏少步等统一通过通用--extra-bodyJSON 传递。Helios-Base仅 Stage 1python 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.mp4Helios-MidStage 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.mp4Helios-DistilledStage 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 中清晰可见构造OmniDiffusionSamplingParams来自 vllm_omni/inputs/data.py通过get_extra_body_params(model_class_name)获取该模型声明的extra_body_params白名单若模型有声明调用apply_declared_extra_args(sampling_params, declared_extra_body_params, extra_body)位于 vllm_omni/diffusion/utils/param_utils.py将 JSON 中命中的键合并进sampling_params.extra_args未声明的键会被丢弃若模型无声明则保留通用行为把非空值原样并入extra_args。这套“白名单过滤 合并到 extra_args”的设计让一个通用示例脚本既能驱动 Helios、Cosmos3 这类参数丰富的模型又不至于被未知键污染采样配置。六、关键参数速查6.1 通用参数参数说明--modelDiffusers 模型 ID 或本地路径--model-class-name可选显式覆盖 pipeline 类名--prompt文本描述字符串--negative-prompt负向提示词模型特定默认值--height/--width输出分辨率默认取决于模型--num-frames帧数默认取决于模型--guidance-scaleCFG 系数默认取决于模型--num-inference-steps采样步数默认取决于模型--fps输出 MP4 的帧率--frame-rate生成期 FPS如 LTX2 需要默认取--fps--output视频保存路径--extra-body模型专属生成旋钮 JSON按模型声明的extra_body_params过滤后并入采样extra_args--vae-use-slicing启用 VAE slicing 节省显存--vae-use-tiling启用 VAE tiling 节省显存--cfg-parallel-size设为 2 开启 CFG Parallel详见 CFG-Parallel 指南--tensor-parallel-sizeDiT 内张量并行大小适用于支持 TP 的模型如 LTX2--enable-cpu-offload启用 CPU offload--enable-layerwise-offload对 DiT 模块启用逐层 offload--diffusion-offload-config组件级选择 offload 的 JSON不要与上述旧式开关混用--audio-sample-rate输出含音频时的备用采样率默认 24000--quantization量化方法fp8、mxfp8、mxfp4、mxfp4_dualscale、int8GPU 用fp8在线量化NPU 用 MXFP 系列--flow-shiftscheduler 的 flow_shift 参数--lora-pathPEFT LoRA 适配器目录或检查点文件可多个Wan2.2 MoE 需按高/低噪声模块位置映射两个--lora-scaleLoRA 权重缩放系数--lora-backendLoRA 加载后端默认peft可选peft/distill--enforce-eager关闭 torch.compile强制 eager 执行--seed随机种子默认 426.2 Wan2.2 专属参数说明--negative-prompt抑制伪影的负向提示词--guidance-scale-high高噪声阶段的独立 CFG 系数--boundary-ratio低/高 DiT 分界比例默认 0.875--flow-shiftscheduler flow_shift720p 用 5.0480p 用 12.0--cache-backendcache_dit加速后端启用时会注入 Fn/Bn compute blocks、warmup/cached steps、残差阈值等缓存配置6.3 并行与显存扩展参数脚本还暴露了完整的并行维度控制这些参数会直接透传进Omni引擎构造参数--ulysses-degree/--ring-degreeUlysses 与 Ring 序列并行 GPU 数--ulysses-modestrict要求可整除或advanced_uaa--cfg-parallel-sizeCFG 并行卡数仅 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-sizeVAE 解码的 patch/tile 并行卡数--pipeline-parallel-size流水线并行级数--enable-expert-parallelMoE 层专家并行--use-hsdp/--hsdp-shard-size/--hsdp-replicate-sizeHybrid 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 最优配置变体flow_shiftguidance_scalesteps480p T2V5.06.050720p T2V9.06.050480p I2V5.06.050720p I2V7.06.050CFG-distilled同上1.0506.5 性能剖析脚本内置两档性能工具--enable-diffusion-pipeline-profiler展示各阶段耗时--profiler-config {profiler:torch,torch_profiler_dir:./perf}torch/cuda 级 profile生成结束后逐 rank 打印 trace 路径。七、从采样输出到 MP4结果后处理管线脚本在拿到引擎输出后还会执行一系列规范化的后处理理解这段逻辑有助于排查输出异常峰值显存上报通过_extract_peak_memory_mb从 worker 结果中解析peak_memory_mb并打印与vllm_omni/entrypoints/openai/serving_video.py的实现一致多模态输出拆包处理OmniRequestOutput中可能携带的音频multimodal_output[audio]、(frames, audio)元组、{frames|video, audio}字典等三种形态兼容 pipeline 输出与普通输出张量归一化_normalize_float_tensor依据模型声明的output_tensor_rangenegative_one_to_one时执行clamp(-1,1)*0.50.5zero_to_one时直接 clamp将浮点帧归一化到 [0,1]维度整理_ensure_frame_list统一处理 5D/4D/3D 数组与列表嵌套适配export_to_video期望的“[0,1] 帧列表”音视频合成若输出含音频如 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做组件级 offloadVAE、文本编码器、DiT 按需选择或用--enable-layerwise-offload对 DiT 逐层卸载追求极致显存压缩时使用--quantization fp8HunyuanVideo-1.5 720p 即官方建议 FP8 VAE tiling多卡场景优先考虑--cfg-parallel-size 2CFG 开启时约 1.8 倍加速与--tensor-parallel-sizeLTX2 等支持 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 非4n1会被自动取整属正常行为而非错误。九、延伸阅读图像到视频共享入口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.mdLTX-2 全量检查点与高级选项recipes/LTX/LTX-2.mdMAGI-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考